[brainstorming] crowdsec bouncer integration ideas

[AnthonyMichaelTDM]

If you're running behind a cloudflare proxy, a firewall-based crowsec bouncer isn't going to be effective since all it sees are the cloudflare ips, zoraxy can extract the real IP from the request headers which is great.

Anyway, I was thinking about ways to integrate a crowdsec bouncer with zoraxy and thought, since https://github.com/fbonalair/traefik-crowdsec-bouncer is apparently just some forwardauth middleware, and zoraxy supports forwardauth, could it be possible to use the traefik crowdsec bouncer with zoraxy?
Is this even possible, or is it not worth playing around with?

I had another idea as well that would work by editing the conf/access/*.json files that the access control profiles are persisted to, but figured that would have too many issues. I've included it below for reference, though:

Describe the solution you'd like

Currently, blocked IPs are persisted in conf/access/*.json files for each access control set, integrating crowdsec directly into zoraxy would be difficult, but an easier route could be creating a separate program that simply updates these files when new "decisions" (i.e. ban this ip, unban this ip, force this ip to solve a captcha, etc.) are added. The problem is, to my knowledge, changing these files won't immediately update zoraxy's internal state.
What could resolve this is either having an endpoint to trigger a reload, or automatically triggering a reload either at some time interval or when file changes are detected (I think having an endpoint is better, personally).

Security-wise, I'm not sure how this script would authenticate with the API, having it authenticate with users admin accounts seems very unwise, and if people don't have the zoraxy dashboard exposed publicly the endpoint could be unauthenticated, but that also seems like a bad assumption to make.
Some other ideas:

• having a separate unauthenticated "management" api on a different port that only listens to internal traffic (runs on localhost)?
  • seams easier, but possibly harder to maintain
• adding some form of scoped token-based authentication that scripts and plugins can use?
  • seems like it'd be more work, but maybe worth it since it could be used for other integrations down the line
    I'm not too sure, honestly.

Describe alternatives you've considered

• some sort of integration with https://github.com/crowdsecurity/go-cs-bouncer, essentially checking if there's a decision whenever someone makes a request. This would likely be done with a plugin, but I'm not sure how far along plugin support is currently.

Anyway, if anyone has any other ideas please leave them down below, I think proper crowdsec integration would be very helpful for a lot of people.

[AnthonyMichaelTDM]

On second thought, I'm going to play around more with using https://github.com/crowdsecurity/go-cs-bouncer to implement a dynamic capture plugin

[AnthonyMichaelTDM]

potential issue(s):

• auth routing happens before plugin routing, so if an IP we want to ban is hitting an endpoint protected by auth, the plugin won't be able to stop them
• if a static route matches the request, it won't even get to this dynamic router, which again allows people to bypass the bouncer
• there's no way to set the "priority" of a plugin, that is, there's no way to ensure that this plugin sees the request before any others … other than just not using any other plugins.
• Ideally, we'd want to waste as few CPU cycles as possible on banned IPs, but there's a lot of logic between "received a request" and "passing it to this specific plugin"

I'm going to keep working on a prototype, but I foresee these being issues in the future

[tobychui]

True, that is kinda the downside of a "no need to recompile the whole binary, just put it into the plugin file and it will works" type of plugins. I can add a "authentication" type plugin in the future if auth plugin is something the community wanted, but for now I think the dynamic routing plugin should be enough for your purpose?

[AnthonyMichaelTDM]

I hope so

[AnthonyMichaelTDM]

@tobychui I'm working on 2 PR's that, together, should resolve these issues.

The first is implementing a way for plugins to register "PermittedAPIEndpoints" and get an API-key that they can use to make requests to the zoraxy API from the permitted endpoints

Second is an implementation of an event system (using the previously unused SubscriptionPath and SubscriptionsEvents), and then implementing the 3 events I think I'll need for the next version of the zoraxy_crowsec_bouncer

Currently wrapping up the first one.

[tobychui]

@AnthonyMichaelTDM Cool! I think the first one should worth its own branch for development. In fact I kinda want to work on a restful API sub system for Zoraxy (for automation and testing), maybe these two features can share the same token db?

For two, thanks for the help and I am looking forward to see your PR!

[AnthonyMichaelTDM]

sorry, didn't see this earlier bc I was writing the PR description...

first one is done, since tokens are ephemeral they're just stored in a map.

For the second, the feature is done but I haven't integrated it into the web ui or created an example plugin yet, it's late so I don't think I'll finish that tonight but I'll open a draft PR

[AnthonyMichaelTDM]

Okay, I haven't tested this at all, and it's my first time programming in Go, but here's my prototype:

https://github.com/AnthonyMichaelTDM/zoraxy_crowdsec_bouncer

[AnthonyMichaelTDM]

Okay, it's mostly working, but I'm having trouble extracting the real ip of the clients (running behind cloudflare)

Currently running this function on the DynamicSniffForwardRequest's but it's still giving me the cloudflare IPs:

https://github.com/AnthonyMichaelTDM/zoraxy_crowdsec_bouncer/blob/924ebcaef466f704207b8c9d19c2f91a682a30f7/main.go#L121-L165

I also wrote a bunch of tests for this function (source), and they all pass, so the only reason I can think of for why it's failing is if the sniff endpoint isn't being given all the headers.
Do you have any advice/insight @tobychui ?

This is what I'm seeing in the logs:

...
[2025-07-16 02:06:31.099312] [plugin-manager] [system:info] [Crowdsec Bouncer Plugin for Zoraxy:7811] Request captured by dynamic sniff path: /d_sniff/
[2025-07-16 02:06:31.195916] [plugin-manager] [system:info] [Crowdsec Bouncer Plugin for Zoraxy:7811] No decision found for IP: 162.158.167.72
[2025-07-16 02:06:31.431462] [router:host-http] [origin:nextcloud.mydomain.com] [client: <my ip address>] [useragent: COOLWSD HTTP Agent 25.04.3.1] GET /apps/richdocuments/settings/fonts.json 200
[2025-07-16 02:06:43.505830] [plugin-manager] [system:info] [Crowdsec Bouncer Plugin for Zoraxy:7811] Request captured by dynamic sniff path: /d_sniff/
[2025-07-16 02:06:43.602797] [plugin-manager] [system:info] [Crowdsec Bouncer Plugin for Zoraxy:7811] No decision found for IP: 172.69.134.212
[2025-07-16 02:06:43.749389] [router:host-http] [origin:nextcloud.mydomain.com] [client: <my ip address>] [useragent: Mozilla/5.0 (X11; Linux x86_64; rv:140.0) Gecko/20100101 Firefox/140.0] POST /apps/notify_push/pre_auth 200
...

note that 162.158.167.72 and 172.69.134.212 are both cloudflare ips

[AnthonyMichaelTDM]

I fixed it by reading from dsfr.Header instead of dsfr.GetRequest().Header. Not sure why, but it seems that the rawRequest field isn't being set properly or something

[AnthonyMichaelTDM]

Update, after a decent bit of testing and tweaking things, https://github.com/AnthonyMichaelTDM/zoraxy_crowdsec_bouncer/tree/main is now functional.

There are some caveats thought:

• It currently only supports ban decisions, no captchas
• It is a LiveBouncer, meaning it calls your local crowdsec api on every request. I do plan on changing this, but no ETA.
• Since auth provider routing happens before plugin routing, it won't be able to stop banned IPs from hitting your auth provider
  • This is a pretty big problem if you're using BasicAuth. However it might be fine if your auth service is itself proxied behind zoraxy and protected by the plugin, I haven't tested this, so I'm not sure.
• Since static capture plugins have priority over dynamic capture plugins, this won't protect endpoints that an enabled static capture plugin would control
• Since only one plugin can accept a given request, this plugin might get bypassed if another plugin would accept a given request
• It introduces latency. I haven't tested how bad it is, but something like this will inevitably introduce latency to every request made to your server.
• It is my first golang project. I trust myself, but you might not.

see: #738 (comment)

But, other than that, it is functional!