When an attacker finds your server, the first thing they do is look for an open door: a few passwords on 22, an RDP attempt on 3389, a password-less Redis on 6379, an old SMB flaw on 445. Most of those attempts go to ports you don't use — and because nothing is listening there, they leave no trace. The attack happened; you never saw it.
A honeypot sensor fills exactly that gap: it puts realistic-looking fake services on your unused ports, records who tried what, and contributes it to the shared threat pool. Installing it is one command, it costs nothing, and you get two things out of it — visibility into who is probing your server, and the contributor tier on your account.
What a sensor does, and what it doesn't
It does: show a fake Exchange sign-in page, a FortiGate panel, a MySQL greeting or a Telnet prompt on your free ports; read the request, tag it when it matches a known exploit pattern, and report "this address tried this on this port".
It does not: store or send passwords, usernames or request bodies. The decoys run no commands, write no files and open no shell — this is not a "high-interaction" honeypot where an attacker actually gets in. An event is a tag and a timestamp.
That is a deliberate choice: high-interaction honeypots are maintenance work and a genuine risk. The goal here is not to study the attacker but to identify the scanning address.
Installing it in one command
You need a Linux server with systemd, Python 3.6 or newer, a publicly reachable IP, and a free API key — a minute's work in the dashboard.
The command sets up a hardened systemd service (ipdb-sensor) listening on ports your server does not use. If you would rather not trust a pipe blindly — and you shouldn't — read the script first; the SHA-256 of the download is verified during install:
The options you are most likely to want:
| Option | What it does |
|---|---|
--name web-01 | The sensor's name in the dashboard (defaults to the hostname) |
--profiles @edge,exchange | Which decoys to run |
--ports 23,3389,6379 | Extra raw TCP ports to listen on |
--ignore 198.51.100.0/24 | Never report your own office or monitoring addresses |
--fail2ban | Also read bans out of the fail2ban log |
--status / --upgrade / --uninstall | Health, upgrade, removal |
Which traps to open
The sensor ships with 64 ready-made decoy profiles, and you do not have to pick them one by one: the bundles that start with @ are themed groups.
| Bundle | What's in it | Who it suits |
|---|---|---|
@classic | FTP, Telnet, SSH, RDP, MySQL, Redis, MongoDB, VNC… | The default; sensible on any server |
@recommended | Exchange, FortiGate, GlobalProtect, NetScaler + the classics | The mix that actually gets scanned most |
@edge | FortiGate, Ivanti, Cisco ASA, F5, SonicWall, pfSense… | Catching edge-device and VPN scans |
@web | WordPress, phpMyAdmin, cPanel, Plesk, Tomcat… | Hosting and web servers |
@devops | Jenkins, GitLab, Grafana, Docker, Kubernetes, etcd… | CI/CD and internal tooling scans |
@mail · @databases · @remote · @iot | Mail, database, remote-access and IoT groups | Machines with a defined role |
Pick ports you do not use: if the sensor cannot bind one, it skips that decoy silently. To see which decoy sits on which port, use the builder on the honeypot page — it writes the install command from your selection.
What the service is allowed to do
Installation needs sudo once; the service itself does not run as root. It runs as a throw-away unprivileged user created by systemd (DynamicUser) whose only capability is binding ports (CAP_NET_BIND_SERVICE). The file system is read-only, /tmp is private, there is no device access, only IPv4/IPv6 and the systemd notify socket are permitted, system calls are filtered, and memory is capped at 96 MB. The whole thing is one dependency-free Python file — short enough to read, also on purpose.
Checking that it works
The log shows which decoys opened, which were skipped because the port was taken, and the first batch going out. Events are batched and shipped once a minute, so the first ones can take a minute to appear. Your sensors, the addresses they saw and the event counts are listed under My sensors.
On a cloud server, check the security group: if your provider's firewall closes the ports, no scanner ever reaches the sensor and the page stays empty. Seeing events within the first few hours is the normal outcome — the internet is not a quiet place.
What happens to the data: the two-account rule
An address your sensor sees does not go straight onto the blocklist. To enter the sensor pool it has to have been seen within the last 7 days by sensors belonging to at least two different accounts and two different networks. One sensor cannot put anyone on the list by itself — so a misconfigured security scan, or someone acting in bad faith, cannot poison the pool.
What does enter the pool becomes available to everybody through the open datasets and the API. The scan your server absorbs turns into a block in someone else's firewall — which is the only reason the list is worth anything.
What you get back: the contributor tier
A free account gets 1,000 lookups a day, a verified one 10,000. Verified accounts with an active sensor (or a Shield or WordPress install) get 30,000 a day. The tier is computed, not granted: it holds while the sensor has reported within the last 7 days, and lapses on its own when it goes quiet. No payment, no plan, no "enterprise edition".
Mistakes people make
- Reporting your own scanners. If your internal vulnerability scan touches every port every week, exclude your ranges with
--ignore. - Choosing a real service's port. If SSH is on 22, the SSH decoy will not open. Move it (
ssh:2222) or leave that bundle out. - Installing it behind NAT. On an address nothing outside can reach, a honeypot sees nothing; without port forwarding, put the sensor on a machine with a public IP.
- Starting with the critical machine. It is safe enough technically, but installing on a spare edge server and reading the log for a day is the better habit.
Upgrading and removing it
Removal deletes the service, the unit file and the directory; only the past events in your dashboard remain. Your account is untouched — the contributor tier simply lapses after 7 days.
Frequently asked questions
Does a honeypot sensor put my server at risk?
The decoys run no commands, write no files and open no shell: they read the request, return a realistic answer and tag the event. The service does not run as root but as a throw-away unprivileged user created by systemd (DynamicUser); its only capability is binding ports, its file system is read-only and its memory is capped at 96 MB. Even so, a spare edge machine is a better first host than your critical database server.
Will it touch ports I already use?
No. The sensor tries to bind each port first; if the port is taken it skips that decoy and says so in the log. If real SSH is running on 22, the SSH decoy quietly stays off — either leave that port free or move the decoy elsewhere (ssh:2222, for instance).
How much traffic does it send, and does it burn my quota?
Events are batched and shipped once a minute, and they do not come out of your daily lookup quota: reporting and looking up are separate counters. If anything it works the other way round — an active sensor moves your account to the contributor tier.
Does an address one sensor sees go straight onto the blocklist?
No. To enter the sensor pool an address has to have been seen within the last 7 days by sensors belonging to at least two different accounts and two different networks. One sensor cannot put an address on the list by itself — so a misconfigured scanner, or someone acting in bad faith, cannot poison the pool.
To protect your own site with the same data, see the Shield install guide, the WordPress plugin guide if that is your stack, and the reputation score post for how the numbers are built.
Comments 0
Share a question, your experience or a correction. You can comment as a registered user or anonymously.
No comments yet. Be the first.