Skip to main content

Bot Detector

The bot-detector policy runs in the input phase. It keeps recent requests in an in-memory window. It makes a fingerprint from selected fields. It flags traffic when a duplicate count or text score is equal to or more than its configured limit.

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​

FieldTypeDefaultNotes
fingerprint_fieldsstring[]['user-agent', 'x-forwarded-for', 'authorization']Header names are not case-sensitive. You can also use body and model.
profile_window_secondsinteger60Rolling in-memory window that keeps previous request events.
similarity_thresholdnumber0.9Compared against Jaccard similarity of the input request text to recent request text.
max_requests_per_windowinteger5Flags when the number of duplicate fingerprints in the active window is equal to or more than this count.
actionwarn | blockwarnwarn keeps the verdict as allow. block returns block for a flagged request.

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 available in that window.
  4. It calculates a Jaccard score for the input text and prior request text.
  5. The request is flagged when one of these conditions is met:
    • duplicate fingerprint count >= max_requests_per_window
    • text similarity >= similarity_threshold
  6. The gateway returns block only when the two conditions apply:
    • The policy flags the request.
    • The config contains action: block.

Behavior notes​

  • similarity_threshold is about request text similarity, not fingerprint similarity.
  • The gateway keeps state in process memory. When the gateway starts again, the detector window is empty.
  • 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. Examine flagged traffic before you use blocks.
  • Add body or model when header fingerprints do not give sufficient detail.
  • Set similarity_threshold from request-text overlap. This score does not compare shared headers.

Next steps​