Using the Uber Class
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.
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
andclient_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 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.
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_renew_window | Integer | 120 | Amount of time before token expiration where a token is automatically renewed. |
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. |