How-to · Troubleshooting

Handle a false-positive block

This guide shows you how to investigate and resolve false-positive blocks reported by users or detected via monitoring. For your own lockout, see self-rescue-lockout.

When this happens

A legitimate user, customer, or webhook source receives HTTP 403 from a kup6s site. Triggers:

  • User complaint via email or chat

  • Grafana shows a sudden 4xx spike

  • Loki logs show repeated 403 responses with crowdsec tags

Step 1: Confirm the block

Determine the affected source IP. For a user complaint, ask the user — curl ifconfig.me is the simplest method. For a monitoring spike, query Loki for the top 403-returning IPs in the time window.

Check whether the IP is in the decision list:

kubectl exec -n crowdsec deploy/crowdsec-lapi -- cscli decisions list --ip <user-ip>

If the command returns an entry, note the origin field:

  • CAPI — generic community feed

  • lists:crowdsecurity/<name> — premium blocklist

  • cscli — manually added

Step 2: Decide false-positive or real

Use these criteria.

If the IP belongs to a known customer or partner — false-positive. If the IP belongs to an internal monitoring or webhook source — false-positive. If the source is from a too-aggressive blocklist for our use case — false-positive for our context. If the IP shows recognizable botnet patterns (multiple scenarios, repeated scan attempts) — not a false-positive.

Inspect alert details for context:

kubectl exec -n crowdsec deploy/crowdsec-lapi -- cscli alerts list --ip <ip>

Step 3: Ad-hoc unblock

Remove the decision immediately:

kubectl exec -n crowdsec deploy/crowdsec-lapi -- cscli decisions delete --ip <user-ip>

The unblock takes effect within 60 seconds.

This is temporary — the decision can return when the source refreshes.

Step 4: Permanent allowlist entry

Maintain a customer-trust allowlist for IPs that should always be permitted:

kubectl exec -n crowdsec deploy/crowdsec-lapi -- cscli allowlists create trusted-customers \
  --description "Known customer IPs and CIDRs"

Add a single IP:

kubectl exec -n crowdsec deploy/crowdsec-lapi -- cscli allowlists add-item trusted-customers --value <ip>

Add a CIDR (a customer office range, for example):

kubectl exec -n crowdsec deploy/crowdsec-lapi -- cscli allowlists add-item trusted-customers --value <cidr>

List the allowlist contents:

kubectl exec -n crowdsec deploy/crowdsec-lapi -- cscli allowlists inspect trusted-customers

Allowlists override decisions from any source, including CAPI and premium blocklists.

Step 5: Disable the noisy source if false-positives recur

If a single blocklist produces multiple false-positives, disable it:

kubectl exec -n crowdsec deploy/crowdsec-lapi -- cscli blocklists disable crowdsecurity/<name>

The plugin stops applying new decisions from this blocklist within 60 seconds.

Existing decisions remain in the cache until their TTL expires. To force-clear them:

kubectl exec -n crowdsec deploy/crowdsec-lapi -- cscli decisions delete \
  --origin "lists:crowdsecurity/<name>"

Step 6: When CAPI itself produces false-positives

The CAPI feed cannot be disabled — it is the default. Address recurring CAPI false-positives by either:

  • Adding the legitimate IP or CIDR to the trusted-customers allowlist (step 4)

  • Per-endpoint allowlists in middlewares.ts (future work, not yet implemented in kup6s)

  • Temporarily reverting to detect-only via self-rescue-lockout Action 3 Option A while investigating

Audit trail

CrowdSec does not maintain an automatic audit log of manual decision deletes and allowlist edits. Document each manual action in a team channel (Slack, email) with the reason and date. For stricter compliance, snapshot cscli decisions list -o json into Loki on a schedule.