Aileron Journal

Aileron

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

$ 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

Usage

SDK: @track decorator

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

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:

$ 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 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":

{"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:

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.

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:

$ 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

# 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))