Security Architecture Overview

Multi-layer defense-in-depth security architecture protecting your data and credentials

IronClaw implements defense in depth to protect your data and prevent misuse by AI agents, malicious tools, and external attackers. Security is not an afterthought—it’s the foundation of every component.

Security Philosophy

IronClaw’s security model is built on three principles:

1. Your data stays yours - All information stored locally, encrypted, never shared
2. Zero trust for code - All tools run in isolated sandboxes with explicit permissions
3. Defense in depth - Multiple security layers protect against different attack vectors

Multi-Layer Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    Layer 1: WASM Sandbox                        │
│  • Memory isolation (10MB limit)                                │
│  • CPU metering (fuel system)                                   │
│  • No filesystem access                                         │
│  • Capability-based permissions                                 │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                Layer 2: Network Security                        │
│  • Endpoint allowlisting (host + path)                          │
│  • HTTPS enforcement                                            │
│  • Rate limiting per tool                                       │
│  • Request/response size limits                                 │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│              Layer 3: Credential Protection                     │
│  • Secrets never exposed to tools                               │
│  • Injection at host boundary only                              │
│  • AES-256-GCM encryption at rest                               │
│  • Per-secret key derivation (HKDF)                             │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                Layer 4: Leak Detection                          │
│  • Scan outbound requests for secrets                           │
│  • Scan responses before returning to WASM                      │
│  • Pattern matching (regex + Aho-Corasick)                      │
│  • Block/redact/warn actions                                    │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│            Layer 5: Prompt Injection Defense                    │
│  • Pattern detection in external content                        │
│  • Content sanitization & escaping                              │
│  • Policy enforcement (block/warn/review)                       │
│  • Safety wrappers for LLM context                              │
└─────────────────────────────────────────────────────────────────┘

Security Components

WASM Sandbox

All untrusted tools execute in WebAssembly containers with:

• Resource limits: 10MB memory, configurable CPU fuel
• No system access: No filesystem, no raw sockets, no subprocess spawning
• Fresh instances: Each execution creates a new isolated instance
• Explicit capabilities: HTTP, secrets, workspace, and tool invocation are opt-in

See WASM Sandbox for details.

Network Isolation

HTTP requests from WASM tools pass through multiple validation layers:

WASM ──► Allowlist ──► Leak Scan ──► Credential ──► Execute ──► Leak Scan ──► WASM
         Validator     (request)     Injector       Request     (response)

Every request is checked against:

• Host allowlist: Only approved domains (e.g., api.openai.com)
• Path prefixes: Restricted to specific API paths (e.g., /v1/)
• HTTP methods: GET/POST/etc. explicitly allowed per endpoint
• Secret scanning: Block requests containing leaked credentials

See Network Security for details.

Credential Management

Secrets are never exposed to WASM tools:

1. Storage: Encrypted with AES-256-GCM using per-secret derived keys
2. Master key: Stored in OS keychain or environment variable
3. Existence checks: Tools can verify secrets exist without reading values
4. Injection: Host injects credentials at request time (WASM never sees plaintext)
5. Leak detection: All responses scanned before returning to WASM

See Credential Management for details.

Prompt Injection Defenses

External content (emails, webhooks, API responses) is sanitized before reaching the LLM:

• Pattern detection: Identify injection attempts (“ignore previous”, “system:”, etc.)
• Content wrapping: Structural delimiters for untrusted data
• Policy rules: Block dangerous patterns (system file access, shell injection)
• Escape sequences: Neutralize special tokens (<|endoftext|>, [INST], etc.)

See Prompt Injection Defense for details.

Threat Model

Protected Against

Threat	Mitigation
Malicious WASM tool	Sandbox isolation, capability restrictions
Secret exfiltration	Leak detection, credential injection at boundary
Unauthorized API access	Endpoint allowlisting, rate limiting
Prompt injection	Pattern detection, content sanitization
Resource exhaustion	CPU fuel metering, memory limits, timeouts
Path traversal	Path validation (no .., no absolute paths)
Data exfiltration	No network access by default, allowlist required
Infinite loops	Epoch interruption + tokio timeout
Side channels	Fresh instance per execution, no state reuse

Out of Scope

• Physical security: Assumes attacker doesn’t have direct machine access
• OS compromise: Trust the host operating system
• LLM jailbreaking: Defense against adversarial prompts (best effort)
• Supply chain: Trust the Rust toolchain and dependencies

Security Defaults

IronClaw ships with secure defaults:

• ✅ All tools run in WASM sandbox (no native code execution)
• ✅ HTTPS-only for HTTP requests (HTTP blocked by default)
• ✅ Secrets encrypted at rest with AES-256-GCM
• ✅ Leak detection enabled for all outputs
• ✅ Prompt injection checking enabled
• ✅ No telemetry or analytics
• ✅ No data sharing with third parties

Audit and Logging

All security-relevant events are logged:

// Leak detection blocked a secret
tracing::warn!(
    pattern = "openai_api_key",
    severity = "critical",
    "Secret leak blocked in HTTP request"
);

// Allowlist denied a request
tracing::warn!(
    tool = "untrusted_tool",
    host = "evil.com",
    "HTTP request denied: host not in allowlist"
);

// Prompt injection detected
tracing::warn!(
    pattern = "ignore previous",
    severity = "high",
    "Potential prompt injection detected"
);

Set RUST_LOG=ironclaw=debug to see all security checks.

Security Configuration

Master Key Setup

The master key encrypts all secrets. Two options:

Option 1: OS Keychain (recommended for local use)

ironclaw onboard  # Auto-generates and stores in keychain

Option 2: Environment Variable (for CI/Docker)

export SECRETS_MASTER_KEY="<32+ byte random string>"

Generate a secure key:

openssl rand -base64 32

Safety Configuration

Configure in ~/.ironclaw/.env or via environment:

# Maximum tool output length (bytes)
SAFETY_MAX_OUTPUT_LENGTH=100000

# Enable prompt injection detection
SAFETY_INJECTION_CHECK_ENABLED=true

Source Code References

• Safety layer: src/safety/mod.rs:28-177
• WASM runtime: src/tools/wasm/mod.rs:1-134
• Leak detector: src/safety/leak_detector.rs:132-252
• Secrets crypto: src/secrets/crypto.rs:38-141
• Allowlist validator: src/tools/wasm/allowlist.rs:74-164

Next Steps

• WASM Sandbox - Deep dive into sandbox isolation
• Prompt Injection Defense - Pattern detection and sanitization
• Credential Management - Encryption and injection architecture
• Network Security - Allowlisting and rate limiting