Extensibility

Extensibility

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.

APIHarness

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

APIHarness 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	Leverages a private method to perform a request for a bearer token and updates the authentication objects current state.
logout	Leverages a private method to revoke the current API bearer token and updates the objects current state.
valid_cred_format	Legacy method handler that returns a boolean indicating if the current credential dictionary 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.

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.
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.

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 (APIHarness) 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.

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.

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
auth_object	The attached FalconInterface object used for authentication and maintaining state.

Methods

Name	Purpose
authenticated	Method handler that returns the current authentication state. Retrieved from the attached auth_objeect 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_objeect 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_status	The current API bearer token status. This property is returned from the auth_object attribute.
token_fail_reason	API authentication failure reason. This property is returned from the auth_object attribute.
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.
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.

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

---