Caracara

A friendly wrapper to help you interact with the CrowdStrike Falcon API. Less code, less fuss, better performance, and full interoperability with FalconPy.

• Caracara
  • Features
  • Installation Instructions
    • Poetry: Installation
    • Poetry: Upgrading
    • Poetry: Removal
    • Pip: Installation
    • Pip: Upgrading
    • Pip: Removal
  • Basic Usage Examples
  • Examples Collection
    • Executing the Examples
  • Documentation
  • Contributing
  • Why Caracara?

Features

A few of the developer experience enhancements provided by the Caracara toolkit include:

Installation Instructions

Caracara supports all major Python packaging solutions. Instructions for Poetry and Pip are provided below.

Caracara supports Python versions that are still supported by the Python Software Foundation, i.e., Python 3.10 and up.

poetry add caracara

poetry update caracara

poetry remove caracara

python3 -m pip install caracara

python3 -m pip install caracara --upgrade

python3 -m pip uninstall caracara

Basic Usage Examples

"""List Windows devices.

This example will use the API credentials provided as keywords to list the
IDs and hostnames of all systems within your Falcon tenant that run Windows.
"""

from caracara import Client

client = Client(
    client_id="12345abcde",
    client_secret="67890fghij",
)

filters = client.FalconFilter()
filters.create_new_filter("OS", "Windows")

response_data = client.hosts.describe_devices(filters)
print(f"Found {len(response_data)} devices running Windows")

for device_id, device_data in response_data.items():
    hostname = device_data.get("hostname", "Unknown Hostname")
    print(f"{device_id} - {hostname}")

You can also leverage the built in context manager and environment variables.

"""List stale sensors.

This example will use the API credentials set in the environment to list the
hostnames and IDs of all systems within your Falcon tenant that have not checked
into your CrowdStrike tenant within the past 7 days.

This is determined based on the filter LastSeen less than or equal (LTE) to 7 days ago (-7d).
"""

from caracara import Client


with Client(client_id="${CLIENT_ID_ENV_VARIABLE}", client_secret="${CLIENT_SECRET_ENV_VARIABLE}") as client:
    filters = client.FalconFilter()
    filters.create_new_filter("LastSeen", "-7d", "LTE")
    response_data = client.hosts.describe_devices(filters)

print(f"Found {len(response_data)} stale devices")

for device_id, device_data in response_data.items():
    hostname = device_data.get("hostname", "Unknown Hostname")
    print(f"{device_id} - {hostname}")

Examples Collection

Each API wrapper is provided alongside example code. Cloning or downloading/extracting this repository allows you to execute examples directly.

Using the examples collection requires that you install our Python packaging tool of choice, Poetry. Please refer to the Poetry project's installation guide if you do not yet have Poetry installed.

Once Poetry is installed, make sure you run poetry install within the root repository folder to set up the Python virtual environment.

To configure the examples, first copy examples/config.example.yml to examples/config.yml. Then, add your API credentials and example-specific settings to examples/config.yml. Once you have set up profiles for each Falcon tenant you want to test with, execute examples using one of the two options below.

Executing the Examples

There are two ways to use Poetry to execute the examples.

poetry shell
examples/get_devices/list_windows_devices.py

poetry run examples/get_devices/list_windows_devices.py

poetry run stale-sensors

Documentation

Coming soon!

Contributing

Interested in taking part in the development of the Caracara project? Start here.

Why Caracara?

Simple! We like birds at CrowdStrike, so what better bird to name a Python project after one that eats just about anything, including snakes :)