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.