CCS Runtime Verifier

Version: 1.1.0

Out-of-process runtime verification for AI agent commands with tamper-evident audit receipts.

Overview

CCS (Command & Control Security) Runtime Verifier enforces security policies on AI agent tool calls at runtime. The verifier runs in a separate process from the agent, ensuring that memory corruption or code injection in the agent process cannot subvert the verification logic.

Key Features

• Process isolation: Verifier runs in a separate process with its own memory space
• Two receipt levels:
  • L0: HMAC-SHA256 receipts (6 fields, backward compatible)
  • L1: Ed25519 signed receipts (29 fields, CAID-compatible)
• 5 built-in security rules:
  • SSRF protection (with IP encoding bypass detection)
  • RCE / command injection detection (obfuscated patterns)
  • Credential leak detection (API keys, JWT, private keys, etc.)
  • Tool poisoning detection (hidden instructions in tool descriptions)
  • Rug pull detection (post-approval behavior change)
• Dimension-specific error codes for automated retry/failover
• Multiple transports: Unix domain socket (default) and TCP
• Auto-detect mode: Tries out-of-process first, falls back to in-process

What's New in v1.1.0

✨ New Features

• L1 Receipt Module (ccs_verifier_l1.py): Full Ed25519 signed receipt with 29 fields

  • CAID (Chain of Attestation for Inference & Deployment) compatible
  • 26-29 field comprehensive receipt covering full verification context
  • Ed25519 signatures (replacing/augmenting HMAC-SHA256)
  • receipt_version: "1.1"

• L1 Receipt Fields (29 total):

  • Core identity: trace_id, receipt_version, verdict, timestamp
  • Tool binding: tool, tool_call_id, params_hash, args_digest
  • Rule context: rule_summary, rule_version
  • Request/response binding: request_hash, response_hash
  • Runtime context: runtime_context_hash, config_hash
  • Verifier identity: verifier_source_class, deployment_mode, issuer
  • Audience & nonce: audience, nonce
  • Sequence & bounds: sequence, issuance_bound, expiry_bound, clock_skew_bound
  • CAID-compatible action: action
  • Signature: signature (Ed25519), signing_algorithm, public_key_fingerprint
  • Metadata: verified_at, latency_us

• Fluent receipt builder: L1ReceiptBuilder for easy receipt construction

• Server L1 mode: Enable Ed25519 receipts with l1_signing_key parameter

• Client L1 support: Automatic L1 receipt parsing and public key exchange

🔧 Improvements

• Backward compatible: L0 HMAC-SHA256 mode remains fully supported
• CLI enhancements: New --l1 flag, --l1-signing-key, --issuer, --audience, --deployment-mode
• Consistent versioning: All modules now report version 1.1.0
• Comprehensive test suite: 154+ tests covering all modules

🐛 Fixes (from v1.0.0 / broken v1.1.0 release)

• Fixed missing ccs_verifier_l1.py module (L1 receipt was absent from package)
• Fixed version mismatch: __init__.py, server.py, __main__.py all report 1.1.0
• Fixed receipt algorithm: L1 uses Ed25519 instead of HMAC-SHA256
• Fixed receipt field count: 29 fields instead of 6
• Fixed pyproject.toml version metadata

Installation

pip install ccs-verifier

With Ed25519 support (recommended for L1 receipts):

pip install "ccs-verifier[ed25519]"

Quick Start

Basic Usage (Auto-detect mode)

from ccs_verifier import Verifier, Command
from ccs_verifier.builtin_rules import SSRFRule, RCERule, CredentialLeakRule

# Auto-detect: tries out-of-process server first, falls back to in-process
verifier = Verifier(rules=[SSRFRule(), RCERule(), CredentialLeakRule()])

# Verify a command
cmd = Command(
    agent_id="my-agent",
    tool="http_get",
    params={"url": "https://api.example.com/data"},
)
result = verifier.verify(cmd)

if result.allowed:
    print("Command approved!")
    print(f"Receipt: {result.receipt}")
else:
    print(f"Blocked: {result.block_reason}")
    print(f"Error code: {result.error_code}")

L1 Ed25519 Receipts

from ccs_verifier import Verifier, Command, generate_ed25519_key
from ccs_verifier.builtin_rules import SSRFRule, RCERule

# Generate an Ed25519 key (or load from secure storage)
l1_key = generate_ed25519_key()

# Create verifier with L1 mode enabled
verifier = Verifier(
    rules=[SSRFRule(), RCERule()],
    mode="in-process",
    l1_signing_key=l1_key,
)

cmd = Command(agent_id="agent-1", tool="shell", params={"command": "ls -la"})
result = verifier.verify(cmd)

# L1 receipt with 29 fields and Ed25519 signature
l1 = result.l1_receipt
print(f"Verdict: {l1['verdict']}")
print(f"Receipt version: {l1['receipt_version']}")
print(f"Algorithm: {l1['signing_algorithm']}")
print(f"Signature: {l1['signature']}")
print(f"Action (CAID): {l1['action']}")
print(f"Issuer: {l1['issuer']}")
print(f"Sequence: {l1['sequence']}")

Verifying L1 Receipts

from ccs_verifier import L1Receipt, get_public_key

# Get public key from the private key seed
public_key = get_public_key(l1_key)

# Parse and verify
receipt = L1Receipt.from_dict(result.l1_receipt)
if receipt.verify_signature(public_key):
    print("✅ Receipt signature verified")
else:
    print("❌ Receipt tampering detected!")

Running as a Daemon

# Unix socket (default)
python -m ccs_verifier

# With L1 Ed25519 receipts
CCS_L1_SIGNING_KEY=$(cat /etc/ccs/l1.key) python -m ccs_verifier --l1

# TCP transport
python -m ccs_verifier --transport tcp --host 0.0.0.0 --port 50051

# Custom rules
python -m ccs_verifier --rules ssrf,rce,credential_leak

Receipt Levels

L0 - HMAC-SHA256 (Backward Compatible)

• 6 covered fields: trace_id, verdict, timestamp, tool, params_hash, rule_summary
• Algorithm: HMAC-SHA256 (first 16 bytes as hex)
• Use case: Simple in-process audit trails, backward compatibility

L1 - Ed25519 (CAID-Compatible)

• 29 fields: Full verification context attestation
• Algorithm: Ed25519 (RFC 8032)
• Use case: Cross-system verification, audit log integrity, regulatory compliance
• Features:
  • Asymmetric signatures (verify with public key)
  • CAID-compatible action field
  • Time bounds (issuance, expiry, clock skew)
  • Sequence numbers for replay protection
  • Verifier identity and deployment mode
  • Full request/response binding

Architecture

┌─────────────────┐     Unix/TCP      ┌────────────────────┐
│   Agent Process │ ────────────────▶ │  Verifier Process  │
│                 │                    │                    │
│  - LLM agent    │                    │  - Rule engine     │
│  - Tool calls   │                    │  - Audit log       │
│  - Verifier     │                    │  - Signing keys    │
│    client       │ ◀──────────────── │  - L0 HMAC + L1 Ed │
└─────────────────┘     Signed result   └────────────────────┘

The process boundary ensures:

1. Memory corruption in the agent doesn't affect verification
2. Audit logs are stored in a separate crash domain
3. Signing keys are never exposed to the agent process

API Reference

Core Classes

• Command: Immutable command representation
• VerificationResult: Verification decision with receipt(s)
• Verdict: Enum (ALLOW, DENY, ESCALATE)
• DimensionError: Dimension-specific error codes
• VerifierServer: Out-of-process verification server
• VerifierClient: Client for connecting to verifier server
• Verifier: High-level auto-detecting verifier

L1 Receipt

• L1Receipt: Ed25519 signed receipt (29 fields)
• L1ReceiptBuilder: Fluent builder for receipt construction
• generate_ed25519_key(): Generate Ed25519 private key
• get_public_key(seed): Derive public key from private seed
• public_key_fingerprint(pubkey): SHA-256 fingerprint
• sign_l1_receipt(receipt, key): Sign a receipt
• verify_l1_receipt(receipt, pubkey): Verify a receipt

Built-in Rules

• SSRFRule: Server-Side Request Forgery protection
• RCERule: Remote Code Execution detection
• CredentialLeakRule: Credential exfiltration detection
• ToolPoisoningRule: Hidden instruction injection detection
• RugPullRule: Post-approval behavior change detection

Testing

pip install "ccs-verifier[dev]"
pytest tests/ -v

License

MIT License - see LICENSE file for details.