bot-cooker
bot-cooker is a defensive HTTP tarpit: a small server you run on a
hostname of your own, which answers unsolicited scanners slowly and with
convincing decoy content. Automated tools that sweep the internet for leaked
.env files, exposed .git directories, database dumps and admin panels
spend their time, connections and proxy budget on it, and leave with nothing
of value.
Why a tarpit
Most of the hostile traffic a public server sees is automated: scripts that
try the same few hundred paths on every address they can find, at a cost
close to zero per target. A firewall rule or a 403 tells such a script to
move on immediately; its cost stays near zero.
A tarpit changes the economics instead. Each request that reaches it is held open and answered at a trickle with material that looks worth reading, so the scanner keeps a slot busy for minutes instead of milliseconds, and whatever it collects is worthless. Spread over many traps, that raises the cost of indiscriminate scanning for everyone who runs one, and gives the scanner’s operator less time for real targets.
What it is not
- Not a weapon. bot-cooker never connects anywhere, never scans, never “hacks back”. It only answers clients that chose to connect to it.
- Not harmful to clients. Responses waste time; they carry no exploits, no malware, nothing aimed at the client’s machine.
- Not a replacement for securing real systems. Run it on hostnames that serve nothing else. It complements patching, firewalls and monitoring of your real services; it does not protect them by itself.
What makes it convincing
A trap is only useful while scanners cannot tell it from a real, careless server. bot-cooker therefore derives a whole imaginary organisation from a secret per-instance key — company, domain, staff, application stack, web server, versions, formatting habits, timing — and renders every response from it: configuration files in the stack’s own format, git metadata, SQL dumps in the right dialect, chronological logs, login pages, JSON APIs, a browsable website. Two instances with different keys look like two unrelated systems. See How it works.
Where to start
- To run a trap: Quick start — one command on a fresh Linux server.
- To understand the design: How it works and Ethics and responsible use.
- To contribute: Architecture and Contributing.
bot-cooker is free software under the Apache License 2.0. Anyone may use it, anywhere; forks keep the NOTICE file that names the original project.
How it works
The persona
Every instance has a secret master key. From it, bot-cooker derives a persona: an imaginary organisation and the system it runs.
- identity: company name, industry, domain, staff, locale and time zone;
- technology: one of ten application stacks (Laravel, Symfony, Django, Rails, Express, Spring Boot, ASP.NET Core, WordPress, Joomla, Drupal), a front server (nginx, Apache, OpenResty, Caddy, IIS, LiteSpeed) that fits the stack and the host’s operating system, real released versions of each, a database, a cache, a mail provider, a cloud;
- habits: how its configuration files are quoted and indented, which comments and leftovers they contain, how its logs are formatted;
- behaviour: which paths exist, which leaks lie around (
.env,.git, backups, logs,phpinfo), header order, how fast it answers.
Each facet comes from its own random stream keyed by the master key, so the persona is stable for that key and unrelated to every other key’s.
Deterministic content
Every response is a pure function of the master key, the requested path and the current epoch. Asking for the same file twice returns the same bytes, as a real file would. Epochs then move the content forward the way a maintained system changes:
- configuration epochs (about a week by default) rotate secrets and bump patch versions;
- log epochs (a few hours) extend logs with new lines;
- epoch boundaries are jittered per instance, so instances do not change in lockstep.
Nothing is stored: no database, no files written. A restart with the same key serves the same system.
What scanners find
- Leaked configuration in the stack’s own format:
.env,wp-config.php,configuration.php,settings.php,database.yml,application.yml,appsettings.json,docker-compose.yml. Values agree with each other and with the rest of the persona. - Version control:
.git/HEAD,config,logs/HEAD, refs, pointing at a plausible remote. - Database dumps in the right tool’s format (mysqldump, MariaDB, pg_dump, SQL Server) with the stack’s real schema and consistent records.
- Logs: access logs in the server’s format, error logs, application logs, in chronological order, with the background noise every public server has.
- APIs shaped like the stack’s own, with real pagination envelopes.
- Pages: login screens,
phpinfo,server-status, version files, sitemaps, feeds, and a website whose pages and directory listings lead deeper — the labyrinth. Pages link stylesheets and scripts that really load. - Realistic misconfiguration: some PHP personas print PHP errors into their pages, consistent with their own configuration and logs.
robots.txt lists, as “disallowed”, paths that really exist on this
instance: well-behaved crawlers stay out, recon tools go in.
How it answers
- Server behaviour: paths the persona does not have get that stack’s or
that server’s real 404; denied dotfiles get 403; directories redirect to
their trailing slash;
HEAD,OPTIONS, unknown methods and malformed requests are answered the way the persona’s server answers them, down to header order and spelling. - Pacing: headers arrive after the application’s usual response time — a few hundred milliseconds, as from a PHP or Rails backend — so the server looks alive. The time is spent in the body, which trickles out in pieces whose size and spacing change during the response (brisk stretches, sluggish ones, stalls, network hiccups followed by a burst), never silent long enough for a client’s read timeout to give up. Some connections are cut at different stages; some requests are answered at normal speed, as a cache hit would be. All distributions are per instance.
- Static files (stylesheets, scripts,
favicon.ico,robots.txt) are answered at once, as a web server serves files from disk. - Limits: per-connection byte and time caps, and a global cap on held connections that protects the host: past it, new requests get fast answers instead of another held slot.
What it never does
It never opens an outbound connection, never runs anything a client sends, never writes to disk, and never sends content meant to harm a client. See Ethics and responsible use.
Ethics and responsible use
bot-cooker exists to protect infrastructure by making automated attacks more expensive. That purpose sets clear limits, and the project keeps to them in code, in documentation and in what it accepts from contributors.
Principles
- Purely reactive. The trap only answers connections that clients open to it. It never scans, never connects out, never follows up on a client.
- Time is the only cost. A client that talks to a trap loses time and gets decoy data. It receives no exploits, malware, decompression bombs or anything else aimed at its machine, and the trap makes no attempt to identify or track the people behind it.
- Decoys are decoys. Credentials, keys, names and records in responses are generated. They are not anyone’s real data, and they do not lead to any real system.
- Your infrastructure only. Run traps on hostnames and servers you control, never on someone else’s address space or in front of a service other people rely on.
Practical guidance
- Use dedicated hostnames. Nothing legitimate should live on a trap hostname. If you must run bot-cooker next to a real site, give it only junk paths and allowlist the IP ranges of your users and partners by CIDR.
- Do not trap people you have a duty to. If customers, colleagues or partners could plausibly reach the hostname, use a different one.
- Keep it separate. A trap should not share secrets, networks or credentials with real systems. The decoy data must never be derived from real data.
- Logs and privacy. bot-cooker keeps per-IP counters in memory only and writes nothing to disk except its own log (if you configure one). Treat what you collect from scanners as personal data where your jurisdiction says so, and keep only what you need.
- Law and policy. Tarpits are a long-established defensive technique, but rules differ between countries and between hosting providers. Check your provider’s acceptable-use policy. This documentation is not legal advice.
Reporting and contributing
If you find that the software can be used to harm anyone, or that it does anything outside these principles, report it privately as described in the security policy. Contributions that add retaliation, exploitation or tracking are not accepted; see Contributing.
Quick start: one command
You need a Linux server you control (x86-64 or ARM64; 1 vCPU and 512 MiB of
RAM are enough) with ports 80 and 443 reachable from the internet,
and a hostname for the trap, e.g. backend-node-1.example.org. Then, on the
server:
curl -fsSL https://raw.githubusercontent.com/koval01/bot-cooker/main/deploy/install.sh | sudo bash
What the installer does
It asks its questions in English or Russian and checks every answer:
- The server: architecture, memory, disk, whether ports 80 and 443 are free (and which program holds them if not), and whether bot-cooker is already installed (then it offers to update or remove it).
- The mode: HTTPS on the trap’s own hostname (recommended), or plain HTTP on port 80 behind a proxy you already have.
- The hostname and its DNS: it finds the server’s public address, asks whether the hostname’s A record points to it, and checks through a public resolver. A missing record, a record pointing elsewhere, Cloudflare proxying left on, or a stray AAAA record that would break the certificate are each explained with exactly what to set; you can fix it and re-check, install anyway, or switch to HTTP only.
- The provider’s firewall: it reminds you to allow inbound TCP 80 and 443 in the cloud console, which cannot be seen from the server.
- Automatic updates: offered, off unless you say yes (see below).
- A summary of the settings and of every change it is about to make to the system. Nothing changes before you confirm.
Then it works the same way on every supported distribution:
| Docker | installed from the distribution’s packages (Ubuntu, Debian, Fedora, Amazon Linux, openSUSE, Arch, Alpine), from Docker’s own repository where the distribution has none (RHEL, Rocky, Alma, CentOS Stream), with the Compose plugin from its official releases (SHA-256 checked) where only that is missing; the service is enabled at boot |
| Firewall | ufw, firewalld, nftables or iptables, whichever is active, gets TCP 80/443 with rules marked bot-cooker, saved to survive a reboot |
| Swap | a swap file when the server has less than 2 GiB of memory and none |
| Network | /etc/sysctl.d/90-bot-cooker.conf raises connection queues and file limits for many long connections; values already higher are kept |
| The trap | /opt/bot-cooker with a fresh master key and admin token, the trap and Caddy containers with log rotation, the bot-cooker-ctl command |
Finally it waits for the certificate and the trap’s first answer. If the
certificate fails it reads Caddy’s log and tells you the cause: closed
firewall, DNS not found, DNS pointing elsewhere, or Let’s Encrypt rate limits.
It ends with a guide (also in /opt/bot-cooker/GUIDE.txt) and a report of
everything it changed on the server.
Afterwards
bot-cooker-ctl status # running? persona, counters
bot-cooker-ctl stats # statistics as JSON
bot-cooker-ctl logs # the log (Ctrl+C to leave)
bot-cooker-ctl stop | start | restart
bot-cooker-ctl update # install a newer release now
bot-cooker-ctl auto-update on # or off
bot-cooker-ctl uninstall # remove; --purge also deletes key and certificate
bot-cooker-ctl guide # the guide again
uninstall also undoes the system changes (firewall rules, swap file,
network settings, update timer). Docker stays, since other programs may use
it.
Automatic updates
With your consent, a systemd timer (or cron where there is no systemd) checks
this repository’s releases once a day at a random time. A newer release is
installed by its own installer, whose SHA-256 is checked against the
release’s SHA256SUMS first; the key, token, certificate and persona stay. If
the new version does not come up, the previous one is restored. Every check
is logged in /opt/bot-cooker/update.log. Pre-releases are never installed.
Unattended installation
Every question has an option, and --yes takes the given options plus the
answers of a previous installation:
curl -fsSL https://raw.githubusercontent.com/koval01/bot-cooker/main/deploy/install.sh \
| sudo bash -s -- --yes --domain backend-node-1.example.org --auto-update
| Option | Effect |
|---|---|
--domain NAME | HTTPS for this hostname |
--http-only | plain HTTP on port 80, no certificate |
--lang en|ru | language of messages |
--auto-update / --no-auto-update | automatic updates on or off |
--version X.Y.Z | a specific release instead of the latest |
--repo OWNER/NAME | releases and image of a fork |
--source DIR | build the image from a source checkout on the server |
--pack DIR | serve a content pack |
--skip-dns-check | do not verify the hostname’s DNS |
Alpine needs bash first (apk add bash). Prefer to read the script before
running it? Download it, read it, then run sudo bash install.sh.
One-click with cloud-init
Most providers (Hetzner, DigitalOcean, AWS, Google Cloud, Oracle Cloud, Vultr, Linode…) accept user data when you create a server. With it, a new server installs the trap on its first boot and needs no login at all.
-
Copy
deploy/cloud-init.yamland replacetrap.example.comwith your trap hostname:#cloud-config runcmd: - curl -fsSL https://raw.githubusercontent.com/koval01/bot-cooker/main/deploy/install.sh | bash -s -- --yes --domain trap.example.com -
Create the server with a supported Linux image and paste the file into the user data / cloud-init field.
-
Allow inbound TCP 80 and 443 in the provider’s firewall or security group.
-
Point the hostname’s DNS A/AAAA record at the new server’s public address (DNS only, not proxied).
Add --auto-update to the options if the server should install new releases
by itself. The installer keeps retrying the HTTPS check for a few minutes; if DNS takes
longer, Caddy obtains the certificate as soon as the record resolves. On the
server, /var/log/cloud-init-output.log shows what happened.
To manage the server later, log in and re-run the installer as in the quick start, or add it to your fleet.
Several nodes
deploy/fleet.sh drives any number of trap servers from your workstation
over SSH. It needs ssh, rsync (for --source), curl and jq locally,
and an SSH user with passwordless sudo on each node.
List the nodes in deploy/nodes (ignored by git, so your addresses never end
up in a commit), one per line, SSH target then trap hostname:
# deploy/nodes
ubuntu@203.0.113.10 trap-1.example.com
root@198.51.100.7 trap-2.example.com
Each node should have its own hostname, and gets its own master key: never reuse a key, the key is the persona.
Commands
deploy/fleet.sh deploy # install or upgrade every node (released image)
deploy/fleet.sh deploy --version 0.2.0 # a specific release
deploy/fleet.sh deploy --source # build this checkout on each node instead
deploy/fleet.sh status # containers and persona per node
deploy/fleet.sh stats # counters per node, totals, busiest clients
deploy/fleet.sh stats --top 20 --raw # more clients / raw JSON
deploy copies deploy/install.sh to each node over SSH and runs it with
the node’s hostname, one node after another. stats reads each node’s admin
token over SSH at the moment it needs it, passes it to curl on standard
input, and never stores it.
Use another inventory with NODES_FILE=path/to/nodes deploy/fleet.sh ….
Rolling out changes
Upgrade one node, watch it for a while, then the rest: see the rollout checklist.
Docker Compose by hand
The installer writes a small Compose project; you can also run the files in the repository directly.
HTTPS with Caddy, built from source
docker-compose.caddy.yml builds the image from the checkout and puts Caddy
in front of it:
git clone https://github.com/koval01/bot-cooker && cd bot-cooker
DOMAIN=trap.example.com \
COOKER_MASTER_KEY="$(openssl rand -hex 32)" \
COOKER_ADMIN_TOKEN="$(openssl rand -hex 24)" \
docker compose -f docker-compose.caddy.yml up -d --build
Keep the key and token: put them in a .env file next to the compose file
(Compose reads it automatically) so that restarts keep the same persona.
The bundled Caddyfile turns off HTTP/3 and strips Caddy’s Via header, so
responses carry the persona’s own server headers. flush_interval -1 makes
Caddy pass the slow trickle through as it is produced; do not remove it.
Plain HTTP
docker-compose.yml runs only bot-cooker on port 8080, for local testing or
behind a proxy you already have. Change the port mapping to "80:8080" for
a public port-80 trap.
The released image
docker run -d --name bot-cooker -p 80:8080 \
-e COOKER_MASTER_KEY="$(openssl rand -hex 32)" \
ghcr.io/koval01/bot-cooker:latest
Images are published for linux/amd64 and linux/arm64 on every release.
The container runs as an unprivileged user and reads
/app/bot-cooker.yaml; mount your own file there to change settings (see the
configuration reference).
Open files
A tarpit holds many idle connections. The compose files raise the open-file limit to 65535; keep that if you write your own. bot-cooker lowers its connection cap to fit whatever limit it gets and logs when it does.
Behind an existing proxy
If TLS is already terminated somewhere else — a load balancer, an nginx you run, a CDN — run bot-cooker in plain HTTP mode and point the proxy at it:
curl -fsSL https://raw.githubusercontent.com/koval01/bot-cooker/main/deploy/install.sh \
| sudo bash -s -- --http-only
This publishes the trap on port 80 of the server. Requirements for the proxy:
- No response buffering. The slow trickle is the whole point; a proxy
that buffers the response until it is complete defeats it and holds memory
for each client. In nginx use
proxy_buffering off;, in Caddyflush_interval -1. - Long timeouts. Allow responses that last up to
tarpit.max_seconds(20 minutes by default), e.g.proxy_read_timeout 1300s;in nginx. - Client address. Pass the client address in
X-Forwarded-FororX-Real-IPso that statistics show the scanners and not the proxy. - Its own headers. A proxy that adds
Via,Serveror other headers of its own makes the persona less convincing; remove them where you can.
A CDN in front of the trap (for example a Cloudflare proxied record) changes what scanners see — its headers, its TLS — and may cache or cut slow responses. Prefer DNS-only records for trap hostnames.
Next to a real site
If the proxy also serves a real site, send only junk paths to the trap, and use the allowlist with the CIDR ranges of your own users if any of them can reach it. See Ethics and responsible use.
Windows Server
Download bot-cooker-<version>-x86_64-pc-windows-msvc.zip from the
releases (a static build:
no Visual C++ runtime needed), unpack it and, in an elevated PowerShell in
that folder:
.\install-service.ps1 -Port 80 -OpenFirewall
The script:
- installs
bot-cooker.exeintoC:\Program Files\bot-cooker; - writes
C:\ProgramData\bot-cooker\bot-cooker.yamlwith a freshly generated master key, readable only by Administrators, SYSTEM and the service; - registers the
bot-cookerservice underLOCAL SERVICEwith delayed automatic start and restart on failure; - optionally opens the port in Windows Firewall, and starts the service.
Logs go to C:\ProgramData\bot-cooker\bot-cooker.log. Re-running the script
upgrades the binary and keeps the configuration; uninstall-service.ps1
removes the service, and -Purge also deletes the configuration and log.
Why the persona is always IIS here
Scanners can tell the operating system from the TCP/IP stack (TTL, window
size, options). A Windows server claiming to be nginx on Ubuntu would give
itself away, so on Windows the persona is always IIS with ASP.NET Core, and
Linux traps never claim IIS. If connections terminate on a different OS than
the one bot-cooker runs on (Docker Desktop on Windows publishes Linux
containers through the Windows stack), set deception.host_os.
HTTPS
bot-cooker speaks plain HTTP. For HTTPS, put a TLS-terminating proxy in front
that streams responses without buffering, e.g. Caddy for Windows or IIS with
Application Request Routing (with response buffering disabled). If IIS already
uses port 80 (netstat -ano | findstr :80), choose another port or server.
Configuration reference
Every setting has a built-in default, so bot-cooker runs without any
configuration file. The repository’s
bot-cooker.yaml
lists them all with comments. Unknown keys are rejected at startup, so a typo
fails loudly instead of being ignored.
bot-cooker --config bot-cooker.yaml --check # validate and print the persona
Environment variables
| Variable | Overrides | Notes |
|---|---|---|
COOKER_MASTER_KEY | deception.master_key | the instance’s identity; keep it secret and stable |
COOKER_ADMIN_TOKEN | stats.admin_token | token for the stats endpoint |
COOKER_HTTP_BIND | http.bind | e.g. 0.0.0.0:80 |
COOKER_TEMPLATES_DIR | deception.templates_dir | e.g. a mounted content pack |
COOKER_MAX_CONCURRENT | limits.max_concurrent | the installer sets it from the server’s memory |
Command line
| Flag | Meaning |
|---|---|
--config <file> | configuration file (default bot-cooker.yaml if present) |
--check | validate the configuration, print the persona and route count, exit |
--log-file <file> | append logs to a file instead of standard error |
--service | (Windows) run as a service; used by the service installer |
--version | print the version |
http
| Key | Default | Meaning |
|---|---|---|
enabled | true | serve plain HTTP (the only listener) |
bind | 0.0.0.0:8080 | address and port |
TLS is terminated by a reverse proxy in front of bot-cooker (Caddy in the standard deployment).
tarpit
| Key | Default | Meaning |
|---|---|---|
initial_delay_ms | 350 | typical time until the headers: the application’s response time |
initial_delay_jitter | 0.5 | spread of that time |
chunk_bytes | 48 | typical size of one piece of the body (pieces stay within 1–8×) |
delay_ms | 800 | typical pause between pieces |
delay_jitter | 0.4 | spread of the pauses |
abort_probability | 0.15 | share of responses cut short |
max_bytes | 4194304 | bytes sent to one client before giving up (4 MiB) |
max_seconds | 1200 | hard cap per connection (20 min) |
max_idle_ms | 6000 | longest silence on an open connection |
The trap answers like a real application: headers after a few hundred
milliseconds, then a body that trickles out unevenly — brisk stretches,
sluggish ones, stalls, and the occasional retransmission-like hiccup followed
by a burst. Keeping every silence under max_idle_ms matters: a client that
hears nothing for longer than its read timeout decides the server is dead and
leaves, while one that keeps receiving bytes keeps waiting. Each instance
draws its own distributions inside these bounds. Setting the delays to 0
turns the tarpit off (useful for testing).
deception
| Key | Default | Meaning |
|---|---|---|
master_key | empty | set a long random secret. Empty means a new random key on every start, so the persona changes on each restart |
config_epoch_hours | 168 | how often configuration-like content rotates (weekly) |
log_epoch_hours | 8 | how often logs move forward |
epoch_jitter_hours | 6 | per-instance fuzz on epoch boundaries |
persona_era_days | 0 | 0: the persona lives as long as the key; N: a new identity every N days |
templates_dir | none | directory overlaid on the built-in templates and data, e.g. a content pack |
host_os | auto | the OS scanners see: auto, unix or windows; personas only use servers that run on it |
routes
Leave it unset: the persona decides which paths exist. Setting it
replaces the persona’s route table; the first matching pattern wins, *
matches any run of characters, and unmatched paths get the persona’s 404.
routes:
- { pattern: "/.env", profile: env }
- { pattern: "/.git/*", profile: git }
- { pattern: "*.sql", profile: sql_dump }
- { pattern: "/my-panel/*", profile: labyrinth }
Profiles: env, git, sql_dump, log, login (alias wp_login),
php_info, server_status, joomla, drupal, json, sitemap, rss,
secrets, labyrinth, not_found, forbidden, blank, asset. Content
still follows the persona: env renders a .env, wp-config.php or
database.yml depending on the path and the stack.
allowlist
| Key | Default | Meaning |
|---|---|---|
cidrs | [] | client networks that get a fast plain 404 instead of the trap |
user_agents | [] | User-Agent substrings to spare (spoofable; avoid) |
Empty on purpose: on a dedicated trap hostname nothing legitimate arrives,
and sparing clients by User-Agent would let any scanner walk out by sending
User-Agent: Googlebot. If you run the trap next to a real site, allowlist
your users by CIDR.
limits
| Key | Default | Meaning |
|---|---|---|
max_concurrent | 8000 | connections held at most (~30 KiB of RAM and one open file each; 8000 ≈ 250 MiB) |
Behind the Caddy sidecar, each held connection also costs Caddy about 250 KiB, so the installer sets the cap from the server’s memory (about 300 KiB per connection over HTTPS, 40 KiB over plain HTTP, 350 MiB left for the system): roughly 2000 on a 1 GiB server.
Past the cap, new requests get fast answers instead of another held slot. At
startup the cap is lowered to fit the open-files limit (ulimit -n,
LimitNOFILE), which bot-cooker raises as far as the hard limit allows.
stats
| Key | Default | Meaning |
|---|---|---|
report_interval_secs | 60 | how often a summary line is logged (0 = never) |
admin_path | /_cooker/stats | path of the token-protected JSON endpoint |
admin_token | empty | token; empty means a random one, printed at startup |
max_tracked_ips | 50000 | size cap of the per-IP table |
See Monitoring and stats.
Monitoring and stats
On a server set up by the installer:
bot-cooker-ctl status # running? persona, active connections, requests, clients
bot-cooker-ctl stats # the full statistics document
bot-cooker-ctl logs # follow the log
The stats endpoint
curl -H "X-Admin-Token: <token>" https://trap.example.com/_cooker/stats
returns JSON:
{
"stats": {
"uptime_secs": 599,
"started_unix": 1792681423,
"requests_total": 72,
"connections_total": 72,
"active": 3,
"bytes_fed": 61345,
"wasted_secs": 1897,
"unique_ips": 58
},
"top_ips": [
{ "ip": "203.0.113.5", "requests": 8, "bytes": 8308, "first_seen": 1792681435, "last_seen": 1792681666 }
]
}
| Field | Meaning |
|---|---|
active | connections held right now |
connections_total, requests_total | since start |
bytes_fed | decoy bytes sent |
wasted_secs | total time clients spent connected — the time the trap took from them |
unique_ips | distinct clients (capped by stats.max_tracked_ips) |
top_ips | the 20 clients that received the most bytes |
The token comes from COOKER_ADMIN_TOKEN (the installer stores it in
/opt/bot-cooker/.env). A request to the stats path without the right token
is answered like any other request: slowly, with decoy content. Send the
token in the header rather than in the URL, so it does not end up in proxy
logs.
Counters live in memory and reset on restart; nothing is written to disk.
Logs
Every stats.report_interval_secs the process logs a summary line:
INFO report: active 1 | conns 3 | requests 3 | unique IPs 3 | fed 111 B | bot-time 14s | up 2m 0s
sudo docker compose -p bot-cooker logs -f bot-cooker # installer deployment
The startup line names the persona (persona: Driftlight Clinic (driftlight-clinic.eu) — Laravel on apache, mysql | routes: 28). Set
RUST_LOG=debug for more detail.
Several nodes
deploy/fleet.sh stats collects the counters of every node in your
inventory, adds them up and lists the busiest clients across all of them. See
Several nodes.
What to watch
- Memory stays proportional to
active(about 30 KiB per held connection) and bounded bylimits.max_concurrent. activeclose tomax_concurrentfor long periods means the cap is protecting the host; raise it only if the server has memory and open-file headroom.- Restarts change nothing for scanners as long as the master key is the same.
Upgrades and keys
The master key is the instance
Everything a scanner sees is derived from the master key. Keep it:
- secret — whoever has it can predict every decoy the instance serves;
- stable — a new key turns the trap into a different organisation overnight, which is not how real servers behave;
- unique — two hosts with the same key serve the same organisation, the clearest possible sign of a trap.
The installer generates the key once and keeps it in
/opt/bot-cooker/.env across upgrades. Back that file up if you want to be
able to rebuild the same instance on another server.
Upgrading
bot-cooker-ctl update # one server, now
bot-cooker-ctl auto-update on # one server, daily, by itself
deploy/fleet.sh deploy # a fleet
Automatic updates are off unless enabled at installation or with
auto-update on; see Quick start.
Read the changelog first. Releases that add stacks, servers or new realism can change what an existing key’s persona looks like; the changelog says so when it happens. Where scanners already know an instance, a fresh key on a fresh hostname is often better than a visible change of identity.
Pin a release with --version X.Y.Z to upgrade on your own schedule.
Rotating identities on purpose
deception.persona_era_days: N makes an instance become a new organisation
every N days, as if the server had been reinstalled for a new owner. Leave it
at 0 unless you want that.
Moving to another server
Copy /opt/bot-cooker/.env to the new server, point DNS at it and run the
installer there: the persona, the admin token and (after re-issue) the
certificate are the same as before.
Rolling out a trap
A checklist for putting a new build or a new instance in production. Every step runs against hosts you own.
1. Before deploying
- CI on the commit is green: lint, tests on Linux and Windows, the Windows service job, the Docker job.
- Each instance has its own long random
master_key(the installers andopenssl rand -hex 32give one). Never reuse a key across hosts: the key is the persona. bot-cooker --checkon the target config prints the persona you expect (stack, front server, route count).host_osmatches the OS whose TCP stack scanners will see (autounless connections terminate on another OS than the one bot-cooker runs on).- Upgrading from an older build changes every key’s content once (new rand sampling, new version data). Prefer a fresh key and hostname over upgrading an instance scanners already know.
2. One staging instance
Deploy one instance on a dedicated trap hostname and let it run for a few days before touching the others.
- Service identification looks like the persona’s server:
nmap -sV -Pn -p <port> <host>names the server and version the persona claims, not an unknown service. - Content checks see the persona’s stack:
nuclei -u http(s)://<host> -tags tech -silentreports the same stack, server and versions as--check. - Protocol edge cases come from the persona’s server:
tools/capture/grab.py <host> <port> <outdir>saves the raw answers to a fixed probe set; read the 400/404/HTTP-1.0 answers and compare them with a real server of the same kind if you have one. - The process stays healthy under load: run
cargo run --release --example load -- --addr <host>:<port> --conns 4000 --secs 120from another box you own and watch memory (about 30 KiB per held connection) and CPU. The stats endpoint showsactivenear the number of held connections.
3. Watch it
GET <admin_path>withX-Admin-Tokenreturns the counters; the log gets onereport:line perstats.report_interval_secs.- Memory stays bounded by
limits.max_concurrent(8000 by default, lowered at startup to fit the open-files limit; the log says so when it happens). - The process restarts cleanly:
docker stop,systemctl stoporStop-Serviceends it within a few seconds.
4. Roll out
- One host at a time, each with its own key and hostname.
- Keep the previous build’s image or binary until the new one has run for a day.
Known gaps
- With the standard Caddy sidecar, the HTTP/1.1 response headers that reach
clients are reordered and re-cased by Caddy (Go’s
net/httpsorts them and writesEtag,X-Xss-Protection), which undoes the front server’s own header style. Caddy also answers port 80 itself (308 Permanent RedirectwithServer: Caddy), answers malformed requests with Go’s own400, and its TLS handshake has Go’s fingerprint. Behind it, HTTP/1.1 clients also see the body’s trickle as many small chunks, because Caddy writes each piece as it arrives (direct clients get buffer-sized chunks). Terminating TLS in bot-cooker itself is planned to remove these. - The site front (the home page and content pages) is drawn by bot-cooker’s own themes, not by captured stock output of the CMS or server. A careful comparison with a real install of the same software can tell them apart.
cooker-packhas only been run with--dry-run, never against the API.
Troubleshooting
Start with bot-cooker-ctl status and bot-cooker-ctl logs. The installer
itself diagnoses the common certificate problems below at the end of an
installation.
The installer says “no answer yet”
- DNS:
getent hosts trap.example.comon the server must print the server’s public address. With a CDN, the record must be DNS only. - Firewall: TCP 80 and 443 must be open in the provider’s firewall or security group, not only on the host. Let’s Encrypt validates over port 80 or 443 from the internet.
- Certificate:
sudo docker compose -p bot-cooker logs caddyshows the ACME exchange. Rate limits apply if you re-create the same hostname many times in a short period.
502 Bad Gateway from Caddy
bot-cooker itself is not running. Check
sudo docker compose -p bot-cooker logs bot-cooker. A configuration error
names the field; fix it and re-run the installer.
A port is already in use
Something else (often a web server installed with the image) listens on 80 or
443: sudo ss -ltnp 'sport = :80'. Stop it or use a dedicated server.
Pages load very slowly
That is the tarpit. robots.txt and static files answer at once; most other
paths answer slowly on purpose. To test without delays, run locally with
tarpit.initial_delay_ms: 0 and tarpit.delay_ms: 0.
The persona changed after an upgrade
The key is the same but the release changed how personas are derived; the changelog mentions it. See Upgrades and keys.
Statistics show only one address
A proxy in front of bot-cooker does not pass the client address. See Behind an existing proxy.
Still stuck
Open an issue with the Bug report template. Include the version and the relevant log lines, but never your master key or admin token.
Content packs
The built-in prose and vocabularies are shared by every instance; the procedural layer recombines them so no two instances read alike, but a content pack makes the text itself unique to one instance.
A pack is a directory of templates and data laid over the built-in catalog
(deception.templates_dir). It contains no executable code: only MiniJinja
templates, YAML and text, checked when the trap starts.
Generating one
cooker-pack runs on your own machine, never on a trap. It asks Claude
to write the prose, comment and commit vocabularies and the site theme for one
instance’s persona, checks that the result loads and renders, and writes the
overlay directory:
export ANTHROPIC_API_KEY=...
COOKER_MASTER_KEY=<the instance key> \
cargo run --release --features pack --bin cooker-pack -- --out packs/node-1
Only the fictional persona (company, industry, stack, staff first names) goes
into the prompts; the master key does not. --dry-run prints the prompts
without calling the API.
The trap binary is built without the pack feature and contains no HTTP
client.
Installing one
Copy the directory to the server and point the configuration at it:
deception:
templates_dir: /path/to/pack
With the installer, put the directory on the server and pass it with
--pack (re-running the installer keeps the key):
sudo bash install.sh --domain trap.example.com --pack /opt/bot-cooker-pack
The pack is mounted read-only into the container and selected with
COOKER_TEMPLATES_DIR. Files in the pack replace the built-in files with the
same path; a broken pack fails at startup instead of serving half-rendered
pages.
Writing one by hand
Any file under templates/ can be overridden: copy it into the pack at the
same relative path and edit it. See Templates and data
for what lives where.
Architecture
bot-cooker is a single Rust binary (Tokio, no web framework) with its content in an embedded template catalog. This chapter follows one request through it.
A request, end to end
- Accept —
http::serveaccepts the connection;http::connreads requests withwire::read_head, applying the persona’s front-server rules (header size limits, keep-alive, timeouts). Malformed requests are refused the way that server refuses them (400,414,505, …). - Persona —
Engine::current()returns the incarnation for the current persona era: thePersonaderived from the master key (persona::derive, one RNG stream per facet) and itsRouter, built fromPersona::routes(). - Route — the router matches the path against glob patterns and picks a
Profile(env,git,sql_dump,labyrinth,asset, …). Unknown paths getnot_found. - Render —
render::renderbuilds aScope(persona,Worldat the current epochs, request) and letsrender::methods::gatedecide what the method gets. The profile module inrender/profiles/chooses templates and context; text comes only fromtemplates/. The result is aDoc, to whichrender::headersadds the front server’s and framework’s headers. - Pace —
tarpit::Plan::sampledecides the wait before the head, the wait before the body, the chunking regimes and whether the response will be cut;tarpit::respondwrites it throughwire::responsein the front server’s dialect. Long artifacts (logs, dumps, sitemaps, API pages) are streamed block by block, each block rendered on demand. - Count —
statsrecords the connection, bytes and time per client IP.
Modules
| Module | Responsibility |
|---|---|
config | the YAML configuration and its defaults |
catalog | MiniJinja environment, embedded templates, overlays, custom filters |
data | typed, validated view of templates/data/*.yaml |
persona | the persona model, its derivation, route table and versions |
world | what happened on the imaginary system: people, records, posts, commits, traffic, icons |
render | profiles, headers, methods, caching of expensive documents |
engine | persona eras, epochs, incarnations; fingerprint tests and audit |
tarpit | pacing plans and the drip |
wire | HTTP/1.1 parsing and serialisation per front server |
http | accept loop, connection handling, admin endpoint |
stats | counters, per-IP table, periodic report |
routing | glob router and allowlist |
text | per-persona prose model and voice |
pack | the offline content-pack generator (feature pack) |
Determinism and time
- Content randomness always comes from keyed streams:
Persona::rng(label),World::fixed_rng,cfg_rng,log_rng, or the templatechoicefilter keyed withpersona_seed. The same key, path and epoch give the same bytes. - Only pacing (
tarpit) and per-request tokens (session cookies, request ids) use fresh randomness. - Epochs come from the wall clock through
engine; tests pin the clock.
Tests that guard the design
engine::tests— every route renders for many personas; stability within an instance; differences across instances; realism checks (autoindex layouts, logs in order, dumps well formed, linked assets served).engine::audit— renders 40 instances and fails if a line of our own making appears on more than 15% of them.render::tests,persona::tests,world::*— formats and invariants.tests/http.rs,tests/server.rs— the real binary over real sockets.
Where it is heading
The contributing guide lists the planned steps that make new stacks, servers and artifacts mostly a matter of data, and packs the supported form of third-party extension.
Template catalog
Everything bot-cooker serves is rendered from this tree by one MiniJinja
environment (src/catalog). The tree is embedded into the binary at build
time; set deception.templates_dir to overlay files from disk.
*.j2— templates. Names ending in.html.j2/.xml.j2are HTML-escaped, everything else is written verbatim. Whitespace:trim_blocks,lstrip_blocks, trailing newline kept. Undefined variables are errors.*.yaml— data the persona is derived from (word lists, stack and server facts).
Filters available on top of MiniJinja’s built-ins: quote(mode), php,
sql(dialect), strftime(fmt, offset_min), ljust(n), rjust(n),
human_size(style), hexnum, base36, chunks(n).
Layout
data/— what personas and records are drawn from:stacks.yaml,servers.yaml,infra.yaml,names.yaml(by locale),agents.yaml(browser release cadences),probes.yaml(scanner request parts),schemas.yaml,env/*.yaml(.envlayouts),php_errors.yaml(what PHP prints withdisplay_errorson),words.yaml,notes.yaml,synonyms.yamlandcorpus/*.txt(training text for the prose model).servers/<frontend>/,stacks/<stack>/— per-layer pages (errors, login, autoindex,OPTIONSanswers…);stacks/default/is the fallback.site/,pages/,sql/,logs/,api/,vcs/,secrets/,common/— the artifacts themselves.php/— PHP’s own error output, put in front of (or into) the pages of personas that display errors.assets/— the stylesheets and scripts pages link to. Which files a stack has, and how their hashed names look, isdata/assets.yaml; the persona fixes the names once, so pages, access logs and the route table agree.pack/— prompts of the offlinecooker-packtool (not served).
An overlay file replaces the embedded file with the same path; data files are
validated at startup, so a broken overlay fails loudly instead of serving
half-rendered pages. cargo run -- --check loads the catalog and prints the
persona.
Contributing to bot-cooker
Thank you for helping. bot-cooker raises the cost of automated attacks on infrastructure its operators own, and it only works if it stays trustworthy: for the people who deploy it, and for everyone whose traffic it touches. Please read the principles first; a pull request that breaks one of them will not be merged however good the code is.
Principles
- Defence only. The trap answers requests that clients chose to send. It
never connects out, never scans, never “strikes back”. No feature may make
an outbound connection from the trap binary (the offline
cooker-packtool, which never runs on a trap, is the one place with an HTTP client). - Harmless to clients. Responses waste a scanner’s time and nothing else: no exploit payloads, no malware, no decompression or parser bombs, no content aimed at the client’s machine, no attempts to identify or track the people behind a scanner. Decoy credentials must never be real credentials of anyone.
- Realism over invention. Every surface copies real software: stock error
pages and directory listings, real header order and spelling, versions that
were actually released, file formats as the real tools write them. When in
doubt, capture the real thing (see
tools/capture/grab.py) rather than writing it from memory. - No shared fingerprint. Two instances (two master keys) must not share anything a scanner could match on. Content is a deterministic function of the master key, the request path and the current epoch; anything random per request is limited to timing and per-request tokens.
- Calm tone. Code, comments, docs and commit messages describe what the software does in plain, professional language. The project is about making attacks expensive, not about mocking or punishing anyone.
Getting started
You need Rust (the exact toolchain is pinned in rust-toolchain.toml; rustup
installs it on the first build). Docker is only needed for the deployment
files.
cargo run # serves the trap on http://0.0.0.0:8080
cargo run -- --check # validate the config and print the persona
cargo test # unit, engine, fingerprint-audit, HTTP and process tests
cargo clippy --all-targets # must be warning-free
cargo fmt
COOKER_MASTER_KEY=some-key cargo run -- --check shows the persona another
key would get; a handful of keys is the quickest way to see the variety.
The documentation site lives in docs/ (mdBook). Preview it with:
cargo install mdbook
mdbook serve docs
How the code is laid out
| Path | What lives there |
|---|---|
src/main.rs, src/server.rs, src/service.rs | CLI, process wiring, Windows service |
src/http/, src/wire/ | connection loop and the HTTP/1.1 wire layer, in each front server’s dialect |
src/tarpit/ | how a response is paced: delays, chunking, aborts |
src/engine/ | the current persona and router; the fingerprint audit and engine tests |
src/persona/ | the persona model and its derivation from the master key, one RNG stream per facet |
src/world/ | things that “happened” on the imaginary system: people, records, posts, commits, traffic |
src/render/ | turning a routed request into a document: profiles, headers, method handling |
src/catalog/, src/data/ | the template engine and the typed view of templates/data/*.yaml |
templates/ | every artifact as a MiniJinja template, plus the data personas are drawn from |
The architecture chapter of the documentation walks through a request end to end.
Making changes
Content (most contributions)
Most of what a scanner sees is data and templates, not Rust:
- word lists, names, versions, stacks and servers:
templates/data/*.yaml; - files, pages and logs:
templates/**/*.j2; - which static files a stack links to:
templates/data/assets.yaml.
Rules for content:
- Use only versions that were really released; the version tests reject
impossible series, but they cannot know whether
1.24.1ever shipped. - Templates that reproduce real software output verbatim belong in the
directories listed in
VERBATIM_DIRSinsrc/engine/audit.rs. Everything else must vary between instances; the audit test fails when a line of our own making appears on more than 15% of 40 rendered instances. - Randomness comes from the persona and the world (
Persona::rng,World::fixed_rng,cfg_rng,log_rng, the templatechoicefilter keyed withpersona_seed), never from a fresh RNG or the clock.
Adding a stack, a front server or a new kind of artifact
Today these need a few coordinated edits in Rust as well as data. Until the planned restructuring lands (see “Roadmap for extensibility” below), follow the existing examples:
- Stack: a variant in
Stack(src/persona/model.rs), an entry intemplates/data/stacks.yaml,templates/data/env/<stack>.yaml, a schema inschemas.yamlif it differs, an entry inassets.yaml, templates undertemplates/stacks/<stack>/andtemplates/logs/app/<stack>.log.j2. Then searchsrc/forstack.id()to find the few places with stack-specific behaviour. - Front server: a variant in
Frontend, an entry intemplates/data/servers.yamlincluding itswirefacts, andtemplates/servers/<server>/{error,autoindex,redirect}.html.j2, captured from a real installation you run yourself. Add it to thefrontendsof the stacks it can serve. - Artifact: a variant in
Profile(src/config.rs), a module insrc/render/profiles/, its branch inrender::render, its class inrender/methods.rs, and a place inPersona::routes.
Adding a stack, server or weight changes which persona existing master keys get. Say so in the pull request; operators will see their instances change on upgrade.
Roadmap for extensibility
The direction agreed for the codebase, in small reviewable steps:
- guard rails:
clippy.tomldisallowed methods (no clocks or fresh RNGs in content code, no outbound sockets),cargo-deny, golden snapshots of personas for fixed keys, a test that scans all output for harmful content; - stack and server behaviour expressed as data instead of
matchon ids; - a generic
fileprofile with a template per route, replacing single-file profiles; - a profile registry, so metadata (static or not, boilerplate, streaming) lives in one place;
- one directory per stack and per server, each with its own manifest;
- string ids with rendezvous hashing, so adding an option moves as few existing personas as possible;
- packs — directories of templates and data with a manifest — as the only form of third-party plugin. Packs carry no executable code by design.
If you want to work on one of these, open an issue first so the steps stay coordinated.
Pull requests
- One topic per pull request; keep refactors separate from behaviour changes.
cargo fmt --check,cargo clippy --all-targets(no warnings) andcargo testpass. CI runs them on Linux and Windows.- New behaviour comes with tests: stable for one key, different across keys, and realistic where a real reference exists.
- Commit messages: an imperative subject line that says what changes for the user of the trap, then a body explaining why.
- Update the documentation in
docs/andCHANGELOG.mdwhen behaviour or configuration changes. - Found a way to tell a trap from a real server? Report it privately (see SECURITY.md) before opening a pull request that fixes it.
License of contributions
bot-cooker is licensed under Apache-2.0. Unless you state otherwise, any contribution you submit is licensed under the same terms (section 5 of the license), without additional conditions.
Everyone taking part is expected to follow the Code of Conduct.
Releasing
Releases are cut from main by pushing a version tag.
-
Make sure CI is green on
mainandCHANGELOG.mdhas an entry for the version: move the Unreleased items under a new## [X.Y.Z] - YYYY-MM-DDheading and add the comparison link at the bottom. -
Bump
versioninCargo.tomland runcargo buildsoCargo.lockfollows. Commit both with the changelog. -
Tag and push:
git tag -a vX.Y.Z -m "bot-cooker X.Y.Z" git push origin vX.Y.Z
The Release workflow then:
- builds static binaries for Linux x86-64 and ARM64 (musl) and Windows
x86-64, with
README.md,LICENSE,NOTICEand the sample configuration, and attaches them with aSHA256SUMSfile to a GitHub release; - builds the container image natively on x86-64 and ARM64 runners and
publishes
ghcr.io/koval01/bot-cooker:X.Y.Zand:latest.
After the first release, set the package’s visibility to public in the repository’s Packages settings; the one-line installer pulls the image without logging in.
If a release changes what existing keys’ personas look like, say so at the top of its changelog entry.
FAQ
Is this legal?
Tarpits and honeypots on your own infrastructure are a long-established defensive technique: you decide how your own server answers requests sent to it. bot-cooker sends nothing to anyone who did not connect to it, and sends nothing harmful. Rules still differ by country and by hosting provider, so check your provider’s terms. This is not legal advice.
Will it hurt real users or search engines?
Not on a dedicated hostname: no person or legitimate crawler has a reason to
go there. robots.txt asks crawlers to stay out of the decoy paths, and
well-behaved ones do. Do not put the trap on a hostname your users rely on.
Why not just block scanners?
Blocking is free for the scanner: it moves on in milliseconds. A tarpit makes each attempt cost minutes and returns nothing usable. Use both: block what targets your real services, and let traps raise the cost of indiscriminate scanning.
Can scanners tell it is a trap?
Making that hard is most of the work in this project: personas, real server behaviour, real versions, consistent artifacts, per-instance timing and an automated audit that looks for shared lines across instances. No disguise is perfect; if you find a reliable tell, please report it privately (see the security policy) so it can be fixed.
How many resources does it need?
Very few. Each held connection costs about 30 KiB of memory and one open file; the default cap of 8000 connections stays around 250 MiB. A small VPS is plenty.
Does it store anything?
No. Decoy content is generated on the fly from the master key; counters live in memory. The only thing written is the log, where you configure one.
Why Rust and no web framework?
A trap must speak HTTP the way the server it imitates does, down to header order, spelling and error pages, which general-purpose frameworks normalise away. A small wire layer of its own gives that control and keeps the binary small.
Can I use it at work, in a company or a public institution?
Yes. The Apache 2.0 license allows any use. Keep the NOTICE file when you
redistribute it or a modified version.