AI verification / Case study
Nexus Aegis
Attach verifiable evidence to an agent’s proposed change.
- Type
- Open-source engineering
- Release
- v1.0.0
- Stack
- Python 3.12 · RFC 6962 Merkle Proofs · PCAE Kernel · MCP JSON-RPC 2.0
- Automated tests
- 87
System architecture
- 7-Gate Deterministic PCAE Verification Pipeline (nexus_aegis/gates.py)
- RFC 6962 Domain-Separated Merkle Tree Engine (nexus_aegis/merkle.py)
- PR Attestation Renderer & JSON-RPC 2.0 MCP Server (kernel.py / mcp_server.py)
01 / Problem
Why it exists
When an autonomous AI agent opens a pull request or completes a production workflow, engineering teams have zero mathematical proof that the agent was not prompt-injected, did not exceed its budget, did not clobber peer files, did not reward-hack tests (assert True / deleting tests), and did not hallucinate citations or AST symbols.
02 / Design
How it works
Compile all 7 gate verdicts plus input/output digests into an RFC 6962 domain-separated SHA-256 Merkle tree so any single gate can be verified via an O(log N) inclusion proof.
7-Gate Deterministic PCAE Verification Pipeline (nexus_aegis/gates.py)
Evaluates prompt-injection/SSRF safety (G1), budget/tier routing (G2), file-lease isolation (G3), loop/schema health (G4), AST test integrity (G5), citation/symbol grounding (G6), and temporal memory freshness (G7).
RFC 6962 Domain-Separated Merkle Tree Engine (nexus_aegis/merkle.py)
Computes 0x00/0x01 domain-separated SHA-256 Merkle roots, O(log N) inclusion proofs, and selective-disclosure verification packages.
PR Attestation Renderer & JSON-RPC 2.0 MCP Server (kernel.py / mcp_server.py)
Renders drop-in GitHub PR Attestation Markdown tables and exposes 4 MCP tools (aegis_attest_agent_run, aegis_verify_merkle_proof, aegis_list_gates, aegis_run_benchmark).
Proof-Carrying Agent Execution (PCAE) with RFC 6962 Selective-Disclosure Merkle Trees
- Context
- Enterprise teams adopting autonomous coding agents need cryptographic assurance that an AI-authored PR passed security, anti-reward-hacking, and grounding gates without exposing private system prompts in public PR comments.
- Decision
- Compile all 7 gate verdicts plus input/output digests into an RFC 6962 domain-separated SHA-256 Merkle tree so any single gate can be verified via an O(log N) inclusion proof.
- Trade-offs
- Adds ~0.04 ms of cryptographic hashing overhead per run, but provides mathematical tamper-evidence and selective disclosure.
- Verification
- Verified across 87 pytest tests, 35 multi-agent scenarios, and 245 tampered-proof rejection tests.
Security and operational constraints
- RFC 6962 domain separation (SHA-256(0x00 || leaf) vs SHA-256(0x01 || L || R)) mathematically prevents leaf/node second-preimage collisions.
- Wall-clock-independent canonical JSON leaf hashing combined with HMAC-SHA256 bundle signatures blocks any post-hoc tampering (100% rejection across 245 mutated proof tests).
- Selective-disclosure proof verification allows zero-knowledge-style gate auditing in untrusted CI environments.
- An AegisAttestationBundle is marked overall_passed == True if and only if all 7 deterministic gates pass with zero violations.
- Every gate leaf hash is computed over canonical sorted-key JSON with 0x00 prefixing so leaf hashes can never collide with 0x01 internal Merkle nodes.
- Any single-bit mutation to a gate verdict, sibling hash, or direction flag causes verify_merkle_inclusion_proof() to return False.
03 / Evidence
How to verify it
Repository-reported / 7-Gate Attestation & Merkle Proofs
100% Recall · 0.27 ms P50 · 87 Tests100% recall (0% FPR) across 35 multi-agent scenarios + 245/245 RFC 6962 selective-disclosure Merkle proofs verified
Reproduce from the command line
git clone https://github.com/codesphere-u/nexus-aegis.git
cd nexus-aegis && pytest -v
python -m nexus_aegis.cli demo && python -m nexus_aegis.cli benchmark