Metadata-Version: 2.4
Name: ccs-verifier
Version: 1.1.3
Summary: CCS Runtime Verifier — Out-of-process AI agent command verification with tamper-evident receipts
Author: CCS Runtime Verifier Team
License: MIT
Project-URL: Homepage, https://github.com/ccs-runtime/ccs-verifier
Project-URL: Documentation, https://ccs-verifier.readthedocs.io/
Project-URL: Repository, https://github.com/ccs-runtime/ccs-verifier.git
Project-URL: Issues, https://github.com/ccs-runtime/ccs-verifier/issues
Keywords: ai-safety,agent-security,verification,runtime-verification,ed25519,hmac,ssrf,rce,audit-trail,caid
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: ed25519
Requires-Dist: cryptography>=41.0; extra == "ed25519"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"

# CCS Runtime Verifier

**Version: 1.1.0**

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

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)

## 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

```bash
pip install ccs-verifier
```

With Ed25519 support (recommended for L1 receipts):

```bash
pip install "ccs-verifier[ed25519]"
```

## Quick Start

### Basic Usage (Auto-detect mode)

```python
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

```python
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

```python
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

```bash
# 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

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

## License

MIT License - see LICENSE file for details.
