Traffic Policy Rules

Security Rules

Protect your endpoint with IP restrictions, rate limiting, authentication, and circuit breaking.

IP Restriction

Allow or deny requests from specific IP ranges (IPv4/IPv6 CIDR).

Rate Limit

Limit requests per time window. Protect your backend from abuse.

Verify Webhook

Validate incoming webhook signatures against a shared secret.

The secret is write-only: reads answer ****. Send **** back on an update to keep it, or a new value to replace it.

JWT Validation

Validate JSON Web Tokens at the edge. Supports HMAC and RSA/ECDSA algorithms. Request phase only (on_http_request). This rule is how ngris checks JWTs — it is not an endpoint auth mode (those are none, basic and SSO, under Access Controls), so it works alongside any of them.

The secret is write-only: reads answer ****. Send **** back on an update to keep it, a new value to replace it, or "" to remove it (an RS*/ES* rule uses jwks_url).

API Key Validation

Validate API keys at the edge. Manage keys in the API Keys tab.

Body Validation

Validate JSON request bodies against a JSON Schema (draft 2020-12). Only validates application/json requests.

Circuit Breaker

Stop sending traffic to failing backends. The circuit opens when error rates exceed a threshold, and automatically recovers after a cooldown period.

Client certificates (mTLS)

Client certificates are not a traffic-policy rule. Turn them on in the endpoint's Mutual TLS settings (or with the agent's --mutual-tls flag): pick a mode and the client CAs you trust — see Mutual TLS. mTLS works on HTTP(S) endpoints only.

Traffic Rules

Control traffic flow with caching, redirects, custom responses, and webhooks.

Cache Response

Cache responses at the edge (Redis-backed). Serve cached content without hitting your backend.

Image Optimization

Resize and re-encode image responses at the edge — smaller, modern-format images without touching your backend. Runs in the response phase on any endpoint, both agent tunnels and hosted apps. Only image responses (Content-Type: image/*) are transformed; everything else passes through untouched.

Transforms are driven per-request by the URL: add ?w=/?width= to resize, ?q=/?quality= to set quality, and ?format=webp|avif|jpeg|png to force an output format. With no ?format=, the client's Accept header auto-negotiates a modern format (WebP/AVIF). Each optimized variant is cached at the edge (like Cache Response), and encoding never upscales past the original.

Force HTTPS

Redirect all HTTP requests to HTTPS with a 301 status code. No configuration needed. Also available as a toggle on the Endpoint Overview tab.

Redirect

Redirect requests to a different URL with configurable status code.

Custom Response

Return a custom response without forwarding to your backend. Useful for maintenance pages, health checks, or static content. Subject to AI content safety validation.

Custom Error Page

Replace error responses from your backend with custom-branded error pages. Supports template tokens for dynamic content.

Webhook

Forward request or response data to an external HTTP endpoint. Useful for logging, notifications, or custom processing pipelines.

Modification Rules

Modify request and response headers and rewrite URLs.

Add Headers

Inject custom headers into requests (before forwarding) or responses (before returning to client).

Send the bot score to your origin. A request-phase Add Headers rule can pass each request's bot score to your app, so the app can decide for itself:

{"type": "add-headers", "phase": "on_http_request",
 "config": {"headers": {"X-Ngris-Bot-Score": "${req.bot_score}"}}}

Your origin then receives a header such as X-Ngris-Bot-Score: 95 (1–99, low means likely automated). A value the visitor sends in that header is replaced. Nothing is sent until you add the rule; the Send the bot score to your origin switch on the endpoint's Under attack card adds or removes exactly this rule.

Remove Headers

Strip specific headers from requests or responses.

URL Rewrite

Rewrite request URLs before forwarding to your backend using regex patterns with capture groups.

# Example: Strip /api/v1 prefix
# Pattern: ^/api/v1/(.*)$
# Replacement: /$1

API Gateway Rules

Additional edge rule types for full API-gateway behavior. Add them from the same Traffic Policy editor.

CORS

Answer CORS preflight (OPTIONS) requests at the edge and add Access-Control-Allow-* headers to responses — no backend changes. Runs in the request phase.

Set Variables

Compute named variables from CEL expressions into a per-request bus. Later rules read them in conditions (vars.tier == "gold") and in header / redirect / custom-response values (${vars.tier}). Runs in the request phase. One name = expression per line.

tier = req.headers["x-tier"]
is_admin = req.path.startsWith("/admin")
# then, in an Add Headers rule:  X-Plan: plan-${vars.tier}

Replace Body

Find/replace in the response body (literal or regex) — e.g. rewrite internal URLs or redact strings. Applies to complete, uncompressed responses up to a size cap; streamed and already-compressed responses pass through untouched.

Compress

Compress eligible response bodies at the edge, negotiating br (Brotli, preferred) or gzip from the client's Accept-Encoding. Compressible text/JSON types only; never inflates or double-compresses.

WAF

A web application firewall that inspects each request (URI, headers, and optionally an inline body) against an OWASP-style ruleset via the Coraza engine and blocks or logs matches. Runs in the request phase. The built-in core ruleset covers SQL injection and XSS (libinjection), path traversal / sensitive-file access, OS-command and template injection, Log4Shell/JNDI, and known scanner user-agents — no external OWASP CRS to manage. Advanced users can supply their own Coraza SecLang.

Mode defaults to detect (log only) so turning the WAF on can never break a live endpoint on day one — watch the logs, then switch to block. The compiled engine is cached per ruleset; endpoints without a WAF rule pay nothing.

Bot Management

Match the client's TLS JA3 fingerprint — computed at the edge from the ClientHello — against allow/deny lists to block or log automated clients. Runs in the request phase. Mode defaults to detect (log only). Fingerprinting is only computed when a bot-management rule exists on some endpoint, so endpoints not using it pay nothing.

The JA3 is GREASE-normalized (RFC 8701 random values stripped) so it's stable per client. Run in detect mode first and copy the exact fingerprints the edge logs into your denylist — those match what the matcher computes. The fingerprint is also readable in any rule's CEL guard as conn.ja3 (e.g. conn.ja3 == "e7d705…" && req.path.startsWith("/api")).

Challenge (Under attack mode)

Make each visitor's browser pass a short automatic check before the request reaches your endpoint. The browser solves a small JavaScript proof-of-work (nothing is sent to a third party), and the edge then sets a signed clearance cookie so later requests go straight through. By default there is nothing to click; set interaction to checkbox or puzzle to also ask visitors to tick a box or slide a puzzle piece into place. It is a request-phase rule on the endpoint, so it protects agent tunnels and hosted apps alike, and it is available on every plan. The quickest way to turn it on is the Under attack mode switch on the endpoint's Overview tab.

The challenge runs before every other request rule and before the edge cache, so no cached page is served to a visitor who has not passed. The clearance cookie only works on the site that issued it, in the browser that solved the check and (by default) from the same network, so it cannot be copied to other machines.

What visitors see: a page naming your site in large type, with a progress line under it and the line “Making sure you're a person, not a bot”. Your message, if you set one, appears below it. With the automatic type the check needs no clicks and usually finishes in about a second; with checkbox or puzzle the visitor ticks the box or slides the piece first. Then they land on the page they asked for. If their browser blocks cookies or has JavaScript turned off, the page says so and how to fix it. The footer shows “Protected by ngris” and a Ref code: the request's ID (its X-Request-Id), so a visitor who is stuck can quote it to you or to ngris support. To find that request's log entry, filter the traffic logs by request_id. The page follows the visitor's light or dark setting.

What gets blocked: requests that cannot show the check page and have no clearance — API calls, fetch/XHR from other sites, POSTs, WebSocket upgrades, curl, webhooks from other services and crawlers we can't verify — get a 403 with the header X-Ngris-Challenge: required. Add your API and webhook prefixes to skip_paths, or your office and monitoring IPs to allow_ips. Use the rule's expression to challenge only part of the site (for example req.path.startsWith("/login")); a request whose path isn't in plain form (//login, /x/../login) is challenged whatever the expression says, so it can't slip past. Expressions compare paths exactly and case-sensitively (/ADMIN doesn't match startsWith("/admin")), so if your origin treats paths case-insensitively, challenge the whole site and use skip_paths for the exceptions, or lower-case the path in the expression.

Verified search engines and AI crawlers pass. A request from one of the crawlers below goes through without a check when its IP address is in the list its operator publishes for it, so your site stays in search results and AI answers while the rule is on. A bot that only copies one of these user agents is checked like anyone else (and scores fake_crawler). To check verified crawlers too, set allow_verified_bots to false, or turn off Let verified search engines and AI crawlers through on the Under attack card. Other crawlers are checked.

Fetchers such as ChatGPT-User, Perplexity-User or Google-Read-Aloud fetch a page when one of their users asks for it, so anyone can make them load a URL on your site. Turn allow_verified_bots off if that matters for the protected paths. The operators' IP lists are refreshed every hour; while a list can't be loaded, that operator's crawlers are checked like everyone else.

Challenge only suspicious visitors. By default (mode always) every visitor without a clearance is checked. Set mode to smart, or turn on Challenge only suspicious visitors on the Under attack card, and the rule decides by each request's bot score (1–99, low means likely automated): a score at or above pass_score (default 70) goes through without a check, a score below block_score (default 10) gets a 403 without a check, and every score in between gets the check. A verified crawler is never blocked by its score. With today's scores, a normal browser (about 95) is not checked; a browser from a cloud provider's network or a Tor exit, or one missing headers every browser sends, is checked; scripts, empty user agents, fake crawlers and blocklisted networks (5 or less) get the 403 straight away. The trade-off: a bot that imitates a browser well can score high and get through without the check, which always would have asked of it. Smart mode is off until you turn it on.

Re-checking busy visitors. Each clearance has its own ID, and the edge counts the requests made with it. A visitor who sends more than clearance_max_rpm requests in a minute (default 600) loses the clearance and is checked again, with a stronger check, so passing once doesn't buy a flood. A page with many images and scripts stays well under 600 a minute.

What it does not do: it stops scripts and tools that don't run JavaScript and makes every network pay for a check, but a headless browser can pass it. Pair it with a rate limit for floods from real browsers.

Rate limit — flexible keying

The Rate Limit rule's Scope now supports per-IP, per-endpoint, and per header, cookie, or JWT claim value (with a key name). Counting is shared across edges. Header/cookie/JWT-claim scopes bucket by client-controlled values (the JWT claim is not signature-verified) — use them for fair sharing, and pair with a per-IP rule as the hard ceiling against abuse.

Impact preview (blast radius)

In the rule editor, replayable rule types show a Preview impact button. It replays your last ~2 hours of captured traffic through the unsaved rule and reports how many requests would be newly blocked / throttled / redirected, how many previously-successful requests would break, the client IPs affected, and a safe / caution / risky verdict — so you can check the blast radius before you save. Requires request capture enabled on the endpoint.