Does it slow requests down?

A new visitor waits for one check, at most 1.5 seconds, and passes if it takes longer. Repeat requests within 10 minutes are answered from the gate's memory.

Does it work with Nginx Proxy Manager?

Yes. Put the gate on NPM's Docker network and paste the snippet into the proxy host's Advanced tab.

What if the gate container is down?

The nginx and NPM snippets let requests through after the 1 second connect timeout, HAProxy sends them straight to your app, and Apache does after one failed request. Traefik and Caddy answer with an error, so run the gate with restart: unless-stopped.

Which IP address does it check?

The visitor's address from X-Forwarded-For, but only when the request comes from a trusted proxy (private ranges by default). From anyone else it uses the connecting address.

Can it block a country?

Not from the policy, which works per traffic class. The gate passes the visitor's country to your app as X-IPScanner-Country, so your app can act on it.

Can it block an IP range?

For a fixed range, nginx's own deny directive is simpler. The gate covers the addresses that keep moving: VPN servers, Tor exits, proxies and hosting networks.

What does the free plan include?

30,000 requests a month, up to 1,000 a day. Each new visitor check uses 2. On Free, a site managed from the dashboard runs in monitor mode; blocking starts on Starter.

IPScanner

Products

IP DetectionVPN, proxy, Tor and hosting checks on any IP AgentscanTell humans, bots and AI agents apart ProvenanceLocation checks with a tamper-evident audit log

Integrations

Cloudflare Worker WordPress plugin Traefik plugin Caddy module nginx, Apache, HAProxy Form gate MCP server All integrations

Detection servicesVPN Detection Proxy Detection Geolocation ASN Data WHOIS Info

Forward auth for your server

Block bots, VPNs and Tor in nginx, Apache and HAProxy

One container next to your server checks every request for bots, Tor, VPNs and proxies. It starts in monitor mode and blocks nothing until you switch.

View on GitHub Read the setup guide

Free, MIT licenseDocker, amd64 and arm64

Enforce

Traffic classes

What it can block

Each class reaches your app as X-IPScanner-Class. Allow, flag or block it per site in the dashboard.

Malicious automation
malicious_automation
Automation with no good identity. Headless tells, a masked origin, or both.
AI agent
ai_agent
Automation that names itself, or an AI fetcher. Not hostile, but not a person either.
Tor
tor
A Tor exit node. Origin is deliberately unknowable.
VPN
vpn
A commercial VPN exit. The true origin is hidden.
Proxy
proxy
Traffic relayed through a proxy, often someone else's home connection.
Hosting
hosting
A hosting provider network.
Private relay
relay
An Apple or Cloudflare privacy relay. The real IP is hidden, the region is kept.
Verified bot
verified_bot
A crawler whose identity was proven against what its operator publishes. Always passes.
Human
human
A person in a real browser. A human on a VPN is still a human, so origin alone never convicts.

Setup

Live in four steps

1
Create an API key
The free plan is enough to start.
IPSCANNER_API_KEY
pk_live_••••••••3f9a
Create a free API key

Run the container

On the same Docker network as your proxy. Do not publish its port.

docker-compose.yml

services:
  ipscanner:
    image: ghcr.io/ipscanner/forward-auth:0.1
    restart: unless-stopped
    environment:
      IPSCANNER_API_KEY: ${IPSCANNER_API_KEY}
      SITE_ID: site_...

3
Add a site and set SITE_ID
The dashboard then holds the site's policy and shows its traffic.
SITE_ID
site_4fQ8nZ2kLm7xR1vT9cBw
Add a site
4
Add the snippet to your server
Pick your server below. Each snippet is tested end to end.

Server config

Snippets for your server

Copy the one for your setup. Traefik and Caddy also work through the same container.

Goes in your server block. Start the gate first: nginx resolves ipscanner at startup.

Gate down: requests pass after 1 s

nginx.conf

location / {
    auth_request /_ipscanner;
    auth_request_set $ipscanner_status     $upstream_http_x_ipscanner_status;
    auth_request_set $ipscanner_class      $upstream_http_x_ipscanner_class;
    auth_request_set $ipscanner_action     $upstream_http_x_ipscanner_action;
    auth_request_set $ipscanner_network    $upstream_http_x_ipscanner_network_class;
    auth_request_set $ipscanner_anonymized $upstream_http_x_ipscanner_anonymized;
    auth_request_set $ipscanner_risk       $upstream_http_x_ipscanner_risk;
    auth_request_set $ipscanner_country    $upstream_http_x_ipscanner_country;
    auth_request_set $ipscanner_site       $upstream_http_x_ipscanner_site;
    auth_request_set $ipscanner_request_id $upstream_http_x_ipscanner_request_id;
    error_page 403 = @ipscanner_blocked;

    proxy_set_header X-IPScanner-Status        $ipscanner_status;
    proxy_set_header X-IPScanner-Class         $ipscanner_class;
    proxy_set_header X-IPScanner-Action        $ipscanner_action;
    proxy_set_header X-IPScanner-Network-Class $ipscanner_network;
    proxy_set_header X-IPScanner-Anonymized    $ipscanner_anonymized;
    proxy_set_header X-IPScanner-Risk          $ipscanner_risk;
    proxy_set_header X-IPScanner-Country       $ipscanner_country;
    proxy_set_header X-IPScanner-Site          $ipscanner_site;
    proxy_set_header Host                      $host;
    proxy_set_header X-Forwarded-For           $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto         $scheme;
    proxy_pass http://app:80;
}

location = /_ipscanner {
    internal;
    proxy_pass http://ipscanner:8080/check;
    proxy_pass_request_body off;
    proxy_set_header Content-Length "";
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Original-URI $request_uri;
    proxy_set_header X-Original-Method $request_method;
    proxy_connect_timeout 1s;
    proxy_read_timeout 5s;
    error_page 500 502 503 504 = @ipscanner_down;
}

location @ipscanner_down {
    return 204;
}

location @ipscanner_blocked {
    internal;
    proxy_method GET;
    proxy_pass_request_body off;
    proxy_set_header Content-Length "";
    proxy_set_header X-IPScanner-Request-Id $ipscanner_request_id;
    rewrite ^ /blocked break;
    proxy_pass http://ipscanner:8080;
}

Settings

Environment variables

Set them on the container. CACHE_TTL and POLICY_TTL also take values like 10m.

Container

A small image with a health check

GET /healthz always answers 200 and shows what the gate is doing.

Verified search and AI crawlers always pass.
If IPScanner is slow or down, requests go through.
Your API key never shows up in the logs.

GET /healthz

{
  "status": "ok",
  "version": "0.1.0",
  "mode": "forward_auth",
  "enabled": true,
  "site": "site_4fQ8nZ2kLm7xR1vT9cBw",
  "backoff": false,
  "policyMode": "monitor",
  "policyVersion": 3,
  "cachedVerdicts": 128
}

ghcr.io/ipscanner/forward-auth:0.1

linux/amd64
linux/arm64
Under 4 MB
Non-root, no shell

Questions

nginx, Apache and HAProxy FAQ

No. It is a per-request check of the visitor's IP and automation signals, not a rule-based WAF that inspects payloads for SQL injection or XSS. If you need one, keep your WAF next to it.

Start in monitor mode

Run the gate, read a week of decisions, then block.

Create a free API key Add a site

Variable	Default	What it does
`IPSCANNER_API_KEY`Your API key. Without it every request passesDefault:Empty	Empty	Your API key. Without it every request passes
`IPSCANNER_API_KEY_FILE`Reads the key from a file, for Docker secretsDefault:Empty	Empty	Reads the key from a file, for Docker secrets
`SITE_ID`Links the gate to a dashboard site and its policyDefault:Empty	Empty	Links the gate to a dashboard site and its policy
`MODE`monitor or enforce. With `SITE_ID`, the dashboard decides unless this is monitorDefault:monitor	monitor	monitor or enforce. With `SITE_ID`, the dashboard decides unless this is monitor
`BLOCK_CLASSES`Classes blocked in enforce mode when there is no `SITE_ID`Default:malicious_automation	malicious_automation	Classes blocked in enforce mode when there is no `SITE_ID`
`TRUSTED_PROXIES`Proxies whose `X-Forwarded-For` is believedDefault:private	private	Proxies whose `X-Forwarded-For` is believed
`IP_HEADERS`Headers read for the visitor IP, in orderDefault:X-Forwarded-For	X-Forwarded-For	Headers read for the visitor IP, in order
`TIMEOUT_MS`Budget per check, then the request passesDefault:1500	1500	Budget per check, then the request passes
`CACHE_TTL`Seconds a verdict is reused per visitorDefault:600	600	Seconds a verdict is reused per visitor
`CACHE_SIZE`Verdicts kept in memoryDefault:10000	10000	Verdicts kept in memory
`POLICY_TTL`Seconds a site policy is reusedDefault:30	30	Seconds a site policy is reused
`SKIP_PATHS`Path regex that skips the checkDefault:Static assets	Static assets	Path regex that skips the check
`UPSTREAM_URL`Turns on proxy mode and forwards allowed requests hereDefault:Empty	Empty	Turns on proxy mode and forwards allowed requests here
`LISTEN`Listen addressDefault::8080	:8080	Listen address
`HEALTH_PATH`Health endpointDefault:/healthz	/healthz	Health endpoint
`BLOCK_MESSAGE`Text of the 403 pageDefault:Blocked by IPScanner edge guard.	Blocked by IPScanner edge guard.	Text of the 403 page
`IPSCANNER_API_URL`API base URLDefault:https://ipscanner.io	https://ipscanner.io	API base URL
`DEBUG`Logs one line per decisionDefault:false	false	Logs one line per decision

Block bots, VPNs and Tor in nginx, Apache and HAProxy

What it can block

Malicious automation

AI agent

Tor

VPN

Proxy

Hosting

Private relay

Verified bot

Human

Live in four steps

Create an API key

Run the container

Add a site and set SITE_ID

Add the snippet to your server

Snippets for your server

Environment variables

A small image with a health check

nginx, Apache and HAProxy FAQ

Start in monitor mode

Add a site and set `SITE_ID`