A lightweight Stream Processing Offload Agent (SPOA) that contacts the CrowdSec Local API to fetch decisions in real time while aiming to be highly performant and minimize latency for clients. It manages an in-memory cache of bans and captchas, and directs HAProxy on how to treat each connection without blocking the data path.

• Real-time enforcement – Streams decisions from CrowdSec via the Go bouncer SDK so ban/captcha/allow changes are visible within seconds.
• HTTP and TCP coverage – Supports early IP checks via crowdsec-tcp and HTTP inspection via crowdsec-http-body / crowdsec-http-no-body to protect both web frontends and raw TCP services.
• Host-aware responses – Each host entry can customize ban pages, captcha providers, and logging while sharing the same SPOA worker.
• Captcha challenges built in – hCaptcha, reCAPTCHA, and Cloudflare Turnstile are supported with signed, stateless cookies so solved challenges can be verified without round-tripping to the provider.
• Memory-efficient dataset – IPs live in a lock-free map and CIDRs are stored in a BART radix tree, which keeps lookups in the tens of nanoseconds.
• Optional GeoIP tagging – Plug in MaxMind ASN/City databases to enrich decisions with ISO country codes for templating or ACLs.
• Operational visibility – Structured logging, Prometheus counters, and an optional pprof endpoint make it easy to monitor and debug the bouncer.
• Optional AppSec validation – When enabled, forwards HTTP request data to CrowdSec AppSec and can escalate a request to a ban.

The bouncer is a single binary with three key loops:

1. go-cs-bouncer maintains a long-lived stream to the CrowdSec Local API and feeds new/deleted decisions into the dataset (pkg/dataset).
2. The SPOA worker (pkg/spoa) listens on TCP and/or Unix sockets, answers HAProxy messages, and applies host-specific logic such as captchas or ban pages.
3. Auxiliary services (optional) expose Prometheus metrics and pprof diagnostics.

More detailed request/decision flow diagrams are in ARCHITECTURE.md.

1sequenceDiagram
2    participant Client
3    participant HAProxy
4    participant SPOA as SPOA bouncer
5    participant Backend
6
7    Note over Client,HAProxy: Client connects
8    Client->>HAProxy: Connect (TCP)
9
10    Note over HAProxy,SPOA: Early decision (session-level)
11    HAProxy->>SPOA: SPOE: crowdsec-tcp
12    SPOA-->>HAProxy: Set txn.crowdsec.* (remediation baseline)
13
14    Note over Client,HAProxy: HTTP request (per request)
15    Client->>HAProxy: HTTP request
16    alt body not sent
17        HAProxy->>SPOA: SPOE group: crowdsec-http-no-body
18    else body sent (required for captcha POST)
19        HAProxy->>SPOA: SPOE group: crowdsec-http-body
20    end
21    SPOA-->>HAProxy: Set txn.crowdsec.* (final remediation + metadata)
22
23    alt remediation = allow
24        HAProxy->>Backend: Forward request
25        Backend-->>Client: Response
26    else remediation = captcha or ban
27        HAProxy->>HAProxy: Render response page with HAProxy lf-file
28        HAProxy-->>Client: Response
29    end

The official documentation covers packaging and upgrade notes. If you want to manually build, see the build section below. A quick happy path:

1. Install the package (Debian/RPM), use the provided Docker image, or build locally with make build.
2. Copy config/crowdsec-spoa-bouncer.yaml to /etc/crowdsec/bouncers/ and set your CrowdSec LAPI URL and API key.
3. Wire the SPOE filter into HAProxy (see below) and copy the HTML templates from templates/ to the path used by HAProxy.
4. Start the service with systemctl start crowdsec-haproxy-spoa-bouncer or run ./crowdsec-spoa-bouncer -c /path/to/config.yaml for local tests.

Configuration is YAML. Start from the example in config/crowdsec-spoa-bouncer.yaml and override locally with .yaml.local.

The bouncer supports:

• LAPI decision streaming and an in-memory dataset
• TCP and/or Unix socket listeners for HAProxy SPOE
• Optional per-host policy (ban page templating, captcha providers, logging)
• Optional GeoIP enrichment, Prometheus metrics, pprof, and AppSec validation

Detailed configuration guides:

• Hosts and match priority: pkg/host/README.md
• Captcha providers and configuration: pkg/captcha/README.md
• Ban page templating values: internal/remediation/ban/README.md
• Architecture and request flow: ARCHITECTURE.md

Add the SPOE filter and native HAProxy remediation returns to your frontend. This is the default path and does not require HAProxy Lua support. The config files in config/ show complete examples; the snippet below highlights the essentials:

1frontend www
2    bind :80
3    unique-id-format %[uuid()]
4    unique-id-header X-Unique-ID
5    filter spoe engine crowdsec config /etc/haproxy/crowdsec.cfg
6
7    acl body_within_limit req.body_size -m int le 51200
8    http-request send-spoe-group crowdsec crowdsec-http-body if body_within_limit || !{ req.body_size -m found }
9    http-request send-spoe-group crowdsec crowdsec-http-no-body if !body_within_limit { req.body_size -m found }
10
11    http-request redirect code 302 location %[url] if { var(txn.crowdsec.remediation) -m str "allow" } { var(txn.crowdsec.redirect) -m found }
12    acl render_html req.hdr_cnt(Accept) eq 0
13    acl render_html req.hdr(Accept) -m sub text/html
14    acl render_html req.hdr(Accept) -m sub */*
15    acl html_rejected req.hdr(Accept) -m reg -i "text/html[[:space:]]*;[[:space:]]*q=0(\.0+)?([,[:space:]]|$)"
16
17    acl has_contact_url var(txn.crowdsec.contact_us_url) -m found
18    acl empty_contact_url var(txn.crowdsec.contact_us_url) -m str ""
19
20    http-request return status 200 content-type "text/html; charset=utf-8" hdr Cache-Control "no-cache, no-store" lf-file /var/lib/crowdsec-haproxy-spoa-bouncer/html/captcha.html if { var(txn.crowdsec.remediation) -m str "captcha" } render_html !html_rejected
21    http-request return status 403 content-type "text/html; charset=utf-8" hdr Cache-Control "no-cache, no-store" lf-file /var/lib/crowdsec-haproxy-spoa-bouncer/html/ban-with-contact.html if { var(txn.crowdsec.remediation) -m str "ban" } render_html !html_rejected has_contact_url !empty_contact_url
22    http-request return status 403 content-type "text/html; charset=utf-8" hdr Cache-Control "no-cache, no-store" lf-file /var/lib/crowdsec-haproxy-spoa-bouncer/html/ban.html if { var(txn.crowdsec.remediation) -m str "ban" } render_html !html_rejected !has_contact_url
23    http-request return status 403 content-type "text/html; charset=utf-8" hdr Cache-Control "no-cache, no-store" lf-file /var/lib/crowdsec-haproxy-spoa-bouncer/html/ban.html if { var(txn.crowdsec.remediation) -m str "ban" } render_html !html_rejected empty_contact_url
24    http-request return status 200 content-type text/plain hdr Cache-Control "no-cache, no-store" string "Captcha required\n" if { var(txn.crowdsec.remediation) -m str "captcha" } !render_html
25    http-request return status 200 content-type text/plain hdr Cache-Control "no-cache, no-store" string "Captcha required\n" if { var(txn.crowdsec.remediation) -m str "captcha" } html_rejected
26    http-request return status 403 content-type text/plain hdr Cache-Control "no-cache, no-store" string "Forbidden\n" if { var(txn.crowdsec.remediation) -m str "ban" } !render_html
27    http-request return status 403 content-type text/plain hdr Cache-Control "no-cache, no-store" string "Forbidden\n" if { var(txn.crowdsec.remediation) -m str "ban" } html_rejected
28
29    http-after-response set-header Set-Cookie %[var(txn.crowdsec.captcha_cookie)] if { var(txn.crowdsec.captcha_status) -m found } { var(txn.crowdsec.captcha_cookie) -m found }
30    http-after-response set-header Set-Cookie %[var(txn.crowdsec.captcha_cookie)] if { var(txn.crowdsec.captcha_cookie) -m found } !{ var(txn.crowdsec.captcha_status) -m found }
31
32    default_backend app

Use a dedicated SPOE section (crowdsec.cfg) to declare the messages HAProxy sends and which request variables are exported. The provided sample uses:

• crowdsec-tcp (event on-client-session) for early, connection-level IP decisions
• crowdsec-http-body / crowdsec-http-no-body (sent via SPOE groups with the same names) for per-request HTTP inspection, with conditional body forwarding

Important: captcha validation needs the request body (form-encoded POST). Ensure your frontend sends captcha submissions via the crowdsec-http-body group (see http-request send-spoe-group ... crowdsec-http-body in the examples).

For complete, working examples (including optional request-body forwarding, captcha redirects, and cookie management), see config/haproxy.cfg and config/crowdsec.cfg.

The package still ships the legacy Lua handler for users who prefer rendering remediation pages through HAProxy Lua. To enable it, use a HAProxy build with Lua support and start from these examples instead of the default no-Lua config:

• config/haproxy-lua.cfg
• config/haproxy-upstreamproxy-lua.cfg

The Lua examples load helpers from /usr/lib/crowdsec-haproxy-spoa-bouncer/lua/ and use Lua-compatible templates from /var/lib/crowdsec-haproxy-spoa-bouncer/html/lua/. The default config/haproxy.cfg remains the simpler plain-HAProxy path.

Docker + Lua mode: the default docker-compose.yaml omits the lua: shared volume because the standard path does not need it. When switching to haproxy-lua.cfg, uncomment the lua: volume entries in docker-compose.yaml (see inline comments) so the HAProxy container can access the Lua scripts from the bouncer image.

Template paths (non-Lua path): the lf-file directives in haproxy.cfg hard-code /var/lib/crowdsec-haproxy-spoa-bouncer/html/. If you need custom template locations, edit those lf-file paths directly. Note that HAProxy does not validate lf-file paths at startup; a missing file produces a runtime error on the first blocked request rather than a startup failure.

• Prometheus metrics – Enable the metrics endpoint to scrape bouncer and decision counters.
• Logging – File or stdout logging is configurable; per-host log levels help when debugging only a subset of domains.
• Profiling – Switch on pprof in non-production environments to inspect CPU, heap, or goroutines via standard Go tooling.
• Dataset inspection – Use log_level: trace to watch BART operations and confirm that lists/ranges are loaded as expected.

Everything you need for local development is included in the repository:

1git clone https://github.com/crowdsecurity/cs-haproxy-spoa-bouncer.git
2cd cs-haproxy-spoa-bouncer
3make build    # builds the binary in ./crowdsec-spoa-bouncer
4make test     # runs Go tests

Docker Compose files under docker/ and docker-compose*.yaml spin up HAProxy, the bouncer, and a CrowdSec LAPI for integration testing.

• AppSec validation is available for HTTP flows when configured; feedback on coverage and performance is welcome.
• Performance optimizations (batching, decision compression) continue so high-volume HAProxy tiers can rely on a single SPOA worker.

Contributions are welcome—feel free to open an issue or PR:

1. Fork the repo and create a topic branch (git checkout -b feature/my-change).
2. Run make test (and any relevant integration checks) before submitting.
3. Open a PR with context about the problem you solved or the feature you added.

MIT – see LICENSE for the full text.

• HAProxy for the SPOE protocol and native response templating.
• BART for the radix tree implementation that backs range lookups.