> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/RightNow-AI/openfang/llms.txt
> Use this file to discover all available pages before exploring further.
# 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:
WASM sandbox, Merkle audit trail, taint tracking, Ed25519 signing, SSRF protection, secret zeroization, and more
Multiple independent controls—no single point of failure
Capability-based permissions, privilege escalation prevention, cryptographic verification
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.
```toml theme={null}
# 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:
```bash theme={null}
# Generate 32-byte random key
openssl rand -base64 32
# Or use OpenFang's built-in generator
openfang keygen
```
### Using the API Key
```bash cURL theme={null}
curl -H "Authorization: Bearer your-api-key" \
http://your-server:4200/api/agents
```
```python Python theme={null}
import requests
headers = {
"Authorization": "Bearer your-api-key"
}
response = requests.get(
"http://your-server:4200/api/agents",
headers=headers
)
```
```javascript JavaScript theme={null}
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
```toml theme={null}
# 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:
```toml theme={null}
[network]
listen_addr = "0.0.0.0:4200" # OFP network bind address
shared_secret = "your-p2p-secret" # Required for peer authentication
```
OFP network listen address. Use `0.0.0.0` for public peer networking.
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:
```toml theme={null}
# 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
```toml theme={null}
[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:
```toml theme={null}
[[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:
```toml theme={null}
# 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:
```bash theme={null}
# 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:
```rust theme={null}
// API keys are wrapped in Zeroizing
// 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:
```toml theme={null}
[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:
```toml theme={null}
[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:
```toml theme={null}
[audit]
enabled = true
log_path = "~/.openfang/audit.jsonl" # JSONL format
hash_algorithm = "sha256" # Cryptographic hashing
```
### Verify Audit Integrity
```bash theme={null}
# 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:
```toml theme={null}
[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:
```toml theme={null}
[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:
```toml theme={null}
[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:
```toml theme={null}
[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
Set `api_key` in `config.toml` with a strong random key (32+ characters)
Use `api_listen = "0.0.0.0:4200"` with authentication, or `127.0.0.1:4200` for local-only
Set `api_rate_limit` and per-channel `rate_limit_per_user`
Define users with appropriate roles (owner/admin/user/viewer)
Set `audit.enabled = true` and monitor audit trail
Enable `strict_path_validation` and disable `allow_symlinks`
Enable `block_private_ips` and `block_metadata_endpoints`
Never hardcode API keys in config files
Use nginx/Caddy with TLS certificates in front of OpenFang
Keep OpenFang updated: `openfang update`
## Reverse Proxy (HTTPS)
### Nginx Configuration
```nginx theme={null}
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
```caddy theme={null}
agents.example.com {
reverse_proxy localhost:4200
}
```
## Firewall Rules
```bash theme={null}
# 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
```bash theme={null}
# 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
```bash theme={null}
# 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
```toml theme={null}
# config.toml
[[users]]
name = "CompromisedUser"
role = "viewer" # Downgrade to read-only
enabled = false # Disable entirely
```
## Security Reporting
**Found a vulnerability?** Report it responsibly:
* **Email**: [security@openfang.ai](mailto:security@openfang.ai)
* **Do NOT** open public GitHub issues for security issues
* **Expect**: Acknowledgment within 48 hours, fix within 14 days
See [SECURITY.md](https://github.com/RightNow-AI/openfang/blob/main/SECURITY.md) for full policy.
## Next Steps
Complete configuration guide
Production deployment best practices