Authenticating to the API - CrowdStrike/falconpy GitHub Wiki
FalconPy is designed to make authentication and token management easy and supports multiple methods of providing your API credentials.
These examples only focus on authentication. Review Environment Configuration for details regarding other keywords that can be specified during object creation to customize functionality for your environment.
- Direct Authentication
- Credential Authentication
- Object Authentication
- Context Authentication
- Environment Authentication
- Token (Legacy) Authentication
WARNING
client_id
,client_secret
andmember_cid
are keyword arguments that contain your CrowdStrike API credentials and the customer ID of a child tenant. 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.
As of version 0.6.2, Direct Authentication
is the standard method used for authenticating.
- This method is supported in Service Classes and the Uber Class.
- You do not need to call the
authenticate()
method before making your first request. - Your token and your authentication status will not be valid / True until the first request is made.
- You cannot mix Direct Authentication and Credential Authentication. Values provided directly via keywords will be overridden by any
creds
dictionaries provided (regardless if that value is used).
The legacy Uber class only supports
Credential Authentication
andDirect Authentication
. The newer version (APIHarnessV2) supportsDirect Authentication
,Credential Authentication
,Environment Authentication
andLegacy Authentication
. The new version of the Uber Class may also be used as an authentication object forObject Authentication
but cannot be authenticated in this manner.
from falconpy import Hosts
falcon = Hosts(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
# You can use PEP8 or Operation ID syntax for this call
response = falcon.query_devices_by_filter()
from falconpy import APIHarnessV2
falcon = APIHarnessV2(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
response = falcon.command("QueryDevicesByFilter")
print(response)
Starting in version 0.8.3, Direct Authentication supports the member_cid
keyword for MSSP authentication.
from falconpy import Hosts
falcon = Hosts(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
member_cid=CHILD_CID
)
# You can use PEP8 or Operation ID syntax for this call
response = falcon.query_devices_by_filter()
print(response)
from falconpy import APIHarnessV2
falcon = APIHarnessV2(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
member_cid=CHILD_CID
)
response = falcon.command("QueryDevicesByFilter")
print(response)
- This method is supported in Service Classes and the Uber Class.
- You do not need to call the
authenticate()
method before making your first request. - Your token and your authentication status will not be valid / True until the first request is made.
- Credential Authentication has precedence and will override authentication values provided when you use Direct Authentication. This means that if you provide a
creds
dictionary theclient_id
,client_secret
andmember_cid
keyword value s will be overridden by the contents of this dictionary.
The Uber class only supports
Credential Authentication
andDirect Authentication
.
from falconpy import CloudConnectAWS
falcon = CloudConnectAWS(creds={
"client_id": CLIENT_ID,
"client_secret": CLIENT_SECRET
})
# You can use PEP8 or Operation ID syntax for this call
response = falcon.QueryAWSAccounts()
print(response)
from falconpy import APIHarnessV2
falcon = APIHarnessV2(creds={
"client_id": CLIENT_ID,
"client_secret": CLIENT_SECRET
}
)
response = falcon.command('QueryAWSAccounts')
print(response)
MSSP authentication scenarios are also supported using Credential Authentication (v0.2.1+).
from falconpy import CloudConnectAWS
falcon = CloudConnectAWS(creds={
"client_id": CLIENT_ID,
"client_secret": CLIENT_SECRET
"member_cid": CHILD_CID
})
# You can use PEP8 or Operation ID syntax for this call
response = falcon.query_aws_accounts()
print(response)
from falconpy import APIHarnessV2
falcon = APIHarnessV2(creds={
"client_id": CLIENT_ID,
"client_secret": CLIENT_SECRET
"member_cid": CHILD_CID
}
)
response = falcon.command('QueryAWSAccounts')
print(response)
Object Authentication
allows you to authenticate to the API, and then pass the returned authentication object to other Service Classes, allowing developers to easily authenticate to multiple API service collections with the same token.
- Using Object Authentication to authenticate to the CrowdStrike API is only supported in Service Classes.
- Beginning in
v1.3.0
, the Uber Class may be used for Object Authentication to authenticate a Service Class.
from falconpy import OAuth2
from falconpy import CloudConnectAWS
from falconpy import Detects
# You may also use Credential Authentication to
# create the instance of the authentication object
auth = OAuth2(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
# The auth object is then passed when instantiating
# subsequent Service Class objects
falcon_aws = CloudConnectAWS(auth_object=auth)
falcon_detects = Detects(auth_object=auth)
# You can use PEP8 or Operation ID syntax for these calls
print(falcon_aws.query_aws_accounts())
print(falcon_detects.query_detects())
You do not need to create an instance of the OAuth2 object if you are working with more than one Service Class. The authentication object that is created as part of your instantiation of the first class, may be used to authenticate to subsequent classes.
from falconpy import RealTimeResponse, RealTimeResponseAdmin
# We authenticate to our first Service Class like normal
rtr = RealTimeResponse(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
# Now we can just reuse our existing auth_object
rtr_admin = RealTimeResponseAdmin(auth_object=rtr.auth_object)
# And make use of our second class
print(rtr_admin.list_scripts())
Starting in v1.2.2, you no longer need to specify the auth_object
attribute of the Service Class instance you are using to share authentication.
from falconpy import Hosts, HostGroup
# We authenticate to our first Service Class using our preferred method (Direct / Credential)
hosts = Hosts(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
# Then we can pass this newly created object
host_group = HostGroup(auth_object=hosts)
# And make use of our second class
print(host_group.query_combined_host_groups())
With the extensibility updates included as part of v1.3.0, the Uber Class may now be used to authenticate Service Classes.
from falconpy import (
APIHarnessV2,
Hosts
)
# The Uber Class does not have an auth_object attribute,
# so we cannot authenticate it using Object Authentication.
uber = APIHarnessV2(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
# Since the Uber Class is a derivative of the FalconInterface
# object, it can be used to authenticate Service Classes via
# Object Authentication.
hosts = Hosts(auth_object=uber)
print(hosts.query_devices_by_filter_scroll())
Context Authentication is a variation of Token Authentication that leverages a predefined object stored as a Python Context Variable to provide the bearer token and CrowdStrike cloud region used for authorization. This object must exist within the current running context prior to instantiating an instance of a FalconPy class via the constructor. Constructor keyword arguments are supported but not required when constructing an instance of a FalconPy class while using Context Authentication.
The Context Variable object must contain an attribute or property named access_token
in order for Context Authentication to be successful. CrowdStrike cloud region may be specified by including an attribute or property named cs_cloud
. When the cs_cloud
attribute / property is not present, the value of the base_url
constructor keyword argument is used (or the default). Cloud Region autodiscovery is not supported when using Context Authentication.
The following example demonstrates basic Context Authentication using the Hosts Service Class.
from dataclasses import field, dataclass
from falconpy import Hosts
@dataclass
class ContextRequest:
"""A simple structure to hold our context data."""
access_token: str = field(default="")
cs_cloud: str = field(default="")
# The provided Context Variable can have any name.
request_context = ContextVar("request", default=ContextRequest())
req: ContextRequest = request_context.get()
req.access_token = "BEARER TOKEN GOES HERE"
req.cs_cloud = "REGION SHORTNAME OR BASE URL GOES HERE"
context_token = request_context.set(req)
# Construct an instance of the Service Class, all constructor keywords are supported
hosts = Hosts()
# Clear the context for example purposes
request_context.reset(context_token)
# Confirm authentication was successful
assert bool(hosts.query_devices_by_filter_scroll["status_code"] == 200)
This functionality is supported in the Uber Class as well.
from dataclasses import field, dataclass
from falconpy import APIHarnessV2
# ... as shown above
context_token = request_context.set(req)
# Construct an instance of the Uber Class
uber = APIHarnessV2()
# Clear the context for example purposes
request_context.reset(context_token)
# Confirm authentication was successful
assert bool(uber.command("QueryDevicesByFilterScroll")["status_code"] == 200)
This authentication mechanism is a variation of Direct Authentication that leverages environment variables to store the credentials used for authentication. Every other authentication mechanism supported within FalconPy takes precedence over Environment Authentication (this includes the Token (Legacy) Authentication mechanism described below.)
Environment Authentication was released in FalconPy v1.3.0.
There are two environment variables that must be present for Environment Authentication to work, one containing the API client ID, and one containing the API client secret. By default, the following two variable names are used if they are present within the running environment:
Variable Name | Purpose | Data type |
---|---|---|
FALCON_CLIENT_ID |
CrowdStrike Falcon API client ID | string |
FALCON_CLIENT_SECRET |
CrowdStrike Falcon API client secret | string |
You can specify which values are used for environment authentication by providing the environment
keyword argument when you construct an instance of any Service Class or the Uber Class.
This argument is a dictionary and contains three keys with the following default values.
Environment Authentication variable customization was released in FalconPy v1.4.2.
{
"prefix": "FALCON_",
"id_name": "CLIENT_ID",
"secret_name": "CLIENT_SECRET"
}
Any or all of these values may be overridden.
Both variables specified must be defined in the enviroment before Environment Authentication will be attempted. If both environment variables are present, and only one of these values exists within the
creds
dictionary, then the missing value will be replaced with the value stored within the environment.
Environment Authentication allows developers to authenticate to the CrowdStrike API using credentials they defined in their environment.
from falconpy import Hosts
# Both environment variables, FALCON_CLIENT_ID and FALCON_CLIENT_SECRET
# must be present in the running environment if we do not want to
# provide credentials when we create the instance of the class.
hosts = Hosts()
print(hosts.query_devices_by_filter_scroll())
This functionality is also available to the Uber Class, and can be used to provide only one value if necessary.
from falconpy import APIHarnessV2
# If only one of the required authentication keywords is provided
# and both environment variables are present, the missing value
# is retrieved from the environment.
uber = APIHarnessV2(client_id=CLIENT_ID)
print(uber.command("QueryDevicesByFilterScroll"))
To change which values are used, provide the environment
keyword. This example changes the detected keys to CROWDSTRIKE_CLIENT_ID
and CROWDSTRIKE_CLIENT_SECRET
.
from falconpy import Hosts
# Create a dictionary that specifies a new prefix.
environment = {
"prefix": "CROWDSTRIKE_"
}
# Provide this dictionary to the constructor argument.
hosts = Hosts(environment=environment)
print(hosts.query_devices_by_filter_scroll())
This example changes the keys to be API_CLIENT_ID
and API_CLIENT_SECRET
. Instead of using a prefix, we specify the key and secret variable names directly and tell the constructor to ignore prefix altogether.
from falconpy import APIHarnessV2
# Note we provide an empty string for prefix in this example.
# If you do not specify it, it will default to "FALCON_"
# and search for an incorrectly named variable.
environment = {
"prefix": "",
"id_name": "API_CLIENT_ID",
"secret_name": "API_CLIENT_SECRET"
}
# Provide the dictionary to the constructor keyword like our previous example.
uber = APIHarnessV2(environment=environment)
print(uber.command("QueryDevicesByFilterScroll"))
Prior to version 0.4.0, FalconPy Service Classes authenticated using Legacy Authentication
.
This method authenticates by providing the token directly to the Service Class and requires the developer to handle authentication using the OAuth2 Service Class.
- Legacy Authentication is only supported in Service Classes and the latest version of the Uber Class (APIHarnessV2).
- This method of authentication does not support automatic token refresh.
- This method of authentication cannot automatically authenticate your first request.
- Developers can authenticate to multiple classes using the same token utilizing this method.
from falconpy import OAuth2
from falconpy import FalconXSandbox
# You may also use Credential Authentication to
# create the instance of the authentication object
auth = OAuth2(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
try:
token = auth.token()['body']['access_token']
except:
token = False
if token:
falcon = FalconXSandbox(access_token=token)
# You can use PEP8 or Operation ID syntax for this call
response = falcon.QueryReports()
print(response)