What does it send to IPScanner?

The visitor's IP address, user agent, method and path, a few request headers such as Accept-Language and Sec-CH-UA, and your Site ID. Never cookies or request bodies.

Does it work with Coolify and Dokploy?

Yes. Both run Traefik with Docker labels: declare the plugin in the proxy's configuration, then add the middleware labels to your app.

Does it only work with Docker?

No. Traefik reads the middleware from Docker labels, Kubernetes resources or a YAML file, and the plugin works the same with each.

How is it different from the CrowdSec bouncer or a geoblock plugin?

A geoblock plugin blocks by country, and the CrowdSec bouncer blocks IPs flagged in your logs or on shared blocklists. This plugin gives every visitor a class (Tor, VPN, proxy, hosting, automation) and you set the action per class.

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

Traefik plugin

Traefik plugin that blocks bots and VPNs

Bots, Tor, VPNs and proxies, checked per router with one label. It starts in monitor mode and blocks nothing until you switch.

Read the setup guide View on GitHub

Free, MIT licenseTested with Traefik v3.7

HTTP routers/app@dockerEnforce

84.128.0.1GET /

Entrypoint

websecure:443

Router

app@dockerHost(`example.com`)

Middlewares

gzip@dockeripscanner@dockerHumanAllow

Service

app@docker200X-IPScanner-Class: humanX-IPScanner-Action: allow

Access log

20084.128.0.1GET /Human
403185.220.101.1GET /Tor

Traffic classes

What it checks

Each visitor gets one class. Your service receives it as X-IPScanner-Class.

Humanhuman
Verified botverified_bot
VPNvpn
Private relayrelay
Hostinghosting
Proxyproxy
Tortor
AI agentai_agent
Malicious automationmalicious_automation

Setup

Four steps, monitor mode first

1
Create an API key
Put it in the Traefik container's environment. Every ipscanner middleware reads it.
Create a free API key
docker-compose.yml
```
environment:
  IPSCANNER_API_KEY: pk_live_...
```

Declare the plugin

In the static configuration, or as two CLI flags. Restart Traefik.

traefik.yml

experimental:
  plugins:
    ipscanner:
      moduleName: github.com/ipscanner/ipscanner-traefik
      version: v0.1.0

3
Add a site and set siteId
Mode and policy then come from the dashboard, without a reload.
Add a site in the dashboard
labels
```
traefik.http.middlewares.ipscanner.plugin.ipscanner.siteId=site_...
```
4
Attach it to a router
Other routers reuse it as ipscanner@docker.
labels
```
traefik.http.routers.app.middlewares=ipscanner
```

Your stack

Coolify, Compose or Kubernetes

Same plugin, wherever Traefik reads its config.

Servers › your server › Proxy

command:
  # ...the flags Coolify set
  - '--experimental.plugins.ipscanner.modulename=github.com/ipscanner/ipscanner-traefik'
  - '--experimental.plugins.ipscanner.version=v0.1.0'
environment:
  - IPSCANNER_API_KEY=pk_live_...

Your app › Configuration › Container Labels

traefik.http.middlewares.ipscanner-myapp.plugin.ipscanner.siteId=site_...
traefik.http.routers.https-0-<uuid>.middlewares=gzip,ipscanner-myapp

One middleware name per app, appended to each router Coolify generated. Behind Cloudflare, also set trustedProxies=cloudflare and ipHeaders=CF-Connecting-IP.

docker-compose.yml

services:
  traefik:
    image: traefik:v3.7
    command:
      - --providers.docker=true
      - --entrypoints.web.address=:80
      - --experimental.plugins.ipscanner.modulename=github.com/ipscanner/ipscanner-traefik
      - --experimental.plugins.ipscanner.version=v0.1.0
    environment:
      IPSCANNER_API_KEY: ${IPSCANNER_API_KEY}
    ports: ["80:80"]
    volumes: ["/var/run/docker.sock:/var/run/docker.sock:ro"]

  app:
    image: traefik/whoami:v1.11.0
    labels:
      - traefik.enable=true
      - traefik.http.routers.app.rule=Host(`example.com`)
      - traefik.http.routers.app.middlewares=ipscanner
      - traefik.http.middlewares.ipscanner.plugin.ipscanner.siteId=site_...

Dokploy and plain Compose read the same labels.

middleware.yml

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: ipscanner
spec:
  plugin:
    ipscanner:
      apiKey: urn:k8s:secret:ipscanner:apiKey
      siteId: site_...

Reference it from an IngressRoute or with the router.middlewares annotation on an Ingress.

dynamic.yml

http:
  middlewares:
    ipscanner:
      plugin:
        ipscanner:
          apiKeyFile: /run/secrets/ipscanner_api_key
          siteId: site_...

The key comes from a mounted Docker or Kubernetes secret.

Sites dashboard

Change the policy without touching Traefik

Allow, flag or block each class from the dashboard. The middleware picks up a change within 30 seconds.

Verified search and AI crawlers always pass.
Monitor mode blocks nothing and shows what it would have blocked.
If IPScanner does not answer within 1.5 seconds, the request goes through.

example.comTraefik pluginMonitorEnforce

Policy

HumanAllow
Verified botAllow
VPNFlag
TorBlock
AI agentFlag
Malicious automationBlock

185.220.101.1TorWould block

Options

Middleware options

Set them on the middleware: as labels, in YAML or on the CRD.

Option	Default	What it does
`siteId`Your dashboard site; mode and policy come from it	Empty	Your dashboard site; mode and policy come from it
`mode`monitor or enforce, when there is no `siteId`	monitor	monitor or enforce, when there is no `siteId`
`blockClasses`Classes blocked in enforce mode without `siteId`	malicious_automation	Classes blocked in enforce mode without `siteId`
`trustedProxies`Proxies whose IP headers are trusted: CIDRs, private, cloudflare	Empty	Proxies whose IP headers are trusted: CIDRs, private, cloudflare
`ipHeaders`Headers read from a trusted proxy, in order	X-Forwarded-For	Headers read from a trusted proxy, in order
`timeout`Budget for one check, then the request passes	1500ms	Budget for one check, then the request passes
`cacheTTL`Verdict cache per visitor	10m	Verdict cache per visitor
`cacheSize`Visitors kept in the cache	10000	Visitors kept in the cache
`policyTTL`How long a fetched policy stays fresh	30s	How long a fetched policy stays fresh
`skipPaths`Path regex that skips the check	Static assets	Path regex that skips the check
`apiKeyFile`File holding the API key, for secrets	Empty	File holding the API key, for secrets
`debug`Adds the headers to responses and logs each decision	false	Adds the headers to responses and logs each decision

Questions

Traefik plugin FAQ

Each visitor is checked once every 10 minutes and the verdict is cached in memory, so repeat requests skip the API. A check has 1.5 seconds; after that the request goes through.

Start in monitor mode

Add the middleware, read a week of traffic in the dashboard, then block.

Create a free API key Add a site

Traefik plugin that blocks bots and VPNs

What it checks

Four steps, monitor mode first

Create an API key

Declare the plugin

Add a site and set siteId

Attach it to a router

Coolify, Compose or Kubernetes

Change the policy without touching Traefik

Middleware options

Traefik plugin FAQ

Start in monitor mode

Add a site and set `siteId`