Technical Documentation

Aurora WAAP Docs

Everything you need to know about Aurora's ML-powered traffic analysis, AI rule generation, and the Link11 WAAP integration.

Introduction

What is Aurora?

Aurora is the intelligent eye of the Link11 WAAP platform. It analyzes traffic on-demand, detects anomalies via ML clustering, and proposes precise security rules.

ML Clustering

DBSCAN/K-Means groups requests by behavioral patterns

AI Rule Gen

LLM translates cluster patterns into valid WAAP rules

Shadow Testing

Simulates rules against historical traffic before deployment

System Design

Architecture

Aurora is a monorepo with three main services communicating via REST APIs.

Frontend (app/)

Next.js 16 + Tailwind v4 + shadcn/ui

Responsive dashboard with real-time job tracking, cluster visualization via Recharts, and a human-in-the-loop approval workflow.

Backend (api/)

Express 5 + TypeScript + Drizzle ORM

REST API managing jobs, rules, settings, and the full analysis pipeline orchestration. PostgreSQL 16 with RLS for persistence.

ML Sidecar (ml/)

Python FastAPI + Scikit-learn

Feature extraction (18-dim vectors) and behavioral clustering via DBSCAN. Communicates with the API via HTTP.

Database

PostgreSQL 16 + Drizzle ORM

Stores analysis jobs, raw requests, cluster results, rule proposals, shadow test results, and system settings. Uses Row-Level Security (RLS) for tenant data isolation.

Shared (shared/)

TypeScript + Zod Schemas

Shared type definitions, Zod validation schemas for rules, conditions, and API contracts used by both frontend and backend.

LLM Integration

OpenRouter API (Claude)

The AI engine uses Claude via OpenRouter to analyze clusters and generate structured WAAP rule proposals using tool-use.

Core Flow

Analysis Pipeline

Aurora runs a 5-stage async pipeline for each analysis job. Each stage transitions the job status automatically. After completion, rules enter a manual review phase.

Ingest

ingesting

Fetches WAAP access logs from the Link11 API for the configured site and time range. Raw requests are stored in PostgreSQL.

Feature Extraction

clustering

Extracts an 18-dimensional feature vector per request: URL patterns, HTTP methods, headers, payload characteristics, IP metadata, and timing features.

ML Clustering

clustering

The Python ML sidecar runs DBSCAN to group requests by behavioral similarity. Each cluster gets a profile with top discriminative features.

Rule Generation

generating_rules

Each cluster is sent to the LLM (Claude via OpenRouter). The AI analyzes the cluster profile and generates a structured WAAP rule or skips benign clusters.

Shadow Testing

shadow_testing

Generated rules are evaluated against the ingested requests. Calculates match count, block rate, and false-positive indicators.

Review & Deploy

completed

Security engineers review AI proposals in the dashboard, approve or reject rules, and optionally deploy to Link11 production with one click.

Intelligence

AI Rule Engine

How Aurora uses LLMs to translate traffic patterns into precise WAAP rules with full explainability.

System Prompt

The LLM receives a system prompt defining its role as a WAAP security expert for Link11. It analyzes cluster profiles (size, discriminative features, sample requests) and generates rules only for clusters that appear malicious or suspicious.

Structured Output via Tool Use

Instead of freeform text, the LLM is constrained to a tool schema that enforces the exact rule structure. This guarantees valid output every time.

Fields

path, method, ip.address, ip.country, header:<name>, query:<name>

Operators

eq, neq, contains, regex, gt, lt, in

Actions

block, challenge, log, allow

Severity

low, medium, high, critical

Explainability (XAI)

Every rule proposal includes an xai_summary field: a human-readable explanation of why this rule was suggested, referencing specific cluster features and observed patterns. Combined with a confidence score (0-1), this gives security engineers full context for informed approve/reject decisions.

Validation Chain

LLM OutputJSON ParseZod ValidationShadow Test

Reference

Rule Condition Syntax

Aurora rules use a recursive AND/OR condition structure. Here are examples of the supported formats.

Simple condition — Block a specific path

{
  "field": "path",
  "op": "contains",
  "value": "/wp-admin"
}

AND group — Block SQLi attempts on login

{
  "operator": "AND",
  "conditions": [
    { "field": "path", "op": "eq", "value": "/login" },
    { "field": "body", "op": "regex", "value": "('|--|;|UNION|SELECT)" }
  ]
}

Nested groups — Block suspicious bot traffic

{
  "operator": "AND",
  "conditions": [
    {
      "operator": "OR",
      "conditions": [
        { "field": "header:user-agent", "op": "contains", "value": "python-requests" },
        { "field": "header:user-agent", "op": "contains", "value": "curl" }
      ]
    },
    { "field": "path", "op": "regex", "value": "\\.(env|git|config)" }
  ]
}

Operator	Description	Example
eq	Exact match	path eq "/login"
neq	Not equal	method neq "GET"
contains	Substring match	header:user-agent contains "bot"
regex	Regex pattern	path regex "\.(php\|asp)"
in	Value in list	ip.country in ["CN","RU"]
gt / lt	Greater/less than	response_time_ms gt 5000

Endpoints

API Reference

The Aurora backend exposes a REST API for managing analysis jobs, rules, and settings.

POST/v1/auth/loginRequest magic link for email authentication

POST/v1/auth/verifyVerify magic link token and create session

GET/v1/auth/meGet current user and impersonation state

POST/v1/analysisCreate a new analysis job (siteId, from, to)

GET/v1/analysisList all analysis jobs for current user

GET/v1/analysis/:idGet job details including clusters

GET/v1/rulesList all rule proposals (optional jobId filter)

GET/v1/rules/:idGet rule detail with shadow test results

PATCH/v1/rules/:idApprove or reject a rule proposal

POST/v1/rules/:id/deployDeploy approved rule to Link11 production

GET/v1/sitesList available Link11 sites

GET/v1/sites/traffic-previewGet request counts for 24h, 7d, 30d

GET/v1/settingsGet current configuration

PUT/v1/settingsUpdate settings and credentials

GET/healthHealth check (API, DB, ML sidecar)

Authentication

Aurora uses magic link email authentication. Users receive a one-time login link via email (sent through Resend). Sessions are stored as HTTP-only cookies (aurora_session) valid for 30 days. GitHub OAuth is also supported when configured.

Getting Started

Setup & Configuration

Get Aurora running locally or via Docker in minutes.

Quick Start with Docker

Terminal

git clone https://github.com/link11/aurora-waap.git
cd aurora-waap
cp .env.example .env        # configure your keys
docker compose up -d         # starts API, App, ML sidecar, PostgreSQL

Local Development

Terminal

pnpm install                 # install all workspace deps
pnpm --filter api dev        # start backend on :4000
pnpm --filter app dev        # start frontend on :3000
cd ml && uvicorn main:app    # start ML sidecar on :8000

Environment Variables

Variable	Description	Required
DATABASE_URL	PostgreSQL connection string (e.g. postgresql://aurora:<password>@postgres:5432/aurora)
ENCRYPTION_KEY	AES-256-GCM key for API key encryption (32-byte hex)
RESEND_API_KEY	API key for Resend email service (magic link login)	Optional
FRONTEND_URL	Frontend URL for magic link emails (default: https://aurora.app.link11.com)	Optional
ML_SIDECAR_URL	URL of the Python ML sidecar (default: http://localhost:8000)	Optional
GH_CLIENT_ID	GitHub OAuth App client ID (enables GitHub login)	Optional
GH_CLIENT_SECRET	GitHub OAuth App client secret	Optional
POSTGRES_PASSWORD	PostgreSQL password (auto-generated on first deploy if missing)	Optional

Credential Storage

Link11 credentials and the OpenRouter API key can be set per-user via the Dashboard Settings page. They are stored encrypted (AES-256-GCM) in PostgreSQL. Per-user credentials take priority over environment variables.

Technologies

Tech Stack

Aurora is built with a modern, type-safe stack optimized for developer experience and reliability.

Layer	Technology	Purpose
Frontend	Next.js 16 + Tailwind v4 + shadcn/ui	Dashboard, visualizations, HITL workflow
Icons	Lucide React	Consistent icon system
Charts	Recharts 2.x	Traffic & cluster visualizations
Backend	Express 5 (TypeScript)	REST API, pipeline orchestration
Validation	Zod 3.x	Schema validation at API boundaries
Database	PostgreSQL 16 + Drizzle ORM	Type-safe database access with RLS
Auth	Magic Link (Resend) + GitHub OAuth	Passwordless authentication
ML Engine	Python FastAPI + Scikit-learn	Feature extraction, DBSCAN clustering
LLM	Claude via OpenRouter	Rule generation with tool-use
Pkg Manager	pnpm 10.x (workspaces)	Monorepo dependency management
Infra	Docker + Caddy on Hetzner	Containerization & reverse proxy