# Aileron [![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE) [![Tests](https://github.com/Aileron-sh/aileron/actions/workflows/ci.yml/badge.svg)](https://github.com/Aileron-sh/aileron/actions/workflows/ci.yml) [![Python](https://img.shields.io/badge/python-3.10%2B-blue)](pyproject.toml) **Aileron is a flight recorder for AI agents.** Not another tracer. Aileron produces a tamper-evident, replayable record of every tool call your agents make - evidence you can verify offline, not telemetry you have to trust. - **Tamper-evident audit trail.** Every agent action is appended to a SHA-256 hash-chained JSONL journal with Ed25519-signed checkpoints. Edit, delete, or reorder a single line and `aileron verify` says exactly where the chain broke. - **Policy enforcement on tool calls.** Sigma-like YAML rules with `allow` / `alert` / `block` actions, applied *before* execution via the MCP stdio proxy or the SDK decorator. A blocked tool call never runs; the attempt is logged anyway. - **Forensic incident replay.** One command turns a journal into a self-contained HTML incident report with a verification badge and a filterable timeline - the answer to "what did the agent actually touch?" ## 60-second quickstart ```console $ pip install aileron $ aileron demo # scripted fake-agent session (no network, no keys needed) demo: wrote 8 events to demo.chain.jsonl demo: chain VERIFIED (8 events) demo: blocked shell call by rule aileron-001 demo: 2 anomaly alert(s) emitted $ aileron verify demo.chain.jsonl OK: 8 events verified in demo.chain.jsonl $ aileron report demo.chain.jsonl -o incident.html # open it in a browser $ aileron serve --root . # or ask an assistant instead ``` The demo runs in the default digest-only mode: the destructive shell call is blocked by a content rule and flagged by the behavioral baseline, yet the journal on disk contains only argument digests - never the raw command. ## Features | Feature | What you get | |---|---| | Hash-chained journal | Append-only JSONL; each event's `prev_hash` links to the previous event's SHA-256 hash; genesis is `0x00…00` | | Signed checkpoints | Ed25519 signature over the chain tip, verifiable offline against the public key (`aileron sign-checkpoint` / `verify-checkpoint`). Checkpoints cover a *prefix*: appending later events never invalidates them; truncating or rewriting the signed prefix does | | Policy rules | **32 bundled rules** covering credential theft, cloud metadata abuse, exfiltration, supply chain, persistence, anti-forensics, database destruction, and prompt-injection artifacts. Sigma-like YAML; substring, regex, and dotted-key matchers. Rules are evaluated against the full call **in memory**, so content rules fire even in digest-only mode | | Behavioral anomaly detection | Rolling baselines flag first-seen tools, rate spikes (>3x baseline), and novel tool-call sequences - live via the SDK (`baseline=`) or offline via `aileron detect` | | MCP stdio proxy | Sits between any MCP client and server; logs and mediates every `tools/call` before it reaches the child process. Verified against the official filesystem and memory servers, not just test doubles | | Claude Code hook | `aileron hook` plugs into Claude Code's PreToolUse and PostToolUse hooks: every tool call is journaled before it runs and again when it returns, a matching block rule stops it (exit 2, reason shown in the session, even in bypassPermissions mode), and a journal that cannot be written blocks the call instead of losing it. One settings.json snippet covers a project. See [docs/claude-code.md](docs/claude-code.md) | | MCP server mode | `aileron serve` exposes your journals read-only, so an assistant can answer "what did the agent touch?" from the record. Listed in the [official MCP Registry](https://registry.modelcontextprotocol.io) as `io.github.aileron-sh/aileron` | | OTel GenAI export | Events export as `gen_ai.*`-aligned span dicts (`aileron export`) for your existing collector | | HTML incident reports | Single file, inline CSS, no external assets, verification badge (`VERIFIED` / `TAMPERED at seq N`) | | Privacy by default | Tool arguments/results are recorded as digests only, unless you opt in with `--capture-content` | ## Usage ### SDK: `@track` decorator ```python from aileron import ChainLog, track, PolicyBlocked, bundled_rules_dir from aileron.policy import load_rules log = ChainLog("run.chain.jsonl") # capture_content=False by default rules = load_rules(bundled_rules_dir()) # or load_rules("rules") after `aileron init` @track(log=log, rules=rules) def shell(cmd: str) -> str: ... # your tool implementation shell("ls /tmp") # -> tool_call event, status=ok, args recorded as digest shell("rm -rf /") # -> PolicyBlocked raised; blocked attempt is logged ``` Rules see the full arguments in memory at decision time; the journal still stores digests only. Turn on `capture_content=True` only when you want raw arguments *persisted* for forensics. ### SDK: `track_agent` session ```python from aileron import track_agent with track_agent("research-agent", framework="langchain", log=log): shell("ls /tmp") # inherits the session's agent identity and session_id # agent_start / agent_end events bracket the run automatically ``` ### MCP proxy: framework-agnostic interception Wrap any MCP server. Every `tools/call` is logged and policy-checked *before* the child process sees it: ```console $ aileron init # seeds a ./rules directory with starter rules $ aileron proxy --log run.chain.jsonl --rules rules -- \ npx -y @modelcontextprotocol/server-filesystem /tmp $ AILERON_SESSION_ID=run-4821 aileron proxy --log run.chain.jsonl --rules rules \ --agent researcher --framework crewai -- npx -y @modelcontextprotocol/server-filesystem /tmp ``` Proxy flags go before `--`; everything after it belongs to the child. A harness can set `AILERON_AGENT`, `AILERON_FRAMEWORK` and `AILERON_SESSION_ID` per spawn instead of passing flags, and a flag wins over the environment. The journal records the identity you give it, so a rule such as `agent.name: researcher` matches on the proxy path. Reusing a session id across runs groups them: `detect` treats them as one session and the OTel export puts them in one trace. A blocked call returns a JSON-RPC error (`-32000: blocked by aileron rule `) to the client; the child is never invoked. **Verified against real MCP servers**, not just test doubles. Aileron has been run in front of the official `@modelcontextprotocol/server-filesystem` (`secure-filesystem-server` 0.2.0, 14 tools) and `@modelcontextprotocol/server-memory` (0.6.3, 9 tools): the handshake completes, tools list normally, real calls work, a blocked write never reaches the server, and the journal verifies. That check ships as a test (`tests/test_real_mcp_server.py`, run with `AILERON_LIVE_MCP=1`). The proxy itself costs **well under a millisecond per `tools/call`**. Matching content rules against large payloads costs more, and how much is yours to choose: see [Performance](#performance) for the split, measured. The proxy speaks both newline-delimited and `Content-Length`-framed JSON-RPC. Content rules (`tool.arguments_contains`, `_regex`) work in the default digest-only mode - `--capture-content` changes what is persisted, not what is enforced. Calls still in flight when the child dies are journaled with `status=error`, so a crash never erases the attempt. ### Claude Code: record and police every tool call Claude Code's own tools (`Bash`, `Edit`, `Write`, MCP tools) go through its hook system, and `aileron hook` is a command hook for it. One entry, registered under `PreToolUse`, `PostToolUse` and `PostToolUseFailure`; the `PreToolUse` copy also gets `"onFailure": "block"`: ```json {"type": "command", "command": "aileron", "args": ["hook", "--log", "${CLAUDE_PROJECT_DIR}/aileron.chain.jsonl", "--rules", "${CLAUDE_PROJECT_DIR}/rules"], "timeout": 30} ``` Every call is journaled before it runs and again when it returns, digests only by default. A matching block rule stops the call by exit code 2 and Claude sees the reason in the session: ```text PreToolUse:Bash hook error: [aileron hook ...]: blocked by aileron rule local-001 (Block destructive shell commands from Claude Code); recorded as seq 3 in /home/me/my-project/aileron.chain.jsonl ``` The hook fails closed: a journal that cannot be written or rules that cannot be loaded block the call rather than let it run unrecorded, and it never writes to stdout or emits an `allow`, so it can only narrow what Claude Code would have permitted. Hook processes run in parallel and serialise on `.lock`. `aileron verify` and `aileron report` work on the journal as on any other. Full setup, the event shapes and the limits (what a timed-out hook means, `@` file reads, mods) are in [docs/claude-code.md](docs/claude-code.md). ### MCP server: ask your assistant what the agent did Aileron sits in front of MCP servers. It is also one. Point it at a directory of journals and an assistant can read the record for you: ```console $ aileron serve --root ./journals ``` Three tools, all read only: `verify_journal` (is this record intact), `query_events` (what happened, filtered by tool, status, or time), and `explain_rule` (what does aileron-130 catch). There is no write, delete, or sign tool, and there should never be. The agent being recorded is the untrusted party, so giving it a way to edit the journal would hand the suspect the evidence locker. Four things follow from that, and they are the reason this is more than a wrapper around `aileron verify`: - **Paths are confined to `--root`** and only `.jsonl` opens. Otherwise `verify_journal(path)` is an arbitrary file read. - **Every answer carries its own integrity status.** Confinement stops an agent reading files it should not; it does not stop one *writing* a plausible journal inside the root and handing you an invented history. So each reply says whether the chain verifies and whether an adjacent signed checkpoint agrees. - **Recorded values are treated as hostile.** Tool names and rule ids were chosen by the agent under investigation, so they reach an assistant labelled as untrusted data, stripped of control characters, and truncated. A tool named `IGNORE PREVIOUS INSTRUCTIONS...` is evidence to report, not an instruction to follow. - **Digest-only stays digest-only.** `capture_content` governs what the journal stores. It never widens what this server hands back, and errors never echo file contents. ### Policy rules ```yaml # a policy rule (see the bundled rules/examples/destructive-shell.yml) id: aileron-001 title: Block destructive shell commands severity: high match: type: tool_call tool.name: shell tool.arguments_contains: ["rm -rf", "DROP TABLE", ":(){ :|:& };:"] action: block ``` Dry-run rules against a recorded session: `aileron rules test rules/ run.chain.jsonl` ## How it works ``` agent ──tool call──► [ SDK @track ] ──┐ [ MCP proxy ] ──┼─► policy decide (allow/alert/block) │ │ block? ──► call never executes, MCP client ──JSON-RPC──► proxy ───────┘ │ attempt still logged ▼ append to chain log (JSONL) event 0 event 1 event N ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ seq: 0 │ │ seq: 1 │ │ seq: N │ │ prev: 0000… │─►│ prev: H(e0) │─► … ──►│ prev: H(eN-1)│ │ hash: H(e0) │ │ hash: H(e1) │ │ hash: H(eN) │──► Ed25519 checkpoint └──────────────┘ └──────────────┘ └──────────────┘ signature over tip H(e) = sha256(canonical_json(e \ hash)) aileron verify → recompute every hash + link (exit 2 on tamper) aileron verify-checkpoint → re-verify chain tip against Ed25519 signature ``` Tampering with any event breaks the hash link at the first modified sequence; `verify` reports `first_bad_seq` and exits non-zero. The journal is local-only and self-contained - verification needs no network and no trusted third party. ### Independent verification You do not have to take Aileron's word for what the journal says. A second verifier, written in Go with nothing but the standard library, lives in [`verifiers/go/`](verifiers/go/) and reimplements `verify` and `verify-checkpoint` from [SPEC.md](SPEC.md#independent-verification) alone: ```console $ cd verifiers/go && go build ./cmd/aileron-verify $ ./aileron-verify verify demo.chain.jsonl OK: 8 events verified in demo.chain.jsonl $ ./aileron-verify verify-checkpoint demo.chain.jsonl --key aileron_ed25519.pub ``` It exists because a tamper-evidence tool whose only verifier was written by its author, in one language, asks you to trust the author twice. Two implementations that share only the specification are evidence that the specification is complete and that neither has a convenient blind spot. The fixtures under `tests/conformance/` hold both to the same verdicts and the same canonical bytes on every test run. ## Performance The proxy adds **well under a millisecond** per `tools/call`. Matching the full 32-rule bundled pack against the payload is a **separate** cost that grows with payload size, and it is reported separately below, because the two scale differently and you choose your own rules. Every number is reproducible with one command: ```console $ python scripts/benchmark.py ``` **Method.** [`scripts/benchmark.py`](scripts/benchmark.py) drives an identical stdio MCP child server three ways - directly, through `aileron proxy` with no rules, and through `aileron proxy` with all 32 bundled rules - and subtracts. The deltas are the proxy's true cost, so you never have to trust an absolute figure. The absolute baseline is printed alongside so the subtraction can be checked. 2,000 sequential calls per configuration after 200 discarded warmup calls; digest-only journaling. Overhead covers JSON-RPC parsing, policy evaluation, hash-chain append, re-serialization, and the extra process hop. **About the payload.** The tool arguments are fixed text that looks like real tool arguments: English words, paths, flags, quotes and punctuation. That matters more than it sounds. This benchmark used to send a run of one repeated character, which is the friendliest possible input both to the regex engine, which fails on the first character everywhere, and to the literal prefilter described below, which finds nothing anywhere. It was flattering the result by about 3x. A test asserts no bundled rule fires on the filler, so these numbers are the ordinary path and not the alert path. ### Added latency per `tools/call` (milliseconds) **Linux x86_64** - GitHub Actions `ubuntu-latest` (2 shared vCPU), Python 3.12.14. Re-measured by CI on every push: [![Benchmark](https://github.com/Aileron-sh/aileron/actions/workflows/benchmark.yml/badge.svg)](https://github.com/Aileron-sh/aileron/actions/workflows/benchmark.yml) | tool arguments | direct | through proxy | + 32 rules | added by proxy | added by rules | **added total** | |---|---|---|---|---|---|---| | 64 B | 0.077 | 0.305 | 0.546 | 0.228 | 0.242 | **0.469** | | 4 KB | 0.078 | 0.348 | 0.740 | 0.270 | 0.392 | **0.662** | | 32 KB | 0.241 | 0.799 | 3.030 | 0.558 | 2.231 | **2.789** | Shared CI runners vary between runs, by as much as 1.6x on the small-payload row. This table quotes the slower of two consecutive measurements. The regression baseline uses the faster one, so a slow runner cannot quietly widen the guard. **macOS arm64** - Apple M2 Pro, Python 3.13.7, idle machine. The worst of three passes, quoted whole, so `added = (proxy & rules) - direct` holds exactly within the run: | tool arguments | direct | through proxy | + 32 rules | added by proxy | added by rules | **added total** | |---|---|---|---|---|---|---| | 64 B | 0.016 | 0.089 | 0.195 | 0.073 | 0.105 | **0.178** | | 4 KB | 0.034 | 0.157 | 0.507 | 0.123 | 0.350 | **0.474** | | 32 KB | 0.156 | 0.457 | 2.604 | 0.300 | 2.147 | **2.447** | ### What these numbers mean **The proxy is cheap and nearly flat.** Interception, journaling, and re-serialization cost about 0.23 ms on a small call and about 0.56 ms on a 32 KB one, on the slowest hardware tested. **Rules cost more on big payloads, and the cost is yours to choose.** Content rules are matched against the payload, so their cost grows with payload size. With all 32 bundled rules loaded that is 0.24 ms on a small call and 2.23 ms at 32 KB. **Most of that work is skipped before it starts.** A rule looking for `auditctl` cannot fire on a payload with no `auditctl` in it. Each pattern is read once and reduced to the literals it requires, and cheap substring searches decide whether the regex runs at all. Requirements are conjunctions, so a rule needing `systemctl` near `disable` near `auditd` is skipped on ordinary prose that merely contains the word "service". On a benign 32 KB call, 17 of the 19 patterns that would otherwise scan the whole payload never run. It changes speed and nothing else, and `AILERON_NO_PREFILTER=1` turns it off if you want it ruled out during an investigation. **In context.** A real MCP server call is typically 10 to 1000 ms. At 2.8 ms for a 32 KB argument with every rule loaded, and 0.47 ms for an ordinary small one, mediation is a small fraction of the call it is mediating. **Caveats, stated plainly.** These are *sequential* stdio round-trips, one call in flight at a time, which is how an agent actually calls tools. This is not a concurrent-client benchmark; a many-client run is on the roadmap. The tool reports mean, median, p95 and p99; these tables quote medians, because medians are stable across runs and **p95 is not** - tail latency swings with scheduling. Linux is the slower machine because a shared-vCPU CI runner is slower than an idle laptop, and those are the conservative figures CI enforces. Measure on your own hardware before quoting a number. CI enforces this: a job fails if median overhead regresses more than 2x against [`scripts/benchmark_baseline.json`](scripts/benchmark_baseline.json), so performance cannot decay silently. It re-measures once before failing, so a single slow runner does not cry wolf. The baseline records both the rule-pack size and the payload shape it was measured against, because a change to either is more work rather than slower code, and the guard says so instead of reporting a regression that is not there. ## Integrations & ecosystem - **OpenTelemetry GenAI** - `aileron export` emits `gen_ai.operation.name` / `gen_ai.tool.name` / `gen_ai.agent.name` span attributes plus `aileron.event.hash`, so Aileron sits *beside* your existing tracing stack as the evidence layer, not instead of it. - **LangChain / CrewAI / any Python framework** - `@track` is a plain decorator; `track_agent` accepts a free-form `framework=` label. No framework dependency is required. See `examples/langchain_tool_tracking.py`. - **LiveKit Agents (voice and video)** - `@track` wraps `async def` tools too, so a LiveKit `@function_tool` can be recorded and policed before it runs, and the whole `AgentSession` sits inside `track_agent(..., framework="livekit")`. LiveKit is the framework being recorded, not a transport: Aileron makes no network calls and gains no dependency on it. See `examples/livekit_agent_tracking.py`, which runs with the standard library alone when LiveKit is not installed. - **MCP** - the proxy wraps any stdio MCP server regardless of which client or framework drives it. - **Claude Code** - `aileron hook` records and polices Claude Code's own tools (Bash, Edit, Write, MCP tools) through its hook system; no SDK, no proxy, no network, no change to how Claude Code is launched. See [docs/claude-code.md](docs/claude-code.md). - **Community rules** - rule contributions are the intended contribution unit (see Roadmap). ## Telemetry & privacy - **Aileron sends no telemetry.** No analytics, no phone-home, no network calls anywhere in the library or CLI. If that ever changes, it will be opt-in only, behind a documented RFC - for a security tool, anything less is disqualifying. - **Content capture is off by default.** Tool arguments and results are recorded as SHA-256 digests; raw content is only stored when you pass `capture_content=True` / `--capture-content`. You get a verifiable record of *what happened* without persisting secrets or PII by accident. Policy rules and the anomaly detector still see the full call in memory at decision time - capture only controls what is *persisted*, never what is *enforced*. ## Honest limitations - **SDK instrumentation is bypassable.** `@track` wraps the functions you decorate; code paths you don't instrument are not recorded. For enforcement that agent code cannot skip, use the MCP proxy - mediation happens in a separate process on the tool-call path. - **Policy rules are pattern matching, not intent classification.** They catch known-bad shapes (`rm -rf`, `id_rsa`, exfil patterns); they will not reliably detect novel malicious reasoning. Detection-of-effect complements detection-of-intent tools (garak, PromptGuard); it does not replace them. - **Tamper-evidence is not tamper-proof.** The chain proves modification after the fact; an attacker with write access can truncate or rewrite the whole log and forge it forward. Signed checkpoints make forgery require the private key - keep keys off the host being recorded, and anchor checkpoints externally (see Roadmap) if you need non-repudiation. - **The Claude Code hook is as strong as Claude Code's hook contract.** It blocks by exit code 2, which Claude Code honours in every permission mode, but a timed-out or crashed hook fails open unless `onFailure: "block"` is set (Claude Code 2.1.295 or later), files pulled in with `@` never fire a tool hook, a mod handling `tool.check` can override a hook that is not in managed settings, hooks do not run until the workspace trust dialog is accepted, and the hook runs as the same OS user as the agent, so it makes journal deletion and hook removal evident rather than impossible. ## Roadmap - **`aileron-rules` community rule repo** - Sigma-for-agents: community detection rules mapped to the OWASP Agentic Security Initiative's threat taxonomy, CI-validated against recorded incident traces. - **Sigstore/Rekor checkpoint anchoring** - now a companion package, `aileron-anchor`, kept separate so this package keeps making no network calls. It pushes signed checkpoints to a public transparency log and checks the local journal against what was anchored, which is what makes tail truncation detectable. - **OCSF export** - emit Open Cybersecurity Schema Framework events for direct SIEM ingestion (Splunk/Elastic quickstarts). - **Out of scope for v1: eBPF / kernel-level interception.** Aileron stays at the MCP-proxy and SDK layer where the semantic meaning of a tool call is still visible; syscall-level tracing is Falco/Cilium territory and would trade agent semantics for volume. ## Contributing Contributions are welcome - see [CONTRIBUTING.md](CONTRIBUTING.md). Good starting points: new detection rules under `src/aileron/rules/examples/` and new framework adapters under `examples/`. DCO sign-off, no CLA. Security issues: see [SECURITY.md](SECURITY.md). ## License Apache License 2.0 - see [LICENSE](LICENSE).