Package: caracara
CaracaraA friendly wrapper to help you interact with the CrowdStrike Falcon API. Less code, less fuss, better performance, and full interoperability withFalconPy.FeaturesInstallationBasic UsageExamplesDocumentationContributingFeaturesA few of the developer experience enhancements provided by the Caracara toolkit include:FeatureDetailsAutomatic pagination with concurrencyCaracara will handle all request pagination for you, so you do not have to think about things like batch sizes, batch tokens or parallelisation. Caracara will also multithread batch data retrieval requests where possible, dramatically reducing data retrieval times for large datasets such as host lists.Friendly to your IDE (and you!)Caracara is written with full support for IDE autocomplete in mind. We have tested autocomplete in Visual Studio Code and PyCharm, and will accept issues and patches for more IDE support where needed. Furthermore, all code, where possible, is written with type hints so you can be confident in parameters and return values.LoggingCaracara is built with the in-boxlogginglibrary provided with Python 3. Simply set up your logging handlers in your main code file, and Caracara will forward overdebug,infoanderrorlogs as they are produced. Note that thedebuglogs are very verbose, and we recommend writing these outputs to a file as opposed to the console when retrieving large amounts of lightly filtered data.Real Time Response (RTR) batch session abstractionCaracara provides a rich interface to RTR session batching, allowing you to connect to as many hosts as possible. Want to download a specific file from every system in your Falcon tenant? Caracara will even extract it from the.7zcontainer for you.Rich and detailed sample codeEvery module of Caracara comes bundled with executable, fully configurable code samples that address frequent use cases. All samples are built around a common structure allowing for code reuse and easy reading. Just add your API credentials toconfig.yml, and all samples will be ready to go.Simple filter syntaxCaracara provides an object-orientated Falcon Query Language (FQL) generator. TheFalconFilterobject lets you specify filters such asHostname,OSandRole, automatically converting them to valid FQL. Never write a FQL filter yourself again!Single authentication point of entryAuthenticate once and have access to every module.100% FalconPy compatibilityCaracara is built on FalconPy, and can even be configured with a FalconPyOAuth2object via theauth_objectconstructor parameter, allowing you to reuse FalconPy authentication objects across Caracara and FalconPy. Authenticate once with FalconPy, and access every feature of FalconPy and Caracara.Installation InstructionsCaracara supports all major Python packaging solutions. Instructions forPoetryandPipare provided below.Installing Caracara from PyPI using Poetry (Recommended!)Poetry: InstallationpoetryaddcaracaraPoetry: UpgradingpoetryupdatecaracaraPoetry: RemovalpoetryremovecaracaraInstalling Caracara from PyPI using PipPip: Installationpython3-mpipinstallcaracaraPip: Upgradingpython3-mpipinstallcaracara--upgradePip: Removalpython3-mpipuninstallcaracaraBasic Usage Examples"""List Windows devices.This example will use the API credentials provided as keywords to list theIDs and hostnames of all systems within your Falcon tenant that run Windows."""fromcaracaraimportClientclient=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")fordevice_id,device_datainresponse_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 thehostnames and IDs of all systems within your Falcon tenant that have not checkedinto 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)."""fromcaracaraimportClientwithClient(client_id="${CLIENT_ID_ENV_VARIABLE}",client_secret="${CLIENT_SECRET_ENV_VARIABLE}")asclient: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")fordevice_id,device_datainresponse_data.items():hostname=device_data.get("hostname","Unknown Hostname")print(f"{device_id}-{hostname}")Examples CollectionEach 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'sinstallation guideif you do not yet have Poetry installed.Once Poetry is installed, make sure you runpoetry installwithin the root repository folder to set up the Python virtual environment.To configure the examples, first copyexamples/config.example.ymltoexamples/config.yml. Then, add your API credentials and example-specific settings toexamples/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 ExamplesThere are two ways to use Poetry to execute the examples.Executing from a Poetry ShellThepoetry shellcommand will enter you into the virtual environment. All future commands will run within the Caracara virtual environment using Python 3, until you run thedeactivatecommand.poetryshell
examples/get_devices/list_windows_devices.pyExecuting without Activating the Virtual EnvironmentIf you do not want to enter the Caracara virtual environment (e.g., because you are using your system's installation of Python for other purposes), you can use thepoetry runcommand to temporarily invoke the virtual environment for one-off commands.poetryrunexamples/get_devices/list_windows_devices.pyAll examples are also configured in thepyproject.tomlfile as scripts, allowing them to be executed simply.poetryrunstale-sensorsTo get a complete list of available examples, execute the commandutil/list-examples.shfrom the root of the repository folder.DocumentationComing soon!ContributingInterested in taking part in the development of the Caracara project? Starthere.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 :)