Enforce: Gateway Setup

Goal

Set up Checkpoint Gateway to enforce AI agent policies at the DNS/edge level — no code changes required. By the end of this cookbook, you'll have:

• Traffic routing through Checkpoint's edge network
• WASM-based detection running on every request
• Automatic SSL/TLS certificate provisioning
• Policy enforcement (block, redirect, challenge) for detected agents

Best for: Protecting any website or API without touching application code. Works with any origin server.

Prerequisites

• A Checkpoint account with a project created
• A domain or subdomain you control
• Access to your domain's DNS settings

Time Estimate

10-15 minutes (plus DNS propagation time)

Steps

Type:  CNAME
Name:  shop (or your subdomain)
Value: cname.checkpoint-gateway.ai
TTL:   Auto (or 300)

Type:  CNAME
Name:  @ (or leave blank)
Value: cname.checkpoint-gateway.ai
TTL:   Auto

# Check if CNAME is set correctly
dig shop.example.com CNAME +short
# Should return: cname.checkpoint-gateway.ai

# Check if the domain resolves
curl -I https://shop.example.com
# Should return headers including the KYA-* detection headers (e.g. KYA-Detected, KYA-Detection-Class)

@id("block-scraper-on-pricing")
@verdict("BLOCK")
forbid ( principal, action, resource )
when { resource.path like "/pricing*" && principal.name == "GPTBot" };

@id("redirect-scrapers")
@verdict("REDIRECT")
@redirect("/for-ai")
forbid ( principal, action, resource )
when { principal.category == "scraper" };

curl -I https://shop.example.com
# Should return 200 OK with your origin's response

curl -I -H "User-Agent: Mozilla/5.0 (compatible; GPTBot/1.0)" \
  https://shop.example.com
# Should return 403 (if blocking AI agents)

curl -I -H "User-Agent: Googlebot/2.1" \
  https://shop.example.com
# Should return 200 OK (if Googlebot is allowed)

Understanding Gateway Headers

The Gateway works with two distinct sets of headers.

Detection headers returned to the client

On every proxied response, the Gateway sets KYA-* headers describing the detection result. These are visible on the response you get back (e.g. via curl -I):

Headers forwarded to your origin

Separately, the Gateway adds tracing/context headers to the request it forwards to your origin server:

Your origin can inspect the forwarded context headers, and clients can read the KYA-* detection headers off the response:

// Express example — reading a forwarded context header at the origin
app.get('/api/data', (req, res) => {
  const requestId = req.headers['kya-request-id'];
  const region = req.headers['kya-region'];

  // Detection results are attached to the response the Gateway returns to the
  // client (KYA-Detected, KYA-Detection-Class, etc.), not to the origin request.
  res.set('X-Trace-Id', String(requestId ?? ''));
  res.json({ data: 'full', region });
});

Verify It's Working

Dashboard Verification

1. Go to Analytics in your dashboard
2. You should see requests categorized by detection class
3. Blocked requests will show in the Enforced tab

Health Endpoint

The Gateway exposes health endpoints:

# Health check
curl https://shop.example.com/__gateway/health
# Returns: { "status": "healthy", "version": "1.0.0", "timestamp": "...", "region": "SFO", "environment": "production" }

# Readiness check
curl https://shop.example.com/__gateway/ready
# Returns: { "ready": true }   (or 503 { "ready": false, "error": "..." })

# Version info
curl https://shop.example.com/__gateway/version
# Returns: { "version": "1.0.0", "environment": "production" }

See Monitoring for the full field reference and the separate /__detect/health endpoint that reports WASM engine status.

Troubleshooting

DNS Not Detected

SSL Certificate Not Provisioning

• Check DNS again — Must resolve correctly before cert issuance
• Check CAA records — Remove or add Cloudflare to allowed issuers
• Cloudflare users — Ensure proxy is OFF (gray cloud)

Origin Not Reachable

• Check firewall — Allow Cloudflare IP ranges
• Check origin URL — Verify in dashboard settings
• Check HTTPS — Origin must support HTTPS

Requests Not Being Blocked

• Deployed, not just drafted — make sure you clicked Authorize & deploy, not just "Save as draft"
• Give the cache a minute — the gateway refreshes the deployed policy within ~60s
• Dry-run it — use Run dry test to see which rule matched and why

What You Learned

• How to create and configure a Checkpoint Gateway
• How to update DNS records for different providers
• How to configure enforcement policies
• How to test Gateway functionality
• How to read the KYA-* detection headers and origin-forwarded context headers

Next Steps

Related Documentation

• Gateway Reference
• Policies
• Detection in Enforce Mode
• Monitoring