Basic Service Class usage

Using Service Classes

• Import and Authentication
• Performing a request
• API responses

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

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

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

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. Direct Authentication or Credential Authentication may be used to authenticate to the OAuth2 Service Class.

Object Authentication using keywords

from falconpy import OAuth2
from falconpy import CloudConnectAWS

auth = OAuth2(client_id="CLIENT_ID_HERE",
              client_secret="CLIENT_SECRET_HERE"
              )

falcon = CloudConnectAWS(auth_object=auth)

Object Authentication using a credential dictionary

from falconpy import OAuth2
from falconpy import CloudConnectAWS

auth = OAuth2(creds={
        "client_id": "CLIENT_ID_HERE",
        "client_secret": "CLIENT_SECRET_HERE"
    })

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.

from falconpy import OAuth2
from falconpy import CloudConnectAWS

authorization = OAuth2(creds={
        "client_id": "CLIENT_ID_HERE",
        "client_secret": "CLIENT_SECRET_HERE"
    })

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

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

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

# 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 Service Collection pages 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."
                    }
                }
            }
        ]
    }
}