HoneyLabs MCP Server

The population behind one client fingerprint over the full retained window: how many source addresses carry it, across how many networks and countries, the ports they hit, the top networks, a sample of addresses, and a read on its shape. Use for "is this JA4 one botnet or a common tool", "how many networks use this HASSH", "how concentrated is this fingerprint". The concentration field says concentrated (many addresses on few networks), dispersed (many networks in one short burst on one or two ports, a coordinated operation spread thinly on purpose), spread (a common client) or mixed; concentrated and dispersed both point to one operator. For the individual events, use fingerprint_search_tool with a time window. fp_type: 'ja4' (TLS; a QUIC JA4 starting with q is answered from UDP traffic, whose sources can be forged), 'akin' (HTTP request shape) or 'hassh' (SSH). No date range: it reads everything retained.

Events and sources that carried one client fingerprint in a time window. Use for "have you seen this JA4", "which IPs share this TLS fingerprint", "find every scanner with this SSH client fingerprint". For how widespread a fingerprint is and whether it is one operation or a common client, use fingerprint_population_tool. For HTTP request shapes a few headers away from an Akin fingerprint, use fingerprint_similar_tool. A JA4 that starts with q comes from QUIC over UDP and is answered by udp_activity_tool. fp_type: 'ja4' (TLS client), 'ja3' (legacy TLS client hash, still keyed by many feeds), 'akin' (HTTP request shape, such as b11cun030_00040014_54d07b6d) or 'hassh' (SSH client). since and until are ISO-8601 UTC within the plan's query window. limit is 1 to 200, default 50.

HTTP request shapes within a few headers of one Akin fingerprint, with what those clients request and call themselves, and the family the fingerprint belongs to. Use when an unfamiliar request shape turns up in your own web server, WAF or proxy logs and you want to know whether it is a known tool or a variant of one: "what is close to this fingerprint", "is this the same scanner with one header added". Only Akin fingerprints work here, because a hashed fingerprint such as JA4 changes completely when one header is added. For the sources that carried the exact fingerprint, use fingerprint_search_tool. fingerprint: an Akin token such as b11cun030_00040014_54d07b6d. max_distance: 1 to 4 headers, default 2. limit: 1 to 25 neighbours, default 8.

Plaintext logins captured by the interactive sensors (sensors that answer as a real service and hold the session): username, password, the service they were tried on, the outcome and the source address, newest first, plus the pairs tried most and a per-service breakdown. Use for "what passwords are attackers trying on SSH", "which credentials did this IP try", "what logins hit MySQL this week". For whether an address is hostile overall, use ioc_lookup_tool; for the rest of what it did in its sessions, use interactive_sessions_tool. service: a service name such as ssh-password, telnet-login, mysql-login, rdp-credssp or smb-ntlmssp, or empty for all. source: an address or CIDR, or empty for all. window: 24h, 7d (default) or 30d, capped at the plan's query window. limit: 1 to 200, default 50. These records feed no verdict, and ioc_lookup_tool does not include them.

Files clients handed to the interactive sensors: uploads, mail attachments, published messages and other artifacts, by SHA-256, with name, size, MIME type, the sessions that carried them and the VirusTotal verdict when one is known. Use for "have you seen this hash", "what files did this IP upload", "which malware samples reached the honeypots this month". For files referenced by URL in exploit payloads rather than delivered in a session, use payload_search_tool with the URL or path. sha256: one hash, or empty for every file in the window. source: an address or CIDR, or empty. window: 24h, 7d or 30d (default), capped at the plan's query window. limit: 1 to 200, default 50.

Sessions one address or range held with the interactive sensors: when, which port and protocol, the service the sensor answered as, the session verdict (scan, credential or exploit), labels, turns, bytes, duration, CVE ids proven by the payload, path-only CVE candidates and the download URLs the client named, newest first, with verdict, service and port breakdowns. Use after ioc_lookup_tool when the question is what an address did inside a session: "what did this IP do on the honeypots", "did this range get past a login", "which exploits did it try". For the logins alone, use interactive_credentials_tool; for files it delivered, interactive_files_tool. source is required: an address or CIDR. window: 24h, 7d (default) or 30d, capped at the plan's query window. limit: 1 to 200, default 50.

Profile of one autonomous system (a hosting provider, ISP or company network) over a time window: total events, unique addresses, top targeted ports, source countries, top user agents and the organisation name. Use for "tell me about AS202425", "what is this hosting provider doing", "is this network a source of scanning". To attribute one address to its network, ioc_lookup_tool already returns the ASN; call this one afterwards for the network's wider behaviour. To rank networks against each other, use top_attackers_tool with by='asn'. asn: 'AS12345' or '12345'. since and until are ISO-8601 UTC within the plan's query window.

Event counts over time, in hourly or daily buckets, optionally filtered by protocol, country or destination port. Use for "show the trend this week", "was there a spike on port 22", "how has SSH scanning changed over 30 days". Do not use it to find who caused a spike (follow up with top_attackers_tool on the same window and filter) or to see the events themselves (use search_events_tool). bucket: 'hour' or 'day' (default). filter_protocol: 'tls', or '' for raw TCP. filter_country: ISO two-letter code. filter_dest_port: a port number. since and until are ISO-8601 UTC within the plan's query window. Counts are raw totals from the first-contact sensors.

Who is probing one named CVE, and how: counts, top probing addresses, networks, countries, fingerprints, sample request paths and a daily timeline. Use whenever the user names a CVE: "is CVE-2024-4577 being exploited in the wild", "who scans for CVE-2023-1389", "has anyone probed this before it was published". Do not pass a CVE id to payload_search_tool: the id is our label for a detection pattern and never appears in request text. For the list of CVEs being probed right now, use top_attackers_tool with by='cve'. Returns title, severity, actively_exploited and kev (the CISA KEV entry with date_added, or null), event and unique-address counts across both sensor types (first_contact_events and interactive_requests split them; an address both saw counts once), up to `limit` top probing addresses (1 to 25, default 25) with country, ASN and scanner (name and kind of a recognised research or vendor scanner, else null), top networks and countries, exploiter fingerprints, sample paths, a daily timeline and `interactive` (what the interactive sensors recorded of the probes). window: 24h, 7d (default), 30d or 90d, and on plans with the full history also 180d, 365d or all. observed: false with a note means we hold no detection pattern for that CVE, which is not evidence that nobody is scanning for it.

Individual honeypot events with every field, newest first, filtered by source, network, port, protocol or fingerprint. Use when the user wants to see the records themselves: "show me the events from this IP", "what hit port 443 yesterday", "every request carrying this JA4", "all RDP traffic regardless of port". Do not use it to judge one address (use ioc_lookup_tool), to rank or count (use top_attackers_tool or attack_timeline_tool), to search request text (use payload_search_tool), or for a CVE (use cve_lookup_tool). Filters, all optional and combined with AND: source_ip, country (ISO 3166 two-letter code), asn ('AS12345'), dest_port, protocol ('tls', or '' for raw TCP), app_protocol (detected layer-7 protocol such as 'ssh', 'rdp', 'mssql-tds', 'rtsp', 'smbv1', 'bittorrent' or 'mining', whatever the port), http_method, request_header (substring of the masked request headers), source_domain (reverse DNS substring), ja4 or ja3 (exact TLS client fingerprint), akin (exact HTTP request fingerprint such as b11cun030_00040014_54d07b6d), has_client_cert (true for clients that presented an mTLS certificate), ip_version (4 or 6). limit is 1 to 500, default 100. since and until are ISO-8601 UTC timestamps; the span between them may not exceed the query window of the caller's plan (https://honeylabs.net/pricing.json). Each record carries 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 ClientHello), ssh_client_hassh, tls_client_cert_subject and issuer, event_sequence, event_duration, byte counts, network_protocol, application_protocol and timestamp. TCP events from first-contact sensors only.

Everything the sensors hold on one IP address, a CIDR range, several ranges at once, or a domain, with our verdict and the reasons for it. Start here for any question about a specific indicator. Use for "is this IP malicious", "is this a known scanner", "have you seen this address", "when was it last seen", "have any of this vendor's ranges touched you". Do not use it to rank many sources (use top_attackers_tool), to profile a whole ASN (use asn_enrich_tool), or to list raw events (use search_events_tool). For what an address did inside sessions with the interactive sensors, follow up with interactive_sessions_tool. Returns total_events (0 means never observed in the window), first_seen, last_seen, country, ASN, the 50 most-hit ports with ports_targeted_count, top user agents and URL paths, TLS/HTTP/SSH fingerprints, cve_probes (the CVE signatures it was seen probing), verdict (a sentence), verdict_key (a stable value to alert on: scanner, tor, malicious, scanning, probing or none), verdict_why (the signals behind it) and scanner (the identity of a recognised research scanner, else null). Report the verdict with its reasons. A high count from a recognised scanner is research traffic, not an attack. A single address may also carry udp_unverified: UDP traffic that claimed it as source, which can be forged and never counts against it. days limits the lookback. Leave it unset for a single address to read every retained event. A CIDR or domain defaults to 90 days because neither can use an index; pass days to change that. The response names the window it used in `window`; quote it with any count. Pass ranges as one string separated by commas, spaces or newlines ('103.66.28.0/22, 8.34.210.32/27'). Never expand a range into addresses and loop: one call answers it, and looping burns the daily credits. A range answer has query_type 'cidr' or 'cidr_set', per_range counts and top_source_ips.

Literal substring search, ignoring case, over captured request text: URL path, request body, request headers and event summary. Use for "find requests to /wp-admin", "which requests carried this user agent string", "who sent '../../etc/passwd' last week". It matches text that appeared in the request and nothing else, so these return nothing: - a CVE id ('CVE-2024-4577'). Use cve_lookup_tool; this tool rejects CVE ids. - a product or vendor name ('Cisco FMC'). Search the path the product exposes instead, such as '/ccmadmin'. - a description of behaviour ('SQL injection'). Search a marker that occurs in the traffic, such as 'UNION SELECT'. For a fingerprint use fingerprint_search_tool; for events from one source use search_events_tool. An empty list is a real answer: no captured request in the window contained the string. Widen since and until before concluding the activity does not exist. since and until are ISO-8601 UTC within the plan's query window. limit is 1 to 100, default 50.

Ranked leaderboard over a time window: the top source addresses, networks, countries, destination ports, user agents, JA4 fingerprints, URL paths, reverse DNS domains or CVEs by event count. Use for "who is attacking the most", "top countries hitting port 22", "most targeted ports this week", "top networks by volume", and with by='cve' for "which CVEs are being scanned for right now". Do not use it for one known address (use ioc_lookup_tool), one known network (use asn_enrich_tool), one known CVE (use cve_lookup_tool), or a trend over time (use attack_timeline_tool). by: ip, asn, country, port, user_agent, ja4, url_path, domain or cve (default ip). limit is 1 to 100, default 20. Optional filters country (ISO code), dest_port and asn ('AS12345'); add one when the window is long, because an unfiltered ranking over many days can hit the query memory limit. by='cve' takes no filters and returns value (the CVE id), title, severity, actively_exploited (on the CISA KEV catalogue), kev_date_added and counts. since and until are ISO-8601 UTC, within the plan's query window.

UDP datagrams sent to the sensors: DNS questions, QUIC client fingerprints and other UDP probes, with the ports, networks and countries involved. Use for "who is sending DNS ANY queries", "is anyone querying version.bind", "have you seen this QUIC JA4", "which UDP ports are probed", "what hits 5060/udp". Every other tool reads TCP only, so UDP questions belong here. A UDP source address can be forged: treat each address as claimed, never as evidence against it, and do not feed it to ioc_lookup_tool as proof. query uses the /udp search grammar: 'qtype:ANY', 'qname:version.bind', 'proto:quic', 'port:5060 country:CN', 'ja4:q13d0310h3_55b375c5d22e_cd85d2d88918' or 'quic:3f1a9c2b7d40'; leave it empty for the overview. window: 24h, 7d (default) or 30d, shortened to the plan's query window when that is shorter (window_notice then says so). samples: 0 to 25 example datagrams, default 10.