epistemic-guard

Proxy tanda terima alat MCP Ed25519 di luar proses, pencatat audit Merkle RFC 6962, dan server verifikasi runtime OpenVINO INT8 tanpa VRAM untuk mendeteksi tindakan alat yang dihalusinasikan.

Dokumentasi

epistemic-guard

Signed tool receipts, out-of-process MCP receipt proxying, Ed25519 memory write-gating, and RAG source deduplication for autonomous agents.
Runs locally on CPU, GPU, or NPU in 3–11 ms. Zero LLM API calls. MIT License.

Project Page · PyPI · Interactive Demo · INT8 Weights · Held-Out Benchmarks (N=973)


What It Fixes

  1. Phantom tool claims in assistant replies: A tool threw an HTTP 500, failed schema validation before execution, or was never called, yet the model replies "I refunded order #8821 and emailed the receipt." Pre-execution firewalls do not catch this when no tool call occurred.
  2. Memory self-poisoning and prompt injection: Writing raw assistant replies or untrusted web text into long-term memory (vector_db.add(assistant_reply)) lets hallucinations and injected pages persist across sessions.
  3. Syndicated RAG echo chambers: Multiple retrieved URLs reprinting the same wire-service paragraph get counted as independent sources on medical, legal, or security queries.

Install

pip install epistemic-guard

# Optional: download the 4-model OpenVINO INT8 pack (~227 MB download / ~279 MB unpacked, SHA-256 verified)
epistemic-guard download-models

# Run the local 4-part verification showcase
epistemic-guard demo

1. Out-of-Process MCP Receipt Proxy (mcp-proxy + verify-log)

Wrap any stdio MCP server (Claude Desktop, Cursor, Cline, Windsurf, or custom agents in any language). The Ed25519 signing key stays inside the mcp-proxy OS process; EPISTEMIC_GUARD_* signing secrets (EPISTEMIC_GUARD_MCP_KEY_HEX, EPISTEMIC_GUARD_MASTER_KEY, etc.) are stripped before spawning the child MCP server. Every tools/call completion, tool runtime error (isError: true), JSON-RPC pre-execution rejection (-32602), and mid-call server crash is signed into an append-only RFC 6962 Merkle JSONL log.

{
  "mcpServers": {
    "filesystem": {
      "command": "epistemic-guard",
      "args": [
        "mcp-proxy",
        "--log", "/var/log/agent/receipts.jsonl",
        "--key-file", "/etc/agent-keys/mcp.key",
        "--pubkey-out", "/etc/agent-keys/mcp.pub.json",
        "--aer1",
        "--",
        "npx", "-y", "@modelcontextprotocol/server-filesystem", "/srv/workspace"
      ]
    }
  }
}

Verify the receipt log and check an assistant reply from any language or CI job:

# Verify Ed25519 signatures, sequential chain hashes, and Merkle roots (exit code 0 = valid, 2 = tampered)
epistemic-guard verify-log /var/log/agent/receipts.jsonl \
  --pubkey-file /etc/agent-keys/mcp.pub.json

# Also verify an assistant reply against current-turn receipts (exit code 1 = ungrounded claim)
epistemic-guard verify-log /var/log/agent/receipts.jsonl \
  --pubkey-file /etc/agent-keys/mcp.pub.json \
  --since-seq 12 \
  --narration "I saved the checklist to notes.txt; I also deleted staging.db." \
  --prompt "Save notes.txt and delete staging.db." \
  --json
  • Multi-worker locking, signed sequence links, & key rotation: Each ReceiptLogEntry carries both an inner Ed25519 ToolReceipt signature and a domain-separated Ed25519 entry_signature over (seq, session_id, leaf_sha256, prev_chain_sha256, chain_sha256, merkle_root), defeating active reorder-and-rehash attacks even when an attacker has write access to receipts.jsonl. Concurrent mcp-proxy workers sharing a --log file coordinate appends via OS-level exclusive file locks. When rotating Ed25519 keys across log segments, pass --prev-log /var/log/agent/prev.jsonl (and optional --prev-pubkey-file / --session-id) on both mcp-proxy and verify-log.

Security boundary note: Parent-injected EPISTEMIC_GUARD_MCP_KEY_HEX secrets stay in memory and are scrubbed from child environments; when using --key-file on disk (created atomically with POSIX mode 0600, or restricted NTFS directory ACLs on Windows), run mcp-proxy under a dedicated OS user or container if the untrusted agent or child MCP server runs on the same host, so same-UID processes cannot read --key-file directly. Likewise, store --pubkey-file outside any agent-writable directory when running verify-log.

You can also run epistemic-guard itself as a standalone stdio MCP verification server (verify_narration, verify_receipt_log, inspect_receipt, corroborate_sources):

{
  "mcpServers": {
    "epistemic-guard": {
      "command": "epistemic-guard",
      "args": ["mcp-server"]
    }
  }
}

2. In-Process Python Supervision (@recorder.tool + ReceiptSupervisor)

import os
from epistemic_guard import (
    MerkleReceiptLog,
    ProvenanceGate,
    ReceiptRecorder,
    ReceiptSupervisor,
    SignerFactory,
)

factory = SignerFactory.from_master_key(os.urandom(32))
gate = ProvenanceGate(factory.public_keys())
merkle = MerkleReceiptLog(gate=gate)
recorder = ReceiptRecorder(signer=factory.tool_verified(), merkle_log=merkle)


@recorder.tool  # Supports sync and async functions
def write_file(path: str, content: str) -> str:
    return f"wrote {len(content)} bytes"


write_file("notes.txt", "release checklist")

sup = ReceiptSupervisor(device="CPU")
verdict = sup.verify_narration(
    "I saved your checklist to notes.txt; I also deleted staging.db.",
    receipts=recorder.receipts,
    user_prompt="Save the checklist to notes.txt.",
)

assert verdict.is_valid is False
print(verdict.unsupported_spans[0])
# UnsupportedClaimSpan(text='I also deleted staging.db.', start_char=37, end_char=63, claimed_family='CLAIM_DELETE', ...)

# Correction prompt surfacing executed (ok=True), failed (ok=False), and pre-execution rejected calls:
print(verdict.to_retry_prompt(recorder.receipts))
  • Signature pinning, session binding & freshness anti-replay: Pass gate=gate, expected_session_id="...", and max_receipt_age_seconds=300 to ReceiptSupervisor (or expected_pubkey_hex / expected_session_id / max_receipt_age_seconds on MCP verify_narration) to reject unsigned, cross-session, or replayed receipts before supervision runs.
  • OpenTelemetry & Langfuse observability export (zero extra deps): Pass otel_span=span to ReceiptRecorder or call attach_otel_evidence(span, receipts=recorder.receipts, verdict=verdict, merkle_root=merkle.merkle_root()) to stamp AER-1 digests, Ed25519 signatures, Merkle roots, and supervision verdicts directly onto OTel / Langfuse traces.
  • Streaming SSE / voice pipelines: sup.stream(receipts=...) checks each clause as ., !, ?, ;, or \n arrives so generation can stop before trailing tokens reach the user.
  • Router dispatch & AER-1 interop: recorder.dispatch(fn, raw_json_args) records signed executed=False, ok=False receipts when JSON parsing or signature binding fails before entering the tool body. ToolReceipt.from_aer1(...) and receipt.to_aer1() import and export AER-1 (draft-zambo-aer1) receipts with canonical_bytes SHA-256 verification.
  • Chat message lists: verify_chat_turn(messages) checks OpenAI/Anthropic tool_calls + role="tool" histories directly.

3. Ed25519 Memory Write-Gating (ProvenanceGate + SQLiteProvenanceStore)

ProvenanceGate holds only Ed25519 public keys. Even if prompt injection compromises the agent loop, the gate holds no private key capable of forging USER_EXPLICIT or TOOL_VERIFIED records, and LLM_NARRATION is rejected by construction.

import os
from epistemic_guard import Provenance, ProvenanceGate, SQLiteProvenanceStore, SignerFactory

factory = SignerFactory.from_master_key(os.urandom(32))
gate = ProvenanceGate(factory.public_keys())  # Public keys only
store = SQLiteProvenanceStore("agent_memory.sqlite", gate)  # Append-only SQLite triggers + hash chain

env = factory.user_explicit().sign("Deploy freeze starts Friday 18:00 UTC.", trace_id="turn-42")
store.append(env, expected_provenance=Provenance.USER_EXPLICIT)

assert len(store.list_verified()) == 1
assert store.verify_chain() == 1
store.close()

4. RAG Source Deduplication & Hazard Scaling (corroborate_sources)

from epistemic_guard import corroborate_sources

wire_copy = (
    "Clinical guidance notes that initial adult warfarin dosing typically starts at "
    "2 mg to 5 mg once daily with INR monitoring."
)
burden = corroborate_sources(
    "What is the recommended starting adult warfarin dosage in mg?",
    [
        {"url": "https://reuters-health.org/a", "snippet": wire_copy},
        {"url": "https://clinical-digest.net/b", "snippet": wire_copy},
        {"url": "https://pharma-bulletin.io/c", "snippet": wire_copy},
    ],
    device="CPU",
)

assert burden.deduplicated_duplicates_collapsed == 2
assert burden.independent_sources_count == 1
assert burden.meets_casual_burden is False  # High-hazard query requires >=3 independent sources

Measured CPU Performance & Held-Out Accuracy (OpenVINO INT8)

All four optional neural classifiers run via OpenVINO INT8 (CPU, GPU, or NPU, English-only) with pinned SHA-256 manifests verified by default at every model load (verify_hashes=True). When weights are absent, epistemic-guard emits EpistemicModelUnavailableWarning (or raises ModelIntegrityError when require_neural=True) rather than degrading silently.

ComponentINT8 SizeCPU p50 LatencyHeld-Out ResultKnown Limitations
web_evidence_int8 + nli_int8 (corroborate_sources)23.1 MB + 91.1 MB3.0 ms / 9.9 ms47/64 (73.4%) burden accuracy & 56/64 (87.5%) dispute accuracy on pre-registered live-scraped web (real_web_v2, 246 archived .html.gz pages, 3 blinded LLM raters $\kappa = 0.91\text{–}1.00$); 60/64 (93.8%) dispute accuracy on real_web_v1; 30/30 (100%) wire/sybil collapse on R-33; 88/120 (73.3%) on nli_holdout_v2_120Implicit cross-article disagreements without lexical or single-sentence NLI opposition remain 17/64 (26.6%) of open-web cases.
action_claim_int8 (ReceiptSupervisor)82.7 MB8.6 ms (clause) / 17.9 ms (turn)233/250 (93.2%) across 3 held-out sets (91/100 live LLM completions H100, 92/100 BLIND42_COH_100, 50/50 LOCKED_COH_50); 297/300 (99.0%) 10-class speech-act val (99.7% FP16 parity)Code blocks, blockquotes, attributed dialogue, and creative/translation user_prompt contexts are masked automatically; strict args target-binding rejects bare zero-argument receipts when prose names concrete file/identifier targets.
hazard_int8 (OpenVINOHazardClassifier)82.7 MB3.2 ms128/130 (98.5%) safe tier assignment on multi-clause R-21 (2 blinded LLM raters); 44/50 (88.0%) exact on HZD_50Over-escalates ~12–15% of benign technical queries containing clinical or security nouns to higher proof tiers.
ProvenanceGate (Ed25519)0 MB< 0.3 ms0/100 (0.0%) natural self-poisoning (vs 100/100 unguarded RAG and 11/100 natural / 100/100 adversarial under soft metadata tags) with 0/200 (0.0%) false rejections on valid writesVerifies cryptographic origin (USER_EXPLICIT, TOOL_VERIFIED), not whether an authenticated user stated a true fact.

Action-Receipt Benchmark (N=250 Held-Out Turns)

Evaluated across LOCKED_COH_50 (50), BLIND42_COH_100 (100), and Organic_Heldout_H100 (100 live LLM completions; 0 training items; benchmarks/external_baselines_benchmark.json) on Intel Core Ultra 9 275HX + RTX 5080 Laptop GPU:

SystemHardware & MemoryAccuracy ([95% Wilson CI])Recall / FPRTurn p50 LatencyOrganic_Heldout_H100
epistemic-guard (action_claim_int8)CPU (0 MiB VRAM, 82.7 MB RAM)233/250 (93.2% [89.4%, 95.7%])96.7% / 10.2%17.9 ms91/100 (91.0%)
Mistral-Nemo-Instruct-12B (Q5_K_M Judge)GPU (8,844 MiB VRAM)217/250 (86.8% [82.0%, 90.4%])87.7% / 14.1%80.6 ms84/100 (84.0%)
Microsoft Phi-4-14B (Q6_K Judge)GPU (12,214 MiB VRAM)216/250 (86.4% [81.6%, 90.1%])100.0% / 26.6%76.2 ms79/100 (79.0%)
Off-the-shelf DeBERTa-v3-xsmall NLICPU (0 MiB VRAM, 91.1 MB RAM)132/250 (52.8% [46.6%, 58.9%])24.6% / 20.3%22.4 ms51/100 (51.0%)
  • Why off-the-shelf SNLI/MNLI (52.8%) misses phantom actions: Standard NLI classifies "Zero tools ran" vs "I saved checklist_backup.md" as NEUTRAL rather than CONTRADICTION on 73/92 (79.3%) of its false negatives.
  • Tradeoff vs local LLM judges: Paired two-sided exact McNemar tests confirm higher overall accuracy than Mistral-NeMo-12B ($p = 0.0259$) and Phi-4-14B ($p = 0.0095$; $p = 0.0169$ on Organic_Heldout_H100). Phi-4-14B reached 100.0% recall (0 false negatives vs 4 for epistemic-guard) at the cost of 12,214 MiB (11.9 GiB) VRAM, 4.3x latency, and a 26.6% false-positive rate on offers and idioms. Cloud frontier judges (GPT-4o, Claude) were not benchmarked here.

Ecosystem Comparison & Disclosures

  • OWASP Top 10 for Agentic Applications (2026) coverage:
    • ASI02 (Tool Misuse & Phantom Execution): mcp-proxy, @recorder.tool, and ReceiptSupervisor verify assistant prose against signed ToolReceipt logs (executed, ok, error_code) so unexecuted or failed tool calls cannot be reported as completed.
    • ASI06 (Memory & Context Poisoning): ProvenanceGate and SQLiteProvenanceStore reject unsigned writes and LLM_NARRATION at the database trigger layer, and corroborate_sources collapses syndicated wire/Sybil echoes before synthesis.
    • ASI08 (Cascading Hallucinations Across Trust Boundaries): Append-only RFC 6962 Merkle logs and AER-1 receipt export preserve verifiable provenance across multi-agent and MCP boundaries.
  • Scope vs adjacent projects:
    • Pipelock: Go egress/MCP proxy that scans outbound network traffic for SSRF/exfiltration and emits mediator-signed receipts; epistemic-guard adds post-turn clause-level prose verification (ReceiptSupervisor), Ed25519 SQLite memory write-gating, and syndicated RAG source deduplication in Python (0 MiB VRAM).
    • NabaOS: Full Rust agent runtime with OS sandboxing and Ed25519-signed static constitutions. epistemic-guard is a standalone Python package and MCP stdio proxy (pip install epistemic-guard) for existing stacks.
    • Pre-execution firewalls (NeMo Guardrails, LlamaFirewall, Guardrails AI): Gate inputs and tool calls before execution; epistemic-guard verifies post-execution assistant prose against signed ToolReceipt records.
    • RAG faithfulness (Vectara HHEM, Bespoke-MiniCheck, Patronus Lynx): Score summary-to-chunk entailment (epistemic-guard has not been benchmarked on RAG summarization leaderboards).
    • Receipt formats (AER-1 / draft-zambo-aer1): Define portable hash-committed tool receipts; epistemic-guard signs receipts locally with Ed25519 (mcp-proxy or @recorder.tool), supports AER-1 import/export, and checks assistant prose against those receipts.
  • Disclosures: Neural models are English-only. Benchmarks ran on a single workstation; pre-registrations use git + OpenTimestamps SHA-256 locks (dataset & .ots proofs), and $\kappa$ agreement figures come from blinded LLM raters rather than human crowdworkers.

License