AnomalyShield is an internal agentic Web Application Firewall (WAF) designed to analyze normal API traffic baseline characteristics per tenant/API key and automatically isolate anomaly events (e.g. volumetric spam, payload size outliers, missing client headers) in real-time.
The system features a decoupled, multi-tenant architecture:
- Control Plane (Next.js): Developer dashboard for provisioning API keys, tracking rates, and configuring tenant client access.
- Multi-Tenant ML Engine (Python/FastAPI): High-speed engine with per-tenant
IsolationForestmodels dynamically loaded via an LRU cache, async batch traffic logging, background model retraining, and a global baseline cold-start fallback. - Data Plane (Go Middleware): Lightweight middleware that wraps standard Go routers (
net/http) to intercept client requests, extract metadata, query the ML engine, and handle connection hijacking or fail-open fallbacks.
graph TD
Client[Client Browser/API] -->|HTTP Request + X-API-Key| GoWAF[Go Middleware Data Plane]
GoWAF -->|1. Extract Features| MetricParser[Request Metrics: Size, Rate, Headers]
GoWAF -->|2. Evaluate Traffic (25ms timeout)| FastAPI[Python ML Engine]
subgraph Multi-Tenant ML Engine
FastAPI -->|Resolve Tenant| KeyCheck[API Key Authentication & Cache]
KeyCheck -->|Fetch Model| Registry[TenantModelRegistry LRU Cache]
Registry -->|Model Hit| TenantModel[Dedicated Tenant IsolationForest]
Registry -->|Cold Start| BaseModel[Global Baseline IsolationForest]
FastAPI -->|Log Metrics| Buffer[Async TrafficLogBuffer]
Buffer -->|Batch Flush| DB[(Shared Database - TrafficLog)]
Worker[Background Trainer Thread] -->|Read Logs & Retrain| DB
Worker -->|Save Trained Binary| Disk[models/tenant_id.joblib]
end
GoWAF -->|Pass or Block| App[Protected App Handler]
NextJS[Next.js Dashboard Control Plane] -->|Manage Users & Keys| DB
style GoWAF fill:#0a305e,stroke:#38bdf8,stroke-width:2px,color:#fff
style FastAPI fill:#3b2057,stroke:#a855f7,stroke-width:2px,color:#fff
style Registry fill:#1f2937,stroke:#a855f7,stroke-width:2px,color:#fff
style NextJS fill:#0c3e30,stroke:#10b981,stroke-width:2px,color:#fff
style DB fill:#1f2937,stroke:#94a3b8,stroke-width:2px,color:#fff
WAFproject/
├── anomalyshield/ # Go Middleware Module
│ ├── anomalyshield.go # Interceptor and rate limit tracker
│ └── anomalyshield_test.go # Test cases (blocking, timeout, fail-open)
├── anomaly_shield_waf/ # Python Multi-Tenant ML Engine (FastAPI)
│ ├── config.py # Configuration environment variables & thresholds
│ ├── database.py # DB connection, API keys, TrafficLog & TenantModelMeta
│ ├── model.py # TenantModelRegistry (LRU), TrafficLogBuffer & BackgroundTrainer
│ ├── main.py # FastAPI HTTP server & management endpoints
│ └── test_service.py # Multi-tenant test suite (Phases 1-5)
├── frontend/ # Next.js Control Plane (Dashboard)
│ ├── prisma/ # Schema definitions (SQLite + Prisma models)
│ └── src/ # Authentication, components & layout
├── waf_demo/ # Demo Application Wrapper
│ ├── main.go # Go server wrapping WAF middleware
│ └── go.mod # Demo configuration pointing to local middleware
├── provision_test_key.py # DB helper script to seed mock dev credentials
└── verify.sh # Verification test suite runner
-
Phase 1: Metric Logging & Storage: Async batch logging buffers request metrics in memory (
TrafficLogBuffer) and flushes toTrafficLogtable in batches to eliminate per-request DB write overhead. -
Phase 2: Automated Background Trainer: A background thread (
BackgroundTrainer) periodically scans tenants and trains dedicatedIsolationForestmodels for tenants with$\ge 1,000$ traffic records. -
Phase 3: Model Management & LRU Cache:
TenantModelRegistryprovides a thread-safe LRU cache (default max 100 models in RAM) with memory eviction and dynamic disk loading (models/tenant_<user_id>.joblib). - Phase 4: Cold-Start & Fallback: Tenants with insufficient data dynamically fall back to a pre-trained global baseline model.
-
Phase 5: Management Endpoints: FastAPI exposes API routes for tenant status (
GET /tenants/{user_id}/status), manual retraining (POST /tenants/{user_id}/train), cache status (GET /cache), and buffer flushing (POST /logs/flush).
- Go Compiler (v1.18+)
- Python (v3.10+) &
pip - Node.js (v18+) &
npm
# Install Python ML server dependencies
pip3 install fastapi uvicorn scikit-learn joblib anyio
# Install Next.js frontend dependencies
cd frontend
npm install
cd ..cd frontend
npx prisma db push
cd ..python3 provision_test_key.pypython3 -m anomaly_shield_waf.maincd frontend
npm run devcd waf_demo
go run main.goRun the full multi-tenant test suite:
python3 -m anomaly_shield_waf.test_serviceOr run the complete verification script:
./verify.sh