Basic Uber Class usage

Using the Uber Class

• Import and Authentication
• The command method
• API responses
• Uber Class attributes

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

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 doing so, the results will be False.

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_HERE",
                  client_secret="CLIENT_SECRET_HERE"
                  )

# 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()

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_HERE",
            "client_secret": "CLIENT_SECRET_HERE"
            })

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

Additional constants

Authorization status and the token are still available as constants.

from falconpy import APIHarness
falcon = APIHarness(client_id="CLIENT_ID_HERE",
                    client_secret="CLIENT_SECRET_HERE"
                    )

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.

Keyword	Description
action	Operation ID to perform. Can be omitted if passed as the first argument to the method.
action_name	Name of the operation-specific action to perform. Only has effect on operations that require it.
parameters	JSON formatted query string payload.
body	JSON or binary formatted body payload.
content_type	Forces the Content-Type header for the request being performed.
data	JSON or binary formatted form data payload.
files	File array formatted file data payload.
file_name	Name of the file represented within a form or file data payload.
headers	Dictionary of additional headers to add to request performed.
ids	Comma-delimited string or list of strings containing the IDs necessary for the requested operation.
partition	Number of the stream partition to refresh. Specific to the Event Streams API service collection.
distinct_field	Name of the field to search for distinct references. Specific to the Sensor Update Policy API service collection.
override	String 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 name	Data type	Default Value	Description
authenticated	Boolean	False	Flag indicating if the Uber Class has successfully generated a token to use for requests to the API.
base_url	String	https://api.crowdstrike.com	The URL to use for all requests performed.
commands	Dictionary	None	Complete list of available API operations.
creds	Dictionary	None	Dictionary containing the credentials used for token generation.
headers	Dictionary	Empty	Dictionary containing the headers sent to the API. This dictionary is updated based upon the requirements of the requested operation.
proxy	Dictionary	None	Dictionary of proxy servers to use for all requests made to the API.
timeout	Float or Tuple of Floats	None	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.
token	String	None	String representation of the current authentication token.
token_expiration	Integer	0	Integer representation of the remaining seconds before the current token expires.
token_fail_reason	String	None	String 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_status	Integer	None	The 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_time	Time	None	Timestamp for when the token was generated.
user_agent	String	crowdstrike-falconpy/VERSION	String used as the User-Agent header for all requests made to the API.
ssl_verify	Boolean	True	Flag indicating if SSL verification should be used for all requests made to the API.