CrowdStrike FalconPy SDK

Warnings

• breaking Python 3.7 support was dropped in FalconPy v1.6.0. Projects using Python 3.7 or older will fail to install or run this version.
  Fix: Upgrade your Python environment to version 3.8 or newer before upgrading to FalconPy v1.6.0+.
• deprecated Specific API operations are periodically deprecated or replaced. For example, `combinedUserRolesV1` was deprecated in v1.5.1 in favor of `CombinedUserRolesV2`.
  Fix: Always refer to the official CrowdStrike API documentation for the latest operation names and best practices. Monitor release notes for deprecated operations and update your code accordingly.
• gotcha The `base_url` parameter must be set correctly for your CrowdStrike cloud region (e.g., api.us-1.crowdstrike.com, api.eu-1.crowdstrike.com). The default is `https://api.crowdstrike.com` (US-1).
  Fix: Explicitly pass the `base_url` argument to your `APIHarness` or service class initializer, e.g., `APIHarness(..., base_url='https://api.eu-1.crowdstrike.com')`.
• gotcha API responses should always be checked for `status_code` and the presence of an `errors` key in the response body. A successful HTTP status code (e.g., 200) does not always guarantee the absence of application-level errors.
  Fix: After any API call, inspect `response['status_code']` and `response.get('body', {}).get('errors')` to ensure both HTTP and application-level success.
• gotcha Service collection names and their associated operations can change over time. For example, 'Compliance Assessments' was renamed to 'Container Image Compliance' in v1.4.9.
  Fix: Consult the `falconpy` release notes and the CrowdStrike API documentation when upgrading to ensure you are using the correct service class and operation names for your version.

Install

• pip install crowdstrike-falconpy Install latest version

Imports

• APIHarness

  from falconpy import APIHarness

  The primary API client is directly exposed under the top-level 'falconpy' package, not within submodules like 'api_harness'.
• HostGroup

  from falconpy import HostGroup

  Service classes like 'HostGroup' are also directly exposed at the top-level package.

Quickstart

This quickstart demonstrates how to initialize the FalconPy APIHarness client using environment variables for authentication and retrieve the CrowdStrike Customer ID (CID). It highlights the recommended practice of externalizing credentials and includes basic error handling for API responses.

import os
from falconpy import APIHarness

# Retrieve credentials from environment variables
client_id = os.environ.get('FALCON_CLIENT_ID', '')
client_secret = os.environ.get('FALCON_CLIENT_SECRET', '')
base_url = os.environ.get('FALCON_BASE_URL', 'https://api.crowdstrike.com')

if not client_id or not client_secret:
    print("Please set FALCON_CLIENT_ID and FALCON_CLIENT_SECRET environment variables.")
else:
    try:
        # Initialize the APIHarness client
        falcon = APIHarness(client_id=client_id, 
                            client_secret=client_secret, 
                            base_url=base_url)
        
        # Example: Get the Customer ID (CID)
        response = falcon.get_cid()
        
        if response['status_code'] == 200:
            print(f"Successfully connected. Customer ID: {response['body']['cid']}")
        else:
            print(f"Error getting CID: {response['status_code']} - {response.get('body', {}).get('errors', 'Unknown error')}")
            
    except Exception as e:
        print(f"An unexpected error occurred: {e}")