CrowdStrike Falcon Twitter URL

Using the Uber Class

Documentation Version Page Updated

Import and Authentication

To make use of the Uber Class, you will need to import it, provide API credentials for authentication and specify any additional configuration options required by your environment.

The Uber class leverages two authentication methods, Direct Authentication and Credential Authentication. These methods abstract token administration and allow developers to skip the initial authentication step if desired1.

1

You will not authenticate until 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 False.

Passing credentials

WARNING

client_id and client_secret are input variables 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 APIHarness

auth = APIHarness(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.
account_list = falcon.command(action="QueryAWSAccounts", limit=100)

print(account_list)

# Only de-auth when you are done interacting with the API
falcon.deauthenticate()

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 APIHarness

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

PARAMS = {"limit": 100}

account_list = falcon.command(action="QueryAWSAccounts", parameters=PARAMS)

print(account_list)

# Only de-auth when you are done interacting with the API
falcon.deauthenticate()

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

Additional attributes

Authorization status and the token are available as attributes.

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

falcon.authenticate()

if falcon.authenticated:
    print(falcon.token)

Example result

$ eyJhbGciOiJSUzI1NiIsImtpZCI6InB1YmxpYzph...really long token string

Aditional configuration options

The Uber Class supports custom environment configuration similar to Service Classes and provides full support for all environment configuration keywords.

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 Classes 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 the action keyword present, in order to make use of the command method.

KeywordDescription
actionOperation ID to perform. Can be omitted if passed as the first argument to the method.
action_nameName of the operation-specific action to perform. Only has effect on operations that require it.
parametersJSON formatted query string payload.
bodyJSON or binary formatted body payload.
content_typeForces the Content-Type header for the request being performed.
dataJSON or binary formatted form data payload.
filesFile array formatted file data payload.
file_nameName of the file represented within a form or file data payload.
headersDictionary of additional headers to add to request performed.
idsComma-delimited string or list of strings containing the IDs necessary for the requested operation.
partitionNumber of the stream partition to refresh. Specific to the Event Streams API service collection.
distinct_fieldName of the field to search for distinct references. Specific to the Sensor Update Policy API service collection.
overrideString representation of the operation to perform when the Operation ID is unknown. Should be provided in METHOD,ENDPOINT format. Endpoint should not contain the base URL.

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 APIHarness

falcon = APIHarness(client_id="API_KEY_HERE",
                    client_secret="API_SECRET_HERE"
                    )

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

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": {
        "Content-Encoding": "gzip",
        "Content-Length": "699",
        "Content-Type": "application/json",
        "Date": "Thu, 12 Nov 2020 22:34:47 GMT",
        "X-Cs-Region": "us-1",
        "X-Ratelimit-Limit": "6000",
        "X-Ratelimit-Remaining": "5954"
    },
    "body": {
        "meta": {
            "query_time": 0.0030413,
            "pagination": {
                "offset": 3,
                "limit": 100,
                "total": 3
            },
            "powered_by": "cloud-connect-manager",
            "trace_id": "7c182b49-fe3c-4704-9042-12345678e8d3"
        },
        "errors": [],
        "resources": [
            {
                "cid": "123456-redacted-cid",
                "id": "987654321098",
                "iam_role_arn": "arn:aws:iam::987654321098:role/FalconDiscover",
                "external_id": "IwXe54tosfaSDfsE32dS",
                "policy_version": "1",
                "cloudtrail_bucket_owner_id": "987654321098",
                "cloudtrail_bucket_region": "eu-west-1",
                "created_timestamp": "2020-11-12T20:18:28Z",
                "last_modified_timestamp": "2020-11-12T20:18:28Z",
                "last_scanned_timestamp": "2020-11-12T20:18:28Z",
                "provisioning_state": "registered"
            },
            {
                "cid": "123456-redacted-cid",
                "id": "2109876543210",
                "iam_role_arn": "arn:aws:iam::2109876543210:role/CrowdStrikeFalcon",
                "external_id": "AnotherExternalID",
                "policy_version": "1",
                "cloudtrail_bucket_owner_id": "2109876543210",
                "cloudtrail_bucket_region": "eu-west-1",
                "created_timestamp": "2020-10-08T12:44:49Z",
                "last_modified_timestamp": "2020-10-08T12:44:49Z",
                "last_scanned_timestamp": "2020-11-01T00:14:13Z",
                "provisioning_state": "registered",
                "access_health": {
                    "api": {
                        "valid": true,
                        "last_checked": "2020-11-12T22:34:00Z"
                    }
                }
            },
            {
                "cid": "123456-redacted-cid",
                "id": "0123456789012",
                "iam_role_arn": "arn:aws:iam::0123456789012:role/FalconDiscover",
                "external_id": "CrossAccountExternalID",
                "policy_version": "1",
                "cloudtrail_bucket_owner_id": "0123456789012",
                "cloudtrail_bucket_region": "us-east-1",
                "created_timestamp": "2020-08-12T12:43:16Z",
                "last_modified_timestamp": "2020-10-07T09:44:00Z",
                "last_scanned_timestamp": "2020-11-01T00:13:12Z",
                "provisioning_state": "registered",
                "access_health": {
                    "api": {
                        "valid": false,
                        "last_checked": "2020-11-12T22:34:00Z",
                        "reason": "Assume role failed. IAM role arn and/or external is invalid."
                    }
                }
            }
        ]
    }
}

Uber Class attributes

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

Attribute nameData typeDefault ValueDescription
authenticatedBooleanFalseFlag indicating if the Uber Class has successfully generated a token to use for requests to the API.
base_urlStringhttps://api.crowdstrike.comThe URL to use for all requests performed.
commandsDictionaryNoneComplete list of available API operations.
credsDictionaryNoneDictionary containing the credentials used for token generation.
headersDictionaryEmptyDictionary containing the headers sent to the API. This dictionary is updated based upon the requirements of the requested operation.
proxyDictionaryNoneDictionary of proxy servers to use for all requests made to the API.
timeoutFloat or Tuple of FloatsNoneAmount 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.
tokenStringNoneString representation of the current authentication token.
token_expirationInteger0Integer representation of the remaining seconds before the current token expires.
token_fail_reasonStringNoneString containing the authentication failure reason. This attribute is only populated upon token generation failure. This value will be populated immediately after calling the authenticate method, or after making your first request.
token_renew_windowInteger120Amount of time before token expiration where a token is automatically renewed.
token_statusIntegerNoneThe returned status code when the token was generated. 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_timeTimeNoneTimestamp for when the token was generated.
user_agentStringcrowdstrike-falconpy/VERSIONString used as the User-Agent header for all requests made to the API.
ssl_verifyBooleanTrueFlag indicating if SSL verification should be used for all requests made to the API.