CrowdStrike Falcon Twitter URL

Using Service Classes

Documentation Version Page Updated

Import and Authentication

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

Service Classes support multiple methods of authentication depending on the needs of your solution.

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 directly to the class as keywords when you create it.

from falconpy import CloudConnectAWS

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

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

Credential Authentication

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

from falconpy import CloudConnectAWS

auth = CloudConnectAWS(creds={
        "client_id": CLIENT_ID,
        "client_secret": CLIENT_SECRET
    })

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

Object Authentication

Object Authentication allows you to create an instance of the OAuth2 Service Class, authenticate, and then use this object to interact with other API service collections. Either Direct Authentication or Credential Authentication may be used to create the instance of the OAuth2 Service Class (auth_object).

Object Authentication using keywords

from falconpy import OAuth2
from falconpy import CloudConnectAWS

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

falcon = CloudConnectAWS(auth_object=auth)

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

Object Authentication using a credential dictionary

from falconpy import OAuth2
from falconpy import CloudConnectAWS

auth = OAuth2(creds={
        "client_id": CLIENT_ID,
        "client_secret": CLIENT_SECRET
    })

falcon = CloudConnectAWS(auth_object=auth)

Legacy Authentication

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

from falconpy import OAuth2
from falconpy import CloudConnectAWS

authorization = OAuth2(creds={
        "client_id": CLIENT_ID,
        "client_secret": CLIENT_SECRET
    })

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

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

Performing a request

Once you have provided your API credentials (and any necessary customization options) you are ready to interact with different API service collections. Each Service Class has a method defined for every Operation within the API service collection. You may leverage either PEP8 or Operation ID syntax to perform the operations. Depending on the requirements of the selected operation, different payloads will also need to be specified at the time of the request. More detail regarding the requirements of specific API operations and their payloads are provided in the wiki page for the related API service collection.

This examples leverages the Cloud Connect AWS service class to interact with the CrowdStrike OAuth2 API regarding Amazon Web Service deployments.

from falconpy import CloudConnectAWS

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

# You can use PEP8 or Operation ID syntax for this call
account_list = falcon.query_aws_accounts(limit=100)
# Show our results
print(account_list)

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.

{
    "status_code": 200,
    "headers": {
        "Content-Encoding": "gzip",
        "Content-Length": "699",
        "Content-Type": "application/json",
        "Date": "Thu, 12 Nov 2020 20:18:29 GMT",
        "X-Cs-Region": "us-1",
        "X-Ratelimit-Limit": "6000",
        "X-Ratelimit-Remaining": "5987"
    },
    "body": {
        "meta": {
            "query_time": 0.003052599,
            "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-12T20:18: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-12T20:18:00Z",
                        "reason": "Assume role failed. IAM role arn and/or external is invalid."
                    }
                }
            }
        ]
    }
}

Service Class attributes

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

Attribute nameData typeDefault ValueDescription
auth_objectOAuth2 ClassNoneAn instance of the OAuth2 authentication object.
base_urlStringhttps://api.crowdstrike.comThe URL to use for all requests performed.
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.
refreshableBooleanFalseFlag indicating if the token within this Service Class can support automatic refresh.
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 authentication token generated when instantiating this Service Class.
token_fail_reasonStringNoneString containing the authentication failure reason. This attribute is only populated upon token generation failure. For Service Classes, this value will be populated immediately after instantiation.
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 this Service Class. For successful authentication scenarios, this value will be 201. This attribute is populated after creating an instance of any Service Class.
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.
validate_payloadsBooleanFalseFlag indicating if payload contents sent to the API should be validated before being sent.