> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/nearai/ironclaw/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/security/wasm-sandbox) for details.

### Network Isolation

HTTP requests from WASM tools pass through multiple validation layers:

```rust theme={null}
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](/security/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](/security/credentials) 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](/security/prompt-injection) 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:

```rust theme={null}
// 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)

```bash theme={null}
ironclaw onboard  # Auto-generates and stores in keychain
```

**Option 2: Environment Variable** (for CI/Docker)

```bash theme={null}
export SECRETS_MASTER_KEY="<32+ byte random string>"
```

Generate a secure key:

```bash theme={null}
openssl rand -base64 32
```

### Safety Configuration

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

```bash theme={null}
# 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](~/workspace/source/src/safety/mod.rs#L28-L177)
* **WASM runtime**: [src/tools/wasm/mod.rs:1-134](~/workspace/source/src/tools/wasm/mod.rs#L1-L134)
* **Leak detector**: [src/safety/leak\_detector.rs:132-252](~/workspace/source/src/safety/leak_detector.rs#L132-L252)
* **Secrets crypto**: [src/secrets/crypto.rs:38-141](~/workspace/source/src/secrets/crypto.rs#L38-L141)
* **Allowlist validator**: [src/tools/wasm/allowlist.rs:74-164](~/workspace/source/src/tools/wasm/allowlist.rs#L74-L164)

## Next Steps

* [WASM Sandbox](/security/wasm-sandbox) - Deep dive into sandbox isolation
* [Prompt Injection Defense](/security/prompt-injection) - Pattern detection and sanitization
* [Credential Management](/security/credentials) - Encryption and injection architecture
* [Network Security](/security/network-security) - Allowlisting and rate limiting