Metadata-Version: 2.4
Name: attestral
Version: 0.19.0
Summary: Continuous, audit-ready security design review for cloud and agentic systems
Author: Attestral
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: design-review,kubernetes,mcp,prompt-injection,security,terraform,threat-modeling
Requires-Python: >=3.10
Requires-Dist: click>=8.1
Requires-Dist: pyyaml>=6.0
Provides-Extra: deberta
Requires-Dist: torch>=2.2; extra == 'deberta'
Requires-Dist: transformers>=4.44; extra == 'deberta'
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff<0.16,>=0.15; extra == 'dev'
Provides-Extra: llm
Requires-Dist: anthropic>=0.40; extra == 'llm'
Provides-Extra: ml
Requires-Dist: torch>=2.2; extra == 'ml'
Requires-Dist: transformers>=4.44; extra == 'ml'
Provides-Extra: onnx
Requires-Dist: numpy>=1.24; extra == 'onnx'
Requires-Dist: onnxruntime>=1.17; extra == 'onnx'
Requires-Dist: tokenizers>=0.19; extra == 'onnx'
Requires-Dist: transformers>=4.44; extra == 'onnx'
Provides-Extra: sign
Requires-Dist: cryptography>=42; extra == 'sign'
Provides-Extra: terraform
Requires-Dist: python-hcl2>=4.3; extra == 'terraform'
Description-Content-Type: text/markdown

# Attestral

[![PyPI](https://img.shields.io/pypi/v/attestral)](https://pypi.org/project/attestral/)
[![CI](https://github.com/attestral-labs/attestral/actions/workflows/ci.yml/badge.svg)](https://github.com/attestral-labs/attestral/actions/workflows/ci.yml)
[![Python](https://img.shields.io/pypi/pyversions/attestral)](https://pypi.org/project/attestral/)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)

**The security scanner for AI agents and MCP servers.**

<p align="center">
  <img src="examples/vulnerable-agent/demo.gif"
       alt="attestral scan flagging an insecure MCP agent config in seconds"
       width="820">
</p>

<!-- RESEARCH POST: "We scanned N popular MCP servers" - link TBD -->

Your agent has a shell, a browser, your database, and a Slack token. Each tool is fine on its own. Together they are one injected sentence away from walking your secrets out the door. Attestral is the scanner that reads the *whole* picture.

It parses your MCP configs, agent instructions, system prompts, tool descriptions, and **agents defined in code** (LangGraph, CrewAI, the OpenAI Agents SDK, raw Anthropic/MCP tool definitions), builds a single **system model** of the fleet, and reviews the agentic surfaces every other scanner walks right past: prompt injection, tool poisoning, excessive agency, memory poisoning, and the **toxic flows** that only exist across servers. A shell tool and an egress tool are one injected sentence apart whether they were declared in `.mcp.json` or three `@tool` functions, and Attestral sees the flow either way. It models your cloud (Terraform) and Kubernetes in the *same* graph, so it sees the trust boundary between the agent and the infrastructure it can reach, not each in isolation.

Three layers, and every finding is labeled by which one found it: **deterministic rules** (always on, no eval, fails closed), an optional **local ML classifier** for injection text, and an optional **LLM-as-judge** to cut false positives. Every finding lands in a **tamper-evident SHA-256 evidence chain** you can hand an auditor and verify offline. No account, no server, no telemetry.

```bash
pip install attestral
attestral scan ./my-project
```

## Scan the MCP servers you've already installed

No repo needed. Audit the MCP servers your agent tools are already wired to:

```sh
attestral scan --local           # full report: inventory + every finding
attestral scan --local --card     # a compact, screenshot-ready self-audit card
```

Discovers and scans configs from Claude Code (user scope, project `.mcp.json`, and the current project's local scope inside `~/.claude.json`), Claude Desktop, Cursor, VS Code, and Windsurf. It reports which sources were found vs absent and how many servers each contributed, prints an inventory of the agent tool surface it reviewed, and runs everything through the same rule pipeline as a repo scan.

`--card` answers one question in one screen: does your installed fleet assemble the lethal trifecta, yes or no. It is honest by construction, a single-server machine is told the cross-surface checks could not fire (a thin result, not a clean bill of health), and a genuinely clean machine gets a clean result rather than a manufactured scare.

## Get started in one command

```sh
attestral init      # scaffold CI, pre-commit, a waivers file, and a Claude Code skill
attestral scan .    # review the current project - prints straight to your terminal
```

`attestral init` writes four onboarding files, and **never overwrites anything that already exists** (existing files are skipped and reported):

| File | What it does |
|---|---|
| `.github/workflows/attestral.yml` | Gates every PR in CI and uploads findings to the Security tab. |
| `.pre-commit-config.yaml` | Runs attestral on every commit (see [pre-commit](#run-attestral-on-every-commit)). |
| `attestral-waivers.yaml` | Starter for documented, expiring exceptions. |
| `.claude/skills/attestral-review/SKILL.md` | Makes Attestral a review reflex in Claude Code: it knows to scan when you add or edit an MCP server, agent prompt, or tool. |

### Use it inside Claude Code

Attestral also ships as a Claude Code plugin, so the review reflex travels with you across projects:

```
/plugin marketplace add attestral-labs/attestral
/plugin install attestral@attestral-labs
```

The plugin's `attestral-review` skill runs `attestral scan` when your agent's attack surface changes (a new MCP server, tool, or system prompt), then explains the findings and how to gate them. `attestral init` scaffolds the same skill into a single repo; the plugin makes it available everywhere.

### Zero config: point it at a repo

No model file, no setup. `attestral scan .` autodiscovers the Terraform, the Kubernetes manifests, the `.mcp.json`, the agent instructions and A2A cards in a repo and reviews them in one graph. Every scan opens with what it found and, honestly, what it did not read, so a clean result reads as "clean", never "it didn't look":

```
Reviewed 6 components across 2 source files: 6 agent / MCP surface
Design review, not SAST: reads declared config and agent wiring, not arbitrary application logic.
```

### Terminal-first output

`attestral scan` prints a colour-coded, severity-grouped review straight to your terminal and **writes nothing to disk by default** - no more `attestral-report.*` files littering your repo. Ask for report files explicitly, with `-o` (a file stem) or `--format`:

```sh
attestral scan .                          # print only - nothing is written
attestral scan . -o review                # write review.md + review.json
attestral scan . --format sarif -o out    # write out.sarif for GitHub Code Scanning
attestral scan . --format aibom -o inv    # write inv.cdx.json - a CycloneDX 1.6 AI-BOM
attestral scan . --quiet --fail-on high   # CI: just the summary + gate line, exit 1 on high+
attestral scan . --baseline attestral-baseline.json   # first run records; later runs show only net-new
```

The AI-BOM is the inventory counterpart to the findings: every MCP server, subagent, A2A endpoint, and instruction surface in the scan as a CycloneDX 1.6 component or service - with pinned-package purls, capability classes, canonical manifest hashes, and the `authenticated` flag on remote endpoints - ready for the compliance and procurement workflows that consume SBOMs today.

`--quiet` drops the per-finding detail and prints only the summary and gate (nothing at all on a clean scan). Colour is emitted only to an interactive terminal and is suppressed under `NO_COLOR` or when the output is piped, so CI logs and pipes stay plain.

### Explain any rule

```sh
attestral explain ATL-103    # title, severity, description, fix, and framework refs
```

Every finding in the terminal output carries a `run: attestral explain <RULE_ID>` pointer, so the reasoning and the fix are one command away. Rule ids are matched case-insensitively.

## What it catches (265-rule pack)

| Area | Examples |
|---|---|
| **Agentic / MCP** (OWASP LLM Top 10, MCP research, 2026 CVEs) | shell-capable servers, broad filesystem roots, non-TLS transport, secrets in env, auto-installed packages (supply chain), mutable `@latest` tags (rug-pull), outbound-fetch/browser tools, auto-approved actions, unauthenticated remote servers, confused-deputy credential holders, known-CVE package versions (e.g. mcp-remote CVE-2025-6514), known-CVE versions in the agent's own dependency manifest (requirements.txt / pyproject / package.json, e.g. langchain-core "LangGrinch" CVE-2025-68664), hook config-injection in `.claude/settings.json` (CVE-2025-59536) |
| **Memory / context poisoning** (OWASP ASI06, agent-security SoK) | world-writable agent-instruction files (CLAUDE.md, `.cursorrules`, AGENTS.md) that anyone can rewrite to steer every future run; persistent memory / vector stores as memory-poisoning targets |
| **Agent skills** (SKILL.md) | packaged, auto-loaded skills that grant shell or wildcard tool access (excessive agency in a shareable artifact); skill text scored for injection like any instruction file |
| **ML layer** (`attestral[ml]`) | prompt-injection / jailbreak text in MCP tool & server descriptions, system prompts, and agent-instruction files |
| **AWS** (CIS-grounded) | public S3/RDS/Redshift, `0.0.0.0/0` security groups, wildcard IAM, unencrypted RDS/EBS/EFS/Neptune, disabled backups, KMS rotation off, public EC2/EKS, CloudTrail gaps, mutable ECR tags, plaintext ELB listeners |
| **Azure** (CIS-grounded) | public blob access, non-HTTPS storage, storage TLS < 1.2 and no infrastructure encryption, public SQL, wildcard NSG rules, Key Vault purge protection off / public network access, Postgres/MySQL SSL not enforced, Postgres flexible server public access, SQL database TDE off, App Service not HTTPS-only, VM password auth, AKS local accounts enabled |
| **GCP** (CIS-grounded) | `0.0.0.0/0` firewall rules, public Cloud SQL, SQL without SSL, public bucket IAM (`allUsers`), bucket uniform-access off, KMS keys without rotation, Compute cloud-platform scope / IP forwarding / non-Shielded VMs, GKE legacy ABAC, non-private nodes, non-Shielded nodes, client-cert auth |
| **Kubernetes** (CIS K8s) | privileged containers, privilege escalation, dangerous capabilities, run-as-root, host network/PID, hostPath mounts, missing resource limits, mutable image tags |
| **Cross-cutting / toxic flows** (fleet-level, only visible in a system model) | lethal-trifecta capability combos (private data + egress), the same flow as a formal **information-flow lattice property** (confidentiality/integrity labels, ATL-217) that *clears* when you apply the recommended mitigation (an egress allowlist or a human-approval gate) while the heuristic still fires, unsafe data flow (untrusted input → code execution, with named source/sink servers and taint edges), shell + network reach, cross-server tool shadowing (tool-name collisions, steering descriptions, server-identity conflicts), agent runtime and cloud sharing no declared boundary controls |

Every finding maps to NIST 800-53, ASVS, SOC 2, CIS (AWS/Azure/GCP/K8s), OWASP LLM/Agentic, and MITRE ATLAS references. The agentic checks are additionally mapped to the attack/risk taxonomy of the agent-security SoK (Kim et al. 2026) in [docs/agentic-threat-model.md](docs/agentic-threat-model.md).

**Recall you cannot self-grade.** The in-repo benchmark scores 116/116, but its labels come from our own fixtures. So we also measure against eleven published 2025-2026 CVE advisories labelled from the advisory, not our output ([`evaluation/external-recall.md`](evaluation/external-recall.md)): that number is allowed to fall below 100% and does, with every miss itemised and a concrete path to close it.

## How a scan works (the pipeline)

```mermaid
flowchart TB
    subgraph ING["1 · Ingest"]
        TF["Terraform (.tf)<br/>vars · locals · local modules resolved"] --> M
        K8S["Kubernetes<br/>manifests (.yaml)"] --> M
        MCP["MCP configs<br/>(mcp.json, JSONC-tolerant)"] --> M
        SP["System prompts, agent instructions<br/>(CLAUDE.md/.cursorrules), skills (SKILL.md)<br/>+ tool descriptions"] --> M
        AC["Agent settings + hooks, subagents,<br/>A2A agent cards (.claude/**, .well-known/)"] --> M
        CODE["Agent code (.py)<br/>@tool functions, Anthropic/MCP tool defs,<br/>LangGraph · CrewAI · OpenAI Agents SDK"] --> M
        DEP["Dependency manifests<br/>(requirements.txt · pyproject · package.json)<br/>known-CVE version match"] --> M
        GW["Credential broker config<br/>(agentgateway · CB4A)<br/>fail-open · inlined secret"] --> M
        DENV["Deployment env<br/>(docker-compose · .env)<br/>credential concentration"] --> M
        LC["Installed agent configs<br/>(scan --local)"] --> M
        M["SystemModel<br/>components · edges · trust boundaries"]
    end
    M --> L1
    subgraph REV["2 · Review (layered, each finding tagged by origin)"]
        L1["<b>L1 Deterministic rules</b><br/>265 typed matchers · fail-closed<br/>+ cross-server attack path synthesis<br/>+ cross-repo fleet toxic-flow detection<br/>+ information-flow lattice (IFC labels)<br/>+ OWASP AIVSS agentic risk score<br/>origin: deterministic"]
        L2["<b>L2 ML classifier</b> (optional)<br/>DeBERTa prompt-injection on agentic surfaces<br/>origin: ml"]
        L3["<b>L3 LLM</b> (optional)<br/>elicitation + LLM-as-judge verifier<br/>origin: llm"]
        L1 --> L2 --> L3
    end
    REV --> RS["Reachability-based severity<br/>finding on a walked attack chain:<br/>chain attached · raised one band"]
    REV --> BR["Blast-radius scoring<br/>rank every surface by if-compromised reach<br/>feeds the OWASP AIVSS score"]
    REV --> IR["Injection-reachability fusion<br/>escalate an injectable surface only when it<br/>can reach a secret, egress, or code execution"]
    REV --> TA["Trust-asymmetry<br/>raise a tool-name collision when a lower-trust<br/>server can shadow a trusted tool"]
    RS --> W["Waivers + inline suppression<br/>documented exceptions · one-line // attestral:ignore"]
    BR --> W
    IR --> W
    TA --> W
    W --> BL["Baseline<br/>diff-aware: report only net-new findings"]
    BL --> EV["3 · Evidence<br/>SHA-256 hash chain · verify offline<br/>+ optional Ed25519/DSSE signed head"]
    EV --> OUT["Output: Terminal (default, writes nothing) · Markdown · JSON · <b>SARIF</b> (Code Scanning) · <b>AI-BOM</b> (CycloneDX 1.6)"]
    style L1 fill:#0a7d3611,stroke:#0a7d36
    style L3 fill:#96222E11,stroke:#96222E
```

| Layer | What it does | Reproducible? | Cost |
|---|---|---|---|
| **L1 Deterministic** | 265 typed matchers over the model, fail-closed (unknown matcher never matches), plus cross-server attack-path synthesis | Yes, fully | Free, offline |
| **L2 ML** (optional) | Scores agentic text surfaces (MCP tool/server descriptions, system prompts, embedded MCP Apps HTML bodies) for prompt injection / jailbreaks. Three tiers: zero-dep heuristic (default), ONNX (`attestral[onnx]`, model-grade, no torch), or DeBERTa (`attestral[ml]`) | Pinned model + revision | Free, offline after first cache |
| **L3 LLM** (optional) | Elicits novel design threats, and a judge cross-examines findings to cut false positives | Verdicts recorded in the chain | Your API key |

Every finding carries its `origin`, so the deterministic core is never silently mixed with model reasoning. That separation is what makes the review audit-grade.

**Severity you can defend.** When a finding's component sits on an attack chain the symbolic walk shows reachable (a way in, a way to run code, a way out), the finding carries that chain and is raised one severity band - never above the chain's own severity:

```
HIGH (3)
  ATL-107  MCP server grants outbound network or browser access  (mcp_server.web)
    path: internal chain: web -> ops -> web · this component: entry+impact · raised from medium
```

A raised HIGH ships with the entry → pivot → impact path that justifies it, so it is trusted rather than argued with. The inverse move is deliberately never made: a finding off every chain is not downgraded, because the absence of a modeled path is not evidence of safety.

## The sophistication layers (optional)

```bash
# ML prompt-injection scan of agentic text surfaces (MCP tool/server descriptions,
# system-prompt files, embedded MCP Apps HTML bodies). Hits are tagged origin: ml
# and flow into the same evidence chain.
# The zero-dep heuristic tier runs on EVERY scan by default (no flag, no install);
# --ml opts into the model-grade tiers. Three tiers:
#   heuristic  zero-dependency, instant, ships in core     <- the default, always on
#   onnx       model-grade DeBERTa via onnxruntime, no torch, ~276 MB   <- recommended upgrade
#   deberta    heaviest, fine-tunable, pulls torch (~700 MB+)
# `--ml` selects engine `auto` (precedence onnx -> deberta -> heuristic); a missing
# extra is never an error, it just falls back. `--no-ml` turns the layer off entirely.
attestral scan ./my-project                               # heuristic tier already included
pip install "attestral[onnx]"                             # add the light, accurate ONNX tier
attestral scan ./my-project --ml --ml-engine onnx         # weights auto-download once, offline after
# custom or air-gapped model? run scripts/export_onnx.py, then set ATTESTRAL_ML_MODEL=/path
attestral scan ./my-project --ml --ml-threshold 0.7       # tune sensitivity

# LLM threat elicitation on top of the deterministic layer
export ANTHROPIC_API_KEY=...
attestral scan ./my-project --llm

# LLM-as-judge: cross-examine findings to cut false positives.
# Verdicts (confirmed / false_positive / needs_review) are recorded in the chain.
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          # auto-waive confident false positives, on the record
```

The judge never deletes a finding. A confident `false_positive` becomes a machine-generated waiver carrying the judge's reasoning: suppressed from the gate, but kept on the record.

Every finding also carries a static **confidence** (high / medium / low). Deterministic rules are high by contract - structural facts with zero false positives on the benign corpus - while the ML tier's confidence tracks its probability. `attestral scan --min-confidence high` keeps only that CI-safe set and reports what it dropped, so you can fail a build on the findings that cannot be wrong and leave the probabilistic ones for a human. For the individual false positive, a one-line `// attestral:ignore ATL-xxx reason: ...` marker in the config waives it in place (kept in the evidence chain, not hidden). The benign zero-FP promise is a gated test, not a claim; see [`docs/false-positive-budget.md`](docs/false-positive-budget.md).

### Tuning / training the ML layer

The ML layer ships pointed at a DeBERTa classifier already fine-tuned for prompt injection, so **start zero-shot** (`--ml`, no training). If you need to adapt it to your own surfaces, climb three tiers - use as-is, calibrate the `--ml-threshold` on your labeled data, then fine-tune only if a gap remains. A runnable recipe (fine-tune + threshold-calibration scripts, data format, and where to source training data) lives in [`training/`](training/README.md).

## Baseline and waivers

Real repos start with findings. A waiver accepts a known risk and keeps the gate green without hiding anything: the waived finding stays in the evidence chain with its justification, and becomes a SARIF suppression (GitHub shows it dismissed, not open).

```yaml
# attestral-waivers.yaml  (auto-discovered at the scan root)
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
```

Fail-safe: a waiver with no `reason` is ignored, and an expired waiver stops suppressing. A finding can only be silenced by a current, justified exception.

### Accepting a risk is itself an audit record

Prefer `attestral accept` over hand-editing the YAML - it writes the waiver with provenance and a content pin:

```bash
# one line, copied from the finding in the scan output
attestral accept . ATL-104 mcp_server.jira -r "Secrets rotated nightly; tracked in SEC-1234." --expires 2026-12-31
```

The recorded entry says **who** accepted the risk (your git identity), **when**, **why**, and **what** was accepted - a `finding_sha256` pin over the rule, component, severity, and reachable chain as they were at acceptance. The suppressed finding carries that provenance into the evidence chain, so an auditor reads "this engineer accepted this risk on this date with this justification" straight from the record.

The pin is what keeps the acceptance honest: if the risk itself changes - a rule wave re-rates the finding, or a new tool completes an attack chain through the component and reachability raises its severity - the pin stops matching, the scan reports the acceptance as stale, and the finding comes back until someone re-accepts the *current* risk. You accepted a medium; you did not accept the high it became.

## The flow that spans repos: `attestral fleet`

Agentic risk lives in the *integration*. A shell tool in one repo and an untrusted-input tool in another are each fine on their own; together they are an attack chain. No per-repo scanner can see that, because each repo is clean in isolation. `attestral fleet` models several repos as **one** system:

```bash
attestral fleet ./data-agent ./ops-agent ./notify-agent
```

```
Fleet: 3 repos
  data-agent    2 components · reach: network, saas_data
  ops-agent     1 components · reach: shell
  notify-agent  1 components · reach: messaging

cross-repo chain: entry [data-agent] -> pivot [ops-agent] -> impact [notify-agent]
```

It merges every repo into one graph (tagging each component with its repo), then runs the full review over the union. When the fleet's combined capabilities complete an attack chain that **no single repo completes alone**, it fires **ATL-213** and names which repo supplies the entry, the pivot, and the exfiltration. Reachability escalation follows: a medium finding in one repo is raised to high because *another* repo is what completes its chain. This is the one thing a single-file scanner structurally cannot answer, and it is the point of building a system model in the first place.

## Beyond findings: prove it, enforce it, verify it

A scanner stops at a list of findings. Attestral turns the reviewed design into a tamper-evident record and a runtime policy: the depth that makes the review audit-grade, and the reason it can't be trivially cloned. Attest the design, prove the record has not been altered, compile it into a default-deny runtime policy, and detect when what runs diverges from what was reviewed. The whole loop runs offline, on a laptop, free.

### Integrity, and now authenticity

The SHA-256 chain is **tamper-evident**: edit any past finding and every later hash, and the head, stop matching. On its own that proves the chain is internally consistent, not that it is the chain *you* sealed, an attacker could edit a finding, recompute the whole chain and a new head, and `verify` would still say VALID. `attestral sign` closes that with an **Ed25519 signature over the head, wrapped in a DSSE envelope** (the same envelope Sigstore and in-toto use). Now `attestral verify --public-key` checks both: integrity (no entry altered) *and* authenticity (this is the chain the key holder sealed, not a recomputed forgery). Signing needs the `attestral[sign]` extra; the integrity check still runs with zero dependencies.

### Verifiable conformance attestation

`attestral attest` is the capstone: it binds, into one DSSE-signed [in-toto](https://in-toto.io) Statement, the reviewed design (model hash), the review chain head, a digest and severity summary of the findings, the hash of **both** compiled policies (mcp-guard **and** Cedar), and, with `--runtime`, a digest of the runtime events plus the drift verdict (CONFORM, or the list of DRF ids). `attestral attest --verify` recomputes every one of those digests offline from the supplied design, re-runs drift on the supplied events, and checks the signature, so any tamper - a changed design, a swapped policy, a doctored event stream - makes verification **FAIL**, and names the failing step. The structure and every hash recompute run with zero dependencies; only the signature step needs the `attestral[sign]` extra, so an unsigned attestation (all digests still bound) is produced with no install.

One attestation proves one moment. `attestral attest --log conformance.log` makes conformance **monitorable over time**: each attestation is appended to an append-only transparency log (an RFC 6962 Merkle tree, one JSONL file, zero dependencies), every append records the tree root it produced, and `attest --verify --log` proves both that the bundle is in the log (a portable inclusion proof, verifiable without the log file) and that the recorded history is internally consistent - editing any past entry breaks every later checkpoint. A deployment gains an auditable answer to "did this system stay conformant, and when did it drift?" The honest boundary is stated in the output: a self-hosted file proves append-only history, not distributed witness, so publish the head root somewhere you do not control (a commit, Sigstore Rekor - the leaf is a plain SHA-256 of the DSSE bundle, exactly what Rekor logs) and a rewrite has an external copy to contradict.

```bash
attestral attest . --log conformance.log            # attest and append to the log
attestral attest . --verify --log conformance.log   # verify bundle + history + inclusion
```

This is a **tamper-evident, signature-based conformance attestation, not a formal or mathematical proof of security** - the same class of artifact as SLSA's Verification Summary Attestation. It proves exactly one thing: the runtime observed matches the design that was reviewed and the policies compiled from it. It does **not** prove the design is safe, the rule pack is complete, or that no vulnerability exists; a clean attestation over a weak design is still a weak design. The novel contribution is that a third party - an auditor, a platform, another agent - can verify offline, without trusting the runtime or the scanner, that the running system is the one reviewed and that drift (including DRF-008) either did not occur or is recorded honestly in the signed verdict. See [docs/attestation.md](docs/attestation.md) for the full shape and the copyable flagship sequence.

### The loop in one picture

```mermaid
flowchart LR
    A["attestral scan<br/><b>attest</b>"] --> B["attestral verify<br/><b>prove</b>"]
    A --> R["attestral remediate<br/><b>concrete source edit</b>"]
    A --> F["attestral fix<br/><b>compile-the-fix</b>"]
    A --> C["attestral compile<br/><b>enforce</b><br/>+ --verify: prove policy properties"]
    C --> D["attestral drift<br/><b>detect</b>"]
    D --> AT["attestral attest<br/><b>signed conformance attestation</b><br/>+ --log: append-only transparency log"]
    AT -->|"verify offline"| B
    D -->|"design changed?<br/>re-attest"| A
    A --> V["attestral validate<br/><b>show the path is reachable</b><br/>+ proof-of-exploit per path (gated)"]
    A --> DF["attestral diff<br/><b>PR security-impact delta</b>"]
    style A fill:#96222E,color:#fff
    style B fill:#1F6A4A,color:#fff
    style F fill:#96222E11,stroke:#96222E
    style V fill:#96222E11,stroke:#96222E
    style AT fill:#96222E,color:#fff
```

Two commands answer "so what do I do about this finding" from both ends. `attestral remediate` reads the rule's own matcher and the component's real value and prints the **concrete source edit** to make: the boolean flag to flip (`set publicly_accessible = false`), the bad value to replace (`http://… -> https://…`), the control to add, tied to the file it lives in. `attestral fix` compiles the exact **enforceable control** that closes the finding, bound to the review's chain head, with a verification verdict: a fleet finding is proven closed by re-synthesizing the model without the isolated capability (`re-synthesized`), and a per-server finding gets the mcp-guard constraint that governs it at the proxy (`enforced-at-proxy`). A remediation that is *also* an enforceable runtime control is the payoff of the attest-compile-drift loop, and the thing a linter structurally cannot offer.

`attestral drift --remediate` closes the loop the other way, the self-healing half: **detect -> propose the tightening -> a human approves -> re-compile.** A drift finding means the runtime diverged from the *reviewed* design, so remediation synthesizes the minimal policy delta that would have prevented each finding - quarantine the offending server (`allow: false`, carrying the DRF id as the reason) - and re-emits it to **both** compiled targets (mcp-guard and Cedar). The safety principle is load-bearing and non-negotiable: it only ever **narrows** the policy toward denial, and it **never widens** the design to match the drift, because widening would rubber-stamp the very attack the drift caught. A compromised runtime cannot drive its own policy. Every proposed delta is verified a narrowing (`narrowing.classify` must return NARROWING or UNCHANGED, never EXPANSION) *before* it is emitted, and it is a **proposal** only - nothing is applied until a human re-compiles. Terminal-first: the proposed ops and the narrowing verdict print to the terminal; the re-emitted policies are written only with `-o`.

### The four commands

```mermaid
flowchart LR
    subgraph scan["attestral scan"]
        s1["Terraform + MCP"] --> s2["findings + evidence chain<br/>md / json / sarif"]
    end
    subgraph verify["attestral verify"]
        v1["report.json"] --> v2["VALID / INVALID<br/>(offline)"]
    end
    subgraph compile["attestral compile"]
        c1["attested model"] --> c2["default-deny policy<br/>tool manifest hashes pinned,<br/>bound to chain head"]
        c2 --> c3["narrowing check (--against)<br/>a re-attestation must not widen<br/>the reviewed capability envelope"]
    end
    subgraph drift["attestral drift"]
        d1["policy + telemetry"] --> d2["drift findings<br/>rug-pulls (DRF-005),<br/>loop / volume budgets (DRF-006/007)"]
    end
    subgraph memory["attestral memory"]
        m1["memory store + keyring"] --> m2["signed-provenance audit<br/>relabelled / tampered / unsigned<br/>trust claims (MEM-001/002/003)"]
    end
```

```bash
# SCAN: review a project (Terraform + MCP configs discovered automatically)
attestral scan ./my-project --format both          # md + json
attestral scan . --fail-on high                    # CI gate: exit 1 on high/critical
attestral scan . --min-confidence high --fail-on high  # CI-safe set only: structural, 0-FP-on-benign
attestral scan . --format sarif -o attestral       # SARIF -> GitHub Security tab + PR annotations

# VERIFY: prove a report has not been altered (no network, no server)
attestral verify review.json

# SIGN: make the chain authentic, not just tamper-evident (Ed25519 / DSSE)
attestral sign --gen-key reviewer                       # one-time: a keypair
attestral sign review.json --key reviewer.key --signer "Ada L"
attestral verify review.json --public-key reviewer.pub  # checks integrity AND authenticity

# COMPILE: turn the attested design into a default-deny mcp-guard policy
attestral compile ./my-project -o policy.yaml
# other targets: Cedar (AWS Verified Permissions) and a credential-broker config
attestral compile ./my-project --target cedar -o attested.cedar
attestral compile ./my-project --target agentgateway -o gw-policy.yaml  # CB4A default-deny broker
# and verify a later design still NARROWS the reviewed one (fails on an expansion)
attestral compile ./my-project --against policy.yaml

# DRIFT: diff runtime telemetry against the attested design
attestral drift policy.yaml events.jsonl --fail-on-drift
# and close the loop: PROPOSE the minimal tightening that would have prevented each
# drift finding, re-emitted to both targets (proposed only, always a narrowing)
attestral drift policy.yaml events.jsonl --remediate
attestral drift policy.yaml events.jsonl --remediate -o mcp-guard-policy.yaml  # + sibling .cedar

# ATTEST: bind the reviewed design, both compiled policies, and the runtime drift
# verdict into ONE signed conformance attestation a third party can verify offline
attestral attest ./my-project --runtime events.jsonl --gen-key demo --signer "Ada L" -o attestation.json
attestral attest --verify ./my-project --runtime events.jsonl --public-key demo.pub -o attestation.json

# MEMORY: bind an agent-memory entry's trust label to its content with a signature,
# so a relabelled or tampered entry is caught cryptographically (not by hoping)
attestral memory sign --content "..." --label trusted --writer alice --key alice.key -o mem.jsonl
attestral memory verify mem.jsonl --keyring writers.yaml --fail-on-untrusted

# VALIDATE: prove whether the assembled attack paths actually hold
# (tier 0: symbolic walk over the model's edges, no execution, no network)
attestral validate ./my-project
attestral validate ./my-project -o proof --fail-on-reachable   # write proof.md + chain, gate CI

# BLAST-RADIUS: rank every agent surface by its if-compromised reach, so
# hardening prioritises itself (the lethal-trifecta host rises to the top)
attestral blast-radius ./my-project

# DIFF: post the security-impact delta between two design revisions - the
# engine behind the PR-review bot (examples/github-actions/security-delta.yml)
attestral diff ./base ./head
attestral diff ./base ./head --fail-on high   # gate CI on newly-introduced risk

# FLEET: model several repos as ONE agent fleet and find flows that span them
attestral fleet ./repo-a ./repo-b ./repo-c                 # ATL-213: cross-repo toxic flow
```

### Install and run the whole loop (60 seconds)

```bash
pip install attestral

attestral scan examples/demo-project -o review        # attest  -> review.md + review.json
attestral verify review.json                          # prove   -> chain VALID
attestral remediate examples/demo-project             # remediate -> concrete source edit per finding
attestral fix examples/demo-project                   # fix     -> enforceable control per finding
attestral compile examples/demo-project -o policy.yaml # enforce -> default-deny policy
attestral drift policy.yaml examples/demo-project/runtime-events.jsonl --fail-on-drift  # detect
```

## Real-world benchmark

Run on [TerraGoat](https://github.com/bridgecrewio/terragoat) (Bridgecrew's deliberately-vulnerable Terraform), same repo, as the rule pack grew (the pack is **265 rules** today; this table shows the historical progression, not the current pack size):

| | TerraGoat AWS | TerraGoat Azure | TerraGoat GCP | Distinct rules |
|---|---|---|---|---|
| v0.4.0 (10 rules) | 3 | - | - | 3 |
| v0.6.0 (57 rules) | 7 | 2 | 3 | 12 |
| v0.9.0 (169 rules) | **8** | **3** | **5** | **16** |

The pipeline (ingest, evidence chain, tamper detection, gate, SARIF) is verified on real code. One honest caveat: TerraGoat leans heavily on Terraform variables and modules, and Attestral's HCL resolver does not yet evaluate cross-variable interpolation, so a chunk of TerraGoat's misconfigurations sit behind `var.` references the scanner can't see through yet. The TerraGoat number is therefore a **floor** gated by HCL-resolution depth, not a measure of the 163-rule cloud pack's reach. Deeper HCL resolution is on the roadmap; when it lands, these numbers jump without adding a single rule.

## What it does not do

A tool you can trust is one that is honest about its edges. Attestral is a **design review, not a SAST tool**: it reads the declared surface (config, agent wiring, prompts, IaC) and reasons over the system model, but it does not read the inside of a tool's implementation, execute anything against your live agent, or prove exploitability (a reachable path is necessary, not sufficient). It has known blind spots too: HCL cross-variable resolution depth, coarse capability classification, a probabilistic ML tier, and agent-code ingestion that needs a recognizable framework. The full list, including where our own detection breaks under adaptive attack, is in [`docs/limitations.md`](docs/limitations.md). We would rather state the limits than imply coverage we do not have.

## Use it in CI

```yaml
# .github/workflows/attestral.yml
name: attestral
on: [pull_request]
permissions:
  contents: read
  security-events: write        # to upload to the Security tab
jobs:
  design-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-python@v6
        with: { python-version: "3.12" }
      - run: pip install "attestral[terraform]"

      # Inline annotations on the offending line, via GitHub code scanning.
      - run: attestral scan . --format sarif -o attestral
      - uses: github/codeql-action/upload-sarif@v3
        with: { sarif_file: attestral.sarif }

      # A clean job summary rendering the reachable attack paths and the
      # findings this PR introduced (commit attestral-baseline.json first).
      - run: attestral scan . --baseline attestral-baseline.json --format md-summary -o attestral
      - run: cat attestral.summary.md >> "$GITHUB_STEP_SUMMARY"

      # Hard gate: fail only on net-new high/critical (auto-uses attestral-waivers.yaml).
      - run: attestral scan . --baseline attestral-baseline.json --fail-on high --quiet
```

The action does three things a passing check does not: SARIF puts each finding inline on the offending line, the job summary renders the reachable **entry → pivot → impact** path so a reviewer sees the story not a list, and `--baseline` gates on **net-new** findings only, so a brownfield repo adopts without failing on day-one debt. `attestral init` scaffolds exactly this; ready-made workflows also live in `examples/github-actions/`.

## Run attestral on every commit

```sh
pip install pre-commit
```

Add to `.pre-commit-config.yaml`:

```yaml
repos:
  - repo: https://github.com/attestral-labs/attestral
    rev: v0.17.0
    hooks:
      - id: attestral        # gate infra/agent config in this repo
      - id: attestral-local  # optional: audit installed MCP servers
```

Then `pre-commit install`. See `examples/pre-commit/` for details.

## Writing custom rules

Rules are YAML with structured matchers. No `eval` anywhere, and an unknown matcher fails closed (never matches).

```yaml
rules:
  - id: ORG-001
    title: Internal load balancer 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"]
```

```bash
python -c "from attestral.rules import RuleEngine; RuleEngine(['org_rules.yaml'])"
```

## Development

```bash
pip install -e ".[dev,terraform,llm]"   # add ,ml for the DeBERTa layer (pulls torch)
pytest -q                 # offline suite; the live judge test skips without a key
ruff check attestral tests
```

To run the live judge test, set `ATTESTRAL_JUDGE_API_KEY` (or `ANTHROPIC_API_KEY`) and re-run `pytest -q`.

### How a change ships

```mermaid
flowchart LR
    subgraph inner["inner loop (local)"]
        E["edit code / rules / ingesters"] --> T["pytest -q · ruff"]
        T --> S["attestral scan examples/*<br/>(eyeball real findings)"]
        S --> E
    end
    S --> PR["pull request"]
    PR --> CI["CI: lint + tests on 3.10 / 3.12<br/>+ docs-sync gate"]
    CI --> REV["CODEOWNERS review · CLA signed"]
    REV --> MAIN["main (protected: no force push,<br/>required checks)"]
    MAIN --> TAG["tag vX.Y.Z + CHANGELOG entry"]
    TAG --> PUB["publish.yml → PyPI<br/>(Trusted Publishing)"]
```

The **docs-sync gate** (`tests/test_docs_sync.py`) keeps this README honest: it
fails when a pipeline module exists that no diagram shows, when a CLI command
is undocumented, or when the package version has no `CHANGELOG.md` entry. If
you add a stage, draw it - the suite won't pass until you do.

## License

Apache 2.0.
