Authenticating to the API

Authenticating to the API

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
• Legacy Authentication

The Uber class only supports Credential Authentication and Direct Authentication.

Direct Authentication

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

Service Class Example (Hosts)

from falconpy import Hosts

falcon = Hosts(client_id="CLIENT_ID_HERE",
               client_secret="CLIENT_SECRET_HERE"
               )

# You can use PEP8 or Operation ID syntax for this call
response = falcon.query_devices_by_filter()

Uber Class Example (Hosts)

from falconpy import APIHarness

falcon = APIHarness(client_id="CLIENT_ID_HERE",
                    client_secret="CLIENT_SECRET_HERE"
                    )

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

MSSP Examples (Hosts)

Starting in version 0.8.3, Direct Authentication supports the member_cid keyword for MSSP authentication.

Service Class

from falconpy import Hosts

falcon = Hosts(client_id="CLIENT_ID_HERE",
               client_secret="CLIENT_SECRET_HERE",
               member_cid="CHILD_CID_HERE"
               )

# You can use PEP8 or Operation ID syntax for this call
response = falcon.query_devices_by_filter()
print(response)

Uber Class

from falconpy import APIHarness

falcon = APIHarness(client_id="CLIENT_ID_HERE",
                    client_secret="CLIENT_SECRET_HERE",
                    member_cid="CHILD_CID_HERE"
                    )

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

Credential Authentication

• 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 the client_id, client_secret and member_cid keyword value s will be overridden by the contents of this dictionary.

Service Class Example (Cloud Connect AWS)

from falconpy import CloudConnectAWS

falcon = CloudConnectAWS(creds={
     "client_id": "CLIENT_ID_HERE",
     "client_secret": "CLIENT_SECRET_HERE"
})

# You can use PEP8 or Operation ID syntax for this call
response = falcon.QueryAWSAccounts()
print(response)

Uber Class Example (Cloud Connect AWS)

from falconpy import APIHarness

falcon = APIHarness(creds={
      "client_id": "CLIENT_ID_HERE",
      "client_secret": "CLIENT_SECRET_HERE"
   }
)

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

MSSP Examples (Cloud Connect AWS)

MSSP authentication scenarios are also supported using Credential Authentication (v0.2.1+).

Service Class

from falconpy import CloudConnectAWS

falcon = CloudConnectAWS(creds={
     "client_id": "CLIENT_ID_HERE",
     "client_secret": "CLIENT_SECRET_HERE",
     "member_cid": "CHILD_CID_HERE"
})

# You can use PEP8 or Operation ID syntax for this call
response = falcon.query_aws_accounts()
print(response)

Uber Class

from falconpy import APIHarness

falcon = APIHarness(creds={
      "client_id": "CLIENT_ID_HERE",
      "client_secret": "CLIENT_SECRET_HERE",
      "member_cid": "CHILD_CID_HERE"
   }
)

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.

• Object Authentication is only supported in Service Classes.

Example (Cloud Connect AWS and Detects)

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

# 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())

Example (Real Time Response and Real Time Response Admin)

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

Legacy Authentication

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.
• 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 Service Classes using the same token utilizing this method.

Example (FalconX Sandbox)

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

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)