Basic Service Class usage

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 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 name	Data type	Default Value	Description
auth_object	OAuth2 Class	None	An instance of the OAuth2 authentication object.
base_url	String	https://api.crowdstrike.com	The URL to use for all requests performed.
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.
refreshable	Boolean	False	Flag indicating if the token within this Service Class can support automatic refresh.
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 authentication token generated when instantiating this Service Class.
token_fail_reason	String	None	String 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_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 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_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.
validate_payloads	Boolean	False	Flag indicating if payload contents sent to the API should be validated before being sent.