Skip to main content

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.

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

ThreatMitigation
Malicious WASM toolSandbox isolation, capability restrictions
Secret exfiltrationLeak detection, credential injection at boundary
Unauthorized API accessEndpoint allowlisting, rate limiting
Prompt injectionPattern detection, content sanitization
Resource exhaustionCPU fuel metering, memory limits, timeouts
Path traversalPath validation (no .., no absolute paths)
Data exfiltrationNo network access by default, allowlist required
Infinite loopsEpoch interruption + tokio timeout
Side channelsFresh 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

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us