agent-os-kernel 1.1.0__py3-none-any.whl → 1.3.0__py3-none-any.whl

modules/iatp/docker-compose.yml

@@ -0,0 +1,194 @@
+version: '3.8'
+
+# =============================================================================
+# IATP Demo Environment
+# =============================================================================
+# This docker-compose file sets up a complete IATP demonstration environment:
+# 
+# 1. Secure Bank Agent (trusted) with IATP Sidecar
+# 2. Honeypot Agent (untrusted) with IATP Sidecar  
+# 3. Redis for state management
+#
+# Quick Start:
+#   docker-compose up -d
+#
+# Access Points:
+#   - Bank Sidecar (trusted):    http://localhost:8081
+#   - Bank Agent (direct):       http://localhost:8000
+#   - Honeypot Sidecar:          http://localhost:9001
+#   - Honeypot Agent (direct):   http://localhost:9000
+#
+# Test Commands:
+#   # Check sidecar health
+#   curl http://localhost:8081/health
+#
+#   # Get agent capabilities (handshake)
+#   curl http://localhost:8081/.well-known/agent-manifest
+#
+#   # Send a request through the sidecar
+#   curl -X POST http://localhost:8081/proxy \
+#     -H "Content-Type: application/json" \
+#     -d '{"action": "check_balance", "account": "12345"}'
+#
+# =============================================================================
+
+services:
+  # ===========================================================================
+  # REDIS - State Management
+  # ===========================================================================
+  redis:
+    image: redis:alpine
+    ports:
+      - "6379:6379"
+    networks:
+      - iatp-network
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 10s
+      timeout: 5s
+      retries: 3
+
+  # ===========================================================================
+  # SECURE BANK AGENT (The "Good" Agent)
+  # ===========================================================================
+  
+  # The actual bank agent (internal, not directly exposed to clients)
+  bank-agent:
+    build:
+      context: .
+      dockerfile: docker/Dockerfile.agent
+    ports:
+      - "8000:8000"
+    environment:
+      - AGENT_TYPE=secure_bank
+    networks:
+      - iatp-network
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
+      interval: 10s
+      timeout: 5s
+      retries: 3
+
+  # IATP Sidecar protecting the Bank Agent (Main entry point)
+  bank-sidecar:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    ports:
+      - "8081:8081"
+    environment:
+      - IATP_AGENT_URL=http://bank-agent:8000
+      - IATP_PORT=8081
+      - IATP_AGENT_ID=secure-bank-agent
+      - IATP_TRUST_LEVEL=verified_partner
+      - IATP_REVERSIBILITY=full
+      - IATP_RETENTION=ephemeral
+      - IATP_HUMAN_IN_LOOP=false
+      - IATP_TRAINING_CONSENT=false
+    depends_on:
+      - bank-agent
+      - redis
+    networks:
+      - iatp-network
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8081/health"]
+      interval: 10s
+      timeout: 5s
+      retries: 3
+
+  # ===========================================================================
+  # HONEYPOT/ROGUE AGENT (The "Bad" Agent)
+  # ===========================================================================
+  
+  # The untrusted honeypot agent
+  honeypot-agent:
+    build:
+      context: .
+      dockerfile: docker/Dockerfile.agent
+    ports:
+      - "9000:8000"
+    environment:
+      - AGENT_TYPE=untrusted
+    networks:
+      - iatp-network
+
+  # IATP Sidecar for Honeypot (configured as untrusted)
+  honeypot-sidecar:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    ports:
+      - "9001:8081"
+    environment:
+      - IATP_AGENT_URL=http://honeypot-agent:8000
+      - IATP_PORT=8081
+      - IATP_AGENT_ID=honeypot-agent
+      - IATP_TRUST_LEVEL=untrusted
+      - IATP_REVERSIBILITY=none
+      - IATP_RETENTION=permanent
+      - IATP_HUMAN_IN_LOOP=true
+      - IATP_TRAINING_CONSENT=true
+    depends_on:
+      - honeypot-agent
+    networks:
+      - iatp-network
+
+  # ===========================================================================
+  # LEGACY SIDECARS (for compatibility)
+  # ===========================================================================
+  
+  # IATP Sidecar (Python version - legacy)
+  iatp-sidecar-python:
+    build:
+      context: .
+      dockerfile: docker/Dockerfile.sidecar-python
+    ports:
+      - "8001:8001"
+    environment:
+      - IATP_AGENT_URL=http://bank-agent:8000
+      - IATP_PORT=8001
+      - IATP_AGENT_ID=secure-bank-agent
+      - IATP_TRUST_LEVEL=verified_partner
+      - IATP_REVERSIBILITY=full
+      - IATP_RETENTION=ephemeral
+    depends_on:
+      - bank-agent
+    networks:
+      - iatp-network
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8001/health"]
+      interval: 10s
+      timeout: 5s
+      retries: 3
+    profiles:
+      - legacy
+
+  # IATP Sidecar (Go version - production)
+  iatp-sidecar-go:
+    build:
+      context: ./sidecar/go
+      dockerfile: Dockerfile
+    ports:
+      - "8002:8001"
+    environment:
+      - IATP_AGENT_URL=http://bank-agent:8000
+      - IATP_PORT=8001
+      - IATP_AGENT_ID=secure-bank-agent-go
+      - IATP_TRUST_LEVEL=verified_partner
+      - IATP_REVERSIBILITY=full
+      - IATP_RETENTION=ephemeral
+    depends_on:
+      - bank-agent
+    networks:
+      - iatp-network
+    healthcheck:
+      test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost:8001/health"]
+      interval: 10s
+      timeout: 5s
+      retries: 3
+    profiles:
+      - go
+
+networks:
+  iatp-network:
+    driver: bridge

modules/iatp/docs/ARCHITECTURE.md

@@ -0,0 +1,243 @@
+# IATP Architecture
+
+## Overview
+
+The Inter-Agent Trust Protocol (IATP) implements a **Zero-Config Sidecar Architecture** that extracts trust, security, and governance concerns from AI agents. Just like Envoy transformed microservices by extracting networking concerns into a sidecar, IATP extracts trust concerns into a lightweight proxy.
+
+## Core Architecture: "The Agent Mesh"
+
+```
+┌─────────────┐         ┌──────────────┐         ┌─────────────┐
+│ Your Agent  │ ──────> │ IATP Sidecar │ ──────> │ Other Agent │
+│ (Internal)  │         │   (Local)    │         │  (External) │
+└─────────────┘         └──────────────┘         └─────────────┘
+                              │
+                    ┌─────────┴─────────┐
+                    │                   │
+              ┌─────▼─────┐      ┌──────▼──────┐
+              │  Policy   │      │  Recovery   │
+              │  Engine   │      │   Engine    │
+              └───────────┘      └─────────────┘
+```
+
+## The "Invisible Sidecar" Pattern
+
+```
+┌─────────────┐         ┌──────────────┐         ┌─────────────┐
+│   Client    │ ──────> │ IATP Sidecar │ ──────> │ Your Agent  │
+│             │         │  (Port 8081) │         │ (Port 8000) │
+└─────────────┘         └──────────────┘         └─────────────┘
+                              ▼
+                    ┌─────────────────────┐
+                    │  Security Checks    │
+                    │  Privacy Validation │
+                    │  Trace Logging      │
+                    │  Rate Limiting      │
+                    └─────────────────────┘
+```
+
+## Components
+
+### 1. Sidecar Proxy (`iatp/sidecar/` and `iatp/main.py`)
+
+**FastAPI-based Proxy Server**
+
+The sidecar intercepts all incoming requests before they reach the agent:
+- Exchanges capability manifests via `.well-known/agent-manifest` endpoint
+- Validates requests against privacy policies
+- Routes validated requests to backend agent
+- Injects distributed trace IDs (`X-Agent-Trace-ID`)
+
+**Endpoints:**
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| `/.well-known/agent-manifest` | GET | Handshake endpoint |
+| `/proxy` | POST | Main proxy endpoint with validation |
+| `/health` | GET | Health check |
+| `/metrics` | GET | Prometheus-compatible metrics |
+| `/trace/{trace_id}` | GET | Retrieve audit logs |
+| `/quarantine/{trace_id}` | GET | Get quarantine session info |
+
+**Headers:**
+- Request: `X-User-Override` (bypass warnings), `X-Agent-Trace-ID` (tracing)
+- Response: `X-Agent-Trace-ID`, `X-Agent-Trust-Score`, `X-Agent-Latency-Ms`, `X-Agent-Quarantined`
+
+### 2. Policy Engine (`iatp/policy_engine.py`)
+
+Built-in policy validation engine:
+
+- Validates capability manifests against customizable policy rules
+- Provides warn vs. block decision logic
+- Supports custom rule addition at runtime
+- Integrates with existing SecurityValidator
+- Uses Protocol classes for extensibility (duck typing)
+
+### 3. Recovery Engine (`iatp/recovery.py`)
+
+Wraps `scak` (Self-Correcting Agent Kernel) for failure recovery:
+
+- Structured failure tracking using scak's AgentFailure models
+- Intelligent recovery strategies (rollback, retry, give-up)
+- Compensation transaction support
+- Async/sync callback support
+
+### 4. Security & Privacy Layer (`iatp/security/`)
+
+**SecurityValidator:**
+- Detects sensitive data (credit cards with Luhn validation, SSNs, emails)
+- Validates privacy policies against request contents
+- Generates warnings for risky requests
+- **Blocks** dangerous requests (e.g., credit cards to untrusted agents)
+
+**Privacy Rules:**
+- Credit cards → BLOCKED if agent has permanent retention
+- SSNs → BLOCKED if agent has non-ephemeral retention
+- Warnings for low trust scores, no reversibility, permanent storage, human review
+
+### 5. Telemetry & Flight Recorder (`iatp/telemetry/`)
+
+**FlightRecorder** - The "Black Box":
+- Records all requests with timestamps
+- Logs responses with latency metrics
+- Tracks errors and timeouts
+- Logs blocked requests with reasons
+- Records user override decisions
+- All logs include scrubbed payloads
+
+## Request Flow
+
+```
+1. Request arrives at sidecar
+   ↓
+2. Policy Engine validation (agent-control-plane)
+   - Validates manifest against rules
+   - Checks trust level, retention, reversibility
+   ↓
+3. Security validation (SecurityValidator)
+   - Detects sensitive data (credit cards, SSN)
+   - Checks privacy policies
+   ↓
+4. Route to backend agent
+   ↓
+5. On error → Recovery Engine (scak)
+   - Creates AgentFailure record
+   - Determines recovery strategy
+   - Executes compensation if available
+   - Returns recovery information
+```
+
+## Key Architectural Decisions
+
+### 1. The Sidecar Pattern
+
+**Decision**: Extract trust logic from agents into a separate sidecar process.
+
+**Rationale**:
+- Agents stay simple (just business logic)
+- Security is centralized (one sidecar, many agents)
+- Policies are uniform (same rules for all agents)
+- Language-agnostic (works with any agent)
+
+### 2. Trust Score (0-10)
+
+**Decision**: Calculate a simple numeric trust score instead of binary allow/deny.
+
+**Algorithm**:
+```
+Base = trust_level (verified_partner=10, trusted=7, standard=5, unknown=2, untrusted=0)
++2 if reversibility != "none"
++1 if retention == "ephemeral"
+-1 if retention == "permanent"
+-2 if human_in_loop
+-1 if training_consent
+Min: 0, Max: 10
+```
+
+### 3. Three-Tier Policy Enforcement
+
+**Rules**:
+- **Allow** (trust >= 7): Immediate execution
+- **Warn** (trust < 7): 449 status, requires `X-User-Override: true`
+- **Block** (critical violations): 403 Forbidden, no override
+
+### 4. Flight Recorder (JSONL Logs)
+
+**Format**:
+```json
+{"type":"request","trace_id":"...","timestamp":"...","payload":"<scrubbed>"}
+{"type":"response","trace_id":"...","timestamp":"...","latency_ms":123.45}
+{"type":"blocked","trace_id":"...","timestamp":"...","reason":"..."}
+{"type":"quarantine","trace_id":"...","timestamp":"...","override":true}
+```
+
+### 5. Status Code 449 for Warnings
+
+**Rationale**:
+- Semantic meaning: "retry with additional info"
+- Distinguishes from errors (4xx/5xx)
+- Client knows to retry with `X-User-Override: true`
+
+## Performance Targets
+
+| Implementation | Latency (p99) | Throughput | Memory |
+|----------------|---------------|------------|--------|
+| Python Sidecar | < 10ms | ~1k RPS | ~50MB |
+| Go Sidecar | < 1ms | > 10k RPS | ~10MB |
+
+## Deployment Patterns
+
+### Kubernetes Sidecar
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+spec:
+  template:
+    spec:
+      containers:
+      - name: my-agent
+        image: my-agent:latest
+        ports:
+        - containerPort: 8000
+      - name: iatp-sidecar
+        image: iatp-sidecar:latest
+        ports:
+        - containerPort: 8081
+        env:
+        - name: IATP_AGENT_URL
+          value: "http://localhost:8000"
+```
+
+### Docker Compose
+```yaml
+services:
+  my-agent:
+    image: my-agent:latest
+  iatp-sidecar:
+    image: iatp-sidecar:latest
+    environment:
+      - IATP_AGENT_URL=http://my-agent:8000
+    ports:
+      - "8081:8081"
+```
+
+### Standalone Binary
+```bash
+# Go sidecar
+./iatp-sidecar --agent-url=http://localhost:8000 --port=8081
+```
+
+## Integration with External Libraries
+
+### agent-control-plane
+
+Used for policy validation in `IATPPolicyEngine`:
+- Rule-based policy engine
+- Custom conditions and actions
+- Manifest validation
+
+### scak (Self-Correcting Agent Kernel)
+
+Used for failure recovery in `IATPRecoveryEngine`:
+- Structured failure tracking
+- Recovery strategies
+- Compensation transactions

modules/iatp/docs/CLI_GUIDE.md

@@ -0,0 +1,220 @@
+# IATP CLI Guide
+
+The IATP CLI provides developer tools for validating manifests and scanning agents.
+
+## Installation
+
+```bash
+pip install iatp
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/imran-siddique/inter-agent-trust-protocol.git
+cd inter-agent-trust-protocol
+pip install -e .
+```
+
+## Commands
+
+### `iatp verify`
+
+Validate a capability manifest file.
+
+**Usage:**
+
+```bash
+iatp verify <manifest-path> [OPTIONS]
+```
+
+**Options:**
+
+- `--verbose, -v`: Show detailed validation output
+
+**Examples:**
+
+```bash
+# Basic validation
+iatp verify ./manifest.json
+
+# Verbose output
+iatp verify ./manifest.json --verbose
+```
+
+**What It Checks:**
+
+- ✅ Valid JSON schema
+- ✅ Required fields present
+- ✅ Enum values are valid
+- ⚠️ Logical contradictions (e.g., untrusted + no reversibility)
+- ⚠️ Privacy concerns (e.g., permanent retention)
+
+**Example Output:**
+
+```
+🔍 Validating manifest: examples/manifests/secure_bank.json
+
+✅ Schema validation passed
+   Agent ID: secure-bank-agent
+   Trust Level: verified_partner
+   Trust Score: 10/10
+
+✨ Manifest is valid and ready to use!
+```
+
+### `iatp scan`
+
+Scan a running agent and calculate its trust score.
+
+**Usage:**
+
+```bash
+iatp scan <agent-url> [OPTIONS]
+```
+
+**Options:**
+
+- `--timeout, -t`: Request timeout in seconds (default: 10)
+- `--verbose, -v`: Show detailed scan output
+
+**Examples:**
+
+```bash
+# Scan a local agent
+iatp scan http://localhost:8001
+
+# Scan with custom timeout
+iatp scan https://api.example.com/agent --timeout 30
+
+# Verbose scan
+iatp scan http://localhost:8001 --verbose
+```
+
+**What It Does:**
+
+1. Fetches the agent's `/.well-known/agent-manifest` endpoint
+2. Parses the capability manifest
+3. Calculates a trust score (0-100)
+4. Displays security indicators
+5. Provides recommendations
+
+**Example Output:**
+
+```
+🔍 Scanning agent: http://localhost:8001
+
+✅ Trust Score: 100/100 (🟢 LOW RISK)
+
+📊 Agent Profile:
+   Agent ID: secure-bank-agent
+   Trust Level: verified_partner
+   Reversibility: full
+   Data Retention: ephemeral
+
+🔒 Security Indicators:
+   ✅ Idempotent operations
+   ✅ Reversibility support
+   ✅ Limited data retention
+   ✅ Automated processing
+```
+
+### `iatp version`
+
+Show version information.
+
+**Usage:**
+
+```bash
+iatp version
+```
+
+## Trust Score Calculation
+
+Trust scores range from 0-100:
+
+- **80-100**: 🟢 LOW RISK - Highly trustworthy
+- **50-79**: 🟡 MEDIUM RISK - Use with caution
+- **0-49**: 🔴 HIGH RISK - Avoid sensitive data
+
+**Scoring Factors:**
+
+| Factor | Impact |
+|--------|--------|
+| Trust Level: verified_partner | +30 |
+| Trust Level: trusted | +20 |
+| Trust Level: untrusted | -50 |
+| Idempotency enabled | +10 |
+| Reversibility support | +10 |
+| Ephemeral retention | +20 |
+| Permanent retention | -20 |
+| No human review | +10 |
+
+## Exit Codes
+
+- `0`: Success
+- `1`: Validation failed or error occurred
+
+## Integration Examples
+
+### In CI/CD
+
+```yaml
+# GitHub Actions
+- name: Validate manifest
+  run: iatp verify ./config/manifest.json
+```
+
+### Pre-deployment Check
+
+```bash
+#!/bin/bash
+if iatp verify ./manifest.json; then
+  echo "✅ Manifest valid, deploying..."
+  docker compose up -d
+else
+  echo "❌ Manifest invalid, aborting"
+  exit 1
+fi
+```
+
+### Agent Health Monitoring
+
+```bash
+#!/bin/bash
+SCORE=$(iatp scan http://localhost:8001 --verbose | grep "Trust Score" | awk '{print $3}' | cut -d/ -f1)
+if [ "$SCORE" -lt 50 ]; then
+  echo "⚠️ Low trust score detected: $SCORE"
+  # Send alert
+fi
+```
+
+## Troubleshooting
+
+### "Manifest endpoint not found"
+
+The agent doesn't expose `/.well-known/agent-manifest`. Ensure:
+- The agent has an IATP sidecar
+- The sidecar is running
+- The URL is correct
+
+### "Connection error"
+
+The agent is unreachable. Check:
+- Agent is running
+- Network connectivity
+- Firewall rules
+
+### "Validation failed"
+
+The manifest has issues. Run with `--verbose` to see details:
+
+```bash
+iatp verify ./manifest.json --verbose
+```
+
+## Additional Resources
+
+- [Docker Deployment Guide](DOCKER_DEPLOYMENT.md)
+- [Main README](../README.md)
+- [API Documentation](../spec/README.md)