Skip to main content
IT BIBLESign in

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

  1. 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.
  2. Agree to the terms for the honeypot data on your API tokens page.
  3. 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_cursor you were given as cursor to get the next, older page. next_cursor is null on the last page.
  • To keep your own copy up to date, ask for order=asc and remember the last next_cursor. Next time, pass it as cursor and 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.