Skip to main content

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​

FieldDescription
idUnique identifier for the session: the sensor's own ID for the hit, a UUIDv7
deploymentThe estate the sensor belongs to: HF1, HF2, PP1, PP2
startTimeWhen the session began. Also the partition key, which is why every query needs a range
endTimeWhen it ended
sessionLengthDuration in seconds
timedOutWhether the session ended on the 60-second timeout rather than naturally
tunnelCountHow 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​

FieldDescription
categoryExactly one of scan, attempt, intrusion-login, intrusion-commands, intrusion-control
protocolThe protocol presented: dns, doh, dot, ftp, ftps, http, http-connect, https, icmp, sftp, smtp, smtps, socks5, ssh, tcp, telnet, telnets
profileThe sensor's deployment archetype, below
loggedInWhether 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.

ValueCaptures
serverThe protocol set a general-purpose server would plausibly expose
relayThe open relay set: proxy and resolver abuse
allEvery 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​

FieldDescription
clientIPThe attacker's address. Requires IP access
clientPortIts source port
clientVersionThe client banner, where the protocol has one, e.g. SSH-2.0-libssh2_1.4.3
clientASNThe autonomous system number
clientASOrgThe autonomous system's operator
clientEconomyCodeISO 3166-1 alpha-2
clientEconomyNameThe economy's name
clientRegionCodeContinent code: AF, AN, AS, EU, NA, OC, SA
clientSubdivisionCodeState or province code, where MaxMind has one
clientCityCity name
clientLatitude, clientLongitudeCoordinates, to three decimal places
clientTimezoneIANA timezone
fingerprintsThe 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​

FieldDescription
hostIPThe sensor's own address. Requires IP access
hostPortThe port it was listening on
hostNameThe sensor's emulation name, e.g. Generic Shell
versionThe ProxyPot version that recorded it
host* geo fieldsThe same geo set as client*, for the sensor

Credentials​

FieldDescription
credentialsEvery attempt, each with username, password and whether it succeeded
loggedInName, loggedInPasswordThe 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​

FieldDescription
commandsWhat the client typed, in order
unrecognizedCommandsThe parts the sensor could not handle: an unknown program, a typo, a script it does not run
urlsURLs fetched or referenced
urlHostnamesJust the hostnames from those URLs
hashesSHA-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.

FieldDescription
typedirect-tcpip, tcpip-forward, socks5-connect, socks5-bind, socks5-udp-associate, http-connect, dns-exfiltration
sourceIP, sourcePortWhere the request said it came from
destinationIP, destinationPortWhere it asked to go
destinationHostThe destination when it was given as a hostname rather than an address
payloadWhat the client sent through it; a binary payload is recorded by size
seqOrder within the session

One row per tunnel. A hostname destination is preserved in destinationHost rather than discarded.

HTTP requests​

FieldDescription
method, uri, statusThe request line and the response code
headersRequest headers, as a map
cookiesRequest cookies
bodyRequest body
seqOrder 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​

FieldDescription
nameThe name queried
typeRecord type
payloadThe payload decoded from the name, when it smuggled data out
seqOrder within the session

Emails​

Messages delivered to the SMTP sensor. Accepted and kept: the sensor delivers nothing.

FieldDescription
from, toThe envelope sender and recipients, from MAIL FROM and RCPT TO
headersEvery header value, keyed in lower case
bodyThe text body
attachmentsEach attachment's name, size and SHA-256; the file is also kept as a sample
seqOrder 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​

FieldDescription
packetsSentPackets the sensor sent
packetsReceivedPackets 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.