Bot Detector

The bot-detector policy runs in the input phase. It keeps an in-memory rolling window of recent requests, computes a fingerprint from selected fields, and flags traffic when either the duplicate fingerprint count or the request-text similarity exceeds configured thresholds.

Phase and verdicts

• Phase: input
• Possible verdicts: allow, block

Configuration

pack:
  name: bot-detector-example
  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

Field	Type	Default	Notes
fingerprint_fields	string[]	['user-agent', 'x-forwarded-for', 'authorization']	Header names are read case-insensitively. Special pseudo-fields body and model are also supported.
profile_window_seconds	integer	60	Rolling in-memory window for retaining prior request events.
similarity_threshold	number	0.9	Compared against Jaccard similarity of the current request text to recent request text.
max_requests_per_window	integer	5	Flags when duplicate fingerprints in the active window meet or exceed this count.
action	warn | block	warn	warn leaves the verdict as allow; block returns block when flagged.

How it works

1. The gateway hashes the configured fingerprint_fields into a fingerprint.
2. It keeps recent fingerprint events in a rolling window bounded by profile_window_seconds.
3. It counts duplicate fingerprints already present in that window.
4. It computes a Jaccard similarity score between the current request text and prior request text.
5. The request is flagged when either condition is met:
   • duplicate fingerprint count >= max_requests_per_window
   • text similarity >= similarity_threshold
6. The gateway returns block only when the request is flagged and action: block is configured.

Behavior notes

• similarity_threshold is about request text similarity, not fingerprint similarity.
• State is held in-process memory; restarting the gateway resets the detector window.
• The policy records fingerprint, duplicate_count, similarity, and flagged in result details.

Example scenarios

Warn-first rollout

policy:
  bot-detector:
    action: warn

Include body and model in the fingerprint

policy:
  bot-detector:
    fingerprint_fields:
      - authorization
      - body
      - model
    action: block

Best practices

• Start with action: warn so you can inspect flagged traffic before enforcing blocks.
• Add body or model to fingerprint_fields when header-only fingerprints are too coarse for your environment.
• Tune similarity_threshold knowing it reflects request-text overlap, not shared headers.

Next steps

• RBAC policy — pair identity controls with behavioral checks
• Agent Firewall policy — control tool behavior after request admission
• Policies overview — policy chain architecture