Using Service Classes

• Import and Authentication
• Performing a request
• API responses
• Service Class Attributes

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.

• Direct Authentication
• Credential Authentication
• Object Authentcation
• Legacy Authentication

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