SAGE

Agent Incident Forensics

Portable, redactable, hash-chained evidence for agent runs.
Seal it. Ship it. Re-verify it — without trusting the producer’s UI.

---

Why SAGE exists

Traces show you a story in a dashboard.
SAGE gives you an artifact another team can fail-closed verify offline.

Observability products already exist. The gap is a backend-neutral forensic pack: redacted before hash, content-addressed blobs, custody MAC, optional pinned Ed25519, third-party sage verify.

SAGE is a security tool, not a chat UI, not an RCA leaderboard, and not “AI observability SaaS.”

60-second loop

pip install -e ".[dev]"
export SAGE_PACK_KEY="replace-me"

python examples/security_verify_loop.py

sage verify evidence.sage.tar.gz \
  --policy policies/strict.json \
  --witness \
  --hmac-key "$SAGE_PACK_KEY" \
  --receipt verify.receipt.json

Auditor posture (pinned signature):

python examples/auditor_kit.py
# docs: docs/AUDITOR_KIT.md · docs/VERIFY_RUNBOOK.md

from sage import SageRecorder

with SageRecorder(trace_id="incident-42") as rec:
    agent.run(task)
rec.export("incident.sage.json")

What you get

Capability	Detail
Recorder	Sanitize-on-close, redact-before-hash, CAS offload
Journal	Crash-safe live WAL → sealed manifest + merkle
Pack v2	Portable .sage.tar.gz with custody-bound HMAC
Verify	Policies, blob inventory, witness, receipts
Signatures	Optional Ed25519 — pinned key required (TOFU refused)
Handoff	Offline auditor kit (sage handoff)
Adapters	LangChain callback, CrewAI/AutoGen wrappers, OTel tap

Formats are frozen under the 2.x compatibility covenant.

Explicit non-claims

• Does not prove the agent / LLM / tools told the truth
• Research (sage research *) is not forensic custody
• Software HMAC/Ed25519 ≠ HSM identity — see THREAT_MODEL.md

Install

pip install -e ".[dev]"     # core + tests + cryptography
pip install -e ".[sign]"    # Ed25519 only
pip install -e ".[tui]"     # optional inspect TUI

Core recorder / CAS / verify / CLI remain stdlib-only.

Prove it locally

python scripts/release_check.py
pytest -q
python examples/auditor_kit.py
sage doctor

CI: Ubuntu · Windows · macOS × Python 3.10 / 3.12.

Docs

Doc	Purpose
VERIFY_RUNBOOK.md	Record → ship → auditor re-verify
AUDITOR_KIT.md	Pinned-signature verify posture
THREAT_MODEL.md	Assets, adversaries, non-goals
SECURITY.md	Supported versions / reporting
RELEASE.md	Tag / publish checklist
CONTRIBUTING.md	PR bar for a security tool

Design partners

If you run agents in production and want sealed incident packs on one real path — open an issue or reach out. We want brutal feedback, not vanity stars.

License

FSL-1.1-ALv2 — Functional Source License (Fair Source).

• ✅ Internal use, education, research, self-host for your company
• ❌ Competing commercial product/SaaS without a commercial license
• ⏱ Converts to Apache-2.0 2 years after each version’s availability

Commercial terms: COMMERCIAL.md · License FAQ: fsl.software