Authentication

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

As of version 0.6.2, Direct Authentication is the standard method used for authenticating.

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

The legacy Uber class only supports Credential Authentication and Direct Authentication. The newer version (APIHarnessV2) supports Direct Authentication, Credential Authentication, Environment Authentication and Legacy Authentication. The new version of the Uber Class may also be used as an authentication object for Object Authentication but cannot be authenticated in this manner.

Service Class Example (Hosts)

from falconpy import Hosts

falcon = Hosts(client_id=CLIENT_ID,
               client_secret=CLIENT_SECRET
               )

response = falcon.query_devices_by_filter()

Uber Class Example (Hosts)

from falconpy import APIHarnessV2

falcon = APIHarnessV2(client_id=CLIENT_ID,
                      client_secret=CLIENT_SECRET
                      )

response = falcon.command("QueryDevicesByFilter")
print(response)

MSSP Examples (Hosts)

Direct Authentication supports the member_cid keyword for MSSP authentication (v0.8.3+).

Service Class

from falconpy import Hosts

falcon = Hosts(client_id=CLIENT_ID,
               client_secret=CLIENT_SECRET,
               member_cid=CHILD_CID
               )

response = falcon.query_devices_by_filter()
print(response)

Uber Class

from falconpy import APIHarnessV2

falcon = APIHarnessV2(client_id=CLIENT_ID,
                    client_secret=CLIENT_SECRET,
                    member_cid=CHILD_CID
                    )

response = falcon.command("QueryDevicesByFilter")
print(response)

---

Credential Authentication

• Supported in Service Classes and the Uber Class.
• You do not need to call the authenticate() method before making your first request.
• Credential Authentication has precedence and will override authentication values provided when you use Direct Authentication.

Service Class Example (Cloud Connect AWS)

from falconpy import CloudConnectAWS

falcon = CloudConnectAWS(creds={
     "client_id": CLIENT_ID,
     "client_secret": CLIENT_SECRET
})

response = falcon.QueryAWSAccounts()
print(response)

Uber Class Example (Cloud Connect AWS)

from falconpy import APIHarnessV2

falcon = APIHarnessV2(creds={
      "client_id": CLIENT_ID,
      "client_secret": CLIENT_SECRET
   }
)

response = falcon.command('QueryAWSAccounts')
print(response)

MSSP Examples (Cloud Connect AWS)

Service Class

from falconpy import CloudConnectAWS

falcon = CloudConnectAWS(creds={
     "client_id": CLIENT_ID,
     "client_secret": CLIENT_SECRET,
     "member_cid": CHILD_CID
})

response = falcon.query_aws_accounts()
print(response)

Uber Class

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

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.

• Only supported in Service Classes.
• Beginning in v1.3.0, the Uber Class may be used for Object Authentication to authenticate a Service Class.

Example (Cloud Connect AWS and Detects)

from falconpy import OAuth2
from falconpy import CloudConnectAWS
from falconpy import Detects

auth = OAuth2(client_id=CLIENT_ID,
              client_secret=CLIENT_SECRET
              )

falcon_aws = CloudConnectAWS(auth_object=auth)
falcon_detects = Detects(auth_object=auth)

print(falcon_aws.query_aws_accounts())
print(falcon_detects.query_detects())

Example (Real Time Response)

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 from the first class can be reused.

from falconpy import RealTimeResponse, RealTimeResponseAdmin

rtr = RealTimeResponse(client_id=CLIENT_ID,
                       client_secret=CLIENT_SECRET
                       )

rtr_admin = RealTimeResponseAdmin(auth_object=rtr.auth_object)

print(rtr_admin.list_scripts())

Easy Object Authentication

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

hosts = Hosts(client_id=CLIENT_ID,
              client_secret=CLIENT_SECRET
              )

host_group = HostGroup(auth_object=hosts)

print(host_group.query_combined_host_groups())

Example (Uber Class variation)

With the extensibility updates included in v1.3.0, the Uber Class may be used to authenticate Service Classes.

from falconpy import (
     APIHarnessV2,
     Hosts
)

uber = APIHarnessV2(client_id=CLIENT_ID,
                  client_secret=CLIENT_SECRET
                  )

hosts = Hosts(auth_object=uber)

print(hosts.query_devices_by_filter_scroll())

---

Context Authentication

Context Authentication 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 a FalconPy class.

The Context Variable object must contain an attribute or property named access_token. CrowdStrike cloud region may be specified by including an attribute or property named cs_cloud. Cloud Region autodiscovery is not supported when using Context Authentication.

Example (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="")

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)

hosts = Hosts()

request_context.reset(context_token)

assert bool(hosts.query_devices_by_filter_scroll()["status_code"] == 200)

---

Environment Authentication

This mechanism leverages environment variables to store API credentials. Every other authentication mechanism takes precedence over Environment Authentication.

Two environment variables must be present:

Variable Name	Purpose	Data type
FALCON_CLIENT_ID	CrowdStrike Falcon API client ID	string
FALCON_CLIENT_SECRET	CrowdStrike Falcon API client secret	string

Specifying variable names

You can customize which variables are used by providing the environment keyword argument.

{
    "prefix": "FALCON_",
    "id_name": "CLIENT_ID",
    "secret_name": "CLIENT_SECRET"
}

Examples

from falconpy import Hosts

hosts = Hosts()

print(hosts.query_devices_by_filter_scroll())

This functionality is also available to the Uber Class:

from falconpy import APIHarnessV2

uber = APIHarnessV2(client_id=CLIENT_ID)

print(uber.command("QueryDevicesByFilterScroll"))

To change the detected keys to CROWDSTRIKE_CLIENT_ID and CROWDSTRIKE_CLIENT_SECRET:

from falconpy import Hosts

environment = {
    "prefix": "CROWDSTRIKE_"
}

hosts = Hosts(environment=environment)

print(hosts.query_devices_by_filter_scroll())

---

Token (Legacy) Authentication

Prior to version 0.4.0, FalconPy Service Classes authenticated using Legacy Authentication. This method requires the developer to handle authentication using the OAuth2 Service Class.

• Only supported in Service Classes and the latest Uber Class (APIHarnessV2).
• Does not support automatic token refresh.
• Cannot automatically authenticate your first request.

Example (Falcon Intelligence Sandbox)

from falconpy import OAuth2
from falconpy import FalconXSandbox

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)

    response = falcon.QueryReports()
    print(response)

Page Updated: v1.4.2