HoneyLabs

Return individual raw honeypot events with all fields. Use when the user wants to see actual records: 'show me events from this IP', 'what hit port 443 last week', 'events from Russia yesterday'. Filters: source_ip, country (2-letter code), asn (e.g. 'AS12345'), dest_port, protocol ('tls' or '' = the coarse TLS/raw-TCP signal), app_protocol (nDPI L7 protocol label: 'bittorrent', 'ssh', 'rdp', 'mssql-tds', 'mining', 'rtsp', 'smbv1', ... — find everything speaking a protocol regardless of port), http_method, request_header (substring of the masked HTTP request headers), source_domain (reverse DNS name, substring), ja4/ja3 (exact TLS client fingerprint), akin (exact HTTP request fingerprint, e.g. a11cun030_00000049_54d07b6d), has_client_cert (true = only events where the client presented an mTLS cert), ip_version (4 or 6 = only IPv4 or IPv6 sources). since/until are ISO-8601 UTC strings. Each record includes: source_ip, country, asn, dest_port, user_agent, url_path, http_request_headers, tls_client_ja4, tls_client_ja3, tls_client_hello_hex (the raw TLS ClientHello, for verifying or recomputing fingerprints), ssh_client_hassh, tls_client_cert_subject/issuer, event_sequence, event_duration, source_bytes/dest_bytes/network_bytes, network_protocol, application_protocol, timestamp.

{
  "type": "object",
  "properties": {
    "since": {
      "type": "string"
    },
    "until": {
      "type": "string"
    },
    "source_ip": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "country": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "asn": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "dest_port": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "protocol": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "app_protocol": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "http_method": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "source_domain": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "request_header": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "ja4": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "ja3": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "akin": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "has_client_cert": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "ip_version": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "limit": {
      "default": 100,
      "type": "integer"
    }
  },
  "required": [
    "since",
    "until"
  ],
  "additionalProperties": false
}

Ranked leaderboard of attack sources. Use for: 'who is attacking the most?', 'top attacking countries', 'most targeted ports', 'most common user agents', 'top ASNs by attack volume', 'top IPs from China', 'top attackers hitting port 22'. 'by' controls grouping: ip, asn, country, port, user_agent, ja4, url_path, domain, cve. by='cve' answers 'what CVEs are being mass-scanned right now' and returns value (the CVE id), title, severity, actively_exploited and counts; drill into any of them with cve_lookup. by='cve' does not accept the country/dest_port/asn filters. Optional filters: country (2-letter ISO, e.g. 'CN'), dest_port, asn (e.g. 'AS12345'). Adding a filter is required for large time ranges to stay within memory limits. since/until are ISO-8601 UTC strings.

{
  "type": "object",
  "properties": {
    "since": {
      "type": "string"
    },
    "until": {
      "type": "string"
    },
    "by": {
      "default": "ip",
      "type": "string"
    },
    "limit": {
      "default": 20,
      "type": "integer"
    },
    "country": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "dest_port": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "asn": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    }
  },
  "required": [
    "since",
    "until"
  ],
  "additionalProperties": false
}

Look up any IP address, CIDR network, set of networks, or domain in the honeypot dataset. Use this FIRST whenever the user asks: 'is this IP malicious?', 'is this a known scanner?', 'have you seen this IP?', 'what does this IP do?', 'when was it last seen?', 'is this IP in your data?'. Returns: total_events (0 = never observed), first_seen, last_seen, country, ASN, the 50 most-hit ports plus ports_targeted_count for the true total, top user agents, top URL paths, TLS/HTTP/SSH fingerprints. Covers both IPv4 and domains. Also returns our own judgement: `verdict` (human sentence) with `verdict_key` (stable machine value to alert on) and `verdict_why`; `scanner` (benign-scanner identity from our classification table, or null) so research traffic can be told apart from real attacks; and `cve_probes`, the CVE signatures this address was seen probing. WINDOW: `days` bounds the query to the last N days. For a single address leave it unset for every retained event, which is the right default for "have we ever seen this". A CIDR or a domain defaults to the last 90 days, because neither can use an index and unbounded they read the whole table; pass `days` explicitly to widen either back out. The website's /lookup defaults to 7 days for anonymous visitors, so the same address can read very differently on the two surfaces. Every response states which window it used in `window`; quote it alongside any count you report. RANGES: pass a CIDR ('103.66.28.0/22') for a whole-network aggregate, or several at once separated by commas, spaces or newlines ('103.66.28.0/22, 8.34.210.32/27') to answer 'have any of this vendor's ranges touched us' in ONE call. Never expand a network into individual addresses and loop -- that is hundreds of calls for an answer this returns in one, and it will exhaust your quota. A range answer sets query_type to 'cidr' or 'cidr_set', lists every range back in `ranges`, and gives `per_range` counts plus `top_source_ips`; total_events 0 with those fields present is a real observed absence.

{
  "type": "object",
  "properties": {
    "ioc": {
      "type": "string"
    },
    "days": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    }
  },
  "required": [
    "ioc"
  ],
  "additionalProperties": false
}

Who is probing a specific CVE. Use whenever the user names a CVE: 'is CVE-2024-4577 being exploited in the wild?', 'who is scanning for this CVE?', 'show me actors probing CVE-2023-1389'. Returns severity, KEV (actively_exploited), event and unique-IP counts, the top probing IPs with country/ASN/scanner tag, top ASNs, exploiter fingerprints, sample request paths and a daily timeline. window: 24h, 7d, 30d or 90d. `observed: false` with a note means we hold no detection pattern for that CVE, which is NOT the same as nobody scanning it. Do not use payload_search for a CVE id: the id is our tag for a pattern and never appears in the payload text.

{
  "type": "object",
  "properties": {
    "cve_id": {
      "type": "string"
    },
    "window": {
      "default": "7d",
      "type": "string"
    },
    "limit": {
      "default": 25,
      "type": "integer"
    }
  },
  "required": [
    "cve_id"
  ],
  "additionalProperties": false
}

Literal substring search over captured request text: URL path, request body, request headers and event summary. Use for: 'find attacks targeting /wp-admin', 'find requests with this user agent string', 'what payloads hit port 80 last week'. It matches text that literally appeared in the request, and nothing else. These do NOT work and will return an empty list: - a CVE id ('CVE-2024-4577'), which is our tag for a pattern, never payload text. Use cve_lookup instead. This tool rejects them rather than answering emptily. - a product or vendor name ('Cisco FMC', '7-Zip'), which appears in an advisory, not in the request. Search the endpoint it exposes instead, e.g. '/ccmadmin' or the vulnerable path. - a description of behaviour ('SQL injection attempts'). Search a marker that occurs in the traffic, e.g. 'UNION SELECT' or '../'. An empty list is a real answer: it means no captured request in that window contained the string. Widen since/until before concluding the activity does not exist. Free to call; volume is metered like every other tool. since/until are ISO-8601 UTC strings.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string"
    },
    "since": {
      "type": "string"
    },
    "until": {
      "type": "string"
    },
    "limit": {
      "default": 50,
      "type": "integer"
    }
  },
  "required": [
    "query",
    "since",
    "until"
  ],
  "additionalProperties": false
}

Attack volume over time, bucketed by hour or day. Use for: 'show attack trends this week', 'was there a spike on port 22?', 'how has SSH scanning changed?', 'attack volume from China over 30 days'. bucket: 'hour' or 'day'. Optional filters: filter_protocol ('tls'/'''), filter_country (2-letter code), filter_dest_port. since/until ISO-8601 UTC.

{
  "type": "object",
  "properties": {
    "since": {
      "type": "string"
    },
    "until": {
      "type": "string"
    },
    "bucket": {
      "default": "day",
      "type": "string"
    },
    "filter_protocol": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "filter_country": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "filter_dest_port": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    }
  },
  "required": [
    "since",
    "until"
  ],
  "additionalProperties": false
}

Full honeypot profile for an ASN (autonomous system / hosting provider). Use for: 'tell me about AS202425', 'what is Vultr doing in my honeypots?', 'attacks from this hosting provider', 'attribute this IP to its network'. asn format: 'AS12345'. Returns: total events, unique IPs, top targeted ports, top source countries, top user agents, org name. since/until are ISO-8601 UTC strings.

{
  "type": "object",
  "properties": {
    "asn": {
      "type": "string"
    },
    "since": {
      "type": "string"
    },
    "until": {
      "type": "string"
    }
  },
  "required": [
    "asn",
    "since",
    "until"
  ],
  "additionalProperties": false
}

Search honeypot activity by TLS, HTTP, or SSH fingerprint. Use when a user asks: 'have you seen this JA4 fingerprint?', 'which IPs share this TLS fingerprint?', 'how common is this HASSH?', 'find all scanners with this SSH client fingerprint'. fp_type: 'ja4' (TLS client), 'ja3' (legacy TLS client, MD5, still keyed by many TI feeds), 'akin' (HTTP request shape, e.g. a11cun030_00000049_54d07b6d), 'hassh' (SSH client). since/until are ISO-8601 UTC strings.

{
  "type": "object",
  "properties": {
    "fingerprint": {
      "type": "string"
    },
    "fp_type": {
      "type": "string"
    },
    "since": {
      "type": "string"
    },
    "until": {
      "type": "string"
    },
    "limit": {
      "default": 50,
      "type": "integer"
    }
  },
  "required": [
    "fingerprint",
    "fp_type",
    "since",
    "until"
  ],
  "additionalProperties": false
}

Request shapes within a few headers of an Akin HTTP fingerprint, with what those clients ask for and call themselves, plus the family the token belongs to. Use when one odd request shape turns up in your own web, WAF or proxy logs and you want to know whether it is a known tool with variants: 'what is close to this fingerprint', 'is this the same scanner with one header added', 'what does this client family go after'. max_distance is in headers, 1 to 4. Only Akin can answer this; a hashed fingerprint changes completely when a header is added.

{
  "type": "object",
  "properties": {
    "fingerprint": {
      "type": "string"
    },
    "max_distance": {
      "default": 2,
      "type": "integer"
    },
    "limit": {
      "default": 8,
      "type": "integer"
    }
  },
  "required": [
    "fingerprint"
  ],
  "additionalProperties": false
}

The population behind a single client fingerprint: how many source IPs carry it, across how many networks (ASNs) and countries, the ports they hit, the top networks and a sample of the IPs, plus a read on its shape: concentrated (many IPs on few networks), dispersed (many networks but one short burst on one or two ports, which is a coordinated operation spread thinly on purpose), spread (a common client) or mixed. Concentrated and dispersed are both coordinated operations. Use when a user asks: 'is this JA4 one botnet or a common tool?', 'how many networks use this HASSH?', 'how specific / concentrated is this fingerprint?'. fp_type: 'ja4' (TLS), 'akin' (HTTP request shape) or 'hassh' (SSH). Covers the full retained window (no date range).

{
  "type": "object",
  "properties": {
    "fingerprint": {
      "type": "string"
    },
    "fp_type": {
      "type": "string"
    }
  },
  "required": [
    "fingerprint",
    "fp_type"
  ],
  "additionalProperties": false
}