Crow

Crow

A local, read-only assistant for your CrowdStrike Falcon tenant.

• Codename: Huginn — Odin's raven of thought, the one that flies out, observes, and returns with what it saw. Fitting for a watcher that never touches anything.
• Scope: strictly read-only. The API client is scoped so the tool physically cannot mutate your tenant (no contain, no RTR, no incident writes).
• Front-ends: a CLI (cli.py) and an MCP server (server.py) that both wrap the same shared logic in core.py, so they never diverge. The MCP server speaks the standard Model Context Protocol, so any MCP-capable client can use it — Claude Code, Cursor, Zed, any LLM harness or agent that supports MCP — not just one specific tool.

Crow (repo)  ── outward name
  └─ Huginn   ── internal codename (shown in --version / --selftest only)

What it can do (v1, read-only)

See docs/usage.md for full command reference and examples.

Repository layout

Crow/
├── core.py        # shared read-only Falcon logic (falconpy calls)
├── cli.py         # standalone CLI front-end
├── server.py      # MCP server front-end (any MCP-capable client)
├── requirements.txt
├── .env.example   # credential template (copy to .env, chmod 600)
├── .gitignore     # excludes .env and .venv
├── README.md
└── docs/
    ├── usage.md       # command reference + examples
    ├── credentials.md # how to create the read-only API client
    └── architecture.md# how it works / safety model

Quick start

git clone https://github.com/yusif-v/Crow.git
cd Crow
python3 -m venv .venv
./.venv/bin/python -m pip install hatchling wheel setuptools
./.venv/bin/python -m pip install --no-build-isolation "git+https://github.com/CrowdStrike/falconpy.git"
./.venv/bin/python -m pip install "mcp==1.9.4" "python-dotenv>=1.0.0"
cp .env.example .env        # then edit .env with your credentials
chmod 600 .env

Install note: on some networks PyPI returns an empty package list for falconpy(a package filter). Installing it from GitHub source (above) is the workaround.mcp and python-dotenv install normally from PyPI.

Create a read-only Falcon API client (see docs/credentials.md), then:

./.venv/bin/crow detections --severity-min 4

Wiring into an AI client (agent-agnostic)

server.py is a standard MCP server, so it works with any MCP-capable client —Claude Code, Cursor, Zed, your own agent, or any LLM harness that supports theModel Context Protocol. You are not locked into one tool or model.

Example: Hermes Agent

Add to ~/.hermes/config.yaml:

mcp_servers:
  crow:
    command: "/Users/lizard/Development/Projects/Crow/.venv/bin/python"
    args: ["/Users/lizard/Development/Projects/Crow/server.py"]
    timeout: 120
    connect_timeout: 60

Restart the agent. The crow_* tools then appear and you can ask naturally:"show me critical detections in the last 24 hours".

Example: Claude Code

Claude Code auto-discovers an .mcp.json in the project root. Drop this in~/Development/Projects/Crow/.mcp.json (or any project where you want Crowavailable):

{
  "mcpServers": {
    "crow": {
      "command": "/Users/lizard/Development/Projects/Crow/.venv/bin/python",
      "args": ["/Users/lizard/Development/Projects/Crow/server.py"]
    }
  }
}

Or register it globally from the terminal:

claude mcp add crow -- /Users/lizard/Development/Projects/Crow/.venv/bin/python \
  /Users/lizard/Development/Projects/Crow/server.py

Then in Claude Code: /mcp to confirm it connected, and ask naturally.

Example: Codex (OpenAI Codex CLI)

Codex reads MCP servers from ~/.codex/config.toml:

[mcp_servers.crow]
command = "/Users/lizard/Development/Projects/Crow/.venv/bin/python"
args = ["/Users/lizard/Development/Projects/Crow/server.py"]

The crow_* tools are then available to Codex in any session.

Other MCP clients

Any client that reads an MCP server config (stdio transport) can launch server.pythe same way — point its command at the venv Python and pass server.py as theargument. The crow_* tools are then available to whatever model that client drives.

Prefer not to run an MCP client at all? Use the CLI (cli.py) directly — sameread-only logic, no agent required.

Safety model

• Read-only by construction. The Falcon API client is granted only *:readscopes. No write/contain/RTR scope exists, so the server cannot change state.
• Credentials stay local. Your Client ID / Secret live only in a chmod-600.env on your machine. They are sent only to CrowdStrike's API. The MCP layerredacts credential-shaped strings from error messages.
• No third-party transit. Queries go directly from your machine to CrowdStrike(and, for NG-SIEM, directly to your LogScale cluster).

Status

Baseline v0.1.0 — read-only visibility across detections, alerts, hosts, incidents,Falcon X IOC lookups, and NG-SIEM / LogScale search. No caching, no cross-pagepagination beyond API limits, no mutating actions. Those are deliberate follow-ups.