Decision pipeline

Order matters. The PHP agent applies checks roughly in this order:

1. Whitelist: bypass all checks if IP is allowlisted.
2. Path bypass: skip all bot detection for configured URL paths (APIs, webhooks, health checks).
3. SEO safety: allow verified crawlers when enabled.
4. Obsidian: optional output-layer protections.
5. Global blocklist: deny known malicious IPs.
6. Geo: allow/deny by country policy.
7. Bot/scanner: UA signatures + regex.
8. VPN/proxy: RDNS heuristics + proxy domain lists (may challenge).
9. Referrer security: soft-challenge suspicious POSTs; block known referrer spam.

Safety net (IP allowlist)

whitelist_ips bypasses all enforcement. Use for:

• your office IPs
• monitoring systems
• CI/CD health checks

Path bypass rules

bypass_paths lets you exclude specific URL paths from all bot detection layers. Requests matching a bypass pattern are allowed through immediately — no scoring, no challenge, no rate limiting.

Use for:

• REST API endpoints called by curl, python-requests, or backend services
• Webhook receivers (Stripe, GitHub, Shopify callbacks)
• Health check / uptime monitor paths (/health, /ping)
• Well-known URIs (/.well-known/*)

Patterns support exact match and * wildcard:

/api/*          ← matches /api/v1/orders, /api/webhooks, etc.
/webhooks/*     ← matches /webhooks/stripe, /webhooks/github
/health         ← exact match only
/.well-known/*  ← ACME, security.txt, etc.

⚠ Security warning: bypassed paths have zero bot protection. Only bypass paths you fully control. Never bypass login, registration, or user-facing form endpoints.

Configure via Settings → Access Control → Bypass Rules.

SEO safety

When seo_safety_enabled is true, the agent allows verified SEO crawlers. Verification uses reverse-DNS + forward-DNS validation with caching.

Obsidian layer

Enterprise output-buffer protections (compat-first by default): right-click/devtools/copy hardening, optional CSS noise. See Obsidian Layer.

Global blocklist

Large IP list is versioned. Agents send blocked_ips_version; server returns global_blocked_ips only when changed. Agents persist a local cache and hydrate when server sends null.

Geo fencing

geo_mode = blacklist or whitelist and block_geo list of country codes.

Bot/scanner detection

• scanner_uas: substring matches
• bot_ua_regex: regex match

VPN/proxy heuristics

When block_vpn is enabled, agent may perform RDNS on sensitive requests and compare against: proxy_domains, banned_isps, banned_asns. Proxy matches typically trigger a challenge.

Referrer security

Referrer checks are designed to avoid breaking legitimate traffic:

• Suspicious POST with no Referer and no Origin ⇒ challenge (soft)
• Known spam referrers ⇒ block
• HTTPS site receiving same-host http:// referrer ⇒ block (header spoofing)