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
   └── Request patterns

2. Check for KYA-OS signature headers
   ├── If present → Verify the signature
   │   ├── Valid → verified identity, classify as ai_agent
   │   └── Invalid → Block (never falls back to 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 KYA-OS identity challenge. Both the Gateway and the SDKs support it, but the status differs by surface: read the body or the X-Checkpoint-* headers rather than the status code, and see INSTRUCT by surface for the table.

The log action belongs to the legacy structured path-rule layer, not Cedar: it records a match and lets the request through. See Policies for the verdict 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 reads the client's TLS fingerprint and checks it against the browser the request claims to be. A request whose User-Agent claims a mainstream browser but whose TLS stack is one only non-browser software uses is classified as automation and carries the detection/ua-tls-mismatch reason code.

HTTP Header Analysis

Beyond the user agent, the detection engine checks HTTP and header consistency: whether the headers a request sends match the browser or client it claims to be.

Request Pattern Analysis

Detection also weighs behavioral evidence, such as a client's request volume across a session and, where the Pixel or Beacon runs, how the visitor interacts with the page.

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 published public key (see below)
3. Verify the Ed25519 signature against the request
4. If valid: the request is classified as a verified ai_agent

Key discovery

The edge never fetches an agent's key directory on the request path. Checkpoint keeps each supported agent's published keys (its .well-known/http-message-signatures-directory) current and serves them to the edge, so verification never waits on the agent's own servers and picks up key rotation automatically.

Why Signature Verification Matters

Cryptographic signatures are unforgeable. When an agent presents a valid signature, the request is classified at the top of the confidence range. 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
• No network round-trips for classification
• Updated with each Gateway release: the engine is built into the Gateway worker, so there is nothing for you to redeploy

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) scores at the top of the range.

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