{"id":28409949,"url":"https://github.com/crowdstrike/caracara","last_synced_at":"2025-12-14T16:03:33.575Z","repository":{"id":37795210,"uuid":"405512808","full_name":"CrowdStrike/caracara","owner":"CrowdStrike","description":"Developer enhancements (DX) for FalconPy, the CrowdStrike Python SDK","archived":false,"fork":false,"pushed_at":"2025-11-18T22:57:24.000Z","size":1282,"stargazers_count":43,"open_issues_count":16,"forks_count":13,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-11-19T00:23:33.879Z","etag":null,"topics":["api","caracara","crowdstrike","crowdstrike-apis","crowdstrike-falconpy","devsecops","falcon","falconpy","falconpy-tools","python","python3","python310","python37","python38","python39","toolbox","toolkit"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CrowdStrike.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2021-09-12T00:38:34.000Z","updated_at":"2025-11-16T17:29:48.000Z","dependencies_parsed_at":"2023-07-14T05:12:37.064Z","dependency_job_id":"e0f8178c-29b0-4d3a-b275-53d83a248468","html_url":"https://github.com/CrowdStrike/caracara","commit_stats":{"total_commits":225,"total_committers":6,"mean_commits":37.5,"dds":0.4,"last_synced_commit":"0dd2bd265889e1421346f4a8ac58df73642c21c9"},"previous_names":["crowdstrike/falconpy-tools"],"tags_count":29,"template":false,"template_full_name":null,"purl":"pkg:github/CrowdStrike/caracara","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CrowdStrike%2Fcaracara","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CrowdStrike%2Fcaracara/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CrowdStrike%2Fcaracara/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CrowdStrike%2Fcaracara/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CrowdStrike","download_url":"https://codeload.github.com/CrowdStrike/caracara/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CrowdStrike%2Fcaracara/sbom","scorecard":{"id":34089,"data":{"date":"2025-08-11","repo":{"name":"github.com/CrowdStrike/caracara","commit":"a216c12fd0b9cdd8b7a4bdf72f83f5ce59df3258"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":5.2,"checks":[{"name":"Code-Review","score":6,"reason":"Found 11/18 approved changesets -- score normalized to 6","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Security-Policy","score":10,"reason":"security policy file detected","details":["Info: security policy file detected: SECURITY.md:1","Info: Found linked content: SECURITY.md:1","Info: Found disclosure, vulnerability, and/or timelines in security policy: SECURITY.md:1","Info: Found text in security policy: SECURITY.md:1"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: no topLevel permission defined: .github/workflows/code-quality.yml:1","Warn: no topLevel permission defined: .github/workflows/codeql.yml:1","Warn: no topLevel permission defined: .github/workflows/release-deploy.yml:1","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/code-quality.yml:21: update your workflow using https://app.stepsecurity.io/secureworkflow/CrowdStrike/caracara/code-quality.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/code-quality.yml:26: update your workflow using https://app.stepsecurity.io/secureworkflow/CrowdStrike/caracara/code-quality.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codeql.yml:38: update your workflow using https://app.stepsecurity.io/secureworkflow/CrowdStrike/caracara/codeql.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codeql.yml:42: update your workflow using https://app.stepsecurity.io/secureworkflow/CrowdStrike/caracara/codeql.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codeql.yml:49: update your workflow using https://app.stepsecurity.io/secureworkflow/CrowdStrike/caracara/codeql.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codeql.yml:63: update your workflow using https://app.stepsecurity.io/secureworkflow/CrowdStrike/caracara/codeql.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/release-deploy.yml:14: update your workflow using https://app.stepsecurity.io/secureworkflow/CrowdStrike/caracara/release-deploy.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/release-deploy.yml:16: update your workflow using https://app.stepsecurity.io/secureworkflow/CrowdStrike/caracara/release-deploy.yml/main?enable=pin","Warn: pipCommand not pinned by hash: util/install-dependencies.sh:5","Warn: pipCommand not pinned by hash: util/install-dependencies.sh:9","Warn: pipCommand not pinned by hash: .github/workflows/release-deploy.yml:21","Warn: pipCommand not pinned by hash: .github/workflows/release-deploy.yml:22","Info:   0 out of   8 GitHub-owned GitHubAction dependencies pinned","Info:   0 out of   4 pipCommand dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: MIT License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Branch-Protection","score":-1,"reason":"internal error: error during branchesHandler.setup: internal error: githubv4.Query: Resource not accessible by integration","details":null,"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Vulnerabilities","score":6,"reason":"4 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: GHSA-9hjg-9r4m-mvj7","Warn: Project is vulnerable to: PYSEC-2025-49 / GHSA-5rjg-fvgr-3xxf","Warn: Project is vulnerable to: GHSA-48p4-8xcf-vxj5","Warn: Project is vulnerable to: GHSA-pq67-6m6q-mj2v"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}},{"name":"SAST","score":8,"reason":"SAST tool detected but not run on all commits","details":["Info: SAST configuration detected: CodeQL","Warn: 13 commits out of 30 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}}]},"last_synced_at":"2025-08-14T19:53:34.091Z","repository_id":37795210,"created_at":"2025-08-14T19:53:34.092Z","updated_at":"2025-08-14T19:53:34.092Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":27730950,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-14T02:00:11.348Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","caracara","crowdstrike","crowdstrike-apis","crowdstrike-falconpy","devsecops","falcon","falconpy","falconpy-tools","python","python3","python310","python37","python38","python39","toolbox","toolkit"],"created_at":"2025-06-02T11:09:21.215Z","updated_at":"2025-12-14T16:03:33.570Z","avatar_url":"https://github.com/CrowdStrike.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"![CrowdStrike Falcon](https://raw.githubusercontent.com/CrowdStrike/falconpy/main/docs/asset/cs-logo.png) [![Twitter URL](https://img.shields.io/twitter/url?label=Follow%20%40CrowdStrike\u0026style=social\u0026url=https%3A%2F%2Ftwitter.com%2FCrowdStrike)](https://twitter.com/CrowdStrike)\u003cbr/\u003e\n\n# Caracara\n\n\n\n\u003c!--\n![PyPI - Status](https://img.shields.io/pypi/status/caracara)\n[![Pylint](https://github.com/CrowdStrike/caracara/actions/workflows/pylint.yml/badge.svg)](https://github.com/CrowdStrike/caracara/actions/workflows/pylint.yml)\n[![Flake8](https://github.com/CrowdStrike/caracara/actions/workflows/flake8.yml/badge.svg)](https://github.com/CrowdStrike/caracara/actions/workflows/flake8.yml)\n[![Bandit](https://github.com/CrowdStrike/caracara/actions/workflows/bandit.yml/badge.svg)](https://github.com/CrowdStrike/caracara/actions/workflows/bandit.yml)\n[![CodeQL](https://github.com/CrowdStrike/caracara/actions/workflows/codeql.yml/badge.svg)](https://github.com/CrowdStrike/caracara/actions/workflows/codeql.yml)\n--\u003e\n[![PyPI](https://img.shields.io/pypi/v/caracara)](https://pypi.org/project/caracara/)\n![OSS Lifecycle](https://img.shields.io/osslifecycle/CrowdStrike/caracara)\n\nA friendly wrapper to help you interact with the CrowdStrike Falcon API. Less code, less fuss, better performance, and full interoperability with [FalconPy](https://github.com/CrowdStrike/falconpy/).\n\n- [Features](#features)\n- [Installation](#installation-instructions)\n- [Basic Usage](#basic-usage-example)\n- [Examples](#examples-collection)\n- [Documentation](#documentation)\n- [Contributing](#contributing)\n\n## Features\n\nA few of the developer experience enhancements provided by the Caracara toolkit include:\n| Feature | Details |\n| :---  | :--- |\n| __Automatic pagination with concurrency__ | Caracara 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. |\n| __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. |\n| __Logging__ | Caracara is built with the in-box `logging` library provided with Python 3. Simply set up your logging handlers in your main code file, and Caracara will forward over `debug`, `info` and `error` logs as they are produced. Note that the `debug` logs 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. |\n| __Real Time Response (RTR) batch session abstraction__ | Caracara 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 `.7z` container for you. |\n| __Rich and detailed sample code__ | Every 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 to `config.yml`, and all samples will be ready to go. |\n| __Simple filter syntax__ | Caracara provides an object-orientated Falcon Query Language (FQL) generator. The `FalconFilter` object lets you specify filters such as `Hostname`, `OS` and `Role`, automatically converting them to valid FQL. Never write a FQL filter yourself again! |\n| __Single authentication point of entry__ | Authenticate once and have access to every module. |\n| __100% FalconPy compatibility__ | Caracara is built on FalconPy, and can even be configured with a FalconPy `OAuth2` object via the `auth_object` constructor parameter, allowing you to reuse FalconPy authentication objects across Caracara and FalconPy. Authenticate once with FalconPy, and access every feature of FalconPy and Caracara. |\n\n## Installation Instructions\n\nCaracara supports all major Python packaging solutions. Instructions for [Poetry](https://python-poetry.org) and [Pip](https://pypi.org/project/pip/) are provided below.\n\nCaracara supports Python versions that are still supported by the Python Software Foundation, i.e., **Python 3.8 and up**.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ch3\u003eInstalling Caracara from PyPI using Poetry (Recommended!)\u003c/h3\u003e\u003c/summary\u003e\n\n### Poetry: Installation\n\n```shell\npoetry add caracara\n```\n\n### Poetry: Upgrading\n\n```shell\npoetry update caracara\n```\n\n### Poetry: Removal\n\n```shell\npoetry remove caracara\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ch3\u003eInstalling Caracara from PyPI using Pip\u003c/h3\u003e\u003c/summary\u003e\n\n### Pip: Installation\n\n```shell\npython3 -m pip install caracara\n```\n\n### Pip: Upgrading\n\n```shell\npython3 -m pip install caracara --upgrade\n```\n\n### Pip: Removal\n\n```shell\npython3 -m pip uninstall caracara\n```\n\n\u003c/details\u003e\n\n## Basic Usage Examples\n\n```python\n\"\"\"List Windows devices.\n\nThis example will use the API credentials provided as keywords to list the\nIDs and hostnames of all systems within your Falcon tenant that run Windows.\n\"\"\"\n\nfrom caracara import Client\n\nclient = Client(\n    client_id=\"12345abcde\",\n    client_secret=\"67890fghij\",\n)\n\nfilters = client.FalconFilter()\nfilters.create_new_filter(\"OS\", \"Windows\")\n\nresponse_data = client.hosts.describe_devices(filters)\nprint(f\"Found {len(response_data)} devices running Windows\")\n\nfor device_id, device_data in response_data.items():\n    hostname = device_data.get(\"hostname\", \"Unknown Hostname\")\n    print(f\"{device_id} - {hostname}\")\n```\n\nYou can also leverage the built in context manager and environment variables.\n\n```python\n\"\"\"List stale sensors.\n\nThis example will use the API credentials set in the environment to list the\nhostnames and IDs of all systems within your Falcon tenant that have not checked\ninto your CrowdStrike tenant within the past 7 days.\n\nThis is determined based on the filter LastSeen less than or equal (LTE) to 7 days ago (-7d).\n\"\"\"\n\nfrom caracara import Client\n\n\nwith Client(client_id=\"${CLIENT_ID_ENV_VARIABLE}\", client_secret=\"${CLIENT_SECRET_ENV_VARIABLE}\") as client:\n    filters = client.FalconFilter()\n    filters.create_new_filter(\"LastSeen\", \"-7d\", \"LTE\")\n    response_data = client.hosts.describe_devices(filters)\n\nprint(f\"Found {len(response_data)} stale devices\")\n\nfor device_id, device_data in response_data.items():\n    hostname = device_data.get(\"hostname\", \"Unknown Hostname\")\n    print(f\"{device_id} - {hostname}\")\n```\n\n## Examples Collection\n\nEach API wrapper is provided alongside example code. Cloning or downloading/extracting this repository allows you to execute examples directly.\n\nUsing the examples collection requires that you install our Python packaging tool of choice, [Poetry](https://python-poetry.org). Please refer to the Poetry project's [installation guide](https://python-poetry.org/docs/#installation) if you do not yet have Poetry installed.\n\nOnce Poetry is installed, make sure you run `poetry install` within the root repository folder to set up the Python virtual environment.\n\nTo 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.\n\n### Executing the Examples\n\nThere are two ways to use Poetry to execute the examples.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ch4\u003eExecuting from a Poetry Shell\u003c/h4\u003e\u003c/summary\u003e\n\nThe `poetry shell` command will enter you into the virtual environment. All future commands will run within the Caracara virtual environment using Python 3, until you run the `deactivate` command.\n\n```shell\npoetry shell\nexamples/get_devices/list_windows_devices.py\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ch4\u003eExecuting without Activating the Virtual Environment\u003c/h4\u003e\u003c/summary\u003e\n\nIf 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 the `poetry run` command to temporarily invoke the virtual environment for one-off commands.\n\n```shell\npoetry run examples/get_devices/list_windows_devices.py\n```\n\nAll examples are also configured in the `pyproject.toml` file as scripts, allowing them to be executed simply.\n\n```shell\npoetry run stale-sensors\n```\n\n\u003e To get a complete list of available examples, execute the command `util/list-examples.sh` from the root of the repository folder.\n\n\u003c/details\u003e\n\n## Documentation\n\n__*Coming soon!*__\n\n## Contributing\n\nInterested in taking part in the development of the Caracara project? Start [here](CONTRIBUTING.md).\n\n## Why Caracara?\n\nSimple! We like birds at CrowdStrike, so what better bird to name a Python project after one that eats just about anything, including snakes :)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcrowdstrike%2Fcaracara","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcrowdstrike%2Fcaracara","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcrowdstrike%2Fcaracara/lists"}