Extensibility

Documentation Version

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.

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

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

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

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.
`active`	Boolean indicating if this log facility is currently active.
`sanitize_log`	Boolean indicating if log sanitization is currently enabled for the log facility.
`debug_record_count`	Integer representing the maximum number of records the log facility will log per request performed.

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

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.

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.

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.
`ssl_verify`	The SSL verification setting (boolean or certificate location). This property is returned from the `auth_object` attribute.
`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.
`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.
`token`	String representation of the current token.
`token_fail_reason`	API authentication failure reason. This property is returned from the `auth_object` attribute.
`token_stale`	Boolean flag indicating if the current bearer token is stale.
`token_status`	The current API bearer token status. This property is returned from the `auth_object` attribute.
`token_valid`	Boolean flag indicating if we have a valid authentication token.
`refreshable`	Boolean flag indicating if the current bearer token can be automatically refreshed. This property is returned from the `auth_object` attribute.
`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.
`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.
`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.
`token_renew_window`	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.
`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`.
`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.
`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.
`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.
`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.

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.

The CrowdStrike Falcon Wiki for Python