Security Configuration

Configure authentication, rate limiting, and security features in OpenFang

OpenFang implements 16 discrete security layers with defense-in-depth architecture. This guide covers configuring authentication, access control, and security hardening.

Security Architecture

OpenFang’s security is built on multiple independent layers:

16 Security Systems

WASM sandbox, Merkle audit trail, taint tracking, Ed25519 signing, SSRF protection, secret zeroization, and more

Defense in Depth

Multiple independent controls—no single point of failure

Zero Trust

Capability-based permissions, privilege escalation prevention, cryptographic verification

Audit Trail

Tamper-evident Merkle hash chain for all agent actions

API Authentication

Enable Bearer Token Authentication

Production Deployment: Always enable API authentication when exposing OpenFang to the internet.

# config.toml
api_key = "your-secure-random-api-key-here"
api_listen = "0.0.0.0:4200"  # Bind to all interfaces

Generate a secure API key:

# Generate 32-byte random key
openssl rand -base64 32

# Or use OpenFang's built-in generator
openfang keygen

Using the API Key

cURL

curl -H "Authorization: Bearer your-api-key" \
  http://your-server:4200/api/agents

import requests

headers = {
    "Authorization": "Bearer your-api-key"
}

response = requests.get(
    "http://your-server:4200/api/agents",
    headers=headers
)

fetch('http://your-server:4200/api/agents', {
  headers: {
    'Authorization': 'Bearer your-api-key'
  }
});

Localhost Bypass: Requests from 127.0.0.1 bypass authentication by default for local CLI usage. This can be disabled with api_require_auth_local = true.

Network Security

Bind Address Configuration

# Development: localhost only
api_listen = "127.0.0.1:4200"

# Production: all interfaces with authentication
api_listen = "0.0.0.0:4200"
api_key = "your-secure-api-key"

Never bind to 0.0.0.0 without setting api_key. This exposes your instance to the internet without authentication.

OFP Peer Network

Secure peer-to-peer networking for agent collaboration:

[network]
listen_addr = "0.0.0.0:4200"           # OFP network bind address
shared_secret = "your-p2p-secret"      # Required for peer authentication

listen_addr · string · default: "127.0.0.1:4200"

OFP network listen address. Use 0.0.0.0 for public peer networking.

shared_secret · string · required

Shared secret for HMAC-SHA256 mutual authentication. Must be identical across all peers in the network.

OFP Security Features:

• HMAC-SHA256 mutual authentication
• Nonce-based replay protection
• Constant-time verification
• No plain-text credentials on wire

Rate Limiting

OpenFang uses GCRA (Generic Cell Rate Algorithm) for cost-aware rate limiting:

# Global API rate limiting
api_rate_limit = 100  # Requests per minute per IP

# Webhook-specific rate limiting
[webhook_trigger]
enabled = true
token_env = "OPENFANG_WEBHOOK_TOKEN"
rate_limit_per_minute = 30

Per-Channel Rate Limits

[telegram.overrides]
rate_limit_per_user = 10  # Messages per user per minute

[discord.overrides]
rate_limit_per_user = 20

[slack.overrides]
rate_limit_per_user = 30

Role-Based Access Control (RBAC)

Multi-user support with role hierarchy:

[[users]]
name = "Alice"
role = "owner"  # Full system access
channel_bindings = { telegram = "123456789" }

[[users]]
name = "Bob"
role = "admin"  # Manage agents, view all data
channel_bindings = { discord = "987654321" }

[[users]]
name = "Charlie"
role = "user"   # Create and manage own agents only
channel_bindings = { slack = "U01234567" }

[[users]]
name = "Dave"
role = "viewer"  # Read-only access
api_key_hash = "$2b$12$..."  # Bcrypt hash for API access

Role Capabilities

Role	Capabilities
Owner	Full system access, manage users, modify global config
Admin	Create/delete agents, view audit logs, modify agent configs
User	Create and manage own agents, send messages, view own data
Viewer	Read-only access to agents and data

Capability-Based Permissions

Agents declare required tools, kernel enforces access:

# agent.toml
[capabilities]
tools = ["file_read", "web_fetch"]  # Agent can ONLY use these tools

# Child agents cannot exceed parent capabilities
[capabilities]
max_shell_commands = 0  # Disable shell access entirely
max_file_writes = 10     # Limit file write operations

Privilege Escalation Prevention: Child agents spawned by an agent can never have more capabilities than their parent.

Secret Management

Environment Variables (Recommended)

Store all secrets in environment variables:

# LLM API Keys
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."

# Channel Tokens
export TELEGRAM_BOT_TOKEN="..."
export DISCORD_BOT_TOKEN="..."

# OpenFang Secrets
export OPENFANG_API_KEY="..."
export OPENFANG_WEBHOOK_TOKEN="..."

Never commit secrets to version control. Use .env files with .gitignore or secret management systems.

Secret Zeroization

OpenFang automatically wipes secrets from memory:

// API keys are wrapped in Zeroizing<String>
// Memory is auto-wiped when dropped
use zeroize::Zeroizing;

let api_key = Zeroizing::new(std::env::var("ANTHROPIC_API_KEY")?);
// ... use api_key ...
// Memory is securely wiped here when api_key goes out of scope

SSRF Protection

Server-Side Request Forgery prevention:

[web.fetch]
block_private_ips = true        # Block 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16
block_metadata_endpoints = true # Block cloud metadata (169.254.169.254)
max_redirects = 3               # Prevent redirect chains

Blocked Targets:

• Private IP ranges (RFC 1918)
• Loopback addresses (127.0.0.0/8)
• Link-local addresses (169.254.0.0/16)
• Cloud metadata endpoints (AWS, GCP, Azure)
• DNS rebinding attacks

Path Traversal Prevention

All file operations use canonicalized paths:

[security]
strict_path_validation = true  # Enable path traversal protection
allow_symlinks = false         # Block symbolic link following

Protected Operations:

• file_read: Cannot escape workspace
• file_write: Cannot write outside allowed directories
• file_delete: Cannot delete system files

Audit Trail

Tamper-evident Merkle hash chain:

[audit]
enabled = true
log_path = "~/.openfang/audit.jsonl"  # JSONL format
hash_algorithm = "sha256"              # Cryptographic hashing

Verify Audit Integrity

# Verify entire audit chain
openfang audit verify

# View audit log for specific agent
openfang audit show --agent researcher

# Export audit log
openfang audit export --format json > audit-2026-03.json

Audit Events Logged:

• Agent creation/deletion
• Tool invocations
• File system access
• Network requests
• Model API calls
• Configuration changes

Prompt Injection Scanning

Skill content is scanned for injection attempts:

[security]
prompt_injection_scan = true

Detection Patterns:

• Override attempts (“Ignore previous instructions”)
• Data exfiltration (“Send system info to…”)
• Shell reference injection
• Base64-encoded payloads

WASM Sandbox

Tool code runs in WebAssembly with dual metering:

[security.wasm]
fuel_limit = 10_000_000         # Instruction fuel limit
epoch_timeout_ms = 5000         # Watchdog thread timeout
max_memory_pages = 256          # Max WASM memory (16MB)

Dual Metering: Fuel metering catches infinite loops, epoch interruption catches sleep/wait attacks. A watchdog thread forcibly kills runaway code.

Security Headers

HTTP security headers on all responses:

[security.headers]
csp = "default-src 'self'; script-src 'self' 'unsafe-inline'"
x_frame_options = "DENY"
x_content_type_options = "nosniff"
strict_transport_security = "max-age=31536000; includeSubDomains"

Headers Applied:

• Content-Security-Policy
• X-Frame-Options: DENY
• X-Content-Type-Options: nosniff
• Strict-Transport-Security
• Referrer-Policy: strict-origin-when-cross-origin

Docker Sandbox (Optional)

Run code execution in isolated Docker containers:

[security.docker]
enabled = true
image = "python:3.12-slim"
network = "none"              # No network access
memory_limit = "512m"
cpu_limit = 1.0
timeout_secs = 60
read_only_root = true
pids_limit = 100

Docker sandbox requires Docker daemon access. Use WASM sandbox for lightweight isolation without Docker dependency.

Production Security Checklist

1. Enable API Authentication

   Set api_key in config.toml with a strong random key (32+ characters)

2. Configure Network Binding

   Use api_listen = "0.0.0.0:4200" with authentication, or 127.0.0.1:4200 for local-only

3. Enable Rate Limiting

   Set api_rate_limit and per-channel rate_limit_per_user

4. Configure RBAC

   Define users with appropriate roles (owner/admin/user/viewer)

5. Enable Audit Logging

   Set audit.enabled = true and monitor audit trail

6. Restrict File Access

   Enable strict_path_validation and disable allow_symlinks

7. Configure SSRF Protection

   Enable block_private_ips and block_metadata_endpoints

8. Use Environment Variables for Secrets

   Never hardcode API keys in config files

9. Enable HTTPS (Reverse Proxy)

   Use nginx/Caddy with TLS certificates in front of OpenFang

10. Regular Security Updates

    Keep OpenFang updated: openfang update

Reverse Proxy (HTTPS)

Nginx Configuration

server {
    listen 443 ssl http2;
    server_name agents.example.com;

    ssl_certificate /etc/letsencrypt/live/agents.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/agents.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:4200;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Caddy Configuration

agents.example.com {
    reverse_proxy localhost:4200
}

Firewall Rules

# UFW (Ubuntu)
sudo ufw allow 4200/tcp  # OpenFang API
sudo ufw allow 443/tcp   # HTTPS
sudo ufw enable

# iptables
sudo iptables -A INPUT -p tcp --dport 4200 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 443 -j ACCEPT

Security Monitoring

# View security events
openfang logs --level warn

# Monitor failed authentication attempts
openfang audit show --filter auth_failed

# Check rate limit violations
openfang metrics --filter rate_limit

# Verify audit chain integrity
openfang audit verify

Incident Response

Revoke Compromised API Key

# Generate new API key
openfang keygen

# Update config.toml with new key
# Restart OpenFang
openfang restart

# Check who accessed with old key
openfang audit show --filter api_key

Disable Compromised User

# config.toml
[[users]]
name = "CompromisedUser"
role = "viewer"  # Downgrade to read-only
enabled = false  # Disable entirely

Security Reporting

Found a vulnerability? Report it responsibly:

• Email: [e-mail]
• Do NOT open public GitHub issues for security issues
• Expect: Acknowledgment within 48 hours, fix within 14 days

See SECURITY.md for full policy.

Next Steps

Configuration Overview

Complete configuration guide

Deployment

Production deployment best practices