Core Concepts

• 1: Traffic Pipeline & Two-Phase Execution
• 2: Paranoia Level Mechanism
• 3: Isolated vs. Embedded Payloads
• 4: Unified Management Surfaces & Authorization

1 - Traffic Pipeline & Two-Phase Execution

CheeseWAF separates traffic processing into two distinct flows: the Synchronous Detection Pipeline and the Asynchronous Out-of-Band Review Loop. Within the synchronous path, CheeseWAF employs a high-performance Two-Phase Pipeline architecture to achieve microsecond-level short-circuit drops while preserving high throughput for deep AST parsing:

flowchart TB
  Client[Client Request] --> Ingress[Ingress HTTP / HTTPS / HTTP3]
  subgraph Phase1 [Phase 1: Pre-Filters (Sequential / Short-Circuit / Priority < 290)]
    IP{IP / Geo / Fingerprint} -->|Pass| Bot{Bot Challenge / RateLimit}
    Bot -->|Pass| Rules{Custom Rules Priority 250}
  end
  Ingress --> IP
  IP -->|Blacklisted| Block[Render Block Page]
  Bot -->|Trigger Challenge| Challenge[Solve Challenge / Waiting Room]
  Challenge -->|Verified| Rules
  Rules -->|Match Block| Block

  subgraph Phase2 [Phase 2: Semantic Group (Parallel Worker Pool / Deterministic Merge / Priority >= 290)]
    Sem[AST Semantic Analyzers: SQL / XSS / RCE / LFI / NoSQL / SSTI etc.]
  end
  Rules -->|Clean| Sem

  Sem --> Shape{Payload Context}
  Shape -->|Isolated Attack Level 2~5| Block
  Shape -->|Embedded Attack Level 5| Block
  Shape -->|Embedded Attack Level 2~4| Pass[Pass & Enqueue Asynchronously]
  Shape -->|Clean| Origin[Forward to Backend Upstream]
  Pass --> Origin
  Pass -.-> Queue[ALAP Review Queue]
  Sem -.->|Level 5 Blocked Sample| Queue
  Queue --> LLM[LLM Reasoning & Attribution]
  LLM --> Review{Decision}
  Review -->|High / Critical| Rule[Generate Protective Rules]
  Review -->|Low / False Positive| Dismiss[Dismiss / Allowlist]
  Rule -.-> IP

Two-Phase Pipeline Architecture

To ensure deterministic latency guarantees under high concurrent load, the detection pipeline partitions all registered detectors by Priority into two separate execution phases:

1. Phase 1: Pre-Filters (Priority < 290)

• Components: IP Access Control, GeoIP, Soft Client Fingerprinting, Bot Challenges, Rate Limiting, and the Custom Regex Rule Engine (Priority 250).
• Execution Model: Strictly sequential single-threaded execution.
• Fast Short-Circuiting: If any pre-filter returns ActionBlock, the request is immediately dropped and the pipeline terminates. The request never reaches the AST semantic parsing stage, allowing reconnaissance probes and known signatures to be discarded within microseconds.

2. Phase 2: Semantic Group (Priority >= 290)

• Components: Deep syntax analyzers for SQL injection, Cross-Site Scripting (XSS), Remote Code Execution (RCE), Local File Inclusion (LFI), NoSQL injection, Server-Side Template Injection (SSTI), SSRF, and XXE.
• Execution Model:
  • Shared Worker Pool: Dispatched across a shared worker pool (bounded at 8 workers) to maximize multi-core CPU efficiency without unbounded goroutine proliferation.
  • Context Forking: Each detector executes with a forked RequestContext, guaranteeing data race immunity for Metadata and Results writes.
  • Deterministic Merge: Once parallel evaluations conclude, results are merged in strict priority order, ensuring 100% deterministic decision-making and logging.

Pipeline Timeout & Budget Protection

• 100ms Hard Timeout: A global 100ms pipeline deadline guarantees that adversarial payloads cannot cause request processing hangs.
• Analysis Budget Depletion Policy (budget_exhausted_policy): If deep parsing cannot finish within the deadline, the fallback policy takes effect:
  • auto: Follows the global web_attack policy level.
  • open: Fails open to preserve application availability while recording metrics.
  • observe: Logs observation details without a hard drop.
  • closed: Security-first challenge or strict block.
• Overload Guarding: Built-in guard monitors detect backpressure and return ErrDetectionOverload, protecting the primary service from cascading degradation.

Asynchronous Review Loop (ALAP)

The asynchronous path runs completely decoupled from real-time reverse proxying:

• Sample Dispatch: Embedded samples passed under Paranoia Levels 2–4 and blocked samples under Level 5 are delivered to the review queue after response delivery.
• LLM Intent Extraction: Background workers issue inference requests to extract threat semantics and confidence scores.
• Closed-Loop Rule Derivation: Manual review decisions can promote a verified sample to the selected payload, URI, IP, or fingerprint rule. Site-level automated adoption is narrower: it writes a site-scoped custom payload rule only.

2 - Paranoia Level Mechanism

CheeseWAF allows configuring the paranoia level independently for each reverse proxy site via sites[].waf.paranoia_level. Supported values range from 0 to 5, with 3 (Standard Smart Protection) recommended as the production baseline.

The paranoia level mechanism balances high threat detection rates with false-positive suppression. When inspecting decoded parameter values, the AST semantic engine executes tiered responses based on payload morphology (Isolated vs. Embedded).

Paranoia Levels Comparison

Dynamic Auto-Promotion Mechanism

At Paranoia Level 4, when suspicious embedded payloads are detected within live traffic, the system proactively promotes the site to Level 5 (Strict Mode) for a configurable duration defined by promote_seconds (e.g., 300 seconds) to prevent reconnaissance-stage exploitation.

• State Persistence: The promotion deadline timestamp is stored in local management storage and persists across service restarts; access logs can stream asynchronously to external PostgreSQL.
• Automatic Decay: Once the promotion window elapses without subsequent suspicious triggers, the site seamlessly reverts to its baseline Level 4 configuration.

Level 5 Review Constraints

Samples blocked under Paranoia Level 5 are submitted to the ALAP review queue with a blocked status tag:

• Non-Retroactive Release: Because the connection was physically terminated, operators cannot mutate the sample status to “Allowed”.
• Rule Synthesis: Upon review, confirmed threats can be exported into permanent global defense rules (including signature patterns, URL path filters, IP blacklists, or client soft-fingerprints).

3 - Isolated vs. Embedded Payloads

In modern web applications, user submissions vary widely in structure. In community forums, developer blogs, or technical support tickets, legitimate users frequently submit code snippets, SQL queries, or log entries. Applying strict signature matching to such content inevitably causes widespread false positives.

To resolve this challenge, CheeseWAF’s AST semantic engine evaluates the contextual proportion and structural wrapping of decoded parameter values, categorizing detections into Isolated Payloads or Embedded Payloads.

Payload Morphologies

1. Isolated Payloads

An isolated payload indicates that the parameter value consists almost entirely of an attack pattern without legitimate surrounding business text.

• Typical Scenario: Direct inputs into search boxes or login fields such as UNION SELECT 1,2,3 or ' OR 1=1 --.
• Wrapping Evaluation: Even when attackers prepend/append light obfuscation—such as @, trailing semicolons, or ${...} wrappers—the engine still classifies the value as isolated if the payload dominates the syntax tree.
• Enforcement: Under Paranoia Levels 2 through 5, isolated payload detections trigger an immediate block.

2. Embedded Payloads

An embedded payload occurs when suspicious syntax constructs are enclosed within larger natural language text, documentation, or product descriptions.

• Typical Scenario: A user posting in a technical forum discussing database tuning by quoting an example SQL query, or an article referencing a Log4j JNDI string.
• Enforcement: Under standard paranoia levels (2–4), the engine allows the request and asynchronously enqueues the sample to ALAP, preserving user experience while maintaining vigilance. Under strict mode (Level 5), embedded hits are blocked immediately.

Gadget Coverage & Engineering Scope

To ensure complete operational clarity, the following outlines the exact engineering boundaries of the current feature isolation implementation:

• Targeted Gadgets: Dedicated gadget isolation analyzers currently cover PHP/JSP dynamic webshells, Log4j JNDI injection, and short quoted/predicate SQL injection (constrained to fragments under 96 runes/characters).
• Document Shape Guards: Attack vectors such as XSS, Remote Code Execution (RCE), Server-Side Template Injection (SSTI), Server-Side Request Forgery (SSRF), and XML External Entity (XXE) are evaluated by specialized Document Shape Guards, operating independently of the short-gadget analyzer.
• Evidence Fallback: Detections classified as embedded bypass inline blocking below Level 5. Unclassified or ambiguous hits adhere strictly to deterministic blockableHit evidence rules and are never silently downgraded to embedded status.
• Operational Guidance: Isolation mitigates false positives on known gadgets in rich-text workflows. For strictly structured API endpoints, enabling higher paranoia levels or schema validation remains recommended.

4 - Unified Management Surfaces & Authorization

CheeseWAF provides three dedicated management surfaces tailored for visual operations, headless terminal maintenance, and automated CI/CD workflows:

Unified Identity & RBAC Matrix

When setup.three_end_unified: true is configured, CheeseWAF synchronizes identity and authorization across all three surfaces:

• Universal User Credentials: Administrator and operator accounts provisioned in the Web console can be used directly for TUI login and API authentication.
• Consistent RBAC Enforcement: API Tokens created in the console’s System Management section inherit the exact RBAC permission matrix defined in apisec.permissions.
• Granular Roles: Built-in default roles include admin (holding full ["*"] permissions) and readonly (scoped to ["read:*", "read:cluster"]).
• Exact identity fields: Usernames use the canonical 3–32 ASCII-character form documented in the CLI reference. Roles must exactly match configured apisec.permissions keys; leading/trailing/embedded Unicode whitespace, control characters (Cc), format/invisible characters (Cf), and permission expressions such as * or : are rejected. The server never trims or case-normalizes identity fields.

Operational Audit Trail

When apisec.audit.enabled: true is active, all configuration mutations, policy changes, and user management operations initiated via the Web Console, TUI, or REST API are written to the structured audit log specified by apisec.audit.path, ensuring enterprise-grade auditability.

Related Documentation

• Web Console Guide
• CLI & TUI Operations Manual
• REST API Reference & Permission Matrix