“Show me the evidence.” It is the most important question in any compliance review, and for AI-governed systems, it is the question that separates organizations that can demonstrate control from those that cannot. Ethosure’s answer to this question is the evidence ledger – a structured, tamper-evident record of every action an AI agent attempted and every decision the governance system made.
What the evidence ledger is
The evidence ledger is the continuous output of Ethosure’s enforcement layer. Every time a hook fires – whether to allow, transform, escalate, or block an agent’s proposed action – it emits a structured record of what happened, why it happened, and what policy drove the decision.
The ledger has two storage layers that work in concert:
An append-only JSONL log. JSONL means “JSON Lines” – a file format where each line is a self-contained JSON record. Append-only means new events are added to the end of the file; existing entries are never modified or deleted. This is the tamper-evident property: any retrospective alteration of the log would be visible as a structural inconsistency. The log is the primary record of what happened.
A rebuildable DuckDB store. DuckDB is a fast, embedded analytical database – think of it as a local database that lives inside the project directory, with no server required. The JSONL log is ingested into DuckDB tables, where it becomes queryable. An organization can ask: “Show me all BLOCK decisions in the last 30 days.” “Which policy fired most often?” “Which sessions had the most escalations?” The DuckDB store can be rebuilt from the JSONL log at any time, which means the JSONL log is the authoritative record and the DuckDB store is an index over it.
Three evidence formats, one event
For each enforcement event, the coding-ethos project emits findings in multiple formats to serve different consumers:
SARIF. The Static Analysis Results Interchange Format is an industry standard for code-scanning findings, supported by GitHub Advanced Security, Azure DevOps, and many other CI and IDE platforms. SARIF findings include the rule that fired, the location of the finding, the severity, the message, and additional metadata. SARIF is the format regulators and auditors recognize from CI/CD tooling.
TOON. A compact structured text format used by coding-ethos for machine-readable evidence that is also human-readable at a glance.
JSON. Full structured records suitable for programmatic processing, feeding dashboards, or ingestion into a SIEM (Security Information and Event Management) system.
The same enforcement event appears in all three formats, ensuring that the evidence can be consumed by whatever toolchain an organization already uses.
What is recorded in each event
Every event in the ledger contains enough information to reconstruct the decision independently:
- What was proposed. The action – command, file edit, Git operation – is captured in enough detail to understand what the agent was trying to do.
- What decision was made. One of the four dispositions: ALLOW, TRANSFORM, ESCALATE, or BLOCK.
- Which policy applied. The specific policy ID from the compiled policy bundle.
- Which principle owns that policy. The engineering principle that the policy enforces (e.g., `security-by-design`, `one-path-for-critical-operations`).
- The policy bundle version. Which version of the compiled policy was in effect at decision time, so the decision can be reproduced against the same rule set.
- A timestamp and trace ID. For correlating events across a session.
- Suggested remediation. What the agent should do to resolve a block or comply with a transform.
For MCP and code-intelligence events, the ledger additionally tracks token counts, payload hashes, cache hits, and session-level read and write activity – without storing the content of prompts or responses.
Why “tamper-evident” matters
Standard log files can be edited by anyone with filesystem access. An auditor examining a standard log cannot know whether entries have been removed or modified. This is why “a folder of screenshots” is not an acceptable audit trail for AI agent governance – screenshots can be staged, timestamps can be changed, and there is no way to prove completeness.
The append-only JSONL structure addresses this directly. Because entries are only ever appended and never modified, the log is structurally tamper-evident: the ordering and continuity of entries can be verified. Additionally, because the DuckDB store is derived from the JSONL log, any discrepancy between the log and the store is detectable.
Combined with the supply-chain attestations that coding-ethos applies to its own software releases (SPDX SBOMs, GitHub artifact attestations, SHA-256 checksums), the system presents a defensible chain of evidence from the enforcement binary to the log entry.
Connecting to compliance frameworks
The evidence ledger is not just useful for internal audits. It is specifically designed to produce evidence that maps to the requirements of external frameworks:
- NIST AI RMF requires organizations to “document AI system decisions” and maintain records of how AI systems behave in production. The ledger provides those records at the decision level.
- ISO/IEC 42001 requires governance artifacts that demonstrate AI system controls are operating as intended. Queryable SARIF findings and policy-linked decision records satisfy that requirement.
- EU AI Act (enforceable August 2026, per Article 99) requires high-risk AI systems to keep logs of operation. The append-only JSONL log with policy IDs and principle references is precisely this kind of operational record.
The point is not to file the ledger away until an audit arrives. It is to ensure that when an auditor asks “show me the evidence,” the answer is ready – queryable, structured, linked to specific rules, and impossible to fabricate retroactively.
