Concepts

• 1: Request pipeline
• 2: Paranoia levels
• 3: Isolated vs embedded
• 4: Three management surfaces

1 - Request pipeline

flowchart TB
  Client[Client] --> Ingress[HTTP / HTTPS / HTTP3]
  Ingress --> IP{IP / geo / fingerprint}
  IP -->|deny list| Block[Block page]
  IP -->|allow| Bot{Bot / rate limit / waiting room}
  Bot -->|challenge| Challenge[CAPTCHA or queue]
  Challenge -->|pass| Sem
  Bot -->|allow| Sem[Semantic engine]
  Sem --> Shape{Isolated or embedded}
  Shape -->|isolated 2-5| Block
  Shape -->|embedded 5| Block
  Shape -->|embedded 2-4| Pass[Allow and enqueue]
  Shape -->|clean| Origin[Upstream]
  Pass --> Origin
  Pass -.-> Queue[ALAP queue]
  Sem -.->|level 5 block| Queue
  Queue --> LLM[Configured model]
  LLM --> Review{Decision}
  Review -->|high / critical| Rule[Lasting rule]
  Review -->|low or false positive| Dismiss[Archive or allow list]
  Rule -.-> IP

Solid arrows stay on the request path. Dashed arrows run after the client already has a response.

Site-level waf.mode can be block or a record-only style depending on paranoia. Level 0 and 1 never block on semantic hits.

See Protection for each filter in this diagram.

2 - Paranoia levels

Set sites[].waf.paranoia_level per site. Legal values are 0–5. The default is 3.

The engine looks at one decoded parameter value at a time. Path and parameter names stay visible.

Temporary rise

At level 4, an embedded hit can raise the site to level 5 for promote_seconds (for example 300 seconds). The deadline is stored in SQLite. A process restart does not clear it.

Level 5 review

A sample blocked at level 5 still enters the review queue with a blocked mark. You cannot flip it to allow. You can save a lasting deny rule (feature, URL, IP, or fingerprint).

3 - Isolated vs embedded

The semantic engine classifies each decoded value as isolated or embedded. Paranoia levels treat the two shapes differently.

Isolated

The value is almost entirely an attack payload. Weak wrappers such as @, a trailing semicolon, or /{${...}} still count as isolated.

Example: a search box that contains UNION SELECT 1,2,3.

Embedded

Attack-like tokens sit inside a long article, a product description, or a technical discussion.

Example: a forum post that quotes a SQL snippet.

Levels 2–4 allow embedded hits and enqueue them for ALAP. Level 5 blocks them.

Current isolation scope

This is an implementation fact, not a marketing promise:

• Isolated gadget coverage includes PHP/JSP live shells, Log4j JNDI, and short quoted/predicate SQL (at most 96 runes).
• XSS, command/RCE, SSTI, SSRF, and XXE use the document-shape guard. They are not on that gadget list.
• Hits marked embedded skip the block below level 5.
• Unclassified hits still follow blockableHit evidence. They are not auto-treated as embedded.
• Isolation lowers false positives on covered gadgets. It is not a free pass for every technical article.

4 - Three management surfaces

setup.three_end_unified is on in the sample config. A user created in the console can use the CLI. A token created under System can call REST with the same RBAC permissions.

Permissions live under apisec.permissions. The sample grants admin: ["*"] and readonly: ["read:*", "read:cluster"].

Audit events write to apisec.audit.path when apisec.audit.enabled is true.

See Console, CLI, and REST API.