Skip to content

Extensibility

Joshua Hiller edited this page Mar 23, 2024 · 6 revisions

CrowdStrike Falcon CrowdStrike Subreddit

Extensibility

Documentation Version Page Updated

FalconPy has been designed to be fully extensible, allowing developers to customize or enhance its functionality as required.

This page exists to provide documentation for developers wanting to extend native FalconPy functionality. When the goal is to interact with CrowdStrike APIs in a standardized fashion, existing functionality provided by Service Classes or the Uber Class should suffice for most scenarios.

Many of the features discussed on this page were released in the 1.3.0 version of FalconPy and are not supported in prior versions. Whenever possible, developers should upgrade to the most recent stable release in order to access the latest functionality.

FalconInterface APIHarnessV2 ServiceClass Service Classes

APIRequest Result LogFacility SDKError SDKWarning

Class types

FalconPy leverages several class types to provide developer functionality.

Type Purpose
Data Class A generic class abstraction layer used to represent a discrete type or segment of data.
Interface Class A generic class abstraction layer used to provide base functionality to all derivative clases that leverage it.
Derivative Class A stand-alone class that extends the functionality provided by an interface class to deliver a solution for directly interacting with CrowdStrike APIs.

APIHarnessV2

A derivative class and an interface class combined, the Uber Class provides an all-in-one interface to the CrowdStrike Falcon API.

APIHarnessV2 directly extends UberInterface (an Uber-specific interface class that extends the FalconInterface class) by using it as a base class. This results in the Uber Class inheriting all functionality provided by the FalconInterface class. The Uber Class does not maintain an auth_object attribute, as the Uber class is an authentication object. This means the Uber Class can be used for Object Authentication just like any Service Class.

For more information on how to use the Uber Class to interact with the CrowdStrike API, please refer to the Uber Class usage documentation.

Methods

Name Purpose
authenticate

DEPRECATED
Legacy method handler for triggering a authentication request and state update. This method is deprecated, developers should move to using the updated login method to access updated functionality.
command The generic method handler for processing any API operation available within the CrowdStrike API. More details about the command method can be found in the Uber Class usage documentation.
deauthenticate

DEPRECATED
Legacy method handler for revoking the current API bearer token and performing a state update. This method is deprecated, developers should move to using the updated logout method to access updated functionality.
headers

DEPRECATED
Legacy method handler that returns the current authentication headers. This method is deprecated, developers should move to using the new auth_headers property to access this dictionary.
login Performs a request for a bearer token and updates the object's current state.
logout Performs a request to revoke the current API bearer token and updates the object's current state.
valid_cred_format

DEPRECATED
Legacy method handler that returns a boolean indicating if the current credential dictionary is formatted properly. This method is deprecated, developers should move to using the new cred_format_valid property to access this flag.

Properties

Name Purpose Mutable?
authenticated A boolean flag indicating if the current object is successfully authenticated to the CrowdStrike API. No
auth_headers The authentication headers that are sent along with all requests to the CrowdStrike API. If the FalconInterface object is not currently authenticated, an authentication request will be performed when this property is referenced. No
base_url The base URL for the target CrowdStrike API. This can be the shortname, or the full address. Yes
bearer_token A data class that represents the current CrowdStrike bearer token. Yes
config The InterfaceConfiguration object used for this authentication object. Yes
creds A dictionary containing the client_id and client_secret used to authenticate to the CrowdStrike API. Yes
cred_format_valid A boolean flag indicating if the current format of the creds dictionary is valid. No
debug Boolean flag indicating if the current object has debug mode enabled. No
debug_record_count The maximum number of records per API call performed to be logged in debug logs. Yes
log The logger object used for this object. No
log_facility The attached debug logging facility for this object. No
proxy Proxy dictionary that is leveraged to perform API requests from this object. Yes
pythonic A boolean flag indicating if results returned from the API should be provided as a JSON dictionary or a pythonic object. Yes
renew_window The amount of time in seconds before the token expires and the token is automatically refreshed. Yes
refreshable A boolean flag indicating if the current bearer token can be automatically refreshed. No
sanitize_log A boolean flag indicating if client_id, client_secret, member_cid and bearer token values should be sanitized from debug logs. Yes
ssl_verify The SSL verification setting (boolean or certificate location). Yes
timeout The connect or connect / read timeout for requests made to the CrowdStrike API. Yes
token_status The current API bearer token status. No
token_expired A boolean flag indicating if the current bearer token is expired. No
token_expiration The remaining time, in seconds, the current bearer token is considered valid. Yes
token_fail_reason API authentication failure reason. No
token_renew_window

DEPRECATED
This property recreates the functionality of a legacy attribute and is deprecated. Developers should make use of the renew_window property to make changes to the token renewal window. Yes
token_time The timestamp when the current bearer token was generated. Yes
token_value The bearer token value as a string. Yes
user_agent The User-Agent string that is sent as part of the headers for all API requests performed. Yes

Back to top


APIRequest

A generic data class comprised of several sub-classes containing all of the details for the API request to be performed.

The APIRequest object is used internally to store the details of a discrete request made to the CrowdStrike API. Most of the properties for this object, and it's sub-classes, are set when the object is constructed. These properties are defined as immutable.

Methods

Name Purpose
log_error Leverages the attached LogFacility to log errors generated as part of a request.
log_warning Leverages the attached LogFacility to log errors generated as part of a request.

Properties

Name Purpose Mutable?
meta Returns the RequestMeta data sub-class object. No
endpoint The URL route for the API request to perform. No
method The HTTP method for the API request to perform. No
debug_headers Temporary storage for headers returned by the request. Only used when debug logging is enabled. Yes
payloads Returns the RequestPayloads data sub-class object. No
body_payload The request body content provided to the API. Typically, this is a dictionary. No
param_payload The query string parameters appended to the route and provided to the API. Typically, this is a dictionary. No
data_payload The request data content provided to the API. No
files The list of files to be provided along with the API request. List of tuples. No
behavior Returns the RequestBehavior data sub-class object. No
expand_result Boolean indicating if result expansion is enabled. No
container Boolean indicating if this API request targets a Falcon Container endpoint. No
authenticating Boolean indicating if this API request is performing an authentication event. No
perform Boolean indicating if this API request has passed validation and should be performed. Yes
body_validator Dictionary containing body payload validation requirements for the API request to perform. No
body_required List of required keys that must be present within the body payload for this API request. No
request_log Returns the LogFacility sub-class object. No
log_util Returns the underlying python Logger object from the LogFacility sub-class. No
max_debug Maximum number of records to output to a debug log. No
sanitize_log Boolean indicating if log sanitization is enabled. No
connection Returns the RequestConnection data sub-class object. No
user_agent The string provided as the User-Agent header when the API request is performed. No
proxy The dictionary of proxies used for the API request. No
timeout The connect or connect / read timeout for performing the API request. No
verify Boolean indicating the SSL verification status or string pointing to a local certificate file used for the API request. No

Back to top


FalconInterface

A generic object that represents the interface to the CrowdStrike Falcon API.

This class contains the default object constructor, as well as the properties and methods used by derivative classes to maintain state and authenticate to the CrowdStrike API. Typically, a developer should not need to create an instance of the FalconInterface class. This class is intended to be used an attribute or inherited as a base class.

The FalconInterface class is frequently referred to as the "authentication object" or the "auth object". For all but one of the Service Classes that leverage it, this object is available as the auth_object attribute.

The OAuth2 Service Class directly extends the FalconInterface class by using it as a base class.

The UberInterface class directly extends the FalconInterface class by using it as a base class. This class is used by the Uber Class (APIHarnessV2) as it's base class, inheriting all functionality provided by the FalconInterface class.

Methods

Name Purpose
login Leverages a private method to perform a request for a bearer token and updates the authentication object's current state.
logout Leverages a private method to revoke the current API bearer token and updates the object's current state.

Properties

Name Purpose Mutable?
authenticated A boolean flag indicating if the current object is successfully authenticated to the CrowdStrike API. No
auth_headers The authentication headers that are sent along with all requests to the CrowdStrike API. If the FalconInterface object is not currently authenticated, an authentication request will be performed when this property is referenced. No
base_url The base URL for the target CrowdStrike API. This can be the shortname, or the full address. Yes
bearer_token A data class that represents the current CrowdStrike bearer token. Yes
config The InterfaceConfiguration object used for this authentication object. Yes
creds A dictionary containing the client_id and client_secret used to authenticate to the CrowdStrike API. Yes
cred_format_valid A boolean flag indicating if the current format of the creds dictionary is valid. No
debug Boolean flag indicating if the current object has debug mode enabled. No
debug_record_count The maximum number of records per API call performed to be logged in debug logs. Yes
log The logger object used for this object. No
log_facility The attached debug logging facility for this object. No
proxy Proxy dictionary that is leveraged to perform API requests from this object. Yes
pythonic A boolean flag indicating if results returned from the API should be provided as a JSON dictionary or a pythonic object. Yes
renew_window The amount of time in seconds before the token expires and the token is automatically refreshed. Yes
refreshable A boolean flag indicating if the current bearer token can be automatically refreshed. No
sanitize_log A boolean flag indicating if client_id, client_secret, member_cid and bearer token values should be sanitized from debug logs. Yes
ssl_verify The SSL verification setting (boolean or certificate location). Yes
timeout The connect or connect / read timeout for requests made to the CrowdStrike API. Yes
token_status The current API bearer token status. No
token_expired A boolean flag indicating if the current bearer token is expired. No
token_expiration The remaining time, in seconds, the current bearer token is considered valid. Yes
token_fail_reason API authentication failure reason. No
token_time The timestamp when the current bearer token was generated. Yes
token_value The bearer token value as a string. Yes
user_agent The User-Agent string that is sent as part of the headers for all API requests performed. Yes

Back to top


LogFacility

A generic interface class that provides logging functionality for all classes and functions within the library.

Methods

Name Purpose
deactivate_log Removes the underlying Logger object, disabling the log facility.

Properties

Name Purpose Mutable?
log Returns the underlying Logger object for the log facility. No
active Boolean indicating if this log facility is currently active. No
sanitize_log Boolean indicating if log sanitization is currently enabled for the log facility. Yes
debug_record_count Integer representing the maximum number of records the log facility will log per request performed. Yes

Back to top


Result

A generic interface class that represents the result received from the CrowdStrike API.

The Result object is comprised of multiple dynamic components that together provide two discrete styles for consuming results from CrowdStrike APIs.

Style Benefit
Dictionary API results are presented in a standardized dictionary format (JSON).
Pythonic API results are presented as Python objects that can be handled like an iterator.

The default style for consuming API results is Dictionary.

Attributes

Name Purpose Data type
status_code The HTTP status code received for the performed request. Integer
headers All HTTP headers received for the performed request. Headers
meta All metadata received for the performed request. Meta
resources All data results received for the performed request. Resources
errors All errors received for the performed request. Errors
raw The raw result received, regardless of format. RawBody

Methods

Name Purpose
prune Returns a list of matches for the provided substring within available results.

Properties

Name Purpose Mutable?
data Returns all data received from the underlying Resources object. No
total Returns the total number of records matching the request performed. No
offset Returns the current record position for the results returned. No
limit Returns the maximum number of return records allowed for the performed request. No
query_time Returns the total execution time for the query performed. No
powered_by Returns the powered_by value for the performed request from the underlying Meta object. No
trace_id Returns the trace_id for the performed request from the underlying Meta object. No
content_encoding Returns the encoding format used for the content received in this result. No
content_type Returns the content type received for this result. No
content_length Returns the total length of all content received for this result. No
date Returns the date the request was performed. No
region Returns the CrowdStrike region where the request was performed. No
ratelimit_limit Returns the total rate limit from the underlying Headers object. No
ratelimit_remaining Returns the remaining rate limit from the underlying Headers object. No
headers_object Boolean flag indicating if the headers data for this result is stored as a Result object. No
meta_object Boolean flag indicating if the meta data for this result is stored as a Meta object. No
tupled Returns the full result as a tuple. (status_code, headers, content) No
body Returns just the body dictionary of the API result. No
binary Boolean flag indicating if the result is in binary format. No
full_return Returns the full result in dictionary format. No

Back to top


SDKError

A generic interface class that is used as the base class for errors generated at runtime.

The SDKError class inherits from the Python Exception class to provide FalconPy-specific error handling.

The following custom error types are currently defined within the FalconPy SDK:

Error Cause
APIError An unexpected error was received from the CrowdStrike API.
CannotRevokeToken The token revocation request has failed.
FeatureNotSupportedByPythonVersion This feature is not supported by your version of Python.
FunctionalityNotImplemented This functionality is not currently implemented.
InvalidBaseURL The base URL specified is invalid or unavailable.
InvalidCredentialFormat The value provided for the creds keyword does not match the correct dictionary format.
InvalidCredentials The provided API credentials are invalid.
InvalidIndex The requested position within the list or string provided does not exist.
InvalidMethod The specified HTTP method is not accepted.
InvalidOperation The API operation specified does not exist.
KeywordsOnly The specified method does not accept positional arguments, only keywords.
PayloadValidationError Payload validation has failed.
RegionSelectError Cloud region auto-discovery has failed.
SDKError Generic error handler leveraged for all unhandled errors.
TokenNotSpecified The keyword token_value was not provided to the revoke operation.
UnsupportedPythonVersion The version of Python you are attempting to use is not supported.

Back to top


SDKWarning

A generic interface class that is used as the base class for warnings generated at runtime.

The SDKWarning class inherits from the Python RuntimeWarning class to provide FalconPy-specific warnings.

The following custom warnings types are currently defined within the FalconPy SDK:

Warning Cause
NoAuthenticationMechanism A mechanism for performing authentication to the CrowdStrike API was not specified when creating an instance of this class.
NoContentWarning The API response indicates the request was successfully performed, but no content was receieved.
SSLDisabledWarning SSL verification has been disabled for requests made to the CrowdStrike API using this class.

Back to top


ServiceClass

A generic interface class that abstracts functionality leveraged by all derivative Service Classes.

This class extends the BaseServiceClass object, which is not intended for extensible usage outside of this scenario.

All FalconPy Service Classes, excluding OAuth2, extend the ServiceClass object to inherit common functionality.

Attributes

Name Purpose Data type
auth_object The attached FalconInterface object used for authentication and maintaining state. FalconInterface or derivative
validate_payloads Flag indicating if payloa1d contents sent to the API should be validated before being sent. Boolean

Methods

Name Purpose
authenticated Method handler that returns the current authentication state. Retrieved from the attached auth_object attribute.
login Performs a request for a bearer token and updates the authentication objects current state.
logout Revokes the current API bearer token and updates the objects current state.
token_expired Method handler that returns the current token expiration status. Retrieved from the attached auth_object attribute.

Properties

Name Purpose Mutable?
base_url The base URL address for the target CrowdStrike API. This can be the shortname, or the full address. This property is returned from the auth_object attribute. Yes
ssl_verify The SSL verification setting (boolean or certificate location). This property is returned from the auth_object attribute. Yes
log The logger object for this object. This property can be enabled or disabled per Service Class regardless of the setting specified in the attached auth_object. When not specifically enabled or disabled, this property is returned from the auth_object attribute. No
headers The headers that are sent for all API requests performed. This includes authentication headers that are requested from the attached auth_object and any custom headers provided when the object is created via the ext_headers keyword argument. No
token String representation of the current token. No
token_fail_reason API authentication failure reason. This property is returned from the auth_object attribute. No
token_stale Boolean flag indicating if the current bearer token is stale. No
token_status The current API bearer token status. This property is returned from the auth_object attribute. No
token_valid Boolean flag indicating if we have a valid authentication token. No
refreshable Boolean flag indicating if the current bearer token can be automatically refreshed. This property is returned from the auth_object attribute. No
debug Boolean flag indicating if the current object has debug mode enabled. This property can be enabled or disabled per Service Class regardless of the setting specified in the attached auth_object. When not specifically enabled or disabled, this property is returned from the auth_object attribute. No
proxy Proxy dictionary that is leveraged to perform API requests from this object. This property can be set to a unique value per Service Class regardless of the setting specified in the attached auth_object. When not specifically set, this property is returned from the auth_object attribute. Yes
renew_window The amount of time in seconds before the token expires and the token is automatically refreshed. This property is returned from the auth_object attribute. Changing this value will impact all classes that leverage this same authentication object. Yes
token_renew_window

DEPRECATED
This property recreates the functionality of a legacy attribute and is deprecated. Developers should make use of the renew_window property to make changes to the token renewal window. Yes
timeout Amount of time before considering a connection as timed out. When specififying a float for this value, the timeout is used for the entire request. When specified as a tuple this is used for read and connect. Yes
user_agent The User-Agent string that is sent as part of the headers for all API requests performed. This property can be set to a unique value per Service Class regardless of the setting specified in the attached auth_object. When not specifically set, this property is returned from the auth_object attribute. Yes
debug_record_count The maximum number of records per API call performed to be logged in debug logs. This property can be set to a unique value per Service Class regardless of the setting speficied in the attached auth_object. When not specificially set, this property is returned from the auth_object attribute. Yes
sanitize_log Boolean flag indicating if client_id, client_secret, member_cid and bearer token values should be sanitized from debug logs. This property can be enabled or disabled per Service Class regardless of the setting specified in the attached auth_object. When not specifically enabled or disabled, this property is returned from the auth_object attribute. Yes
pythonic Boolean flag indicating if results returned from the API should be provided as a JSON dictionary or a pythonic object. This property can be enabled or disabled per Service Class regardless of the setting specified in the attached auth_object. When not specifically enabled or disabled, this property is returned from the auth_object attribute. No

Back to top


Service Classes

Derivative classes that represent individual CrowdStrike API service collections, each Service Class contains methods that represent every API operation within the collection.

Service Classes extend the ServiceClass class by using it as a base class and inheriting it's attributes, methods and properties.

Service Classes can also be inherited, allowing developers to implement additional methods for extending core Servicee Class functionality.

Each Service Class will contain a PEP8 compliant method name, as well as an alias for the Operation ID (if this ID does not match PEP8 formatting requirements), for every operation within the service collection it represents. More details regarding these methods and their usage can be found in the service collection documentation for the specific API in question or the Operations by Collection page.

For more information regarding how to use Service Classes to interact with the CrowdStrike API, please review the Service Class usage documentation.

Back to top


CrowdStrike Falcon

Clone this wiki locally