Skip to content

Extensibility

jshcodes edited this page Jul 19, 2023 · 31 revisions

CrowdStrike Falcon Twitter URL

Extensibility

Documentation Version Page Updated

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

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

APIHarness FalconInterface ServiceClass

APIRequest LogFacility Result SDKError SDKWarning

FalconPy leverages several class types to provide developer functionality.

Type Purpose
Data Class Generic class abstraction layer used to represent a discrete type or segment of data.
Interface Class Generic class abstraction layer used to provide base functionality to all derivative clases that leverage it.
Derivative Class 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.

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

DEPRECATED
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. 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 data sub-classes containing all of the details for the API request to be performed.

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.

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. 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 within the library.

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.

Back to top


SDKWarning

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

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. 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_status The current API bearer token status. This property is returned from the auth_object attribute. No
token_fail_reason API authentication failure reason. This property is returned from the auth_object attribute. 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
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

Back to top


CrowdStrike Falcon

Clone this wiki locally