Using Service Classes
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
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 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. |