Honeypot data
The honeypot data API
Read what our honeypot servers see, as JSON, with your API token.
IT Bible runs decoy servers (honeypots) on the open internet. Nobody has a reason to connect to them, so everything that does is a scan or an attack. Members with an active plan can read every event through this API: the address it came from, the country, city and network, and the usernames and passwords that were tried.
The public honeypot page shows a redacted version of the same data. This API is the unredacted one, so it comes with terms you agree to once. If you would rather look through the data in your browser, the honeypot data page has the same events with filters, and shows the API address for whatever you are looking at.
Before you start
- You need an active plan (an individual plan, or a place on a team with a plan in force). Access ends when the plan does, and it is checked on every request.
- Agree to the terms for the honeypot data on your API tokens page.
- Make an API token on the same page. The honeypot endpoints use the same tokens as the rest of the read-only API.
Send the token as a bearer token:
curl -H "Authorization: Bearer $ITBIBLE_TOKEN" \
"https://itbible.org/api/v1/honeypot/events?per_page=5"
All times are UTC, in ISO 8601 (2026-11-21T10:04:12+00:00). Every response is JSON.
Endpoints
| Endpoint | What it gives you |
|---|---|
GET /api/v1/honeypot/events |
Every event, a page at a time |
GET /api/v1/honeypot/credentials |
Login attempts with the username and password, or counts of each |
GET /api/v1/honeypot/ips |
The different addresses seen, with when and how much |
GET /api/v1/honeypot/blocklist |
The addresses that keep attacking, as a list to block (see Blocklist) |
GET /api/v1/honeypot/stats |
Daily counts, which are kept for good |
GET /api/v1/honeypot/sensors |
The sensors that feed the data, and where they are |
GET /api/v1/honeypot/exports |
The daily files you can download whole |
GET /api/v1/honeypot/stream |
Where to connect to get new events live (see Live stream) |
Raw events are kept for 90 days. The daily counts behind stats are kept for good and hold no addresses, usernames or passwords.
Filters
These work on events, credentials and ips. Combine as many as you like.
| Parameter | Meaning |
|---|---|
since, until |
Only events from since (included) up to until (not included). Any date or date and time, read as UTC |
type |
One event type, such as login_attempt (see the fields) |
service |
One service: ssh, telnet, http, rdp, smb, mssql, winrm, redis or elasticsearch |
country |
A two-letter country code, such as NL |
city |
A city name, exactly as it appears in the data |
asn |
A network number, such as 64500 |
ip |
One address |
sensor |
A sensor id, from the sensors endpoint |
per_page |
How many to return, from 1 to 1000. The default is 100 |
Events
curl -H "Authorization: Bearer $ITBIBLE_TOKEN" \
"https://itbible.org/api/v1/honeypot/events?type=login_attempt&country=NL&per_page=2"
{
"data": [
{
"id": 184233,
"event_id": "3f9c1e0b7d2a4c58a1b6e9d04f7a2c11",
"time": "2026-11-21T10:04:12+00:00",
"sensor": "ams-1",
"session_id": "b7c2f0a94e1d4d36a0c58e72f19b3d40",
"type": "login_attempt",
"service": "ssh",
"ip": "203.0.113.42",
"port": 51234,
"country": "NL",
"continent": "EU",
"city": "Amsterdam",
"subdivision": "North Holland",
"postal": "1012",
"timezone": "Europe/Amsterdam",
"accuracy_km": 20,
"latitude": 52.37,
"longitude": 4.89,
"asn": 64500,
"network": "Example Hosting B.V.",
"stage": "access",
"actor": "bot",
"username": "root",
"password": "hunter2",
"details": { "method": "password" }
}
],
"next_cursor": 184231
}
Pages and keeping a copy up to date
Pages follow the order events were stored in (id), not the time they happened. A sensor that was offline sends its old events when it is back, so they get a newer id than their time suggests.
- Newest first (the default): pass the
next_cursoryou were given ascursorto get the next, older page.next_cursorisnullon the last page. - To keep your own copy up to date, ask for
order=ascand remember the lastnext_cursor. Next time, pass it ascursorand you get only what has arrived since, in the order it arrived. This never misses a late event.
import requests, time
token = "YOUR_TOKEN"
cursor = 0
while True:
r = requests.get(
"https://itbible.org/api/v1/honeypot/events",
headers={"Authorization": f"Bearer {token}"},
params={"order": "asc", "cursor": cursor, "per_page": 1000},
timeout=30,
)
r.raise_for_status()
body = r.json()
for event in body["data"]:
print(event["time"], event["ip"], event["username"], event["password"])
if body["next_cursor"] is None:
# Caught up. Remember where the last event was and wait a bit.
if body["data"]:
cursor = body["data"][-1]["id"]
time.sleep(30)
else:
cursor = body["next_cursor"]
Waiting for new events
To get events as they arrive without asking over and over, add wait (1 to 25 seconds) to a request for new events. It needs order=asc and the cursor of the last event you have. If something newer exists, you get it at once. If not, the request is held open until something arrives or the time is up.
curl -H "Authorization: Bearer $ITBIBLE_TOKEN" \
"https://itbible.org/api/v1/honeypot/events?order=asc&cursor=184233&wait=25"
With wait, next_cursor is always the cursor to use for your next request (it stays the same when nothing new came), and more says whether there is another page of newer events right now. A token can have one waiting request open at a time, since each one holds a server connection while it waits; a second gets 429. Make your next request as soon as the last one returns.
import requests
token, cursor = "YOUR_TOKEN", 0
while True:
r = requests.get(
"https://itbible.org/api/v1/honeypot/events",
headers={"Authorization": f"Bearer {token}"},
params={"order": "asc", "cursor": cursor, "wait": 25, "per_page": 500},
timeout=40,
)
r.raise_for_status()
body = r.json()
for event in body["data"]:
handle(event)
cursor = body["next_cursor"]
Credentials
Login attempts only (login_attempt and the logins the decoy accepted), with just what is needed to study guesses.
curl -H "Authorization: Bearer $ITBIBLE_TOKEN" \
"https://itbible.org/api/v1/honeypot/credentials?service=ssh&per_page=2"
{
"data": [
{
"id": 184233,
"time": "2026-11-21T10:04:12+00:00",
"sensor": "ams-1",
"service": "ssh",
"accepted": false,
"username": "root",
"password": "hunter2",
"ip": "203.0.113.42",
"country": "NL",
"asn": 64500,
"network": "Example Hosting B.V."
}
],
"next_cursor": 184231
}
Extra filters: username and password (exact match) and accepted (1 for logins the decoy accepted, 0 for the rest).
The most common guesses
Add group=username or group=password to count instead. The list covers the last 7 days unless you pass since, and is sorted by how many attempts each value had.
curl -H "Authorization: Bearer $ITBIBLE_TOKEN" \
"https://itbible.org/api/v1/honeypot/credentials?group=password&per_page=3"
{
"group": "password",
"data": [
{ "value": "123456", "attempts": 4812, "ips": 391, "first_seen": "2026-11-14T00:02:11+00:00", "last_seen": "2026-11-21T10:03:58+00:00" }
]
}
Blocklist
The addresses that attacked, as a list to block. Anyone can download a short version without a token: the free blocklist holds the newest 100 addresses with at least 5 events in the last 7 days. The endpoint gives you longer lists, other windows and more detail.
curl -H "Authorization: Bearer $ITBIBLE_TOKEN" \
"https://itbible.org/api/v1/honeypot/blocklist?window=30&min_events=10&format=txt"
| Parameter | Meaning |
|---|---|
window |
How many days back to look, from 1 to 90. The default is 7 |
min_events |
The fewest events an address must have had in the window. The default is 3 |
limit |
How many addresses to return, up to 5000. The default is 1000 |
sort |
last_seen (the default) or events |
format |
json (the default), txt (one address a line, for firewalls and fail2ban) or csv |
The JSON has the address, its number of events and login attempts, the services it tried, how many sensors saw it, country, network, and when it was first and last seen. Private and reserved addresses, our sensors and the address this site connects from are never listed. Listed addresses may be shared or compromised machines, so treat the list as one signal, not proof. It is cached for about a minute.
Addresses
The different addresses seen, over the last 7 days unless you pass since. Add sort=events, sort=attempts or sort=last_seen (the default). Pages are numbered with page, and next_page is null on the last one. A request cannot reach further than 50,000 rows in, so narrow the filters instead of paging forever.
{
"data": [
{
"ip": "203.0.113.42",
"country": "NL",
"city": "Amsterdam",
"asn": 64500,
"network": "Example Hosting B.V.",
"events": 212,
"login_attempts": 198,
"logins_accepted": 3,
"first_seen": "2026-11-20T03:11:09+00:00",
"last_seen": "2026-11-21T10:04:12+00:00"
}
],
"next_page": 2
}
Daily counts
curl -H "Authorization: Bearer $ITBIBLE_TOKEN" \
"https://itbible.org/api/v1/honeypot/stats?from=2026-11-01&to=2026-11-21"
{
"data": [
{ "date": "2026-11-21", "events": 48210, "ips": 3312, "login_attempts": 40119, "logins_accepted": 87, "countries": 94 }
]
}
from and to are dates (UTC), at most 366 days apart, and default to the last 30 days. Add by=country, service, type, sensor, network or city to split each day. A split row has name, events and ips. The ips of a split are the different addresses in that group on that day, so they do not add up to the day's total.
Sensors
{
"data": [
{ "id": "ams-1", "name": "Amsterdam", "region": "ams3", "latitude": 52.37, "longitude": 4.9, "last_event_at": "2026-11-21T10:04:12+00:00" }
]
}
Daily files
If you would rather take whole days than page through them, a set of files is written each night (00:30 UTC) for the day before, and again the next night so events that a sensor sent late are included. They are kept for as long as the events (90 days).
curl -H "Authorization: Bearer $ITBIBLE_TOKEN" "https://itbible.org/api/v1/honeypot/exports"
{
"data": [
{ "date": "2026-11-20", "kind": "events", "name": "events-2026-11-20.ndjson.gz", "size": 8211440, "url": "https://itbible.org/api/v1/honeypot/exports/events/2026-11-20" },
{ "date": "2026-11-20", "kind": "credentials", "name": "credentials-2026-11-20.csv.gz", "size": 912004, "url": "https://itbible.org/api/v1/honeypot/exports/credentials/2026-11-20" }
]
}
| Kind | Format | What is in it |
|---|---|---|
events |
One JSON event per line, gzipped | Every event of the day, with the same fields as the events endpoint |
credentials |
CSV, gzipped | Every login attempt of the day, with the same columns as the credentials endpoint |
Download one by its url, with your token:
curl -H "Authorization: Bearer $ITBIBLE_TOKEN" -o events-2026-11-20.ndjson.gz \
"https://itbible.org/api/v1/honeypot/exports/events/2026-11-20"
zcat events-2026-11-20.ndjson.gz | head -n 3
A day is the UTC day, by the time of each event. In the CSV, a username or password that starts with =, +, - or @ has a quote mark put in front, because attackers type these on purpose and a spreadsheet would run them as a formula. Remove the quote mark if you need the original value.
Live stream
For events the moment they arrive, without asking again and again, connect to the live stream. It uses the same WebSocket protocol as Pusher, so any Pusher client library works (pusher-js for JavaScript, and others for most languages). You do not need a separate key: you ask the API where to connect and for permission, with your API token.
curl -H "Authorization: Bearer $ITBIBLE_TOKEN" "https://itbible.org/api/v1/honeypot/stream"
{
"protocol": "pusher",
"key": "…",
"host": "ws.itbible.org",
"port": 443,
"scheme": "https",
"channel": "private-honeypot.events.492103",
"next_channel": "private-honeypot.events.492104",
"event": "honeypot.events",
"auth_endpoint": "https://itbible.org/api/v1/honeypot/stream/auth",
"seconds_left": 1210,
"renew_before_seconds": 600
}
Connect to scheme://host:port with the key, subscribe to channel, and bind to the honeypot.events event. Your client library asks auth_endpoint for permission to join the private channel, so give it your token as a bearer token:
import Pusher from "pusher-js";
const token = process.env.ITBIBLE_TOKEN;
const headers = { Authorization: `Bearer ${token}` };
const info = await (await fetch("https://itbible.org/api/v1/honeypot/stream", { headers })).json();
const pusher = new Pusher(info.key, {
cluster: "mt1", // not used, but required by the library
wsHost: info.host,
wsPort: info.port,
wssPort: info.port,
forceTLS: info.scheme === "https",
enabledTransports: ["ws", "wss"],
channelAuthorization: { endpoint: info.auth_endpoint, transport: "ajax", headers },
});
pusher.subscribe(info.channel).bind(info.event, ({ events, first_id, last_id }) => {
for (const event of events) console.log(event.time, event.ip, event.username, event.password);
});
Each message is {"events": [...], "first_id": 184301, "last_id": 184309}, with the same fields as the events endpoint, in the order they were stored.
The channel changes every hour. A member who stops having access is not let into the next one, so the stream stops within the hour. In the last 10 minutes of an hour, events are sent to both the current channel and the next, so you can move over without missing any: before seconds_left drops below renew_before_seconds, ask stream again, subscribe to the new channel, and then unsubscribe from the old one.
It is best effort. Messages are held to 10,000 bytes, so a busy moment is split into several, and past 40 messages a second the rest are not sent. Use the ids to notice: if first_id is higher than the last last_id you saw plus one, ask the events endpoint for what you missed with order=asc&cursor= (see keeping a copy up to date). The stream also has no history, so on start-up, or after a reconnect, catch up from the API first. Connections you have open count against the site's limits, so open one per program, not one per task.
Limits and errors
You can make 120 requests a minute with each token. A request over the limit gets 429, with a Retry-After header. A request that waits for new events counts as one request.
| Status | Meaning |
|---|---|
401 |
No token, or the token is not valid |
403 |
Your plan is not active, or you have not agreed to the terms yet. The message says which |
404 |
The honeypot is not switched on |
422 |
A parameter is not valid. The body says which |
429 |
Too many requests |
What is in the data, and what is not
See the fields for what each value means and how far to trust it. Commands typed in the decoy shell, web requests and what they carried, file names and session recordings are not part of the API.
Stuck on a step?
Create a free account to ask the community. Members who run the real thing answer questions every day.