Gateway Security (WAF)

AgentWatch includes a built-in Web Application Firewall (WAF) that inspects every inbound request — URL, headers, and body — for OWASP Top 10 attack patterns before the request reaches the LLM. The WAF is disabled by default and must be explicitly enabled.

How the WAF Inspects Requests

Inbound Request
      │
      ▼
┌─────────────────────────────────────────────────────┐
│  Whitelist check — is the path in the whitelist?     │
│     YES → skip WAF, pass through                     │
│     NO  → continue ↓                                 │
└─────────────────────────────────────────────────────┘
      │
      ▼
┌─────────────────────────────────────────────────────┐
│  Run enabled built-in rules against:                 │
│    • URL (decoded)                                   │
│    • All request headers                             │
│    • Request body (JSON-stringified)                 │
│                                                      │
│  + Run custom rules (if any) against:                │
│    • url / headers / body / all (per-rule target)    │
└─────────────────────────────────────────────────────┘
      │
      ├── No violations → Request proceeds
      │
      └── Violations found:
            • Detect mode → Log violation, request proceeds
            • Block mode  → 403 Forbidden, request stopped

Up to 10,000 violations are retained in a rolling buffer. Stats (scanned, detected, blocked, by-category) are tracked in real time.

---

Built-in Detection Rules

SQL Injection (7 rules — severity: critical)

Rule ID	Description	Detects
sqli-001	UNION-based SELECT	UNION ALL SELECT ...
sqli-002	Boolean OR tautology	OR 1=1
sqli-003	Boolean AND tautology	AND 1=1
sqli-004	Stacked queries	; DROP TABLE users
sqli-005	Comment injection	'; --
sqli-006	Inline comment	/* comment */
sqli-007	String tautology	' OR 'x'='x

Cross-Site Scripting — XSS (5 rules — severity: high)

Rule ID	Description	Detects
xss-001	Script tag injection	<script>alert(1)</script>
xss-002	Event handler injection	onerror=, onclick=
xss-003	JavaScript URI	javascript:alert(1)
xss-004	Dangerous HTML elements	<svg, <iframe, <embed
xss-005	Base64 data URI	data:text/html;base64,...

Command Injection (5 rules — severity: critical)

Rule ID	Description	Detects
cmd-001	Shell command via semicolon	; cat /etc/passwd
cmd-002	Pipe to command	| grep root
cmd-003	Backtick execution	`id`
cmd-004	Dollar substitution	$(whoami)
cmd-005	Sensitive file access	/etc/passwd, /etc/shadow

Path Traversal (4 rules — severity: high)

Rule ID	Description	Detects
path-001	Directory traversal	../../etc/passwd
path-002	Encoded traversal	%2e%2e%2f
path-003	Null byte injection	%00
path-004	Double-encoded traversal	%252e%252e

---

Operating Modes

Mode	Behavior
Detect Only	Log the violation and forward the request (safe monitoring mode)
Block	Reject the request immediately with 403 Forbidden

Recommended approach: Start in Detect Only to understand your traffic and tune whitelist paths before switching to Block mode.

---

Step-by-Step: Enabling WAF Protection

Step 1: Navigate to WAF Protection

1. Log in to the AgentWatch Admin Panel
2. In the left sidebar, go to Gateway → WAF Protection

Step 2: Review the Dashboard

Before enabling, check the KPI cards:

• Requests Scanned — total requests inspected since last reset
• Threats Detected — violations found (detect or block mode)
• Requests Blocked — requests actually rejected (only in block mode)
• Detection Rate — percentage of scanned requests with violations

Step 3: Set WAF Mode

Use the WAF Mode dropdown:

• Choose Detect Only (log violations) first — this scans all traffic and records violations without blocking anything
• Switch to Block only after reviewing violations and confirming there are no false positives

Step 4: Enable the WAF

Toggle WAF Enabled to on. The WAF begins inspecting all inbound requests immediately.

Step 5: Configure Detection Rules

Each of the four built-in categories can be toggled independently:

Toggle	Default	When to disable
SQL Injection	On	Rarely — only if your use case requires SQL patterns in prompts
XSS	On	Rarely — only for trusted internal APIs that send HTML content
Command Injection	On	Rarely — only for DevOps tooling APIs that legitimately send shell commands
Path Traversal	On	Rarely — only if your prompts legitimately include file path strings

Step 6: Add Whitelist Paths (if needed)

If certain paths generate false positives (e.g., /health, /admin/*, internal endpoints), add them to the whitelist. Whitelisted paths skip all WAF inspection.

Configure via the API:

PUT /api/admin/waf/config
{
  "enabled": true,
  "mode": "detect",
  "whitelistPaths": ["/health", "/agent/*", "/admin/gateway/docs"]
}

Glob patterns are supported: * matches any path segment, ** matches across segments.

Step 7: Add Custom Rules (optional)

For organization-specific patterns (internal codenames, proprietary data formats, competitor keywords), add custom regex rules:

{
  "customRules": [
    {
      "id": "custom-001",
      "name": "Block competitor brand mention",
      "pattern": "CompetitorName",
      "target": "body",
      "severity": "medium",
      "enabled": true
    }
  ]
}

Custom rule targets:

Target	What It Scans
url	The request path only
headers	All request headers (key: value pairs)
body	The request body (JSON-stringified)
all	URL + headers + body

Custom rule severities: low, medium, high, critical

Step 8: Switch to Block Mode

Once you have reviewed violations in Detect mode and confirmed the rules are accurate:

1. Set WAF Mode to Block
2. Save — subsequent requests that match any rule will receive a 403 Forbidden response immediately

---

Block Response Example

When a request is blocked in Block mode:

HTTP 403 Forbidden
{
  "error": {
    "message": "Request blocked by WAF: SQL injection pattern detected",
    "type": "waf_violation",
    "code": "WAF_BLOCKED",
    "details": {
      "ruleId": "sqli-001",
      "ruleName": "SQL Injection: UNION-based SELECT",
      "category": "sqli",
      "severity": "critical",
      "matchedPattern": "union\\s+(all\\s+)?select",
      "matchedValue": "UNION SELECT"
    }
  }
}

---

Violation Record Fields

Each recorded violation includes:

Field	Description
timestamp	When the violation occurred
clientIp	IP address of the caller
method	HTTP method (POST, GET, etc.)
path	Request path
ruleId	The specific rule that fired (e.g., sqli-001)
ruleName	Human-readable rule name
category	sqli, xss, cmd_injection, path_traversal, or custom
severity	low, medium, high, or critical
matchedPattern	The regex pattern that matched
matchedValue	The actual matched string (truncated to 200 chars)
action	detected (detect mode) or blocked (block mode)

---

API Reference

Method	Endpoint	Description
GET	/api/admin/waf/config	Get current WAF configuration
PUT	/api/admin/waf/config	Update WAF configuration (mode, rules, whitelist)
GET	/api/admin/waf/violations	List recent violations
GET	/api/admin/waf/stats	Get detection/block statistics