Architecture Overview

AI Security Gateway - Understanding Your Security Platform

This guide provides a user-friendly overview of the AI Security Gateway, explaining what you get when you download the software and how the components work together to protect your AI infrastructure. This is designed to help you understand the platform without getting into technical details.

What You Get: The Complete Package

When you download the AI Security Gateway, you receive a complete, ready-to-run security platform. No compilation, no complex setup - just configure and run.

📦 Release Package Contents

Each release archive contains everything you need:

ai-security-gateway-<version>-<platform>/
├── 🚀 unified-admin (or .exe)      # The main application
├── 📜 Helper Scripts                # Easy installation and management
│   ├── install.sh                   # Automated setup (Linux/macOS)
│   ├── verify.sh                    # Installation verification
│   ├── start.sh                     # Start all services (Linux/macOS)
│   └── start.ps1                    # Start all services (Windows)
├── 🔧 Service Files                 # Production deployment support
│   ├── ai-security-gateway.service  # Systemd service (Linux)
│   └── com.aisecuritygateway.unified-admin.plist  # Launchd (macOS)
├── 🎨 Frontend Package              # Web interface
│   ├── dist/                        # Pre-built Vue.js application
│   ├── Dockerfile.frontend          # Container definition
│   ├── .env                         # Frontend configuration (editable!)
│   └── docker-compose.frontend.yml  # Docker orchestration
├── ⚙️ Configuration                 # System settings
│   ├── configs/config.example.yaml  # Configuration template
│   └── .env.example                 # Environment variables template
├── 🛡️ Security Policies            # Pre-built security rules
│   └── policies/                    # 7 JSON policy files (250+ rules)
│       ├── llm-critical-security.json
│       ├── llm-standard-security.json
│       ├── mcp-advanced-security.json
│       ├── llm-compliance-gdpr.json
│       ├── llm-data-redaction.json
│       └── ... (and more)
└── 📚 Documentation                 # Complete guides
    ├── README.md                    # Project overview
    ├── INSTALL.md                   # Detailed installation
    ├── QUICKSTART.md                # Quick start guide
    └── LICENSE                      # License information

System Architecture: How It All Works Together

How It Works - Simple View

┌─────────────────────────────────────────────────────────────────┐
│                     YOUR WEB BROWSER                            │
│                   http://localhost:80.                          │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             │ Access Web Interface
                             │
┌────────────────────────────▼────────────────────────────────────┐
│                    WEB INTERFACE                                │
│              Your Control Dashboard                             │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  📊 Dashboard      │  🔄 Proxy Manager  │  🚨 Alerts      │  │
│  │  🔐 Users & Teams  │  🛡️ Policies       │  ⚙️ Settings    │  │
│  │  🤖 A2A Registry   │  📈 Analytics      │  🎮 Playground  │  │
│  │  🛡️ Guardrails     │  🧪 Guardrail Evals│                 │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                 │
│  Easy Setup Options:                                            │
│  ✓ Quick Start: ./start.sh (everything runs automatically)      │
│  ✓ Advanced: Docker containers for production                   │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             │ Communicates with
                             │
┌────────────────────────────▼────────────────────────────────────┐
│                    MAIN APPLICATION                             │
│                  (unified-admin binary)                         │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  🔐 User Authentication                                   │  │
│  │  ├─ Login with OAuth (GitHub, Google, etc.)               │  │
│  │  └─ API Keys for programmatic access                      │  │
│  └───────────────────────────────────────────────────────────┘  │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  Core Management Features                                 │  │
│  │  ├─ Create and manage proxy instances                     │  │
│  │  ├─ Monitor security alerts                               │  │
│  │  ├─ Track token usage and costs                           │  │
│  │  ├─ Control MCP tools                                     │  │
│  │  └─ Manage users, teams, and budgets                      │  │
│  └───────────────────────────────────────────────────────────┘  │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  Real-Time Updates (WebSocket)                            │  │
│  │  ├─ Proxy Status Changes       ├─ Security Alerts         │  │
│  │  ├─ Token Usage Updates        └─ System Notifications    │  │
│  └───────────────────────────────────────────────────────────┘  │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  Security Policy Engine                                   │  │
│  │  ├─ 250+ Detection Rules       ├─ Real-Time Blocking      │  │
│  │  ├─ Custom Policies            └─ Risk Scoring            │  │
│  └───────────────────────────────────────────────────────────┘  │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  Guardrail Provider Engine                                │  │
│  │  ├─ 3rd-Party AI Safety APIs   ├─ Per-Proxy Assignment    │  │
│  │  ├─ Per-Team Scoping           ├─ Concurrent Evaluation   │  │
│  │  ├─ Health Monitoring          └─ Guardrail Eval Testing  │  │
│  └───────────────────────────────────────────────────────────┘  │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  Database (SQLite with GORM)                              │  │
│  │  ├─ Proxy Configurations       ├─ Security Alerts         │  │
│  │  ├─ Request Logs               ├─ Token Usage Data        │  │
│  │  ├─ Users & Teams              ├─ API Keys                │  │
│  │  └─ Audit Logs (35+ event types)                          │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                 │
│  Runs as:                                                       │
│  ✓ Native Binary (./unified-admin) - Optimal performance        │
│  ✓ Systemd Service (Linux) - Production deployment              │
│  ✓ Launchd Service (macOS) - Background service                 │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             │ Proxies Traffic & Monitors
                             │
┌────────────────────────────▼────────────────────────────────────┐
│                   SECURITY PROXIES                              │
│           (The Magic Happens Here)                              │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  MCP Proxies (Port 3000+)                                 │  │
│  │  ├─ Sit between your apps and MCP servers                 │  │
│  │  ├─ Block dangerous tool calls automatically              │  │
│  │  ├─ Monitor what tools are being used                     │  │
│  │  ├─ Apply 3rd-party guardrails (per-proxy or per-team)    │  │
│  │  ├─ Handle user authentication                            │  │
│  │  └─ Log everything for security monitoring                │  │
│  └───────────────────────────────────────────────────────────┘  │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  LLM Proxies (Port 4000+)                                 │  │
│  │  ├─ Work with OpenAI, Anthropic, Azure, and more          │  │
│  │  ├─ Track how much you're spending on AI                  │  │
│  │  ├─ Stop spending when you hit your budget                │  │
│  │  ├─ Add security rules to every AI request                │  │
│  │  ├─ Apply 3rd-party guardrails (per-proxy or per-team)    │  │
│  │  ├─ Hide sensitive data from AI models                    │  │
│  │  └─ Block malicious prompts automatically                 │  │
│  └───────────────────────────────────────────────────────────┘  │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  A2A Agent Proxies (Port 5000+)                           │  │
│  │  ├─ Manage AI agent communications                        │  │
│  │  ├─ Control which agents can talk to each other           │  │
│  │  ├─ Monitor agent tasks and workflows                     │  │
│  │  ├─ Apply 3rd-party guardrails (per-proxy or per-team)    │  │
│  │  └─ Apply security policies to agent interactions         │  │
│  └───────────────────────────────────────────────────────────┘  │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             │ Forwards Requests To
                             │
┌────────────────────────────▼────────────────────────────────────┐
│                     YOUR AI SERVICES                            │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  🤖 MCP Servers                                           │  │
│  │  └─ Claude Desktop, Cursor IDE, Your Custom Tools         │  │
│  └───────────────────────────────────────────────────────────┘  │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  🧠 AI Model APIs                                         │  │
│  │  └─ OpenAI GPT, Claude, Azure OpenAI, Local Models        │  │
│  └───────────────────────────────────────────────────────────┘  │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  🤝 AI Agents                                             │  │
│  │  └─ Custom AI agents and automated workflows              │  │
│  └───────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

                             │
                             │ Integrates With
                             │
┌────────────────────────────▼────────────────────────────────────┐
│              EXTERNAL INTEGRATIONS (Optional)                   │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  🔍 Observability                                         │  │
│  │  ├─ Langfuse (LLM traces & analytics)                     │  │
│  │  ├─ Prometheus (metrics)                                  │  │
│  │  ├─ Grafana (dashboards)                                  │  │
│  │  ├─ OpenTelemetry (distributed tracing)                   │  │
│  │  └─ Jaeger (trace visualization)                          │  │
│  └───────────────────────────────────────────────────────────┘  │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  🚨 Security & Notifications                              │  │
│  │  ├─ SIEM Integration (alert forwarding)                   │  │
│  │  ├─ SOAR Integration (incident automation)                │  │
│  │  ├─ Slack Notifications (webhooks)                        │  │
│  │  └─ Email Alerts (SMTP)                                   │  │
│  └───────────────────────────────────────────────────────────┘  │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  🔐 OAuth Providers (Authentication)                      │  │
│  │  ├─ GitHub         ├─ Google         ├─ Okta              │  │
│  │  ├─ Azure AD       ├─ Auth0          ├─ GitLab            │  │
│  │  ├─ Keycloak       └─ Custom OAuth 2.0/2.1 Providers      │  │
│  └───────────────────────────────────────────────────────────┘  │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  🛡️ Guardrail Providers (AI Safety)                       │  │
│  │  ├─ Groq Safeguard    ├─ EnkryptAI     ├─ DynamoAI        │  │
│  │  ├─ GuardrailsAI      └─ Fiddler AI Guardrails            │  │
│  └───────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

Understanding the Components

1. Web Interface: Your Control Center

The web interface is your main dashboard for managing everything. You access it through your web browser.

What You'll Find:

Dashboard: See what's happening right now - active proxies, recent alerts, spending
Proxy Manager: Create new security proxies, start/stop them, check their status
Alert Monitor: View security alerts and decide what to do about them
User & Team Management: Add team members and control who can do what
Policy Editor: Choose which security rules apply to each proxy
Guardrail Providers: Configure and assign third-party AI safety guardrails to proxies
Guardrail Evaluations: Test your guardrails against 71+ built-in security test cases
Analytics: See how much you're spending on AI and who's using what
Playground: Test your AI connections safely
Settings: Configure the system and connect to other tools

Getting Started:

Quick Start: Just run ./start.sh and visit http://localhost:80
Production: Use Docker containers for team deployments
Advanced: Integrate with existing web servers (nginx, apache)

2. Main Application: The Security Engine

The unified-admin program is the brain of the system. It runs quietly in the background and handles all the security work.

What It Does (Behind the Scenes):

Creates Security Proxies: When you click "Create Proxy" in the web interface
Applies Security Rules: Automatically blocks dangerous requests using 250+ built-in rules
Runs Guardrail Providers: Screens content through third-party AI safety APIs in real time
Manages Users: Handles logins, teams, and permissions
Tracks Spending: Monitors AI costs and enforces budgets
Sends Alerts: Notifies you when something suspicious happens
Stores Data: Keeps logs, settings, and history in a local database

Starting the Application:

bash

# Easiest way - everything starts automatically
./start.sh                  # Linux/macOS
.\start.ps1                 # Windows

# Or run directly
./unified-admin             # Linux/macOS
.\unified-admin.exe         # Windows

Why It's Fast:

Single executable file - no complex installation
Uses very little memory (typically under 100MB)
Handles thousands of requests without slowing down
Works on any modern computer

3. Security Proxies: Your AI Bodyguards

Think of proxies as smart security guards that stand between your apps and AI services. When you create one, it automatically starts protecting your AI connections.

MCP Proxies (for Claude Desktop, Cursor, etc.):

What they do: Monitor your MCP tools and block dangerous ones
Security: Tools are disabled by default - you choose which ones to allow
Guardrails: Apply third-party AI safety guardrails per-proxy or per-team
Monitoring: See exactly which tools are being used and by whom
Authentication: Handle user logins automatically
Logging: Keep records of everything for security audits

LLM Proxies (for ChatGPT, Claude API, etc.):

What they do: Monitor your AI API calls and track spending
Cost Control: Automatically stop requests when you hit your budget
Guardrails: Screen requests and responses through third-party safety APIs
Data Protection: Hide sensitive information from AI models
Compliance: Add required security instructions to every request
Monitoring: Track usage patterns and detect suspicious activity

A2A Agent Proxies (for AI agents):

What they do: Manage communication between AI agents
Access Control: Decide which agents can talk to each other
Guardrails: Apply third-party AI safety guardrails to agent traffic
Task Tracking: Monitor agent workflows from start to finish
Security: Apply your security rules to all agent interactions

Using Proxies is Easy:

Go to the web interface and click "Create Proxy"
Tell it where your AI service is (URL and settings)
Pick which security rules to apply
Click "Start" and you're protected!
Update your apps to use the proxy address instead of the original

4. Security Policies: Your Protection Rules

Security policies are like rule books that tell the system what's safe and what's dangerous. We include several ready-to-use rule sets.

Ready-Made Security Rule Sets:

Critical Security - Maximum protection for high-risk environments
Standard Security - Good balance of security and usability for daily use
GDPR Compliance - Special rules for European data protection laws
Data Protection - Automatically hide sensitive information (emails, phone numbers, etc.)
Advanced MCP Security - 159+ rules specifically for MCP tool monitoring
Custom Template - Starting point for creating your own rules

How Security Works:

Pattern Matching: Rules look for dangerous patterns in requests
Risk Scoring: Each dangerous pattern gets a risk score
Automatic Blocking: High-risk requests are blocked immediately
Alert Generation: You get notified about every security event
Different Levels: Critical, High, Medium, Low severity levels

Customizing Your Security:

Easy Setup: Use the web interface to assign policies to proxies
Custom Rules: Create your own security rules for your specific needs
Testing: Test new rules before applying them to production
Mix and Match: Apply different policies to different proxies

5. Guardrail Providers: Third-Party AI Safety

Guardrail providers let you integrate third-party AI safety APIs into your proxy pipeline. They screen requests and responses through external services that specialize in detecting harmful content, PII, prompt injection, and more.

Supported Providers:

Groq Safeguard - Fast safety classification across 7 categories (illegal acts, violence, hate speech, PII, prompt injection, etc.)
EnkryptAI - Comprehensive security with NSFW, toxicity, PII, injection, and policy violation detection
DynamoAI DynamoGuard - Multi-policy moderation with per-policy scoring
GuardrailsAI - Self-hosted, open-source guardrails with 67+ validators
Fiddler AI Guardrails - Sub-second safety classification across 11 dimensions plus PII detection

How They Work:

Assign to Proxies: Attach one or more guardrail providers to any proxy
Per-Team Scoping: Apply different guardrails to different teams on the same proxy (e.g., stricter screening for Finance)
Direction Control: Screen requests only, responses only, or both
Concurrent Evaluation: All assigned providers run in parallel - total latency equals the slowest provider, not the sum
Fail-Safe Options: Choose "fail open" (allow on error) or "fail closed" (block on error)
Monitor or Block: Start in monitor-only mode to observe, then switch to blocking when ready

Guardrail Evaluations:

Test your guardrail configurations against 71+ built-in security test cases across 12 attack categories
Categories include: prompt injection, data exfiltration, bypass techniques, harmful content, MCP tool poisoning, and more
Get OWASP LLM Top 10 and NIST AI RMF compliance scores
Test providers in isolation or through your full proxy stack

Getting Started with Guardrails:

Go to Security > Guardrail Providers in the web interface
Click Add Provider and select a provider type
Enter your API credentials and configure settings
Run a Health Check to verify connectivity
Use the Playground to test with sample content
Assign the provider to one or more proxies
Optionally scope to specific teams for targeted screening

6. OAuth Authentication: Two-Layer Security

The platform supports two distinct OAuth flows for comprehensive security:

Gateway OAuth (2LO) - User Authentication:

User → Browser → Gateway Web Interface → OAuth Provider

Users authenticate to the Gateway using OAuth providers
Supported: GitHub, Google, Okta, Azure AD, Auth0, GitLab, Keycloak, custom
JWT tokens issued for API access
User groups and teams for access control
API keys for programmatic access

MCP OAuth Delegation (3LO) - Server Authentication:

Client → Gateway Proxy → MCP Server → OAuth Provider

Gateway delegates OAuth authentication to MCP servers
Supports OAuth-enabled MCP servers (e.g., requiring user consent)
Complete token lifecycle management
User attribution for all MCP tool invocations
Full audit trails for compliance

Why Two Flows?

2LO: Controls who can use the Gateway (user access control)
3LO: Controls who can access MCP resources (delegated authorization)
Both work together for end-to-end security

7. Database: Your Data Store

SQLite database (with GORM ORM) stores everything:

What's Stored:

Proxy configurations (name, type, target, port, policies)
Security alerts (severity, status, evidence, timestamps)
Request logs (method, path, status, duration, risk level)
Token usage (input/output tokens, cost, model, user)
Users & teams (OAuth profiles, groups, permissions)
API keys (keys, usage, rate limits, team associations)
Audit logs (35+ event types for compliance)
MCP tools (definitions, enabled status, usage stats)
Guardrail providers (configurations, assignments, health status)
Guardrail check logs (verdict, categories, latency, confidence)
Guardrail evaluations (test runs, results, compliance scores)

Database Location:

Default: ./data/security_gateway.db
Configurable via config.yaml
Automatic backups via web interface

8. Helper Scripts: Simplified Management

The release includes scripts to make your life easier:

install.sh (Linux/macOS):

Interactive installation wizard
Generates secure JWT_SECRET and ENCRYPTION_KEY automatically
Creates .env file with recommended settings
Validates binary and configuration
One-command setup: ./install.sh

verify.sh (Linux/macOS):

Checks binary is executable and correct architecture
Validates environment configuration
Tests database connectivity
Verifies policy files exist
Run before deployment: ./verify.sh

start.sh / start.ps1:

Starts API server in background
Optionally starts frontend Docker container
Shows admin password on first run
Provides access URLs
One-command startup: ./start.sh

Common Tasks

Getting Started: Your First Security Proxy

Step 1: Install and Start

Download the release package for your operating system
Run ./install.sh (Linux/macOS) or follow Windows instructions
Start with ./start.sh - everything launches automatically
Open your browser to http://localhost:80

Step 2: Log In

Use the admin account created during installation
Password is shown when you first run the application
You can change this password in Settings later

Step 3: Create Your First Proxy

Go to "Proxy Management" in the web interface
Click "Create New Proxy"
Choose "MCP" if protecting Claude Desktop/Cursor
Choose "LLM" if protecting OpenAI/Anthropic APIs
Enter your target service URL (where your AI service runs)
Select "Standard Security" for your first proxy
Click "Create" then "Start"

Step 4: Connect Your Applications

Update your applications to use the proxy address
For example: Instead of connecting to localhost:3001, connect to localhost:3000
Your applications now go through the security proxy

Step 5: Monitor and Enjoy

Watch the dashboard for real-time activity
Check alerts for any security events
Review logs to understand usage patterns

Workflow 2: Managing User Access

1. Enable OAuth Authentication
   └─→ Settings → OAuth Providers
   └─→ Add Provider: GitHub, Google, or custom
   └─→ Configure: Client ID, Secret, Scopes
   
2. Create User Groups
   └─→ Access Control → User Groups → Create
   └─→ Name: "Engineering Team"
   └─→ Assign Rules: Domain (@company.com), Provider (GitHub)
   
3. Assign Proxy Access
   └─→ User Groups → "Engineering Team" → Proxy Access
   └─→ Select proxies this group can access
   └─→ Set rate limits (optional)
   
4. Generate API Keys
   └─→ Access Control → API Keys → Generate
   └─→ Assign to User Group
   └─→ Set Budget Limits (e.g., $100/month)
   
5. Users Login
   └─→ Login via OAuth → Auto-assigned to groups
   └─→ Requests attributed to user identity
   └─→ Usage tracked per user/team

Workflow 3: Monitoring & Responding to Alerts

1. Real-Time Monitoring
   └─→ Dashboard: View active alerts
   └─→ WebSocket: Instant notifications
   
2. Alert Investigation
   └─→ Security → Alerts
   └─→ Filter: Severity, Status, Date Range
   └─→ Click alert: View full evidence
   
3. Alert Triage
   └─→ Status: New → Under Review
   └─→ Assign: Team member for investigation
   
4. Response Actions
   └─→ Block Pattern: Add to custom policy
   └─→ Whitelist: Exclude false positives
   └─→ Notify: Send to SIEM/SOAR/Slack
   
5. Resolution
   └─→ Status: Resolved or False Positive
   └─→ Export: Download alert data
   └─→ Audit: Review compliance logs

Workflow 4: Setting Up Guardrail Providers

1. Configure a Guardrail Provider
   └─→ Security → Guardrail Providers → Add Provider
   └─→ Select Type: Groq, EnkryptAI, DynamoAI, GuardrailsAI, or Fiddler
   └─→ Enter API credentials and settings
   └─→ Set Direction: Request, Response, or Both
   └─→ Set Action: Monitor (observe) or Block (enforce)

2. Verify Provider Health
   └─→ Click "Health Check" to test connectivity
   └─→ Use "Playground" to test with sample content
   └─→ Review results before assigning to proxies

3. Assign to Proxies
   └─→ Guardrail Providers → Assignments → Create
   └─→ Select Provider and Target Proxy
   └─→ Proxy-wide: Leave team blank (applies to all users)
   └─→ Team-specific: Select a team (applies only to that team)
   └─→ Set Priority (higher = evaluated first)

4. Run Guardrail Evaluations
   └─→ Security → Guardrail Evaluations → Create
   └─→ Select provider or endpoint to test
   └─→ Run against 71+ built-in security test cases
   └─→ Review OWASP LLM Top 10 compliance scores

5. Monitor & Tune
   └─→ Dashboard: View guardrail check stats
   └─→ Check Logs: Review verdicts and violation categories
   └─→ Adjust: Switch from Monitor to Block when ready
   └─→ Review: Mark false positives and refine settings

Workflow 5: Budget Management & Cost Control

1. Set Team Budgets
   └─→ Access Control → User Groups → Edit
   └─→ Monthly Budget: $500
   └─→ Warning Threshold: 80% ($400)
   └─→ Block at Limit: Yes/No
   
2. Monitor Spending
   └─→ Dashboard → AI Usage Metrics
   └─→ View: Current spend, utilization, remaining
   └─→ Filter: By team, by proxy, by date range
   
3. Handle Budget Warnings
   └─→ Automatic notification at 80% threshold
   └─→ Review: Token usage, cost trends
   └─→ Action: Increase budget or optimize usage
   
4. Budget Exceeded
   └─→ Automatic blocking (if enabled): HTTP 402
   └─→ Alert: Notify team and admins
   └─→ Options: Reset budget or wait for monthly reset
   
5. Monthly Reset
   └─→ Automatic: 1st of each month (00:00 UTC)
   └─→ Manual: Settings → Reset Budget
   └─→ Tracking: Historical data preserved

Deployment Models

Model 1: All-in-One (Quickstart)

Best for: Testing, development, single-user setups

┌─────────────────────────────────────┐
│       Single Machine/Server         │
│  ┌───────────────────────────────┐  │
│  │  Frontend (Docker:80)         │  │
│  └───────────────────────────────┘  │
│  ┌───────────────────────────────┐  │
│  │  API Server (Binary:8080)     │  │
│  └───────────────────────────────┘  │
│  ┌───────────────────────────────┐  │
│  │  Proxies (3000+, 4000+)       │  │
│  └───────────────────────────────┘  │
│  ┌───────────────────────────────┐  │
│  │  SQLite Database              │  │
│  └───────────────────────────────┘  │
└─────────────────────────────────────┘

Commands:

bash

./start.sh  # Starts everything

Model 2: Distributed (Production)

Best for: Teams, high-traffic, production deployments

┌─────────────────────┐     ┌─────────────────────┐
│  Web Server         │     │  Application Server │
│  Frontend (nginx)   │────▶│  API Server (8080)  │
│  Port 80/443        │     │  + Proxies          │
└─────────────────────┘     │  + Database         │
                             └─────────────────────┘
                                      │
                             ┌────────▼────────────┐
                             │  Monitoring Stack   │
                             │  Prometheus/Grafana │
                             │  Langfuse/Jaeger    │
                             └─────────────────────┘

Setup:

Deploy frontend to nginx/apache (load balanced)
Run API server on application servers (systemd/launchd)
Configure reverse proxy: Web → API
Connect to external monitoring/logging

Model 3: Hybrid (Flexible)

Best for: Mixed environments, gradual migration

┌─────────────────────┐     ┌─────────────────────┐
│  Developer Laptop   │     │  Cloud VM           │
│  Frontend (Docker)  │────▶│  API Server         │
│  Local Development  │     │  Shared Resources   │
└─────────────────────┘     └─────────────────────┘
        │                            │
        └────────────────┬───────────┘
                         │
                ┌────────▼────────┐
                │  AI Services    │
                │  (MCP/LLM/A2A)  │
                └─────────────────┘

Use Cases:

Developers test locally, share API server
Centralized policy management
Distributed proxy instances

Key Features Explained

🔐 Security Layers

Layer 1: Authentication (Who are you?)

OAuth 2.1 for users (GitHub, Google, etc.)
JWT tokens for API access
API keys for programmatic access
Role-based access control (RBAC)

Layer 2: Authorization (What can you do?)

User groups and teams
Per-proxy access control
Rate limiting per user/group
Budget limits per team

Layer 3: Policy Enforcement (What's allowed?)

250+ detection rules
Real-time threat blocking
Risk scoring
Custom policies

Layer 4: Guardrail Providers (Is the content safe?)

Third-party AI safety API screening
Per-proxy and per-team guardrail assignments
Concurrent multi-provider evaluation
Configurable block or monitor modes
5 supported providers (Groq, EnkryptAI, DynamoAI, GuardrailsAI, Fiddler)

Layer 5: Monitoring (What happened?)

Request logs with user attribution
Security alerts
Audit logs (35+ event types)
Token usage tracking

💰 Cost Control

Budget Limits:

Set monthly spending caps per team/API key
Configure warning thresholds (e.g., 80%, 90%)
Choose to block or warn when exceeded
Automatic monthly reset

Token Tracking:

Input/output token counts
Cost calculation per model
Usage analytics per user/team
Budget utilization dashboards

Enforcement:

Real-time cost calculation
Automatic request blocking (HTTP 402)
Budget alerts to admins
Historical spending reports

🛡️ Architecture Data Protection

Redaction:

Automatic PII detection (emails, phone numbers, SSNs, etc.)
Sensitive data masking before LLM processing
Configurable redaction patterns
Compliance with GDPR, HIPAA, etc.

Unmasking:

Automatic restoration of original values in responses
Seamless user experience (users don't see masked data)
Preserves context and meaning
Redaction count tracking

📊 Observability

Built-in Metrics:

Prometheus endpoint: /api/v1/metrics/prometheus
Request percentiles (p50, p95, p99)
Database performance
System resource usage

External Integrations:

Langfuse: LLM traces and analytics (configured in Settings)
OpenTelemetry: Distributed tracing
Jaeger: Trace visualization
Grafana: Pre-built dashboards

Alerts & Notifications:

SIEM integration (alert forwarding)
SOAR integration (incident automation)
Slack webhooks
Email notifications (SMTP)

Architecture Configuration Files

.env (Environment Variables)

Critical Settings:

bash

JWT_SECRET=<generated-by-install.sh>      # JWT token signing
ENCRYPTION_KEY=<generated-by-install.sh>  # OAuth token encryption
PORT=8080                                  # API server port
DATABASE_PATH=./data/security_gateway.db  # Database location

Optional Settings:

bash

ENABLE_OAUTH=true                          # Enable OAuth 2.1
ENABLE_LANGFUSE=false                      # Langfuse integration
PROMETHEUS_ENABLED=true                    # Prometheus metrics
OTEL_EXPORTER_OTLP_ENDPOINT=...           # OpenTelemetry endpoint

configs/config.yaml (System Configuration)

Proxy Defaults:

yaml

proxy:
  default_port: 3000
  max_instances: 100
  auto_start: false

Security Settings:

yaml

security:
  default_policy: mcp-standard-security
  block_threshold: 30
  audit_logging: true

Integration Settings:

yaml

integrations:
  slack_webhook: https://hooks.slack.com/...
  siem_endpoint: https://siem.company.com/...

policies/*.json (Security Policies)

Policy Structure:

json

{
  "name": "Custom Policy",
  "version": "1.0",
  "rules": [
    {
      "id": "sql-injection",
      "pattern": "(?i)(union|select|insert|drop|delete).*from",
      "severity": "critical",
      "score": 50,
      "action": "block"
    }
  ]
}

Getting Help

Documentation

INSTALL.md: Step-by-step installation guide
README.md: Project overview and features
CHANGELOG.md: What's new in each version
User Guides: Complete documentation in the docs/ folder

Support Options

GitHub Issues: Report bugs or problems
GitHub Discussions: Ask questions and get community help
Documentation: Comprehensive guides for all features

Troubleshooting

Check the logs: Look in ./data/logs/ for error messages
Verify setup: Run ./verify.sh to check your installation
Test connection: Visit http://localhost:8080/api/v1/health to confirm it's running
Review alerts: Check the Security → Alerts section in the web interface

Next Steps

Ready to get started? Here's your path:

Install the Software: Follow the Installation Guide
Quick Start: Use the Admin Quick Start Guide
Create Your First Proxy: Start protecting your AI services
Set Up Team Access: Add users and configure permissions
Customize Security: Adjust policies for your specific needs
Add Guardrails: Configure third-party AI safety providers with the Guardrail Evaluations Guide

Welcome to safer AI! 🚀

Architecture Overview ​

What You Get: The Complete Package ​

📦 Release Package Contents ​

System Architecture: How It All Works Together ​

How It Works - Simple View ​

Understanding the Components ​

1. Web Interface: Your Control Center ​

2. Main Application: The Security Engine ​

3. Security Proxies: Your AI Bodyguards ​

4. Security Policies: Your Protection Rules ​

5. Guardrail Providers: Third-Party AI Safety ​

6. OAuth Authentication: Two-Layer Security ​

7. Database: Your Data Store ​

8. Helper Scripts: Simplified Management ​

Common Tasks ​

Getting Started: Your First Security Proxy ​

Workflow 2: Managing User Access ​

Workflow 3: Monitoring & Responding to Alerts ​

Workflow 4: Setting Up Guardrail Providers ​

Workflow 5: Budget Management & Cost Control ​

Deployment Models ​

Model 1: All-in-One (Quickstart) ​

Model 2: Distributed (Production) ​

Model 3: Hybrid (Flexible) ​

Key Features Explained ​

🔐 Security Layers ​

💰 Cost Control ​

🛡️ Architecture Data Protection ​

📊 Observability ​

Architecture Configuration Files ​

.env (Environment Variables) ​

configs/config.yaml (System Configuration) ​

policies/*.json (Security Policies) ​

Getting Help ​

Documentation ​

Support Options ​

Troubleshooting ​

Next Steps ​

Architecture Overview

What You Get: The Complete Package

📦 Release Package Contents

System Architecture: How It All Works Together

How It Works - Simple View

Understanding the Components

1. Web Interface: Your Control Center

2. Main Application: The Security Engine

3. Security Proxies: Your AI Bodyguards

4. Security Policies: Your Protection Rules

5. Guardrail Providers: Third-Party AI Safety

6. OAuth Authentication: Two-Layer Security

7. Database: Your Data Store

8. Helper Scripts: Simplified Management

Common Tasks

Getting Started: Your First Security Proxy

Workflow 2: Managing User Access

Workflow 3: Monitoring & Responding to Alerts

Workflow 4: Setting Up Guardrail Providers

Workflow 5: Budget Management & Cost Control

Deployment Models

Model 1: All-in-One (Quickstart)

Model 2: Distributed (Production)

Model 3: Hybrid (Flexible)

Key Features Explained

🔐 Security Layers

💰 Cost Control

🛡️ Architecture Data Protection

📊 Observability

Architecture Configuration Files

.env (Environment Variables)

configs/config.yaml (System Configuration)

policies/*.json (Security Policies)

Getting Help

Documentation

Support Options

Troubleshooting

Next Steps