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

A blocked call returns a JSON-RPC error (-32000: blocked by aileron rule <id>) 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.

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

Performance