[do not merge yet] bot detection feature documentation - #1099
Open
buixor wants to merge 15 commits into
Open
Conversation
buixor
commented
Jun 3, 2026
buixor
commented
Contributor
- Documentation for the upcoming bot detection feature
|
This pull request is automatically being deployed by Amplify Hosting (learn more). |
This was referenced Jul 20, 2026
buixor
marked this pull request as ready for review
August 3, 2026 08:06
Contributor
There was a problem hiding this comment.
Pull request overview
Adds documentation for the upcoming (alpha) AppSec bot-detection feature, including new dedicated doc pages, sidebar navigation, and “Bot Detection” capability badges on relevant remediation-component pages.
Changes:
- Introduces a new AppSec → Bot detection documentation section (intro, enablement, configuration, hooks reference, customization, defaults, request flow).
- Updates remediation-component docs/UI to surface Bot Detection support via a new
BotDetectionbadge. - Extends existing docs with bot-detection-related references (AppSec intro/hooks, allowlists behavior, Prometheus metrics, DNS cache config).
Reviewed changes
Copilot reviewed 20 out of 20 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| crowdsec-docs/unversioned/getting_started/introduction.mdx | Adds a mention/link to bot detection as an optional WAF capability. |
| crowdsec-docs/unversioned/bouncers/traefik.mdx | Adds AppSec/BotDetection support badges for Traefik. |
| crowdsec-docs/unversioned/bouncers/openresty.mdx | Adds BotDetection support badge for OpenResty. |
| crowdsec-docs/unversioned/bouncers/nginx.mdx | Adds BotDetection support badge for Nginx. |
| crowdsec-docs/unversioned/bouncers/envoy.mdx | Adds BotDetection support badge for Envoy. |
| crowdsec-docs/src/components/remediation-support-badge.tsx | Adds a BotDetection prop and renders a new “Bot Detection” badge bubble. |
| crowdsec-docs/sidebars.ts | Adds a new “Bot detection” category under AppSec with dedicated pages. |
| crowdsec-docs/docs/observability/prometheus.md | Documents new Prometheus counters for the challenge lifecycle. |
| crowdsec-docs/docs/local_api/allowlists.md | Clarifies that allowlists bypass AppSec/bot detection and adds a note about exemptions. |
| crowdsec-docs/docs/configuration/crowdsec_configuration.md | Documents global dns_cache settings under crowdsec_service. |
| crowdsec-docs/docs/appsec/intro.md | Adds bot detection to the AppSec feature list and “learn more” links. |
| crowdsec-docs/docs/appsec/hooks.md | Adds bot-detection hook phases and helper references to the AppSec hooks doc. |
| crowdsec-docs/docs/appsec/configuration.md | Documents data: in appsec-configs for shipping known-bot definition files. |
| crowdsec-docs/docs/appsec/bot_detection/intro.md | New: feature overview, objectives, prerequisites, and next steps. |
| crowdsec-docs/docs/appsec/bot_detection/enable.md | New: installation/wiring/verification steps and metrics pointers. |
| crowdsec-docs/docs/appsec/bot_detection/whats_included.md | New: explains what the default collection installs (configs/scenarios/exclusions). |
| crowdsec-docs/docs/appsec/bot_detection/how_it_works.md | New: end-to-end flow and details about fingerprint/PoW behavior and collected signals. |
| crowdsec-docs/docs/appsec/bot_detection/customization.md | New: overlay config recipes and guidance for tuning/exemptions/scenarios. |
| crowdsec-docs/docs/appsec/bot_detection/configuration.md | New: challenge config semantics (secrets, rotation, TTL, obfuscation, safety limits). |
| crowdsec-docs/docs/appsec/bot_detection/hooks.md | New: full helper reference for on_challenge / on_challenge_submit and fingerprint object. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+9
to
+13
| :::warning | ||
|
|
||
| Before moving forward, ensure that your bouncer supports bot-detection feature. Enabling bot detection on a non-compatible bouncer leads to unexpected behavior, most likely silently refusing any client. At the time of writing, only Nginx & Openresty bouncers version >= 1.2.0 support bot-detection. | ||
|
|
||
| ::: |
Comment on lines
+441
to
+444
| dns_cache: | ||
| ttl: 1h | ||
| negative_ttl: 5m | ||
| size: 16384 |
| | Blocklists | IP is removed before database insertion | ✅ | | ||
| | WAF (AppSec) | Request not blocked, action logged. | Refreshed every minute | | ||
| | WAF (AppSec) | Request bypasses AppSec entirely, action logged. | Refreshed every minute | | ||
| | Bot Detection (AppSec) | Request bypasses Bot detection entirely. | Refreshed every minute | |
| sidebar_position: 6 | ||
| --- | ||
|
|
||
| This page references available expr helpers in the dedicated bot detection hooks (`on_challenge_submit` and `on_challenge`), alongside with the `fingerprint` object. |
|
|
||
| This hook fires when a client POSTs a challenge response to `/crowdsec-internal/challenge/submit`, **after** the AppSec component has cryptographically validated the submission and decrypted the fingerprint, but **before** the success cookie is issued. This is the right place to refuse cookies to clients the challenge has positively identified as automation. **In-band only.** | ||
|
|
||
| Note that the default behavior is to accept (grant cookie) to client that submit a valid challenge response. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.