TheFloatingLab/SearxNG-Captcha
TheFloatingLab/SearxNG-Captcha
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Added some links in the readme file

Browse source
This commit is contained in:
Frans Veldman 2026-06-12 12:56:00 +00:00
commit b64f38d52a
1 changed files with 7 additions and 7 deletions
Download patch file Download diff file Expand all files Collapse all files

14
README.md
View file

@ -12,8 +12,8 @@ By combining the captcha system with a cookie, only once in 90 days the user has
- No modification of the SearxNG code is necessary, the captcha system runs entirely within Nginx. - No modification of the SearxNG code is necessary, the captcha system runs entirely within Nginx.
- The captcha, once solved, stays valid for 90 days. - The captcha, once solved, stays valid for 90 days.
- No puzzles to solve, just a confirmation click. - No puzzles to solve, just a confirmation click.
- It is possible and encouraged to self host the captcha system, so no information leaks to the outside world. - It is recommended to [self host the open source captcha system](https://github.com/tiagozip/cap), so no information leaks to the outside world.
- The privacy and security of SearxNG are maintained if a self hosted captcha system is used. - The privacy and security of SearxNG are fully maintained if this self hosted captcha system is used.
- Optional automatic reporting to [AbuseIPDB](https://www.abuseipdb.com). - Optional automatic reporting to [AbuseIPDB](https://www.abuseipdb.com).
- Optionally, Cloudflare Turnstile can be used as captcha provider instead. - Optionally, Cloudflare Turnstile can be used as captcha provider instead.
- Everything is script based, no compilation is necessary. - Everything is script based, no compilation is necessary.
@ -28,14 +28,14 @@ I have not made an attempt to add subdirectories to this git, so you have to dow
## Prerequisites ## Prerequisites
- Nginx is used for the reverse proxying - Nginx is used for the reverse proxying
- Lua and some dependencies needs to be installed (apt install lua) - Lua and some dependencies needs to be installed (apt install lua)
- It is recommended to self host the captcha engine, see: [github.com/tiagozip/cap](https://github.com/tiagozip/cap). - It is recommended to self host the open source captcha engine, see: [github.com/tiagozip/cap](https://github.com/tiagozip/cap).
- A site/secret key set and URL/API-key for the captcha engine. - A site/secret key set and URL/API-key for the captcha engine.
- Optionally, an API key for [AbuseIPDB](https://www.abuseipdb.com). - Optionally, an API key for [AbuseIPDB](https://www.abuseipdb.com).
## 00-captcha-init.conf ## 00-captcha-init.conf
*This file resides on my system in "/etc/nginx/conf.d".* *This file resides on my system in "/etc/nginx/conf.d".*
It configures lua and also creates an extended log format. This log format is optional but it allows you to see in the log file whether someone got passed the captcha. Most bots will not progress beyond the "challenge" state. It configures lua and also creates an extended log format. This log format is optional but it allows you to see in the log file whether someone got passed the captcha. Bots will rarely progress beyond the "challenge" state, if at all.
## captcha.env ## captcha.env
*This file is in my /etc/nginx directory.* *This file is in my /etc/nginx directory.*
@ -101,15 +101,15 @@ Most bots search by using "/?q=" but some also from "/searxng/?q=". So both loca
# Things worth knowing # Things worth knowing
- Single-use tokens + your 90-day cookie. Both providers issue tokens that are good for one verify call, after which your cookie carries the user. The cookie is provider-agnostic, so an existing __ts_verified cookie continues to work after you switch providers — if the same COOKIE_SECRET is still in the env file. Rotating that secret invalidates all passes regardless of who issued them. - Single-use tokens + your 90-day cookie. Both providers issue tokens that are good for one verify call, after which your cookie carries the user. The cookie is provider-agnostic, so an existing __ts_verified cookie continues to work after you switch providers — if the same COOKIE_SECRET is still in the env file. Rotating that secret invalidates all passes regardless of who issued them.
- I'm not affiliated in any way with the CAP self hosted captcha provider, but it looks like a sound project to me. You can fall back on Cloudflare Turnstile if you have more confidence in them, but beware that they do some logging and analysis which partly defeats the purpose of SearxNG.
## Logging ## Logging
- You will not see everything in your logs! Bots are immediately redirected to the captcha system, before an entry in the nginx log is made. Many bots are not even capable of properly interfacing with this redirection and simply never make it to the captcha, and vanish without leaving a trail. - You will not see everything in your logs! Bots are immediately redirected to the captcha system, before an entry in the nginx log is made. Many bots are not even capable of properly interfacing with this redirection and simply never make it to the captcha, and vanish without leaving a trail.
- You will see a sharp decline in bots. This is not a malfunction but the intention. Some bots learn quickly, and getting listed in AbuseIPDB doesn't encourage them. It looks like they are coded to detect reporting, or some bot owners might receive automated notifications if they get listed, but one way or the other, they avoid sites that put and keep them on public blacklists. - You will see a sharp decline in bots. This is not a malfunction but the intention. Some bots learn quickly, and getting listed in AbuseIPDB doesn't encourage them. It looks like they are coded to detect reporting, or some bot owners might receive automated notifications if they get listed, but one way or the other, they avoid sites that put and keep them on public blacklists.
## Self hosted CAP ## Self hosted CAP captcha provider
- I'm not affiliated in any way with this [CAP self hosted captcha provider](https://github.com/tiagozip/cap), but it looks like a sound project to me. You can fall back on Cloudflare Turnstile if you have more confidence in them, but beware that Cloudflare does some logging and analysis which partly defeats the purpose of SearxNG.
- Token format / field name. Cap auto-injects a hidden cap-token field on solve (default name), and the widget docs note tokens are single-use — so don't be alarmed if reloading the verify endpoint with a stale POST body fails. - Token format / field name. Cap auto-injects a hidden cap-token field on solve (default name), and the widget docs note tokens are single-use — so don't be alarmed if reloading the verify endpoint with a stale POST body fails.
- Server-to-server reachability. The verify endpoint runs in your Nginx workers, which now make an outbound HTTPS call to your self hosted captcha provider. If you've firewalled outbound or are running both Nginx and Cap on the same host, you may save a hop by setting CAP_API_URL=http://127.0.0.1:3000 (Cap's default port). The parse_url helper handles plain http:// automatically — no TLS handshake performed in that case. The widget still needs the public URL though, so you'd typically keep the public HTTPS URL for the widget and only flip to localhost for verification by setting them separately. If you want that split, easiest is to add a fourth env var like CAP_VERIFY_URL that defaults to CAP_API_URL — I leave it as an exercise to the reader. - Server-to-server reachability. The verify endpoint runs in your Nginx workers, which now make an outbound HTTPS call to your self hosted captcha provider. If you've firewalled outbound or are running both Nginx and Cap on the same host, you may save a hop by setting CAP_API_URL=http://127.0.0.1:3000 (Cap's default port). The parse_url helper handles plain http:// automatically — no TLS handshake performed in that case. The widget still needs the public URL though, so you'd typically keep the public HTTPS URL for the widget and only flip to localhost for verification by setting them separately. If you want that split, easiest is to add an additional env var like CAP_VERIFY_URL that defaults to CAP_API_URL — I leave it as an exercise to the reader.
- TLS trust. The same lua_ssl_trusted_certificate directive that lets us reach Cloudflare also covers your Cap instance, assuming it's using a publicly-trusted cert (Let's Encrypt etc.). If Cap is on a private CA, point that directive at a bundle that includes your CA. - TLS trust. The same lua_ssl_trusted_certificate directive that lets us reach Cloudflare also covers your Cap instance, assuming it's using a publicly-trusted cert (Let's Encrypt etc.). If Cap is on a private CA, point that directive at a bundle that includes your CA.
- Falling back to Turnstile. Comment out or delete the CAP_SITE_KEY line in /etc/nginx/captcha.env and restart. Provider auto-flips back to Turnstile. - Falling back to Turnstile. Comment out or delete the CAP_SITE_KEY line in /etc/nginx/captcha.env and restart. Provider auto-flips back to Turnstile.
- CSP, if you have one. Cap loads its widget script from cdn.jsdelivr.net and its WASM from the same CDN by default. If you've added a strict CSP, you'll need script-src 'self' cdn.jsdelivr.net 'wasm-unsafe-eval'. For pinning to a specific version, replace cap-widget in the script src with cap-widget@<version> — check the latest release on the project's GitHub. - CSP, if you have one. Cap loads its widget script from cdn.jsdelivr.net and its WASM from the same CDN by default. If you've added a strict CSP, you'll need script-src 'self' cdn.jsdelivr.net 'wasm-unsafe-eval'. For pinning to a specific version, replace cap-widget in the script src with cap-widget@<version> — check the latest release on the project's GitHub.