Using the Uber Class

Both an interface and a derivative class, the Uber Class provides an all-in-one interface to every service collection within the CrowdStrike API.

• Import and Authentication
• The command method
• Uber Class architecture

This documentation reflects functionality available within the latest version of the Uber Class (APIHarnessV2) released in v1.3.2. The legacy version of the Uber Class (APIHarness) is deprecated, does not support Environment Authentication, or several of the methods and properties detailed here.

Import and Authentication

To make use of the Uber Class, you will need to import it, and then construct an instance of the class. During this construction, you will provide API credentials for authentication and specify any additional configuration options required by your environment.

The Uber class leverages four authentication mechanisms, Direct Authentication, Credential Authentication, Environment Authentication and Context Authentication. These methods abstract token administration and allow developers to skip the initial authentication step if desired.

You will not authenticate until you request the headers property, or your first request to the API is made. If you check your authentication status, your token or your token_expiration before performing a request, the results will be 0 or None.

Passing credentials

WARNING

client_id and client_secret are keyword arguments that contain your CrowdStrike API credentials. Please note that all examples below do not hard code these values. (These values are ingested as strings.)

CrowdStrike does NOT recommend hard coding API credentials or customer identifiers within source code.

Direct Authentication

Direct Authentication allows you to pass your credentials to the class as keywords when you create it.

from falconpy import APIHarnessV2

auth = APIHarnessV2(client_id=CLIENT_ID, client_secret=CLIENT_SECRET)

# This example also demonstrates Parameter Abstraction
# within the Uber Class, in our next example, we will
# pass the same argument using the parameters dictionary.
result = falcon.command(action="QueryDevicesByFilterScroll", limit=100)

print(result)

# Only logout when you are done interacting with the API
falcon.logout()

For more detail, please review the full Direct Authentication documentation.

Credential Authentication

Credential Authentication allows you to pass your credentials as a dictionary to the class when you create it.

from falconpy import APIHarnessV2

falcon = APIHarnessV2(creds={"client_id": CLIENT_ID, "client_secret": CLIENT_SECRET})

PARAMS = {"limit": 10}

result = falcon.command(action="QueryDevicesByFilterScroll", parameters=PARAMS)

print(result)

# Only logout when you are done interacting with the API
falcon.logout()

For more detail, please review the full Credential Authentication documentation.

Environment Authentication

Starting in v1.3.0, you may now use the Environment Authentication mechanism to authenticate with the Uber Class.

In order for Environment Authentication to be used, you must have the following two variables defined within the environment at runtime.

Both variables must be defined in the environment before Environment Authentication will be attempted. If both environment variables are present, and only one of these values exist within the creds dictionary, then the missing value will be replaced with the value stored within the environment.

from falconpy import APIHarnessV2

falcon = APIHarnessV2()

hidden_devices = falcon.command("QueryHiddenDevices")

print(hidden_devices)

# Only logout when you are done interacting with the API
falcon.logout()

Context Authentication

Context Authentication enables the retrieval of the bearer token from the current running context. When present, this token is leveraged for all requests to the API. This authentication mechanism is primarily used in Fusion workflow actions. FalconPy classes that have authenticated using Context Authentication do not have access to API credentials and cannot automatically renew the bearer token.

You must be running FalconPy v1.4.3 or greater in order to take advantage of Context Authentication.

from falconpy import APIHarnessV2
from crowdstrike.foundry.function import Function, Response

func = Function.instance()

@func.handler(method='POST', path='/data')
def on_query(request, config: Union[Dict[str, any], None]) -> Response:
	with APIHarnessV2() as uber:
		result = uber.command("GetQueriesAlertsV2")
		return Response(body=result["body"], code=result["status_code"])

Legacy Authentication

In order to make use of legacy authentication, you will first need to create an instance of the OAuth2 derivative class in order to generate a token. You may use Direct Authentication, Credential Authentication or Environment Authentication when you create an instance of this class.

from falconpy import OAuth2
from falconpy import APIHarnessV2

authorization = OAuth2(client_id=CLIENT_ID, client_secret=CLIENT_SECRET)

try:
    token = authorization.token()["body"]["access_token"]
    falcon = APIHarnessV2(access_token=token)
except:
    token = False
    # Failure handling here

For more detail, please review the full Legacy Authentication documentation.

Back to Top

For more detail, please review the full Environment Authentication documentation.

Additional attributes

Authorization status and the token are available as properties.

from falconpy import APIHarnessV2
falcon = APIHarnessV2(client_id=CLIENT_ID, client_secret=CLIENT_SECRET)

falcon.login()

if falcon.authenticated:
    print(falcon.token_value)

Example result

$ eyJhbGciOiJSUzI1NiIsImtpZCI6InB1YmxpYzph...really long token string

Aditional configuration options

The Uber Class provides full support for all custom environment configuration options supported by Service Classes.

Back to Top

The command method

The Uber Class leverages a single method to make calls to the CrowdStrike API. This method is called command, and handles all the same payload types that Service Class API operation methods handle.

Allowed arguments and keywords

The command method accepts only one positional argument, which is assumed to be the action keyword and contain the requested Operation ID. Either this argument must be specified, or one of the keywords, action or override, in order to make use of the command method. All other keywords are optional based upon the API operation being performed.

Parameter Abstraction

As of the v0.8.0 release, the Uber Class supports Parameter Abstraction. This functionality allows developers to specify query string parameter values using keywords as opposed to crafting a parameters dictionary and passing it to the command method using the parameters keyword.

Example

from falconpy import APIHarnessV2

falcon = APIHarnessV2(client_id=CLIENT_ID, client_secret=CLIENT_SECRET)

result = falcon.command("QueryDevicesByFilterScroll", limit=100, sort="hostname.asc")

print(result)

Specifying route and method manually (Override)

The Uber Class supports specifying an API operation's HTTP method and route via the override keyword. This argument is provided as a string and should follow METHOD,ROUTE format.

Parameter Abstraction functionality is not supported when making use of the override keyword.

Example

The following example performs the same request demonstrated above, but instead calls the endpoint manually using the override keyword.

from falconpy import APIHarnessV2

falcon = APIHarnessV2(client_id=CLIENT_ID, client_secret=CLIENT_SECRET)

# When using the override keyword, parameter abstraction functionality is not supported. Instead,
# we will create a dictionary to hold these values and provide them to the parameters keyword.
PARAMS = {"limit": 100, "sort": "hostname.asc"}

result = falcon.command(override="GET,/devices/queries/devices-scroll/v1", parameters=PARAMS)

print(result)

API responses

Most API response results will be in the form of a JSON formatted dictionary.

Review the Content-Type section within the operation details of the related service collection wiki page to identify operations that produce results that are binary and will require being saved to a file.

Example

{
	"status_code": 200,
	"headers": {
		"Server": "nginx",
		"Date": "Sat, 22 Jul 2023 06:11:11 GMT",
		"Content-Type": "application/json",
		"Content-Length": "512",
		"Connection": "keep-alive",
		"Content-Encoding": "gzip",
		"Strict-Transport-Security": "max-age=15724800; includeSubDomains, max-age=31536000; includeSubDomains",
		"X-Cs-Region": "us-1",
		"X-Cs-Traceid": "a1bcd234-efa5-6b78-9012-3c4d56ef7a8b",
		"X-Ratelimit-Limit": "6000",
		"X-Ratelimit-Remaining": "5999"
	},
	"body": {
		"meta": {
			"query_time": 0.006985558,
			"pagination": {
				"total": 21310,
				"offset": "FQluY2x1ZGVfY29udGV4dF91dWlkDnF1ZXJ5VGhlbkZldGNoAhZHTF80UlNJYlRtbV9VVVB2TDNzeXFRAAAAABOoKoMWM1FBbS1nVEVRc0c0YjBsYWdVNnAzUYXASEb8bXRvSVFSS0VsQ3BLd3lZbmRRAAAAABTHsT4WWW0zSVFoM01UM2lmYWlRUFJwdzFwQQ==",
				"expires_at": 1690006391067438708
			},
			"powered_by": "device-api",
			"trace_id": "a1bcd234-efa5-6b78-9012-3c4d56ef7a8b"
		},
		"resources": ["123abcde45f67890a1234b5c6de789f0", "a1b2cde3fa4567bcd8e9f0a1b2c34d5d", "a1b23c45d67e8901fa2a34b56cd78ef9", "1a2b3cd4ef5a67b8c9012dfe34567890", "1a2bcde34f5a6b789012cd3ef456a7b8"],
		"errors": []
	}
}

Back to Top

Uber Class architecture

The following attributes, methods and properties are available within the Uber Class upon creation.

Documentation regarding specific API operations can be found in the related service collection documentation page.

Attributes

Upon creation, an instance of the Uber Class will contain the following attributes.

Methods

The following methods are available within any instance of the Uber Class.

Name	Purpose
authenticate	Legacy handler to authenticate against the CrowdStrike API and generate a bearer token. This method is deprecated, developers should make use of the login method to access this functionality.
authenticated	Returns a boolean flag indicating if the current object is successfully authenticated to the CrowdStrike API.
command	Performs the specified API operation. If the class is not currently authenticated, an attempt to generate the bearer token will be made.
deauthenticate	Legacy handler to revoke the current bearer token. This method is deprecated, developers should make use of the logout method to access this functionality.
headers	Legacy method handler for retrieving the current authorization headers. This method is deprecated, developers should instead use the auth_headers property to access this functionality.
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.
token	Legacy method handler for retrieving the current bearer token value as a string. This method is deprecated, developers should instead use the token_value property to access this functionality.
token_expired	Returns a boolean flag indicating if the current bearer token is expired.
valid_cred_format	Legacy handler that returns a boolean indicating if the current credentials dictionary is in a valid format. This method is deprecated, developers should make use of the cred_format_valid property instead.

Properties

The following properties are available within any instance of the Uber Class.

Name	Purpose	Mutable?
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. For successful authentication scenarios, this value will be 201. This attribute is populated after calling the authenticate method or after your first usage of the command method.
token_expiration	The remaining time, in seconds, the current bearer token is considered valid.
token_fail_reason	API authentication failure reason.
token_stale	Boolean flag indicating if the current token has expired
token_valid	Boolean flag indicating if the current token is valid.
token_renew_window	This property recreates the functionality of a legacy Service Class 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