AI Security Gateway

Appearance

System Configuration Reference ​

This document provides comprehensive reference information for configuring AI Security Gateway, including all available options, their defaults, and usage examples.

Configuration Overview ​

AI Security Gateway uses a combination of:

  • Environment Variables - Primary configuration method (.env file)
  • Database Storage - Runtime settings via web interface or API

Its recommended to drive most of the changes and configurations from the web UI

Environment Variables (Primary Configuration) ​

These are set by default during the first setup using the install.sh and start.sh helper scripts. This section of the documents are to explain the environment variables used and it will be up to you to customise further if you wish!

Configuration Required Variables ​

These are REQUIRED if you plan to use OAuth authentication:

bash
# JWT Secret (minimum 32 characters)
JWT_SECRET=your-secure-jwt-secret-min-32-chars-long

# Session Encryption Key (exactly 32 characters)
ENCRYPTION_KEY=your-secure-encryption-key-exactly-32-chars

Generate secure values:

bash
# Generate JWT_SECRET
openssl rand -base64 32

# Generate ENCRYPTION_KEY (must be exactly 32 characters)
openssl rand -base64 32 | cut -c1-32

Optional Configuration Variables ​

Configuration is organized into three categories based on how settings are managed:

1. Environment Variables (Direct Use) ​

These variables are read directly from environment variables or .env file:

bash
# Server Configuration
SERVER_PORT=8080                        # Default: 8080

# Database Configuration
DB_PATH=./data/security.db              # Default: ./data/ai-gateway-security.db

# CORS Configuration
ENVIRONMENT=development                 # Options: development, production
ALLOWED_ORIGINS=http://localhost:3000,http://localhost:5173

# Rate Limiting
RATE_LIMIT_ENABLED=true                 # Enable/disable rate limiting
RATE_LIMIT_RPM=100                      # Requests per minute
RATE_LIMIT_TPM=10000                    # Tokens per minute
RATE_LIMIT_BURST=2                      # Burst size multiplier

# WebSocket Configuration
WEBSOCKET_MAX_CONNECTIONS=1000          # Max concurrent WebSocket connections
WEBSOCKET_READ_TIMEOUT=60               # Read timeout in seconds
WEBSOCKET_WRITE_TIMEOUT=60              # Write timeout in seconds
WEBSOCKET_PING_INTERVAL=30              # Ping interval in seconds
WEBSOCKET_IDLE_TIMEOUT=300              # Idle timeout in seconds

# OAuth Session Cleanup Automation
OAUTH_CLEANUP_INTERVAL_SECONDS=300      # Cleanup interval (default: 5 minutes)
OAUTH_HARD_DELETE_GRACE_HOURS=24        # Hours before archived sessions are permanently deleted
OAUTH_VACUUM_THRESHOLD=1000             # Hard deletes before database VACUUM

# JWT RSA Keys (Optional - enables JWKS endpoint for external verification)
# JWT_RSA_PRIVATE_KEY_FILE=/path/to/private.pem  # Path to RSA private key
# JWT_KEY_ID=gateway-key-v1                       # Custom key ID for rotation

2. Database/Web UI Configuration ​

These settings are stored in the database and configured via the Web UI or API (not environment variables):

MIGRATING FROM PREVIOUS VERSIONS

If you have OAUTH_* environment variables in your .env file from a previous version, these are no longer used. OAuth providers must be configured via the Web UI at http://localhost:8080/settings → OAuth Providers section.

OAuth Provider Configuration (Web UI Only):

  • Navigate to Settings → OAuth Providers
  • Add providers: GitHub, Google, Microsoft, Okta, etc.
  • Configure Client ID and Client Secret (encrypted at rest)
  • Set callback URLs and scopes
  • Enable/disable providers as needed

API Endpoints for OAuth Configuration:

  • GET /api/v1/admin/oauth/providers - List providers
  • POST /api/v1/admin/oauth/providers - Create provider
  • PUT /api/v1/admin/oauth/providers/{id} - Update provider
  • DELETE /api/v1/admin/oauth/providers/{id} - Delete provider

System Settings (Web UI or API):

  • General settings (system name, auto-refresh intervals)
  • Database retention policies
  • MCP tool monitoring configuration
  • External storage (RDS configuration)
  • Observability integrations (Langfuse)

Environment File (.env) ​

Create a .env file in the project root:

bash
# Copy example file
cp .env.example .env

# Edit with your values
vi .env

Example .env file:

bash
# Authentication (REQUIRED for OAuth)
JWT_SECRET=ZXhhbXBsZS1qd3Qtc2VjcmV0LW1pbi0zMi1jaGFycw==
ENCRYPTION_KEY=ZXhhbXBsZS1lbmNyeXB0aW9uLWtleQ==

# Server
SERVER_PORT=8080

# Database
DB_PATH=./data/ai-gateway-security.db

# CORS
ENVIRONMENT=development
# ALLOWED_ORIGINS not needed in development - auto-allows localhost and private IPs

# Rate Limiting
RATE_LIMIT_ENABLED=true
RATE_LIMIT_RPM=100
RATE_LIMIT_TPM=10000
RATE_LIMIT_BURST=2

# WebSocket Configuration
WEBSOCKET_MAX_CONNECTIONS=1000
WEBSOCKET_READ_TIMEOUT=60
WEBSOCKET_WRITE_TIMEOUT=60
WEBSOCKET_PING_INTERVAL=30
WEBSOCKET_IDLE_TIMEOUT=300

# OAuth Session Cleanup (optional - uses sensible defaults)
# OAUTH_CLEANUP_INTERVAL_SECONDS=300      # Cleanup interval (5 minutes default)
# OAUTH_HARD_DELETE_GRACE_HOURS=24        # Grace period before permanent deletion
# OAUTH_VACUUM_THRESHOLD=1000             # Hard deletes before VACUUM

# OAuth Replay Detection (optional - uses sensible defaults)
# OAUTH_REFRESH_TOKEN_HASH_HISTORY_SIZE=3 # Number of token hashes for replay detection

# Optional: Integration Configuration (can also configure via Web UI)
# SLACK_WEBHOOK_URL=https://hooks.slack.com/services/T00000000/B00000000/XXXX
# SIEM_ENDPOINT=https://your-siem-endpoint.com/api/alerts
# SIEM_API_KEY=your-siem-api-key

OAuth Configuration

OAuth providers (GitHub, Google, Microsoft, Okta) are configured via Web UI at http://localhost:8080/settings, not environment variables. See OAuth Setup Guide for details.

System CORS Configuration ​

AI Security Gateway supports flexible CORS (Cross-Origin Resource Sharing) configuration to balance security with usability across different environments.

Configuration Environment Variables ​

Two key environment variables control CORS behavior:

ENVIRONMENT - Controls the operating mode:

  • development or dev (default) - Permissive mode for local development
  • production - Strict mode requiring explicit origin whitelisting

ALLOWED_ORIGINS - Comma-separated list of allowed origins:

  • Example: http://localhost:3000,http://localhost:5173
  • Production: https://app.example.com,https://admin.example.com

Development Mode (Default) ​

When ENVIRONMENT is not set, or set to development or dev:

Automatically Allowed:

  • All localhost origins on any port (e.g., http://localhost:3000)
  • All 127.0.0.1 origins on any port (e.g., http://127.0.0.1:5173)
  • RFC 1918 private IP ranges:
    • 10.0.0.0/8 (10.0.0.0 - 10.255.255.255)
    • 172.16.0.0/12 (172.16.0.0 - 172.31.255.255)
    • 192.168.0.0/16 (192.168.0.0 - 192.168.255.255)

Default Ports:

  • http://localhost:8080 - Main API server
  • http://localhost:3000 - Common frontend dev port
  • http://localhost:5173 - Vite dev server default

Use Case: Local development and LAN testing without hardcoding IP addresses.

Production Mode ​

When ENVIRONMENT is set to production:

Requirements:

  • MUST set ALLOWED_ORIGINS with explicit domain list
  • ONLY listed origins are allowed
  • No automatic localhost or private IP allowance
  • Recommended to use HTTPS for production domains

Example:

bash
export ENVIRONMENT=production
export ALLOWED_ORIGINS="https://app.example.com,https://admin.example.com"

Basic Configuration Examples ​

Local Development (No Configuration) ​

bash
# No environment variables needed - uses defaults
./build/unified-admin

Allows:

  • http://localhost:* (any port)
  • http://127.0.0.1:* (any port)
  • Default ports: 3000, 5173, 8080

LAN/Internal Network Testing ​

bash
export ENVIRONMENT=development
./build/unified-admin

Allows:

  • All localhost origins
  • All RFC 1918 private IPs (e.g., http://192.168.1.100:3000)

Staging Environment ​

bash
export ENVIRONMENT=production
export ALLOWED_ORIGINS="https://staging.example.com"
./build/unified-admin

Allows:

  • ONLY https://staging.example.com

Configuration Production Environment ​

bash
export ENVIRONMENT=production
export ALLOWED_ORIGINS="https://app.example.com,https://admin.example.com"
./build/unified-admin

Allows:

  • ONLY https://app.example.com
  • ONLY https://admin.example.com

Configuration Security Features ​

Development Mode:

  • Automatic localhost support (no hardcoded ports)
  • Private network IP support for LAN access
  • Rejects public IP addresses (e.g., 8.8.8.8)
  • Rejects malicious domains (e.g., evil.com)

Production Mode:

  • Explicit whitelist validation only
  • No wildcard origins
  • No automatic allowances
  • Enforces HTTPS for production

All Modes:

  • Never uses Access-Control-Allow-Origin: * with credentials
  • Proper origin validation before setting CORS headers
  • Logging of rejected origins for security monitoring
  • Preflight request caching (1 hour)

Testing CORS Configuration ​

Test Valid Origin:

bash
curl -v -H "Origin: http://localhost:3000" http://localhost:8080/api/v1/health
# Should include: Access-Control-Allow-Origin: http://localhost:3000

Test LAN Origin (Development Mode):

bash
export ENVIRONMENT=development
curl -v -H "Origin: http://192.168.1.100:3000" http://localhost:8080/api/v1/health
# Should include: Access-Control-Allow-Origin: http://192.168.1.100:3000

Test Rejected Origin:

bash
curl -v -H "Origin: https://evil.com" http://localhost:8080/api/v1/health
# Should NOT include Access-Control-Allow-Origin header
# Check logs for: "CORS: Rejected origin: https://evil.com"

Environment Variable Configuration ​

Add to your .env file:

bash
# Development mode (default)
# ENVIRONMENT=development

# Production mode
# ENVIRONMENT=production
# ALLOWED_ORIGINS=https://app.example.com,https://admin.example.com

# Custom origins for development
# ALLOWED_ORIGINS=http://localhost:3000,http://localhost:5173,http://192.168.1.100:3000

Configuration Troubleshooting ​

Issue: Frontend can't connect to API

  • Check browser console for CORS errors
  • Verify Origin header in request matches allowed list
  • Check server logs for "CORS: Rejected origin" messages
  • Ensure ENVIRONMENT is set correctly

Issue: LAN access not working

  • Verify ENVIRONMENT=development is set
  • Confirm IP is in RFC 1918 range (10.x, 172.16-31.x, 192.168.x)
  • Check firewall rules on server
  • Test with curl to isolate CORS vs network issues

Issue: Production CORS not working

  • Ensure ALLOWED_ORIGINS includes exact domain (including protocol)
  • Verify using HTTPS in production
  • Check for trailing slashes or port mismatches
  • Confirm environment variable is loaded (check logs)

Migration from Previous Versions ​

If upgrading from a version with hardcoded origins:

  1. No action required for development environments - defaults will work
  2. Set ALLOWED_ORIGINS in production with your specific domains
  3. Review logs for any rejected origins after deployment
  4. Test thoroughly in staging before production rollout

Configuration Development Environment ​

bash
# .env file for development
JWT_SECRET=dev-jwt-secret-min-32-characters-long
ENCRYPTION_KEY=dev-encryption-key-32chars!!!

ENVIRONMENT=development
# ALLOWED_ORIGINS not needed - automatically allows localhost and private IPs

SERVER_PORT=8080
DB_PATH=./data/ai-gateway-security.db

# Rate Limiting (relaxed for development)
RATE_LIMIT_ENABLED=true
RATE_LIMIT_RPM=500
RATE_LIMIT_TPM=50000

# WebSocket Configuration
WEBSOCKET_MAX_CONNECTIONS=100