NoireBox v0.21.0

§Install

Python ≥ 3.11, MIT, zero telemetry. The ML guardrail engine ships inside the wheel (FR + EN detectors, ~250 KB each) — no model download at runtime.

pip install noirebox        # core: journal + API + guardrail + verifier deps
pip install noirebox[pdf]   # + PDF attestation export (reportlab)
pip install noirebox[hsm]   # + PKCS#11 key custody (python-pkcs11)

Or Docker (image includes the ML engine):

docker run -p 8768:8768 ghcr.io/noirebox/noirebox:latest
# API + OpenAPI docs on http://127.0.0.1:8768/docs — data persists in ./data

Or from source (venv + deps + tests + API):

git clone https://github.com/noirebox/noirebox && cd noirebox
./start.sh

Environment variables

§Quickstart

# 1 — run the API
noirebox serve                # http://127.0.0.1:8768 — interactive OpenAPI at /docs

# 2 — seal an event (auth off by default; enable with NOIREBOX_CLIENTS)
curl -X POST http://127.0.0.1:8768/api/v1/events \
  -H 'Content-Type: application/json' \
  -d '{"type":"llm_call","payload":{"model":"gpt-x","prompt_sha256":"…"}}'

# 3 — anchor the chain head with an external TSA witness (RFC 3161)
curl -X POST http://127.0.0.1:8768/api/v1/anchors

# 4 — export the full dossier
curl -s http://127.0.0.1:8768/api/v1/export > export.json

# 5 — verify as a third party, offline (pip install noirebox is enough)
python verifier/verifier.py export.json
# exit 0 = intact & witnesses verified · 1 = broken · 2 = anchoring unproven

One-command demos: make demo (full scene: scan → journal → auditor → caught tampering) · make demo-mcp · make demo-fleet · make demo-tamper-style standalone scripts in demo/.

§Data model

An Event is the only write shape. Types are free-form strings (1–64 chars) — llm_call, llm_output, incident, eval, anchor are conventions, not a closed enum.

Canonical serialization — any third-party reimplementation must produce the same bytes:

json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode("utf-8")

The key is Ed25519, PEM PKCS8, chmod 600, created at database init (<db>.key). The public key alone is enough to verify. Where that key lives is pluggable — see custody.

§HTTP API

FastAPI, 12 routes, interactive OpenAPI at /docs and /redoc; machine-readable spec: docs/openapi.json. Base http://127.0.0.1:8768. 🔒 = behind the bearer token when auth is enabled; verification routes are open by design.

Auth (ADR 004) — enabled only if NOIREBOX_CLIENTS is set: 1-hour JWT HS256, 60 req/min per client (sliding window, 429 + Retry-After), constant-time secret comparison. Errors: 401 (missing/invalid token) · 422 (Pydantic) · 429 (quota) · 503 (engine unavailable, actionable message) · verification failures always carry the exact seq.

§Receipts & sealed payload schemas

Beyond free-form events, subsystems seal versioned payload schemas into the same journal. Each schema version is a contract; the reconciliation layer assembles verdicts from them.

Named states, never silence: unverified_label · independence_undecidable · label_llm_call_mismatch · registry_duplicate_undecidable · scope_check_not_run — an undecidable outcome is never reported as clean, and a skipped check is reported as skipped.

The doctrine behind these schemas — who may judge what, and which verdict outranks which — is written up as the authority ladder (ADR 019–022).

§Verification contract

verifier/verifier.py — strict order, first failure wins, never contacts the server (openssl only):

1. seq of event n equals n — no gaps, no duplicates
2. prev_hash equals event_hash of event n−1
3. event_hash equals the recomputed canonical SHA-256
4. signature valid for the export public key
5. Attestation: head_seq = event count, head_hash = last event_hash, signature valid on the canonical summary
6. Each anchor event: referenced head consistent with the chain, RFC 3161 token verified (openssl ts -verify) against that hash and the embedded TSA certificate

TSA roots for public witnesses are pinned in the repository (verifier/tsa_roots/) — the auditor never trusts a certificate the operator ships. The auditing machine needs pip install noirebox, nothing else.

§Key custody & signing

Every signer answers the same interface — .sign() + .public_hex() — so custody can move without touching callers:

Custody disclosure — the journal states its own proof grade:

• noirebox custody-grade prints witness = min(authoring, retention): a journal is only as provable as the weaker of "was the writer's key in custody at seal time" and "was the retention path itself journaled"
• noirebox seal-retention --action prune|migrate|policy-change|restore — retention operations become first-class sealed events
• Custody vs anchoring are different trust boundaries and are disclosed separately (ADR 022)
• Post-quantum evidence is staged as hybrid signing behind the signer interface — classical Ed25519 stays the trust anchor while a PQ sibling rides along (ADR 027)
• The pinned hardware root remains the deployer's call — stated in the threat model, not hidden

§Anchoring & fleet

A journal that dates itself proves nothing — that's the suspect writing its own report. Anchoring lets an external Timestamp Authority sign "I received hash X at time T". Only the 32-byte head hash ever leaves. A regenerated journal shows a head the old token doesn't cover, and a backdated token is arithmetically impossible — this is the control that catches an operator with the private key.

Witness layers you choose

The anchor event payload carries head_seq, head_hash, the primary RFC 3161 token (tsr, base64 DER), the TSA cert bundle (tsa_cert_pem) and the full witness list (tokens — one token per profile + OTS receipts).

Fleet hub

One seal for the whole fleet: the heads of N journals form a Merkle tree, a single TSA seal covers them all, and each member proves its place with ~11 hashes — verified offline. noirebox fleet-anchor seals it, fleet-verify checks one member, fleet-status checks every member (exit 0 all covered / 1 alarm, --json for alerting), fleet-watch runs that on a cadence with optional re-anchoring (--reanchor shrinks the falsifiable window to the interval) and webhook alarms. The hub sees 32-byte hashes, never your events.

§Guardrails

Prevention is pluggable; proof is universal. Already running Lakera, Llama Guard, your own LLM-judge? Keep them — a guardrail is just another event source, and its verdicts become tamper-evident instead of living in rewritable logs.

Incident contract — same shape from every engine:

{
  "category": "instruction_override|data_exfiltration|pii_request|tool_abuse",
  "score": 0.94,
  "excerpt": "…≤ 120 chars…",
  "start": 214, "end": 305
}

Honest failure modes: unparsable judge output → 503, never a manufactured incident; verdicts outside the taxonomy are dropped; measured false negatives are non-zero and tracked. The bundled detector is a working example of the plugin contract — swappable by design (ADR 003: Meta's Prompt Guard evaluated and declined, integration path documented).

§Integrations

MCP server — agent tools over stdio JSON-RPC

python -m noirebox.mcp_server
# client config: {"mcpServers": {"noirebox": {"command": "python", "args": ["-m", "noirebox.mcp_server"]}}}

Agent hooks & editor

• noirebox hook tool-use / session-end — seal one tool action (PostToolUse) or the full session transcript (SessionEnd) from hook JSON on stdin; best-effort by design (ADR 013)
• noirebox seal-trajectory --rollout <dir> — seal a coding agent's model trajectory (model-io JSONL): per-line digests only, never the payload (ADR 012)
• VS Code / Cursor extension (also on Open VSX) — journal + verify from the editor; versioned separately from the package
• ZCode / Claude Code plugin — plugins/claude + plugins/noirebox in-repo

Operations

• noirebox export-siem --format cef|otlp --since N — CEF (ArcSight) or OpenTelemetry JSON, tail-only with --since
• noirebox audit-pack <outdir> — one folder for the auditor: export + verifier report + the Annexe IV §2(f) logging description (ADR 010)
• noirebox replay <meeting_id> — rebuild the decision timeline from sealed evidence; refuses if the chain doesn't verify first ("replay refuses theater")
• noirebox reconcile --config invariants.json --journal-report --fail-on-findings — invariants over the journal, CI-friendly exit 2
• noirebox crosschain --journal a=path … — consumption edges across journals, partial order, fan-in (ADR 024)
• noirebox toolset-pin --server S --tools tools.json --reviewed-by NAME --check --fail-on-drift — MCP tool descriptions are instructions: pin the baseline, diff on session start (ADR 025)
• Built-in dashboard (heatmap, traffic radar) on the service; Grafana JSON in docs/grafana-dashboard.json

§CLI reference

noirebox --version → 0.21.0. Twenty subcommands; every journal path resolves the same way (--db → NOIREBOX_DB → nearest .noirebox/ → data/noirebox.db).

§Performance & measurements

Every number is reproducible from the repo. A metric we can't reproduce means unknown, not a rounder number.

MacBook M-series, local venv — sealing/verification rows 2026-10-04. Absolute values vary with hardware; make bench on your machine is the reference.

SCAR-BENCH-114 — open-weights measurement

A published, seeded measurement protocol (docs/SCAR-BENCH.md): 120 planned trials against three local models, canary-witness scoring, raw results in-repo. Headline:

Disclosure: single machine, local Ollama, temperature 0.7, per-trial fixed seeds. Measurement, not a verdict. 4 timeouts excluded, disclosed in the results file.

§Project layout

noirebox/            the package
  chain.py store.py schemas.py       hash chain, SQLite append-only store, Pydantic models
  receipt.py reconcile.py independence.py    sealed receipts, invariants, flow independence
  anchors.py witness.py merkle.py fleet.py   RFC 3161 anchoring, fleet hub
  keyholder.py hsm.py                custody: unix-socket signer, PKCS#11
  guardrail.py ml_guardrail.py llm_judge.py tiering.py   three scan engines + tiered judge
  mcp_server.py hookcli.py trajseal.py toolset.py        agent-facing surfaces
  crosschain.py digests.py siem.py replay.py pdf_export.py c2pa.py aiact.py
  cli.py main.py dashboard.py auth.py
verifier/verifier.py  standalone third-party verifier (+ tsa_roots/ pinned certificates)
bench/                SCAR-BENCH harness + published results (scar114)
tsa/                  self-hosted OpenSSL witness (root + leaf chain)
plugins/              VS Code extension · Claude Code hooks · ZCode plugin
tests/                392 tests — the invariant suite, incl. SCAR replay
docs/                 SPECS · THREAT-MODEL · ADRs · compliance & bench docs (this site)
demo/                 runnable end-to-end scenes

§Releases & distribution

History

21 releases since 2026-09-19, every one in the changelog. Recent arc:

• 0.21.0 — 2026-10-15 — external audit round: 10 findings, 0 breaking the cryptography; 8 fixed outright, NB-05/NB-08 closed in their compatible halves, each with a named test. Fail-closed defaults everywhere (unverifiable witness → exit 2, unparseable NOIREBOX_CLIENTS refuses to boot)
• 0.20.0 — 2026-10-14 — retention sealing + custody grade: witness = min(authoring, retention)
• 0.19.0 / 0.18.0 — 2026-10-14 — uid-gate as a tri-state disclosure (off / enforced / unavailable), custody protocol 0.2, PIN moved out of argv
• 0.16.0 / 0.15.0 — 2026-10-13 — the key leaves the disk: keyholder daemon, then PKCS#11 token
• 0.11.0 — 2026-10-11 — receipt/0.2.2 (judged_by + spec_hash), SCAR-BENCH-114 published
• 0.1.0 → 0.10.0 — 2026-09-19 → 10-04 — chain, guardrails, RFC 3161, fleet hub, distribution

§Security & honest limits

The adversary model, trust boundaries and residual risks live in the threat model; the security baseline and scan methodology in SECURITY-BASELINE.md. Report vulnerabilities per SECURITY.md — please don't open public issues for them.

Known limits, assumed and tracked:

• Payloads are not encrypted — GDPR minimization is the caller's responsibility
• Pinned hardware root of custody is still open; the published attestation is the countermeasure until then
• Probabilistic guardrail — measured false negatives are non-zero
• Single-process append lock — sharding/scaling not targeted
• 0.21.0 residual: re-hash detection stays a versioned-format decision (NB-05 compatible half)

§Compliance mapping

Full write-ups: COMPLIANCE-EU.md · ART12-MAPPING.md. A building block, not a certification — the perimeter is stated, not oversold.

§Documentation index

Everything below lives in docs/ in the repository — markdown, versioned with the code.

§ADR index

All 27 in docs/ADRs.md — each with context, decision and what was rejected:

§Contributing

• Branches + pull requests; main is protected (PR + required checks). No direct pushes.
• make test — 392 tests, must stay green · ruff for lint (B/SIM/C4 enforced) · CI runs the suite + Bandit + a stub-LLM coverage pass.
• The spec is the contract: a code change that diverges from docs/SPECS.md updates the spec in the same PR — or it's a bug.
• Numbers cited in docs must be reproducible (make bench, make test) — measured, never rounded up.
• MIT. Issues and PRs welcome; security issues go to SECURITY.md, not public issues.

NoireBox is engineered in the Vosges, France 🇫🇷. NoireBox is a building block, not a certification — it proves the integrity of the record; data minimization and key-root decisions remain the deployer's.