GitHub - viruswami5511/guardclaw: Cryptographic accountability ledger for AI agents

Cryptographic execution integrity for autonomous AI agents.

What Problem This Solves

AI agents are beginning to:

• execute financial transactions
• modify production infrastructure
• invoke tools and shell commands autonomously
• operate without synchronous human review

Traditional logs are mutable. Observability pipelines are not evidence.

If an AI agent makes a critical decision, how do you prove — cryptographically what it actually did?

GuardClaw implements GEF-SPEC-1.0, a language-neutral protocol for generating:

Tamper-evident, offline-verifiable execution ledgers.

No server required. No SaaS dependency. No central verifier.
Just a file and a public key.

Core Concept

Each execution entry is:

1. Canonicalized (RFC 8785 JCS)
2. Linked to the previous entry via SHA-256
3. Signed using Ed25519
4. Appended to a JSONL ledger

Result: tamper-evident execution chain.
Any modification, deletion, or reordering → verification fails.

Install

Requires Python 3.9+

Core dependencies: cryptography, jcs, click

Quick Start

Simplest API for recording events:

from guardclaw import init_global_ledger, Ed25519KeyManager
from guardclaw.api import record_action

key = Ed25519KeyManager.generate()

init_global_ledger(
    key_manager=key,
    agent_id="agent-001",
)

record_action(
    agent_id="agent-001",
    action="tool.search",
    result="success",
    metadata={"query": "AI safety"},
)

Ledger format: JSON Lines (one signed envelope per line).

Default output location:

.guardclaw/ledger/ledger.jsonl

30-Second Example

from guardclaw import GEFLedger, Ed25519KeyManager, RecordType

key = Ed25519KeyManager.generate()

ledger = GEFLedger(
    key_manager=key,
    agent_id="agent-001",
    ledger_path="agent_ledger",
    mode="strict",
)

ledger.emit(
    RecordType.EXECUTION,
    payload={"action": "shell.exec", "cmd": "rm temp.txt"},
)

ledger.emit(
    RecordType.RESULT,
    payload={"status": "success"},
)

ledger.close()

print("Chain valid:", ledger.verify_chain())

Output:

agent_ledger/ledger.jsonl

Each line contains one signed execution envelope.

CLI Verification

Verify a ledger:

guardclaw verify agent_ledger/ledger.jsonl

Machine-readable output:

guardclaw verify agent_ledger/ledger.jsonl --format json

CI mode:

guardclaw verify agent_ledger/ledger.jsonl --quiet

Verification checks:

• signature validity
• hash chain continuity
• sequence monotonicity
• schema correctness
• protocol version consistency

Optional Dependencies

Install integrations:

pip install guardclaw[langchain]
pip install guardclaw[crewai]

Integrations (v0.6.0)

GuardClaw integrates with AI systems at multiple layers.

🐍 LangChain Adapter

from guardclaw.adapters.langchain import GuardClawCallbackHandler

handler = GuardClawCallbackHandler(agent_id="agent")

agent.run(
    "task",
    callbacks=[handler],
)

Records:

• tool calls
• LLM prompts
• completions
• tool errors

🤖 CrewAI Adapter

from guardclaw.adapters.crewai import GuardClawCrewAdapter

adapter = GuardClawCrewAdapter("crew-agent")

crew = Crew(
    agents=[agent],
    tasks=[task],
    step_callback=adapter.record_step,
)

Records:

• agent steps
• task results
• tool errors

🔌 MCP Proxy (Framework-Agnostic)

from guardclaw.mcp import GuardClawMCPProxy

proxy = GuardClawMCPProxy("agent")

proxy.register_tool("search", search)

proxy.call("search", query="AI safety")

Records:

• INTENT → RESULT / FAILURE

Works with tool-calling frameworks including:

• OpenAI
• Anthropic Claude
• LangChain
• CrewAI
• custom agents

Envelope Structure (GEF-SPEC-1.0)

Signing surface excludes the signature field.

Integrity Model

Chain:

causal_hash[N] = SHA256(JCS(entry[N-1]))

Genesis entry uses a zero sentinel hash.

A valid ledger requires:

• valid signatures
• continuous sequence numbers
• correct hash chain
• schema validity
• consistent protocol version

Performance (1M Entry Benchmark)

Environment:

• Python 3.13
• single thread
• strict fsync
• Ed25519 signing enabled

Security Model

GuardClaw guarantees:

• tamper detection
• deletion detection
• reordering detection
• signature authenticity

Limitations:

• key compromise allows history rewrite
• no trusted timestamps
• no distributed consensus

Project Structure

guardclaw/
├── core/          # cryptographic protocol
├── adapters/      # framework integrations
│   ├── langchain.py
│   └── crewai.py
├── mcp/           # tool proxy
│   └── proxy.py
├── api.py         # integration API
└── cli.py         # verification CLI

Tests

62 adversarial tests (1 skipped), covering:

• tamper attacks
• replay attacks
• canonicalization determinism
• crash recovery

Run locally:

Specification

Protocol specification: GEF-SPEC-1.0

Defines:

• envelope schema
• canonicalization contract
• hash chain linkage
• verification algorithm

See:

Status

Version: v0.6.0
Protocol: GEF-SPEC-1.0
License: Apache 2.0

Production-ready cryptographic execution ledger for AI agents.

Philosophy

Observability is not evidence.
Logs are not proof.
Integrity is measurable.