Detection in Enforce Mode

Overview

When operating in Enforce mode, both the Gateway and Middleware perform multi-signal detection to classify incoming traffic. This page explains the detection mechanisms, signals used, and how results feed into policy evaluation.

Detection Flow

1. Extract request metadata
   ├── HTTP headers (User-Agent, Accept, etc.)
   ├── IP address and geolocation
   ├── TLS fingerprint (cipher suites + extensions)
   └── Request patterns

2. Check for KYA-OS signature headers
   ├── If present → Verify Ed25519 signature
   │   ├── Valid → 100% confidence, classify as ai_agent
   │   └── Invalid → Continue to WASM detection
   └── If absent → Continue to WASM detection

3. Run detection engine
   ├── Gateway: WASM module at the Cloudflare edge
   └── Middleware (local engine, `withCheckpoint`): the same WASM engine, in-process
       (the SaaS variant `withCheckpointApi` POSTs to the edge instead)

4. Combine results
   ├── Detection class (human, ai_agent, bot, incomplete_data)
   ├── Confidence score (0–100)
   └── Agent metadata (name, type, verification method)

5. Apply policy
   └── Allow / Block / Redirect / Require Identity (instruct)

The instruct action returns a 401 KYA-OS challenge and is gateway-only. The log action is path-rule-specific — it records a detection match but lets the request through. See Policies for the full action reference.

Detection Signals

User Agent Analysis

The detection engine analyzes the User-Agent header for known agent signatures:

TLS Fingerprinting

At the edge, the Gateway computes a TLS fingerprint from the client's cipher-suite list and TLS extension list. This is a custom cipher-and-extension hash — not the standard JA3/JA4 format.

HTTP Header Analysis

Beyond the user agent, the detection engine examines:

• Accept headers — Browsers send specific accept patterns
• Language headers — Automated tools often omit or misconfigure these
• Connection behavior — Keep-alive patterns, header ordering
• Missing headers — Browsers include standard headers that bots may skip

Request Pattern Analysis

Detection considers behavioral signals:

• Request frequency and timing
• Navigation patterns (do they follow links?)
• Resource loading (do they load CSS, images, JavaScript?)
• Cookie handling

Signature Verification (RFC 9421)

How It Works

Some AI agents cryptographically identify themselves using HTTP Message Signatures as defined in RFC 9421. ChatGPT, for example, signs its requests with Ed25519 keys.

When the Gateway detects signature headers:

1. Extract the Signature and Signature-Input headers
2. Look up the agent's public key from Checkpoint's internal key service (see below)
3. Verify the Ed25519 signature against the request
4. If valid: 100% confidence classification as ai_agent

Key discovery

The edge does not fetch the agent's .well-known directory on the request path. Instead, the Gateway requests the key from an internal signature-key service; a Checkpoint-side cron job periodically scrapes each supported agent's .well-known/http-message-signatures-directory and publishes the keys to that service. If the service is unreachable, the edge falls back to a small set of pinned keys so verification degrades gracefully rather than failing.

Why Signature Verification Matters

Cryptographic signatures are unforgeable. When an agent presents a valid signature, detection confidence is 100% — there's no ambiguity about the request source. This makes signature verification the highest-confidence detection method available.

WASM Detection (Gateway)

The Gateway runs a WebAssembly detection module at Cloudflare's edge:

• Compiled from optimized detection logic
• Runs in under 5ms (p95)
• No network round-trips for classification
• Updated without redeployment via Cloudflare's platform

The WASM module combines multiple signals into a single classification with a confidence score.

Classification and confidence

Enforce reuses the same detection engine as the Detect pillar, so the classification vocabulary (human, ai_agent, bot, incomplete_data) and the 0–100 confidence scale are identical. Detect is the canonical reference for what each class means and how confidence is scored — this page does not restate those definitions.

What is enforcement-specific is how the result is used: the classification and confidence flow straight into policy evaluation, where your Cedar rules decide the verdict. In practice:

• ai_agent vs bot lets you write different rules for AI assistants (ChatGPT, Claude, Perplexity) than for traditional crawlers (Googlebot, scrapers) — for example, allowing a search crawler while challenging an AI scraper.
• Confidence lets a policy act only on higher-certainty classifications rather than on every low-signal match. Cryptographic signature verification (above) is the one path that yields a definitive 100.

Detection Latency

Next Steps

• Policies — Use detection results to make enforcement decisions
• Gateway Enforcement — Edge-based detection setup
• Middleware Enforcement — Server-side detection setup
• Monitoring — Track detection performance