Taxonomy
What a session record contains, and what each field means. This is the reference for reading a Discover result or a CSV export.
Fields are named as they appear in the API. The Discover field allow-list is a subset of them, listed
by GET /api/discover/fields: a column absent from that list is not queryable, which is what keeps
the endpoint from becoming an arbitrary query against a table of billions of rows.
Session identity and timing
| Field | Description |
|---|---|
id | Unique identifier for the session: the sensor's own ID for the hit, a UUIDv7 |
deployment | The estate the sensor belongs to: HF1, HF2, PP1, PP2 |
startTime | When the session began. Also the partition key, which is why every query needs a range |
endTime | When it ended |
sessionLength | Duration in seconds |
timedOut | Whether the session ended on the 60-second timeout rather than naturally |
tunnelCount | How many tunnel requests the session made. The tunnels themselves are child records |
A deployment is an estate, not a host. HF1 alone was around 1,200 sensors. The individual host is
hostIP / hostName.
Classification
| Field | Description |
|---|---|
category | Exactly one of scan, attempt, intrusion-login, intrusion-commands, intrusion-control |
protocol | The protocol presented: dns, doh, dot, ftp, ftps, http, http-connect, https, icmp, sftp, smtp, smtps, socks5, ssh, tcp, telnet, telnets |
profile | The sensor's deployment archetype, below |
loggedIn | Whether any credential worked |
Every session lands in exactly one category, so shares over a set of sessions always sum to 100%. The web interface labels them Scan, Scouting, Credentials worked, Code pushed and Command and control.
Sensor profiles
Sensors do not all run every protocol. Each is assigned an archetype, and the session records the archetype of the sensor that captured it.
| Value | Captures |
|---|---|
server | The protocol set a general-purpose server would plausibly expose |
relay | The open relay set: proxy and resolver abuse |
all | Every protocol |
relay is kept apart from server because an open proxy or resolver alongside a mail server is not a
configuration that occurs naturally, and implausible service combinations are what honeypot
fingerprinting looks for.
Sessions recorded before profiles existed carry all, because every sensor ran every protocol at the
time.
These values, and the protocol and category lists above, are read out of ProxyPot's own enum struct
tags at package init (model.Profiles, model.Protocols, model.Categories). ProxyPot decides the
taxonomy, so a second copy here would drift: this table once listed shell, proxy, resolver and
mail, which ProxyPot has not used since profiles became all/relay/server.
There was also a protocolFamily column, a stored grouping of protocol into shell/web/mail/file/
dns/relay/raw. It is gone as of schema version 2: it was a pure function of protocol, three of its
seven values never appeared in a single one of the corpus's 6.55 billion sessions, and the name read
as "the protocol without its TLS variant", which is not what it held.
Attacker attribution
| Field | Description |
|---|---|
clientIP | The attacker's address. Requires IP access |
clientPort | Its source port |
clientVersion | The client banner, where the protocol has one, e.g. SSH-2.0-libssh2_1.4.3 |
clientASN | The autonomous system number |
clientASOrg | The autonomous system's operator |
clientEconomyCode | ISO 3166-1 alpha-2 |
clientEconomyName | The economy's name |
clientRegionCode | Continent code: AF, AN, AS, EU, NA, OC, SA |
clientSubdivisionCode | State or province code, where MaxMind has one |
clientCity | City name |
clientLatitude, clientLongitude | Coordinates, to three decimal places |
clientTimezone | IANA timezone |
fingerprints | The client's fingerprints by kind: ja4 (TLS ClientHello), hassh (SSH key exchange), tcp (SYN). Discover queries them as fingerprintJA4, fingerprintHASSH, fingerprintTCP |
Fingerprints exist only for sessions from ProxyPot v3.5.0 on, and only for the kinds the protocol allows. A session without one reads as empty and matches no value.
Geo comes from MaxMind at ingest time. An address seen across a month can therefore carry more than one attribution if MaxMind's answer changed; queries that group by geo pick one arbitrarily, so a per-address geo is the geo of one of its sessions rather than a canonical answer.
Addresses are stored IPv4-mapped in an IPv6 column, and rendered back as IPv4 where that is what
they are: 198.51.100.1, not ::ffff:198.51.100.1.
Sensor attribution
| Field | Description |
|---|---|
hostIP | The sensor's own address. Requires IP access |
hostPort | The port it was listening on |
hostName | The sensor's emulation name, e.g. Generic Shell |
version | The ProxyPot version that recorded it |
host* geo fields | The same geo set as client*, for the sensor |
Credentials
| Field | Description |
|---|---|
credentials | Every attempt, each with username, password and whether it succeeded |
loggedInName, loggedInPassword | The pair that worked, where one did |
credentials keeps the outcome per attempt rather than splitting successes and failures into separate
lists, which is what makes a login success rate computable per protocol.
Discover searches one side of credentials with userNames or userPasswords, matching any attempt,
successful or not.
The commonest pairs across the corpus are IoT botnet defaults: root/xc3511, root/vizxv,
admin/admin, 345gs5662d34/345gs5662d34. They are still in use years after the families that
shipped them.
Content
| Field | Description |
|---|---|
commands | What the client typed, in order |
unrecognizedCommands | The parts the sensor could not handle: an unknown program, a typo, a script it does not run |
urls | URLs fetched or referenced |
urlHostnames | Just the hostnames from those URLs |
hashes | SHA-256 of files downloaded |
commands, unrecognizedCommands, urls, urlHostnames and hashes are arrays, and carry skip
indexes, so contains and exists on them are cheap. The text indexes cover commands for token and substring
search.
Child records
Fetched with a session by GET /api/sessions/{id}, and not included in the grid or
in exports: they are more queries and most sessions have none.
Tunnels
SSH port forwarding, SOCKS and HTTP CONNECT requests. Logged and refused: the sensor never establishes the outbound connection, so this is intent, not a relay that worked.
| Field | Description |
|---|---|
type | direct-tcpip, tcpip-forward, socks5-connect, socks5-bind, socks5-udp-associate, http-connect, dns-exfiltration |
sourceIP, sourcePort | Where the request said it came from |
destinationIP, destinationPort | Where it asked to go |
destinationHost | The destination when it was given as a hostname rather than an address |
payload | What the client sent through it; a binary payload is recorded by size |
seq | Order within the session |
One row per tunnel. A hostname destination is preserved in destinationHost rather than discarded.
HTTP requests
| Field | Description |
|---|---|
method, uri, status | The request line and the response code |
headers | Request headers, as a map |
cookies | Request cookies |
body | Request body |
seq | Order within the session |
Header names are attacker-controlled, so a fixed exclusion list is applied at ingest: noise headers are dropped rather than stored. Everything else is kept.
DNS queries
| Field | Description |
|---|---|
name | The name queried |
type | Record type |
payload | The payload decoded from the name, when it smuggled data out |
seq | Order within the session |
Emails
Messages delivered to the SMTP sensor. Accepted and kept: the sensor delivers nothing.
| Field | Description |
|---|---|
from, to | The envelope sender and recipients, from MAIL FROM and RCPT TO |
headers | Every header value, keyed in lower case |
body | The text body |
attachments | Each attachment's name, size and SHA-256; the file is also kept as a sample |
seq | Order within the session |
VirusTotal verdicts
Keyed on file hash rather than on session, so one verdict is shared by every session that fetched the same file. The latest check only: detection counts, each engine's result and the dominant one. A hash seen in more than one session is checked once, busiest first, and again monthly while it is still seen.
Packet counters
| Field | Description |
|---|---|
packetsSent | Packets the sensor sent |
packetsReceived | Packets it received |
Sessions, timeouts and state
A session groups an attacker's activity across connections. For non-persistent protocols such as HTTP and FTP, connections from the same address are tracked under one session. For SSH and Telnet each real connection gets its own, even from the same address.
timedOut records whether the session ended because it exceeded 60 seconds from its first connection,
rather than closing naturally.