Environment Configuration - CrowdStrike/falconpy GitHub Wiki
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. |
Simple examples of these keywords being used to configure an environment.
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.
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.
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 | |
USGOV2 | https://api.us-gov-2.crowdstrike.mil |
You may provide your base URL with or without the
https://
protocol specification.
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)
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)
For scenarios where you wish to route API request traffic through a proxy, or list of proxies, the proxy
keyword may be utilized.
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)
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.
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.
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)
from falconpy import APIHarnessV2
falcon = APIHarnessV2(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET,
ssl_verify=False
)
result = falcon.command("QueryDevicesByFilterScroll")
print(result)
from falconpy import Hosts
falcon = Hosts(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET,
ssl_verify="/path/to/CA_BUNDLE"
)
from falconpy import APIHarnessV2
falcon = APIHarnessV2(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET,
ssl_verify="/path/to/CA_BUNDLE"
)
The timeout
keyword can be used to specify timeouts for connect and read, or the entire operation.
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)
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)
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.
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)
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)
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.
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)
from falconpy import APIHarnessV2
falcon = APIHarnessV2(client_id=CLIENT_ID, client_secret=CLIENT_SECRET, renew_window=300)
result = falcon.command("QueryDevicesByFilterScroll")
print(result)
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 thecommand
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)
Payload validation may be activated using the validate_payloads
keyword.
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)
from falconpy import APIHarnessV2
falcon = APIHarnessV2(client_id=CLIENT_ID, client_secret=CLIENT_SECRET, validate_payloads=True)
result = falcon.command("QueryDevicesByFilterScroll")
print(result)
Debug logging can be enabled using the debug
keyword.
Debug logs are not generate if this keyword is not set to
True
.
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()
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")
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.
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)
from falconpy import APIHarnessV2
falcon = APIHarnessV2(client_id=CLIENT_ID, client_secret=CLIENT_SECRET, debug_record_count=500)
result = falcon.command("QueryDevicesByFilterScroll")
print(result)
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⚠️ This may result in sensitive data being written to debug log files or your console.
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)
from falconpy import APIHarnessV2
falcon = APIHarnessV2(client_id=CLIENT_ID, client_secret=CLIENT_SECRET, sanitize_log=False)
result = falcon.command("QueryDevicesByFilterScroll")
print(result)
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.
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)
from falconpy import APIHarnessV2
falcon = APIHarnessV2(client_id=CLIENT_ID, client_secret=CLIENT_SECRET, pythonic=True)
result = falcon.command("QueryDevicesByFilterScroll")
print(result)