Documentation

Reference for the open-source Attestral CLI, the security scanner for AI agents and MCP servers. Everything here is licensed Apache 2.0 and complete: nothing below requires an account, a key, or a server.

See it run

Every panel below is real output from the CLI against the fixtures that ship in the repo, not a mockup. Switch tabs to walk the whole loop: review a deliberately vulnerable agent, inspect a rule, compile the attested design into a policy, catch runtime drift against it, and verify the evidence chain offline.

The scan is examples/vulnerable-agent: two small config files, fourteen design findings, three of them fleet-level. Compile and drift run against examples/demo-project. To see how a scan flows through the package itself, the architecture page draws the pipeline from Attestral's own code graph.

Pipeline

A scan flows through three stages: ingest your agent (MCP configs, system prompts, tool descriptions) and the cloud it runs on into one model, review in layers (each finding tagged by origin), and commit to a tamper-evident evidence chain. The deterministic core is never silently mixed with model reasoning.

flowchart TB
    MCP["MCP configs (mcp.json)"] --> M["SystemModel
components · edges · trust boundaries"]
    SP["System prompts + tool descriptions"] --> M
    TF["Terraform (.tf)"] --> M
    K8S["Kubernetes manifests (.yaml)"] --> M
    M --> L1["L1 Deterministic rules
typed matchers · fail-closed"]
    L1 --> L2["L2 ML classifier (optional)
prompt-injection scoring, three tiers"]
    L2 --> L3["L3 LLM: elicitation + judge
(optional, tagged origin: llm)"]
    L3 --> W["Waivers
documented, expiring"]
    W --> EV["Evidence: SHA-256 chain
verify offline"]
    EV --> OUT["Markdown · JSON · SARIF · AI-BOM"]
      

And the product loop: attest the design, prove the record, enforce it as a runtime policy, and detect divergence.

flowchart LR
    A["scan (attest)"] --> B["verify (prove)"]
    A --> C["compile (enforce)"]
    C --> D["drift (detect)"]
    D -->|"design changed? re-attest"| A
      

Install

pip install attestral
attestral --version

Python 3.10+. The core has two dependencies (click, pyyaml). Optional extras: [llm] adds the anthropic package for elicitation and the judge; [onnx] adds a light, model-grade prompt-injection classifier without torch; [ml] adds the full local DeBERTa tier (transformers, torch). --ml always works even with no extra installed: it degrades to a zero-dependency heuristic tier.

Try the full loop on the bundled demo:

git clone https://github.com/attestral-labs/attestral && cd attestral
attestral scan examples/demo-project
attestral compile examples/demo-project -o policy.yaml
attestral drift policy.yaml examples/demo-project/runtime-events.jsonl

The loop

Attestral treats the design review, the runtime policy, and the audit evidence as one artifact in three forms:

• Attest. scan builds a system model from Terraform, Kubernetes manifests, and MCP configs and reviews it against typed rules. Findings are committed to a hash chain.
• Enforce. compile turns the reviewed model into a default-deny mcp-guard policy, stamped with the model hash and the review chain head. Your threat model stops being a document and becomes the configuration itself.
• Prove. drift diffs runtime telemetry against the compiled policy. Anything the review never saw (a new server, a denied capability, an out-of-scope path) is drift, and verify proves nobody edited the record afterward.

attestral scan

attestral scan PATH [--local] [-o STEM] [--format md|json|both|sarif|aibom]
               [--ml] [--llm] [--judge] [--waivers FILE] [--fail-on SEVERITY] [-q]

Ingestion is automatic: *.tf feeds the cloud model; Kubernetes manifests feed the cluster model; mcp.json, *.mcp.json, and claude_desktop_config.json feed the agent runtime, along with system prompts, skill and instruction files, subagent definitions, hooks, and A2A agent cards.

attestral verify

attestral verify report.json

Recomputes the hash chain offline and exits 0 (VALID) or 1 (INVALID). No network, no server, no account. An auditor can verify a two-year-old report on an air-gapped laptop. The evidence chain section below runs the same check live on a real chain.

attestral compile

attestral compile PATH [-o mcp-guard-policy.yaml]

Compilation is fail-closed by construction:

• default: deny, so a server absent from the reviewed design is never allowed.
• A critical finding against a server compiles to allow: false with the rule id as the recorded reason.
• Filesystem servers are narrowed to their attested roots; broad roots (/, ~, /home) deny until the design is re-scoped.
• TLS-constrained servers observed with http:// URLs deny.
• The policy header carries the model hash and review chain head, which binds the policy cryptographically to the review that produced it.

attestral drift

attestral drift POLICY_FILE EVENTS_FILE [--fail-on-drift]

--fail-on-drift exits non-zero on any finding, so drift checks run as a CI step or a cron job against yesterday's telemetry.

Code scanning (SARIF)

Scan with --format sarif and the review becomes SARIF 2.1.0, the format GitHub Code Scanning speaks. Findings show up in the Security tab and inline on the pull request, each mapped to a severity GitHub understands and tagged with its framework references.

attestral scan . --format sarif -o attestral

Wire it into a workflow and every push publishes findings straight to the Security tab:

- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: attestral.sarif

A complete workflow ships in examples/github-actions/code-scanning.yml. The job needs security-events: write permission to upload.

Baseline & waivers

Real repositories start with findings. A waiver lets you accept a known risk and keep the gate green, without hiding anything: the finding stays in the evidence chain with its justification, so an auditor sees exactly what was accepted and why. Drop an attestral-waivers.yaml at your scan root and it is picked up automatically.

waivers:
  - rule: ATL-005
    component: aws_db_instance.app   # or "*" for every component
    reason: Encryption enforced at the storage layer; tracked in SEC-1234.
    expires: 2026-12-31              # optional; waiver lapses after this date

Two rules keep waivers honest. A waiver with no reason is ignored, and an expired waiver stops suppressing, so a finding can only be silenced by a current, justified exception. In SARIF, a waived finding becomes a suppression, which GitHub Code Scanning shows as dismissed rather than an open alert.

LLM-as-judge

Deterministic rules fire on patterns; some are false positives in context. The judge is an optional layer that cross-examines each finding. It sees the finding plus its component and returns a structured verdict, confirmed, false_positive, or needs_review, with a confidence and reasoning. Verdicts are recorded on the finding and carried into the evidence chain, so the judgment itself is auditable.

export ATTESTRAL_JUDGE_API_KEY=...        # or reuse ANTHROPIC_API_KEY
attestral scan . --judge --judge-panel 3 # 3 judges vote per finding
attestral scan . --judge --judge-suppress

The judge never deletes a finding. By default it only annotates. With --judge-suppress, a high-confidence false_positive becomes a machine-generated waiver whose reason is the judge's reasoning: suppressed from the gate, but kept on the record like any human waiver. A panel of judges (--judge-panel N) votes, and the majority verdict wins, which blunts any single model's error.

The rule pack

Every deterministic check ships in the open, in plain YAML, and each cites the control it enforces. This is the complete built-in pack, searchable. Click a rule for the same detail attestral explain prints.

The index is generated from the packs in attestral/rules/ at build time, so it matches the release exactly. Agentic and cross-boundary rules cite OWASP Agentic Security and MITRE ATLAS; cloud rules cite CIS and NIST.

Writing rules

Rules are YAML with structured matchers. There is no eval anywhere, and an unknown matcher fails closed: the rule simply never matches.

rules:
 - id: ORG-001
    title: Internal ALB missing auth attribute
    severity: high
    target: aws_lb            # component type prefix, or "model"
    match: { attr_missing: auth }
    description: ...
    recommendation: ...
    frameworks: ["NIST AC-3", "SOC2 CC6.1"]

Load custom packs alongside the core pack via RuleEngine(["org_rules.yaml"]).

Evidence chain

Every run commits its findings to a SHA-256 hash chain: entry N hashes the canonical JSON of finding N together with the hash of entry N-1, starting from a zero genesis. The final hash (the chain head) appears in the report header and in every compiled policy.

The consequence: altering, inserting, or deleting any past entry changes every subsequent hash. A reviewer who records the chain head (in a PR comment, a ticket, an email) has permanently committed the whole review.

Try to tamper with one. Below are the first four entries of a real chain from attestral scan examples/demo-project. Downgrade an entry's severity and your browser recomputes the chain with the exact algorithm attestral verify uses. Watch the break propagate.

Telemetry format

drift reads JSONL, one event per line. mcp-guard emits this format natively, and anything else can adapt to it in a few lines:

{"ts": "2026-07-10T14:01:02Z", "server": "docs", "tool": "read_file", "args": ["/srv/docs/design.md"]}

GitHub Action

Run drift checks on a schedule so conformance is continuous, not annual:

- uses: attestral-labs/attestral@v1
  with:
    policy: policy.yaml
    events: events.jsonl

A complete nightly workflow (pull telemetry, re-compile the policy from the reviewed main branch, drift-check) ships in examples/github-actions/drift-schedule.yml. The mcp-guard telemetry emitter lives in integrations/mcp-guard/.

Terraform extra

The core ships a dependency-free Terraform scanner that resolves variables, locals, and modules. For full-fidelity HCL parsing (nested blocks, correct types), install the extra. Attestral picks it up automatically and falls back gracefully on malformed files:

pip install "attestral[terraform]"

Roadmap

Everything documented above ships today: the deterministic rule pack you can search on this page, SARIF, waivers, the optional ML layer (three tiers of prompt-injection detection on agentic surfaces, tagged origin: ml, with a fine-tuning recipe in training/), and the LLM-as-judge verifier. Next up, roughly in order: more cloud and Kubernetes rules, PR design-diffing, and richer drift telemetry adapters. Issues and contributions are welcome on GitHub.