falcon-axi

Read CrowdStrike Falcon from the shell with compact, structured results for agents and the humans running them.

Ask for a severity count without retrieving every detection. Actual output replayed against the repository's synthetic offline fixture:

$ falcon-axi detection summary --severity critical
detections: 0 detections matching critical severity

Quickstart • Use with your agent • Features • Safety • Configuration • Commands

Why this exists

Investigating Falcon often means stitching together API requests, pagination, and product-specific response shapes. falcon-axi exposes those reads as shell commands with small default schemas, structured errors, and next-step suggestions. It runs as a Python CLI without an MCP server process and uses CrowdStrike's FalconPy SDK.

Features

• Investigation: detections, severity counts, hosts, login and network history, vulnerabilities, and threat intelligence.
• Inventory: Discover assets and accounts, identities, IoT, cloud assets, containers, images, and serverless findings.
• Configuration reads: policies, exclusions, firewall and IOA rules, cases, Data Protection, SaaS posture, and Recon.
• Search: bounded NG-SIEM jobs and fixed account-activity queries, with explicit status and cancellation.
• Structured output: TOON data and errors on stdout, with optional fields and continuation cursors.
• Agent integration: local session context for Claude Code, Codex, and OpenCode, plus an installable skill.

Quickstart

Requires Python 3.11 or newer. Install from PyPI with either command:

pip install falcon-axi
# Or install in an isolated tool environment:
uv tool install falcon-axi

For invocation without a permanent install:

uvx falcon-axi setup

Create a Falcon API client with the permissions needed for your reads. Have your secret manager or protected shell environment supply FALCON_AXI_CLIENT_ID and FALCON_AXI_CLIENT_SECRET. Do not put credentials in shell command arguments, shell history, or agent chat.

falcon-axi setup
falcon-axi auth status
falcon-axi detection summary --severity critical

The example above shows the actual empty-result output; your tenant determines the counts. Run falcon-axi for recent detections, or falcon-axi detection list --severity high --since 24h for a filtered page. For persistent profile configuration, see Configuration.

Use with your agent

Install the CLI in a durable location, then opt in to session context:

falcon-axi setup hooks

This installs or repairs integrations for Claude Code, Codex, and OpenCode. At session start they provide local profile status, region, version, and a command hint without contacting Falcon. Ordinary read commands never install hooks. Temporary installations and git worktrees are refused as hook targets.

The generated skill provides on-demand guidance instead of session context:

npx skills add knowttl/falcon-axi --skill falcon-axi

Add -g for a user-wide skill. Choose either integration or use both; setup does not install the skill.

Safety

falcon-axi reads Falcon data without changing hosts, detections, policies, or identities. It cannot contain endpoints, release quarantined files, update configuration, or send GraphQL mutations. There is no arbitrary API passthrough.

Tenant-side effects are NG-SIEM search jobs, N3's explicitly authorized read-only RTR lifecycle, and N4's bounded MalQuery exact/fuzzy searches. MalQuery pattern search requires optional MalQuery:write and Falcon MalQuery licensing under N4; hunt and all malware downloads stay excluded. See API client permissions for required scopes. Set FALCON_AXI_READ_ONLY=1 to enforce the local switch contract, which lists the affected commands. Identity directory, timeline, and assessment reads require a scope Falcon labels write, but send only fixed read-only query documents. They accept no caller-supplied GraphQL.

falcon-axi rtr run <device_id> --command '<complete command>' previews locally without a network request. See RTR operator guidance for profile opt-in, exact execution confirmation, platform requirements, limits, and recovery.

Credentials and standalone tenant CID fields are redacted from stdout and stderr. Composite detection IDs contain a tenant CID and remain intact so they can be passed to detail commands. Treat output containing detection IDs or security findings as sensitive.

Credentials stay in your environment or referenced local files. API requests send credentials to Falcon's OAuth endpoint and query inputs to the selected Falcon API cloud, through your configured proxy if present. Tokens are held in memory; no persistent token cache is written. The explicit setup installer writes local agent configuration. See read-only enforcement and validation for the mechanics and evidence limits.

API client permissions

Create an API client under Support and resources > API clients and keys in Falcon. Grant only the domains you use; available scopes depend on product licensing.

falcon-axi scopes prints the complete per-command matrix offline, including all product and policy scopes. The full permissions table is generated from the same registry. No other write scope is needed. Missing permissions produce SCOPE_DENIED; leaving optional scopes ungranted is supported.

Configuration

falcon-axi config path reports configuration paths. On Linux and macOS, config defaults to ~/.config/falcon-axi/config.json, respecting an absolute XDG_CONFIG_HOME. Windows uses %APPDATA%\falcon-axi\config.json.

{
  "version": 1,
  "defaultProfile": "production",
  "profiles": {
    "production": {
      "region": "us-1",
      "clientId": "<client-id>",
      "clientSecret": {"env": "FALCON_AXI_CLIENT_SECRET"}
    }
  }
}

falcon-axi profile list
falcon-axi auth status --profile production

Commands

Names below omit the falcon-axi prefix. This table and the full command and permissions reference are generated from the CLI registry and checked locally for drift. Run any command with --help for its arguments and examples.

Output and errors

Data and structured errors use TOON on stdout; diagnostics use stderr. List results use compact columns, explicit empty states, and next-step hints. Detection, host, and vulnerability lists accept --fields to append selected columns; invalid field names are refused. Detail commands that support --full use it to expand truncated content.

Exit status is 0 for success, 2 for VALIDATION_ERROR, CONFIG_INVALID, or FQL_INVALID, and 1 for other failures. Errors carry a stable code and actionable help. Unknown flags and commands fail loudly.

Pagination

One invocation reads one page by default. Use --limit N where supported, then pass the emitted continuation_cursor back as --cursor <token>, preserving query and credential context. Cursors are opaque and cannot be moved between queries or tenants.

Detection, host, account, and vulnerability lists support --all --max-rows N (default cap 1000). An incomplete walk keeps its rows, exits successfully, and prints partial: true with a stop_reason. Detection walks stop at 10000 query rows; host walks stop at 9999. Narrow the filter at these boundaries; a cursor is emitted only if the next page is reachable. Run the selected list with --help for its own limits.

NG-SIEM jobs have no cursor or limit flags. Bound results in CQL with a command such as head(200), poll with search status <id>, and cancel unfinished jobs with search stop <id>. Check parsed_query in status output: NG-SIEM can interpret unknown words as free text.

Troubleshooting

Contributing

See CONTRIBUTING.md for the offline verification commands, synthetic fixtures, and documentation generation. API shapes follow official CrowdStrike sources and offline fixtures; no live-tenant validation is claimed.

License

MIT.

If this project saved you time or helped your workflow, please consider giving it a ⭐ on GitHub to help others find it!