Ban abusive clients automatically

Protect a service from repeated bad behavior with a route-scoped trigger policy that applies temporary IP bans. Automatic bans respond to observed behavior; they do not classify one request as an attack.

The trigger observes only the selected routes. After it fires, the IP ban applies to that client address across Clearplane until it expires or an operator lifts it.

Before you start

  • Publish the service and verify normal requests.
  • Identify which upstream 4xx responses represent repeated bad behavior for this application.
  • Choose a threshold, rolling window, and temporary ban duration.
  • Start with one route and account for clients that may share a public IP address. The resulting ban affects every route for that address.

UI

  1. Open Abuse → Auto-ban policies and create a policy.
  2. Choose Route scope and assign only the service being protected.
  3. Enable Ban on repeated 4xx responses. Leave Counted status codes empty to count every upstream 400–499 response, or enter only the codes that represent bad behavior for this service. Upstream 5xx failures never count. Edge's own 401 counts when a client presents credentials that fail an authentication policy on the route.
  4. Set Responses before ban, Window, and Ban duration. Start with a high threshold and a short ban while observing real traffic.
  5. Leave Ban on repeated rate limit violations off unless an enabled IP-keyed rate limit policy covers the same route.
  6. Enable and save the policy.

Docker labels

Create an inline auto-ban policy on the discovered service:

labels:
  clearplane.proxy.auto-ban: "On"
  clearplane.proxy.auto-ban.rate-limit-violation.enabled: "false"
  clearplane.proxy.auto-ban.error-response.enabled: "true"
  clearplane.proxy.auto-ban.error-response.threshold: "100"
  clearplane.proxy.auto-ban.error-response.window-seconds: "60"
  clearplane.proxy.auto-ban.ban-duration-seconds: "600"

This example bans a client after 100 proxied 4xx responses within 60 seconds and lifts the ban after 600 seconds. Add clearplane.proxy.auto-ban.error-response.status-codes to count only selected 4xx responses. Leave escalation disabled until the initial policy has been observed in normal traffic.

See the proxy directives for accepted values and optional escalation settings.

Verify

Send normal requests and confirm they still reach the application. In a controlled test, reach the configured threshold from one client, confirm the next request receives a ban response, inspect the record under Bans, then confirm traffic resumes after the ban expires or is lifted.