Skip to main content
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 -H "Authorization: Bearer your-api-key" \
  http://your-server:4200/api/agents
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

RoleCapabilities
OwnerFull system access, manage users, modify global config
AdminCreate/delete agents, view audit logs, modify agent configs
UserCreate and manage own agents, send messages, view own data
ViewerRead-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

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: [email protected]
  • 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