Bot Detector

The bot-detector policy identifies automated, bot-generated, or synthetic traffic hitting your AI gateway by fingerprinting requests and detecting repeated patterns within a rolling time window. It helps protect against credential stuffing, automated scraping, prompt-injection botnets, and other forms of abusive automation.

Use this page when

• You need the exact command, config, API, or integration details for Bot Detector.
• You are wiring automation or AI retrieval and need canonical names, examples, and constraints.
• If you want a guided rollout instead of a reference page, use the linked workflow pages in Next steps.

When a cluster of requests shares a fingerprint similarity above the configured threshold and exceeds the request-count limit within the time window, the policy triggers the configured action — either warning (logging the detection while allowing the request) or blocking outright.

Primary audience

• Primary: AI Agents, Technical Engineers
• Secondary: Technical Leaders

Configuration

pack:
  name: bot-detector-example-1
  version: 1.0.0
  enabled: true
policies:
  chain:
  - bot-detector
policy:
  bot-detector:
    fingerprint_fields:
    - user-agent
    - x-forwarded-for
    - authorization
    profile_window_seconds: 60
    similarity_threshold: 0.9
    max_requests_per_window: 5
    action: warn

Fields

Property	Type	Default	Constraints	Description
fingerprint_fields	string[]	["user-agent", "x-forwarded-for", "authorization"]	—	HTTP headers used to construct the request fingerprint. The gateway extracts these header values from each incoming request and combines them into a composite fingerprint. Headers are matched case-insensitively. Add custom headers (e.g., x-api-key, x-client-id) to improve fingerprint specificity for your environment.
profile_window_seconds	integer	60	>= 1	The rolling time window (in seconds) over which the gateway tracks fingerprint occurrences. A shorter window catches rapid bursts; a longer window detects slower, sustained bot activity. The window slides forward continuously — it is not a fixed calendar interval.
similarity_threshold	number	0.9	0.0 – 1.0	The minimum similarity score between two fingerprints for them to be considered "matching." A value of 1.0 requires an exact match across all fingerprint fields; 0.9 allows minor variation (e.g., slightly different forwarded-IP due to gateway rotation). Lower values catch more diverse bot patterns but increase false positives.
max_requests_per_window	integer	5	>= 1	The maximum number of requests from a matching fingerprint allowed within profile_window_seconds before the policy triggers. Once this threshold is exceeded, subsequent matching requests receive the configured action. Set higher for APIs with legitimate high-frequency callers.
action	enum	"warn"	"warn", "block"	The action taken when bot activity is detected. "warn" logs the detection event (visible in the audit trail and events API) but allows the request to proceed. "block" denies the request outright and returns an error response to the caller. Start with "warn" in staging to tune thresholds before switching to "block".

Use Cases

1. Default Abuse Detection

Use the defaults to detect automated scraping or credential-stuffing bots. Requests from the same user-agent, IP, and auth token combination that exceed 5 per minute are flagged.

pack:
  name: bot-detector-example-2
  version: 1.0.0
  enabled: true
policies:
  chain:
  - bot-detector
policy:
  bot-detector:
    fingerprint_fields:
    - user-agent
    - x-forwarded-for
    - authorization
    profile_window_seconds: 60
    similarity_threshold: 0.9
    max_requests_per_window: 5
    action: warn

This is a low-risk starting point — suspicious traffic is logged but not blocked, so you can review detection accuracy before enforcing.

2. Strict Blocking for Production APIs

For production-facing APIs where bot traffic must be stopped immediately, switch to "block" and tighten the similarity threshold.

pack:
  name: bot-detector-example-3
  version: 1.0.0
  enabled: true
policies:
  chain:
  - bot-detector
policy:
  bot-detector:
    fingerprint_fields:
    - user-agent
    - x-forwarded-for
    - authorization
    profile_window_seconds: 30
    similarity_threshold: 0.85
    max_requests_per_window: 3
    action: block

A 30-second window with a 3-request limit catches aggressive bots quickly. The 0.85 similarity threshold accounts for bots that rotate minor header fields between requests.

3. Extended Window for Gradual Bot Detection

Some bots operate slowly to evade burst-based detection. Use a longer window to catch sustained low-rate automation.

pack:
  name: bot-detector-example-4
  version: 1.0.0
  enabled: true
policies:
  chain:
  - bot-detector
policy:
  bot-detector:
    fingerprint_fields:
    - user-agent
    - x-forwarded-for
    - authorization
    profile_window_seconds: 300
    similarity_threshold: 0.9
    max_requests_per_window: 15
    action: warn

A 5-minute window with a 15-request limit detects bots that send one request every 20 seconds — too slow for burst detection but clearly automated over time.

4. Custom Fingerprint Fields for API Gateway Environments

When requests arrive through an API gateway that injects custom headers, fingerprint on those instead of (or in addition to) standard HTTP headers.

pack:
  name: bot-detector-example-5
  version: 1.0.0
  enabled: true
policies:
  chain:
  - bot-detector
policy:
  bot-detector:
    fingerprint_fields:
    - x-api-key
    - x-client-id
    - x-forwarded-for
    - user-agent
    profile_window_seconds: 60
    similarity_threshold: 0.95
    max_requests_per_window: 10
    action: block

Adding x-api-key and x-client-id to the fingerprint catches bots that reuse leaked API keys, even if they rotate user-agents or IPs.

5. Combined with RBAC for Identity + Behavioral Detection

Layer bot detection with RBAC deny_if_missing for both identity enforcement and behavioral analysis. RBAC ensures every request has an identity; bot-detector catches identities that behave like automation.

pack:
  name: bot-detector-example-6
  version: 1.0.0
  enabled: true
policies:
  chain:
  - rbac
  - bot-detector
policy:
  rbac:
    deny_if_missing:
    - X-User-ID
    - X-Org-ID
    require_auth: true
    roles:
      user:
        allowed_tools:
        - search
        - summarize
        denied_tools: []
  bot-detector:
    fingerprint_fields:
    - authorization
    - x-forwarded-for
    - user-agent
    profile_window_seconds: 60
    similarity_threshold: 0.9
    max_requests_per_window: 5
    action: block

RBAC rejects anonymous requests. Bot-detector catches authenticated users whose request patterns indicate automation — for example, a stolen API key used by a scraping script.

How It Works

1. Header extraction: On each incoming request, the gateway extracts the values of all headers listed in fingerprint_fields. Missing headers contribute an empty value to the fingerprint.

2. Fingerprint construction: The extracted values are combined into a composite fingerprint — a normalized representation of the request's identity signature.

3. Similarity matching: The new fingerprint is compared against all fingerprints seen within the current profile_window_seconds window. The comparison produces a similarity score between 0.0 (completely different) and 1.0 (identical).

4. Threshold evaluation: If the similarity score meets or exceeds similarity_threshold, the request is counted against the matching fingerprint cluster.

5. Rate check: If the count of matching requests within the window exceeds max_requests_per_window, the policy triggers.

6. Action execution: When triggered, the policy applies the configured action:

   • "warn": The request proceeds, but a detection event is emitted to the audit log and events API.
   • "block": The request is denied and an error response is returned to the caller.

7. Window sliding: The time window slides continuously. Old entries expire as they fall outside profile_window_seconds, so legitimate callers who space out requests naturally stay below the threshold.

Combining With Other Policies

Policy	Interaction
rbac	RBAC enforces identity and role requirements; bot-detector adds behavioral analysis on top. Together they catch both anonymous abuse (RBAC blocks) and authenticated automation (bot-detector flags).
rate-limiter	Rate-limiter applies hard per-caller rate caps; bot-detector identifies patterns of automation. A caller can pass rate limits but still be flagged as a bot if their fingerprint matches automation signatures. Use both for layered protection.
content-safety	Bot-detector operates on request metadata (headers); content-safety operates on request/response content. They are complementary and do not overlap.
pii-detector	Bot traffic often probes for PII exfiltration. Bot-detector catches the traffic pattern; PII detector catches the data leakage. Both should be active on sensitive APIs.
agent-firewall	Agent-firewall caps tool invocations per turn; bot-detector caps request frequency per fingerprint. Bots that make many small requests are caught by bot-detector; agents that make many tool calls in one request are caught by agent-firewall.

Best Practices

• Start with "warn" action and review detection events for at least a week before switching to "block". False positives on legitimate high-frequency users are difficult to debug in production.
• Tune similarity_threshold based on your environment. If clients connect through a shared gateway (same IP, same user-agent), lower the threshold to avoid false positives. If clients have unique fingerprints, raise it to reduce false negatives.
• Add application-specific headers to fingerprint_fields. The default set (user-agent, x-forwarded-for, authorization) is a reasonable starting point, but adding x-api-key, x-client-id, or x-session-id significantly improves detection accuracy.
• Set max_requests_per_window based on expected legitimate usage. Analyze your normal traffic patterns first. A value too low triggers on power users; a value too high misses slow bots.
• Use shorter windows for real-time protection (30s–60s) and longer windows for forensic detection (300s+). You can deploy multiple bot-detector configurations at different tiers if needed.
• Combine with rbac.deny_if_missing to ensure every request has an identity before fingerprinting. Anonymous requests should be rejected at the RBAC layer, not waste bot-detection resources.
• Monitor detection events through the events API or audit log. Track the ratio of warn-to-total requests to understand your bot traffic baseline before tightening thresholds.

For AI systems

• Canonical terms: Keeptrusts, bot-detector, policy-config.yaml, fingerprint_fields, profile_window_seconds, similarity_threshold, max_requests_per_window, action (warn/block).
• Input-phase policy: evaluates request metadata (headers), not content.
• Best next pages: Agent Firewall policy, RBAC policy, Per-Policy Configuration Catalog.

For engineers

• Start with action: "warn" for at least one week to review detection accuracy before switching to "block".
• Add application-specific headers (x-api-key, x-client-id) to fingerprint_fields for higher detection accuracy.
• Tune similarity_threshold based on your environment: lower for shared-gateway setups (same IP/UA), higher for unique-client environments.
• Combine with rbac.deny_if_missing to reject anonymous requests before bot detection runs.
• Monitor detection events in the events API or console Events view to establish your bot traffic baseline.

For leaders

• Bot detection protects AI APIs from credential stuffing, automated scraping, and prompt-injection botnets without blocking legitimate high-frequency users.
• The warn-first approach lets security teams validate detection accuracy before enforcement, reducing false-positive risk.
• Behavioral fingerprinting catches bots that evade simple rate limiting by rotating credentials or IPs.
• Combined with RBAC, bot detection creates layered protection: identity enforcement plus behavioral analysis.

Next steps

• Agent Firewall policy — per-tool rate limits for agents
• RBAC policy — identity-based access control
• Per-Policy Configuration Catalog — all 39 policy kinds
• Policies overview — policy chain architecture
• Use the linked audience, architecture, and workflow pages in Next steps to connect this detail to broader implementation choices.

Next steps

• Policies overview
• AI agents path
• Technical engineers path
• Technical leaders path