vaara

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="docs/vaara-wordmark-dark.png">
    <img src="docs/vaara-wordmark-light.png" alt="Vaara" width="900">
  </picture>
</p>

<p align="center">
  <a href="https://pypi.org/project/vaara/"><img src="https://img.shields.io/pypi/v/vaara.svg" alt="PyPI"></a>
  <a href="https://github.com/vaaraio/vaara/blob/main/LICENSE"><img src="https://img.shields.io/pypi/l/vaara.svg" alt="License"></a>
  <a href="https://github.com/vaaraio/vaara/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/vaaraio/vaara/ci.yml?branch=main&label=tests" alt="CI"></a>
  <a href="https://scorecard.dev/viewer/?uri=github.com/vaaraio/vaara"><img src="https://api.scorecard.dev/projects/github.com/vaaraio/vaara/badge" alt="OpenSSF Scorecard"></a>
  <a href="https://www.bestpractices.dev/projects/12612"><img src="https://www.bestpractices.dev/projects/12612/badge" alt="OpenSSF Best Practices"></a>
  <a href="https://huggingface.co/spaces/vaaraio/vaara"><img src="https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Space-blue" alt="Hugging Face Space"></a>
</p>

Vaara is an open-source evidence layer for AI governance: it gates each agent tool call against your policy, writes an offline-verifiable execution record, and binds that record to the machine's own TPM 2.0 + IMA attestation. When a regulator, an auditor, or a public-sector buyer needs proof of what your agent actually did and why, that record is the answer. Runs entirely in your own environment. No SaaS, no telemetry.

EU AI Act Article 12 record-keeping is the driver. The same trail answers any "show me exactly what the agent did" demand: procurement validation, incident reconstruction, SOC 2 evidence.

- Article-level EU AI Act evidence report, honest about the gaps instead of rubber-stamping them.
- Hash-chained, tamper-evident audit trail an outside party can verify without trusting your stack, with the chain head anchorable to an external trusted timestamp (RFC 3161 / eIDAS).
- Gate every agent tool call against your own policy: allow, block, or escalate.

## How it works

Every tool call an agent makes passes through Vaara before it runs:

1. **Intercept.** Vaara catches the call (`fs.write_file`, `tx.transfer`, an MCP `tools/call`, and so on) through your framework's own hook, or transparently as an MCP proxy in front of an upstream server.
2. **Score and decide.** Each call gets a risk score and an allow / block / escalate decision against your policy.
3. **Record.** The call, the score, the decision, and the real-world outcome are written to a hash-chained audit trail. An outside auditor can verify the chain is intact without trusting your stack or your word.

The scoring blends five expert signals and keeps adapting as outcomes come back, and each risk score carries a confidence interval with a coverage guarantee that holds regardless of the input distribution. Those are the properties an auditor can check independently; the math is in [Benchmarks](#benchmarks) and [docs/formal_specification.md](docs/formal_specification.md).

### External time anchor

The hash chain proves order and integrity but not *when* it existed: every timestamp comes from your own clock, so a compromised signing key could in principle be used to forge a backdated chain. Vaara can anchor the current chain head to an external RFC 3161 Time-Stamp Authority, the standard behind eIDAS qualified electronic timestamps. The authority signs the chain head and the time, so the chain's existence is provable against a clock you do not control. Verification is offline.

```bash
pip install 'vaara[timeanchor]'
```

```python
from vaara.audit.timeanchor import RFC3161TimeAnchorClient

# Periodically, or after a batch of high-risk actions:
trail.anchor_head(RFC3161TimeAnchorClient("https://freetsa.org/tsr"))
```

The anchor also folds into the one-command regulator package: `vaara trail export-article12 --anchor-tsa https://freetsa.org/tsr` writes the timestamp beside the signed trail as Article 19 existence-in-time evidence, and `vaara trail verify-anchor --zip <package>.zip` checks it offline.

The same command folds cross-org handoffs and confidential-VM enforcement evidence into the package as verified sidecars (`--handoffs ./handoffs --enforcements ./enforced`); an attachment that does not verify fails the export, so the package never ships evidence it cannot back. It is a more complete pack, not a certificate. See [docs/verifying-evidence.md](docs/verifying-evidence.md).

## Install

```bash
pip install vaara
```

Python 3.10+. Zero runtime deps. Optional XGBoost classifier: `pip install vaara[ml]`. Releases ship with SLSA Build Level 3 provenance, verifiable via `slsa-verifier verify-artifact`.

## Quick start

```python
from vaara.pipeline import InterceptionPipeline

pipeline = InterceptionPipeline()
result = pipeline.intercept(
    agent_id="agent-007",
    tool_name="fs.write_file",
    parameters={"path": "/etc/service.yaml", "content": "..."},
    agent_confidence=0.8,
)
if result.allowed:
    pipeline.report_outcome(result.action_id, outcome_severity=0.0)
else:
    print(result.reason)
```

`report_outcome` closes the loop: the signal weights reweight based on which ones predicted the outcome.

## What evidence looks like

`vaara compliance report --format json` against a real audit trail produces an article-level evidence record an auditor can read directly. Articles without recorded events return `evidence_insufficient`, not a rubber-stamp.

```json
{
  "system_name": "Acme HR Assistant",
  "overall_status": "evidence_insufficient",
  "trail_integrity": {"size": 105, "chain_intact": true},
  "articles": [
    {"article": "Article 12(1)", "title": "Record-Keeping (Logging)",
     "status": "evidence_sufficient", "strength": "strong", "evidence_count": 105},
    {"article": "Article 15(1)", "title": "Accuracy, Robustness and Cybersecurity",
     "status": "evidence_insufficient", "strength": "absent", "evidence_count": 0}
  ]
}
```

Each verdict carries the threshold-vs-observed snapshot, the rationale, and the underlying audit records, so a reviewer can trace `status` back to a concrete event without re-running the engine. The same data renders as a styled PDF for Notified Bodies (`--format pdf`, needs `vaara[pdf]`), a static HTML dashboard (`vaara compliance dashboard`), or a Sigstore-signed handoff envelope (`vaara trail export`, optional ML-DSA-65 / FIPS 204 post-quantum signer via `vaara[pq]`).

## Verify the evidence

Producing the trail is half the job. The other half is letting someone who does not trust you check it, with no key, no access to your system, and none of your software. Every verifier below reads the wire format, is fail-closed on authenticity, and ships with public conformance vectors plus a standalone checker that imports no Vaara code, so an independent party reproduces every verdict offline. That property is the point of the standards work behind [SEP-2828](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2828): the evidence is verifiable by someone who runs none of your software.

```bash
vaara verify-bundle evidence-bundle.json
```

| Command | What it checks |
|---|---|
| `verify-bundle` | One evidence bundle through six lenses (identity, signature, back-link, inclusion, consistency, revocation). `ok` only when the signature is actually established, not merely present in a log. |
| `build-bundle` | The issuer side: assembles the exact document `verify-bundle` reads, so producing and checking is one closed loop over one file. |
| `verify-record` | The SEP-2828 wire format of any record, including one Vaara never produced. Keyless: the result commitment is the SHA-256 of the bytes beside it. |
| `conformance-statement` | A producer proves its records conform against the published corpus, naming the exact corpus version and digest. |
| `verify-retained` | A record under a key that has since rotated out, over the Article 12 retention window. |
| hybrid PQC signing (`pq_verdict`) | A receipt's parallel ML-DSA-65 / FIPS 204 signature over the same preimage, for records that must outlive classical crypto. The suite is committed in the signed bytes, so stripping the post-quantum signature is a detectable downgrade, not a silent loss. |
| `build-handoff` / `verify-handoff` | A self-contained package one org hands another org's regulator, offline, years later, under a rotated-out key. |
| `verify-enforcement` | Binds a record to an AMD SEV-SNP confidential-VM attestation report. |
| `verify-records`, `verify-bundles`, `verify-handoffs`, `verify-enforcements` | The set-level forms: each single-file check run over a whole directory, with a roll-up. |
| `audit-summary` | Renders the conformance verdict for a directory as a Markdown page an auditor reads directly. |

Each verifier is honest about where trust comes from: content-addressing proves only that a package is internally consistent, producer identity is pinned out of band, an enforcement binding is never called `attested` in this release, and the eIDAS time anchor is the one component a holder cannot forge. Every command ships a Vaara-free checker under `tests/vectors/` that reproduces its verdicts offline. The full trust model for each verb is in [docs/verifying-evidence.md](docs/verifying-evidence.md).

## Benchmarks

Held-out test recall **84.7%** (95% Wilson [82.4, 86.7]) at a **4.1%** false-positive rate, and **1.2%** FPR on benign tool calls under live injection pressure. The hot-path rule scorer adds 140 µs mean / 210 µs p99 per call on commodity CPU. Every figure is reproducible end-to-end via `make bench`.

<details>
<summary>Full numbers, corpus, calibration, and chain of custody</summary>

- 12,155-entry adversarial corpus (250 hand-curated + 11,905 LLM-generated), 70/15/15 split stratified by (category, source)
- Classifier v9 (236 hand-features + 384-dim MiniLM embeddings) at cal