Environment Configuration

Documentation Version

The following keywords can be provided to Service Classes and the Uber Class during instantiation to customize behavior to meet your specific environment requirements.

These keywords may be mixed in any order or combination when creating an instance of the class. You will still need to provide authentication details based upon your selected authentication method. For most scenarios, none of the keywords listed below are required in order to create an instance of a class.

Name	Data type	Description
`base_url`	String	The CrowdStrike base address target for API operations performed using this class. Defaults to *https://api.crowdstrike.com*.
`debug`	Boolean	Flag indicating that debug log records should be created.
`debug_record_count`	Integer	Maximum number of records to write to debug logs per API operation performed.
`ext_headers`	String	Extended headers that are prepended to the default headers dictionary for the newly created Service Class. Service Classes only
`proxy`	Dictionary	A dictionary containing a list of proxy servers to utilize for making requests to the CrowdStrike API.
`pythonic`	Boolean	Flag indicating that API responses received using this class should be delivered as Python Objects as opposed to JSON dictionaries.
`renew_window`	Integer	Amount of buffer time allotted before token expiration where a token is refreshed automatically. Minimum: 120 seconds Maximum: 1,200 seconds Default: 120
`sanitize_log`	Boolean	Flag indicating if `Log Sanitization` should be enabled.
`ssl_verify`	Boolean or String	Boolean flag used to specify SSL verification configuration, or a string representing the path to a CA_BUNDLE file or directory with certificates of trusted CAs. When set to False, API requests will accept any TLS certificate presented, and will ignore hostname mismatches and/or expired certificates. Defaults to True
`timeout`	Float or Tuple	Connect / Read or Total timeout for requests made to the CrowdStrike API.
`user_agent`	String	Custom User-Agent string to use for requests to the API. Recommended format: `vendor-productname/version`.
`validate_payloads`	Boolean	Flag indicating that payloads should be validated before the API request is performed.

Usage examples

Simple examples of these keywords being used to configure an environment.

WARNING

client_id and client_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.

The base_url keyword allows you to point your requests to the CrowdStrike cloud where your environment resides. You may specify your base URL by using the address or the short name. Short names are not case-sensitive.

When not provided, the base_url keyword defaults to https://api.crowdstrike.com (US1) when creating an instance of any class using v0.8.5 or below.

Cloud region autodiscovery

Starting in v0.8.6, developers using the US1, US2 or EU1 regions no longer need to specify their base_url as this value is auto-discovered as part of the authentication process.

Please note: USGOV1 users will still need to provide this value.

Short name	Base URL	Auto discovery support?
US1	https://api.crowdstrike.com
US2	https://api.us-2.crowdstrike.com
EU1	https://api.eu-1.crowdstrike.com
USGOV1	https://api.laggar.gcw.crowdstrike.com

You may provide your base URL with or without the https:// protocol specification.

Service Class examples

Specifying EU1 using the full Base URL.

from falconpy import Recon

falcon = Recon(client_id=CLIENT_ID,
               client_secret=CLIENT_SECRET,
               base_url="https://api.eu-1.crowdstrike.com"
               )

response = falcon.query_rules(limit=100, q="search-string")
print(response)

Specifying US2 using the short name.

from falconpy import Recon

falcon = Recon(client_id=CLIENT_ID,
               client_secret=CLIENT_SECRET,
               base_url="us2"
               )

response = falcon.query_rules(limit=100, q="search-string")
print(response)

Uber Class examples

Specifying EU1 using the full Base URL.

from falconpy import APIHarnessV2

falcon = APIHarnessV2(client_id=CLIENT_ID,
                    client_secret=CLIENT_SECRET,
                    base_url="https://api.eu-1.crowdstrike.com"
                    )
PARAMS = {
    "limit": 100,
    "q": "search-string"
}

result = falcon.command("QueryRulesV1", parameters=PARAMS)
print(result)

Specifying US2 using the short name.

from falconpy import APIHarnessV2

falcon = APIHarnessV2(client_id=CLIENT_ID, client_secret=CLIENT_SECRET, base_url="us2")

# This example also demonstrates Parameter Abstraction within the Uber Class (v0.8.0+)
result = falcon.command("QueryRulesV1", limit=100, q="search-string")
print(result)

Proxy

For scenarios where you wish to route API request traffic through a proxy, or list of proxies, the proxy keyword may be utilized.

Service Class example

from falconpy import Detects

# Create a dictionary to hold our proxies. 
# There should be at least one http or https key,
# but there should not be two of the same key.
proxies = {
    "http": "http://myproxy:8888",
    "https": "https://myotherproxy:8080"
}

falcon = Detects(client_id=CLIENT_ID, client_secret=CLIENT_SECRET, proxy=proxies)

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

Uber Class example

from falconpy import APIHarnessV2

# Create a dictionary to hold our proxies. 
# There should be at least one http or https key,
# but there should not be two of the same key.
proxies = {
    "http": "http://myproxy:8888",
    "https": "https://myotherproxy:8080"
}

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

result = falcon.command("QueryDetects")
print(result)

Proxies requiring username / password credentials should be provided in https://PROXY_USER:PROXY_PASSWORD@PROXY HOST:PROXY_PORT format.

SSL Verify

For environments where SSL verification cannot be performed at the application layer, you may disable SSL verification when creating your instance of the class using the ssl_verify keyword.

When not specifically disabled, SSL Verification defaults to True when creating an instance of any class.

Service Class example

from falconpy import Hosts

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

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

Uber Class example

from falconpy import APIHarnessV2

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

result = falcon.command("QueryDevicesByFilterScroll")
print(result)

Setting the path to a CA_BUNDLE file

Service Class example

from falconpy import Hosts

falcon = Hosts(client_id=CLIENT_ID,
               client_secret=CLIENT_SECRET,
               ssl_verify="/path/to/CA_BUNDLE"
               )

Uber Class example

from falconpy import APIHarnessV2

falcon = APIHarnessV2(client_id=CLIENT_ID,
                    client_secret=CLIENT_SECRET,
                    ssl_verify="/path/to/CA_BUNDLE"
                    )

Timeout

The timeout keyword can be used to specify timeouts for connect and read, or the entire operation.

Service Class examples

Specifying a global timeout for the entire operation.

# Times out after thirty seconds for the entire operation
from falconpy import Hosts

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

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

Specifying individual timeouts for connect and read operations.

# Times out after 3 seconds for connect and 27 seconds for read
from falconpy import Hosts

falcon = Hosts(client_id=CLIENT_ID, client_secret=CLIENT_SECRET, timeout=(3.05,26.95))

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

Uber Class examples

Specifying a global timeout for the entire operation.

# Times out after thirty seconds for the entire operation
from falconpy import APIHarnessV2

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

result = falcon.command("QueryHiddenDevices")
print(result)

Specifying individual timeouts for connect and read operations.

# Times out after 3 seconds for connect and 27 seconds for read
from falconpy import APIHarnessV2

falcon = APIHarnessV2(client_id=CLIENT_ID,
                    client_secret=CLIENT_SECRET,
                    timeout=(3.05,26.95)
                    )

result = falcon.command("QueryHiddenDevices")
print(result)

User-Agent

Using the user_agent keyword, a custom string may be specified for the User-Agent HTTP request header. This allows developers to properly identify their integrations as per CrowdStrike documented best practice.

Service Class example

from falconpy import Hosts

falcon = Hosts(client_id=CLIENT_ID,
               client_secret=CLIENT_SECRET,
               user_agent="company-productname/1.0"
               )

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

Uber Class example

from falconpy import APIHarnessV2

falcon = APIHarnessV2(client_id=CLIENT_ID,
                    client_secret=CLIENT_SECRET,
                    user_agent="company-productname/1.0"
                    )

result = falcon.command("QueryDevicesByFilterScroll")
print(result)

Renew Window

The token renewal window is designed to allow developers to specify the amount of time to use for a buffer between token expiration and automatic token renewal. This value is represented by an integer and expressed in seconds. The minimum allowed value is 120 and the maximum allowed value is 1200 with 120 being the default.

Service Class example

from falconpy import Hosts

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

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

Uber Class example

from falconpy import APIHarnessV2

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

result = falcon.command("QueryDevicesByFilterScroll")
print(result)

Extended Headers

You can provided additional headers that will be included in all requests made to the API by providing the ext_headers keyword. Values should be provided to the Service Class constructor as a dictionary.

This keyword is not supported in the Uber Class as the Uber Class already supports providing custom headers using the headers keyword within the command method.

from falconpy import Hosts

falcon = Hosts(client_id=CLIENT_ID,
               client_secret=CLIENT_SECRET,
               ext_headers={"X-SOME-HEADER", "Value"}
               )

result = falcon.query_devices_by_filter_scroll()
print(result)

Validating payloads

Payload validation may be activated using the validate_payloads keyword.

Service Class example

from falconpy import Hosts

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

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

Uber Class example

from falconpy import APIHarnessV2

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

result = falcon.command("QueryDevicesByFilterScroll")
print(result)

Enabling debugging

Debug logging can be enabled using the debug keyword.

Debug logs are not generate if this keyword is not set to True.

Service Class example

import logging
from falconpy import Hosts

log = logging.basicConfig(level=logging.DEBUG)
falcon = Hosts(client_id=CLIENT_ID, client_secret=CLIENT_SECRET, debug=True)

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

Uber Class example

import logging
from falconpy import APIHarnessV2

log = logging.basicConfig(level=logging.DEBUG)
falcon = APIHarnessV2(client_id=CLIENT_ID, client_secret=CLIENT_SECRET, debug=True)

result = falcon.command("QueryDevicesByFilterScroll")

Setting the debug record count

By default, the maximum number of records written to debug logs per API operation performed is 100.

This value may be adjusted from 1 up to the global API maximum return record count (5,000) using the debug_record_count keyword.

Service Class example

from falconpy import Hosts

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

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

Uber Class example

from falconpy import APIHarnessV2

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

result = falcon.command("QueryDevicesByFilterScroll")
print(result)

Disabling log sanitization

By default, FalconPy sanitizes bearer tokens, client_id, client_secret and member_cid from all logs that are written.

This functionality can be disabled by providing a False to the sanitize_log keyword.

:warning: WARNING :warning:

This may result in sensitive data being written to debug log files or your console.

Service Class example

from falconpy import Hosts

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

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

Uber Class example

from falconpy import APIHarnessV2

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

result = falcon.command("QueryDevicesByFilterScroll")
print(result)

Enabling pythonic responses

FalconPy returns API responses in the format they are received by default. This functionality may be altered to inform the SDK to instead return results as Python objects using the pythonic keyword.

Service Class example

from falconpy import Hosts

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

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

Uber Class example

from falconpy import APIHarnessV2

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

result = falcon.command("QueryDevicesByFilterScroll")
print(result)

The CrowdStrike Falcon Wiki for Python