Abuse Guard (nginx IDS)

The Abuse Guard is BOA's application-layer defence for the web tier — the net between the firewall and PHP-FPM that keeps scanners, brute-forcers and distributed search-amplification botnets off the backend. It has two halves that run on different clocks: a wall of real-time Nginx map/geo guards that drop or downgrade a hostile request before it costs anything, and a post-hoc log scorer (scan_nginx.sh) that reads recent access.log lines, scores each real client, and feeds genuine offenders into CSF. The firewall ban then flows back into Nginx so the next request from that IP is closed silently.

The defining property: detection is post-hoc, enforcement is real-time. The scorer cannot block mid-burst — it analyses lines that already happened and produces a ban for the next visit. A scanner firing 75 requests in 20 seconds completes before the next scan tick; those requests are served cheaply (a .php probe gets a no-FPM 404) and the IP is blocked for its next visit, then self-unbanned when CSF drops the entry.

The mechanism spans two codebases. The Nginx-template files live in provision-private under http/Provision/Config/Nginx/; the scorer and the ban-pipeline scripts live in boa-private under aegir/tools/system/ and are deployed on a box under /var/xdrago/.

Component File Role
Real-time guards server.tpl.php (maps) + Inc/vhost_include.tpl.php (rules) Classify and drop/downgrade each request
Log scorer aegir/tools/system/monitor/check/scan_nginx.sh Score IPs from access.log, write web.log
Scorer launcher aegir/tools/system/monitor/check/nginx_guard.sh Run scan_nginx 10× per minute (5 s apart); one bounded pass per minute during a load-pause
Temp-ban applier aegir/tools/system/guest-fire.sh web.log → csf -td 900 (80/443)
Persistent escalator aegir/tools/system/guest-water.sh Archive repeat offenders → csf.deny
Geo regenerator (IPv4) aegir/tools/system/nginx_deny.sh CSF state → nginx_banned_ips.conf → reload
Geo regenerator (IPv6) aegir/tools/system/nginx_deny6.sh nginx-native IPv6 ban store → nginx_banned_ips.conf6 → reload
Ban release tool aegir/tools/bin/clearwebbans One-shot release of all web-IDS bans + the state that would re-apply them
Flood reporter aegir/tools/bin/floodreport Read-only i18n-flood / FPM-saturation activity report

Pages in this topic

  • scan_nginx scoring engine — the post-hoc detector: the run model, real-client resolution, the laundering-proof exemption gate, the five ban detectors (per-IP, shared-UA DDoS, path-flood, HTTP/1.0 auth-spam, UA-burst) and the Tier-B alert-only paths (i18n flood, FPM saturation).
  • The ban pipeline — the three separately-scheduled scripts that carry an offender from a log line through CSF and back into the $is_banned geo: guest-fire.sh, guest-water.sh, nginx_deny.sh.
  • Request guards — the real-time map/geo wall: the 444-vs-404 convention, realip keying, $is_banned, the chain-mutation flood maps, print/TLS/scanner guards, the search-amplification family, the $is_cms_probe foreign-CMS probe drop and the Tier-A anonymous-localized concurrency cap (the boa_i18n_anon zone).
  • Configuration reference — every _NGINX_* knob: real default, override semantics, and the computed weights.
  • Operations + tuning — reading live state, lifting or cycling a ban, whitelisting an IP/path/service, debug output, the self-healing watchdogs, and the maintainer caveats.

Adjacent operating topics

  • Web tier (Nginx) internals — the vhost generator, the config-template set, the master http config and the rate-limit zones that host the map/geo guards documented here.
  • Security & isolation — the CSF/LFD firewall lifecycle that consumes the ban pipeline, the trust hierarchy, and the per-tenant boundary.
  • Self-healing monitor stack — the cron fan-out and watchdog framework that launches scan_nginx, guest-fire, guest-water and nginx_deny.
  • Solr search (operator) — the expensive search backend the path-flood detector and the search-amplification maps protect.
  • Operator troubleshooting & recovery — blocked-IP recovery when a ban is wrong or a flood watchdog has fired.

Reference