Retrieve the complete list of GreyNoise tags (from v3/tags, cached 1h). Returns JSON with count and each tag's name and slug. Takes no parameters.

Search GreyNoise tags (client-side over the cached v3/tags list). query substring-matches name/description/slug/label; category and intention are exact (case-insensitive) matches; cve substring-matches associated CVEs. All params optional; omitting all returns every tag.

Get the full record for a single GreyNoise tag, looked up by exact tag id or slug (slug matched case-insensitively) over the cached v3/tags list.

Retrieve time-series unique-IP counts and intention activity for a tag (by id/slug) or by CVE, from v3/tags/{id}/activity. Provide exactly one of id_or_slug or cve. days must be 1, 10, or 30 (default 30); granularity is 1h for 1 day, else 24h.

Filter GreyNoise tags then aggregate their v3/tags/{id}/activity into a summary (total active IPs by classification, most active tags, per-tag detail). query substring-matches name/description/slug/label; category and intention are exact (case-insensitive) matches. days must be 1, 10, or 30 (default 30).

List currently trending and anomalous GreyNoise vulnerability tags. Takes no parameters. Makes two calls (sort=trending, sort=anomalies) and returns the combined set with a 'source' field per tag plus a total count.

Get detailed GreyNoise context for a single IP: classification, tags, Internet Scanner Intelligence (scan/HTTP/TLS/SSH/TCP raw data), Business Service Intelligence, geo, and network metadata.

Get a fast, lightweight classification and business-service check for a single IP address.

Check up to 10,000 IP addresses at once. Returns classification, business-service status, and trust level for each, plus a summary breakdown.

Get aggregate statistics for results matching a GreyNoise GNQL query.

GNQL (GreyNoise Query Language) is a domain-specific query language that uses Lucene deep under the hood.

Facets:

• "ip" - The IP address of the scanning device IP

• "classification" - Whether the device has been categorized as unknown, benign, or malicious

• "first_seen" - The date the device was first observed by GreyNoise

• "last_seen" - The date the device was most recently observed by GreyNoise

• "actor" - The benign actor the device has been associated with, such as Shodan, Censys, GoogleBot, etc

• "tags" - A list of the tags the device has been assigned over the past 90 days

• "spoofable" - This IP address has been opportunistically scanning the Internet, however has failed to complete a full TCP connection. Any reported activity could be spoofed.

• "vpn" - This IP is associated with a VPN service. Activity, malicious or otherwise, should not be attributed to the VPN service provider.

• "vpn_service" - The VPN service the IP is associated with

• "cve" - A list of CVEs that the device has been associated with

• "bot" - If the IP is known to belong to a known BOT

• "single_destination" - A boolean parameter that filters source country IPs that have only been observed in a single destination country

• "metadata.category" - Whether the device belongs to a business, isp, hosting, education, or mobile network

• "metadata.country" - The full name of the country the device is geographically located in (This is the same data as "metadata.source_country". "metadata.source_country" is preferred)

• "metadata.country_code" - The two-character country code of the country the device is geographically located in (This is the same data as "metadata.source_country_code". "metadata.source_country_code" is preferred)

• "metadata.sensor_hits" - The amount of unique data that has been recorded by the sensor

• "metadata.sensor_count" - The number of sensors the IP Address has been observed on

• "metadata.city" - The city the device is geographically located in

• "metadata.region" - The region the device is geographically located in

• "metadata.organization" - The organization that owns the network that the IP address belongs to

• "metadata.rdns" - The reverse DNS pointer of the IP

• "metadata.asn" - The autonomous system the IP address belongs to

• "metadata.tor" - Whether or not the device is a known Tor exit node

• "metadata.destination_country" - The full name where the GreyNoise sensor is physically located

• "metadata.destination_country_code" - The country code where GreyNoise sensor is physically located

• "metadata.source_country_code" - The two-character country code of the country the device is geographically located in

• "metadata.source_country" - The full name of the country the device is geographically located in

• "raw_data.scan.port" - The port number(s) the devices has been observed scanning

• "raw_data.scan.protocol" - The protocol of the port the device has been observed scanning

• "raw_data.web.paths" - Any HTTP paths the device has been observed crawling the Internet for

• "raw_data.web.useragents" - Any HTTP user-agents the device has been observed using while crawling the Internet

• "raw_data.ja3.fingerprint" - The JA3 TLS/SSL fingerprint

• "raw_data.ja3.port" - The corresponding TCP port for the given JA3 fingerprint

• "raw_data.hassh.fingerprint" - The HASSH fingerprint

• "raw_data.hassh.port" - The corresponding TCP port for the given HASSH fingerprint

Behavior:

• You can subtract facets by prefacing the query with a minus character

• The data that this endpoint queries refreshes once per hour

Shortcuts:

• You can find interesting hosts by using the GNQL query term "interesting"

• You can use the keyword "today" in the "first_seen" and "last_seen" parameters: "last_seen:today" or "first_seen:today"

Examples:

• "last_seen:today" - Returns all IPs scanning/crawling the Internet today

• "tags:Mirai" - Returns all devices with the "Mirai" tag

• "tags:"RDP Scanner"" - Returns all devices with the "RDP Scanner" tag

• "classification:malicious metadata.country:Belgium" — Returns all compromised devices located in Belgium

• "classification:malicious metadata.rdns:.gov" - Returns all compromised devices that include .gov in their reverse DNS records

• "metadata.organization:Microsoft classification:malicious" — Returns all compromised devices that belong to Microsoft

• "(raw_data.scan.port:445 and raw_data.scan.protocol:TCP) metadata.os:Windows*" - Return all devices scanning the Internet for port 445/TCP running Windows operating systems (Conficker/EternalBlue/WannaCry)

• "raw_data.scan.port:554" - Returns all devices scanning the Internet for port 554

• "-metadata.organization:Google raw_data.web.useragents:GoogleBot" — Returns all devices crawling the Internet with "GoogleBot" in their useragent from a network that does NOT belong to Google

• "tags:"Siemens PLC Scanner" -classification:benign" - Returns all devices scanning the Internet for SCADA devices who ARE NOT tagged by GreyNoise as "benign" (Shodan/Project Sonar/Censys/Google/Bing/etc)

• "classification:benign" - Returns all "good guys" scanning the Internet

• "raw_data.ja3.fingerprint:795bc7ce13f60d61e9ac03611dd36d90" — Returns all devices crawling the Internet with a matching client JA3 TLS/SSL fingerprint

• "raw_data.hassh.fingerprint:51cba57125523ce4b9db67714a90bf6e" — Returns all devices crawling the Internet with a matching client HASSH fingerprint

• "raw_data.web.paths:"/HNAP1/"" -Returns all devices crawling the Internet for the HTTP path "/HNAP1/"

• "8.0.0.0/8" - Returns all devices scanning the Internet from the CIDR block 8.0.0.0/8

• "cve:CVE-2021-30461" - Returns all devices associated with the supplied CVE

• "source_country:Iran" - Returns all results originating from Iran

• "destination_country:Ukraine single_destination:true" — Returns all results scanning in only Ukraine

Search GreyNoise data using GNQL (GreyNoise Query Language). Returns full IP context results including raw scan data.

GNQL is a domain-specific query language that uses Lucene deep under the hood.

Facets:

• "ip" - The IP address of the scanning device

• "classification" - Whether the device has been categorized as unknown, benign, or malicious

• "first_seen" / "last_seen" - Date the device was first/most recently observed

• "actor" - The benign actor the device has been associated with (Shodan, Censys, etc)

• "tags" - Tags assigned to the device over the past 90 days

• "cve" - CVEs associated with the device

• "vpn" / "vpn_service" / "bot" / "tor" - Boolean/string indicators

• "metadata.category" - Network category (business, isp, hosting, education, mobile)

• "metadata.source_country" / "metadata.source_country_code" - Source location

• "metadata.organization" / "metadata.asn" / "metadata.rdns" - Network info

• "raw_data.scan.port" / "raw_data.scan.protocol" - Scan targets

• "raw_data.web.paths" / "raw_data.web.useragents" - HTTP activity

• "raw_data.ja3.fingerprint" / "raw_data.hassh.fingerprint" - TLS/SSH fingerprints

Examples:

• "classification:malicious last_seen:1d" - Malicious IPs seen in last day

• "tags:Mirai" - Devices tagged as Mirai

• "raw_data.scan.port:445 metadata.os:Windows*" - Windows hosts scanning port 445

• "cve:CVE-2021-30461" - Devices associated with a CVE

• "source_country:Iran destination_country:Ukraine single_destination:true" - Targeted scanning

Results are paginated. Use the scroll parameter to retrieve additional pages.

Search GreyNoise data using GNQL, returning IP metadata without raw scan data. Lighter and faster than gnql-query.

Supports the same GNQL query syntax as gnql-query. Use this when you need IP classification, tags, and metadata but not raw scan details (ports, fingerprints, HTTP paths).

Results are paginated via the scroll token. Set quick=true to return only IP and classification/trust level.

Set format="csv" for spreadsheet-friendly CSV output (columns: ip, classification, actor, organization, source_country, tags, ports, bsi_found, bsi_name, bsi_trust_level); default "json" renders a Markdown summary. structuredContent is always the full JSON regardless of format.

Retrieve hourly GNQL records for a time range. Enables temporal analysis of IP activity matching any GNQL query (Recall).

Returns IP records bucketed by hour, useful for investigating when specific IPs were active and what they were doing.

Time bounds use ISO 8601 (e.g. 2025-01-15T00:00:00Z). size is results per hourly bucket (default: 25, max: 10000).

Get the number of unique IPs matching a GNQL query per hour/day over a time range (Recall Stats).

Returns aggregated counts of unique IPs per time bucket, useful for trend analysis and understanding how scanning/attack activity changes over time.

interval must be 'hour' or 'day'. Time bounds use ISO 8601 format.

Get GreyNoise vulnerability intelligence for one CVE: CVSS/EPSS scores, KEV status, exploitation stats, and observed benign/threat IP activity. cve_id must match 'CVE-YYYY-NNNNN' (e.g. CVE-2023-6549); case-insensitive.

Get full metadata and connection details for a single GreyNoise sensor session by its ID. Returns source/destination IPs and ports, timestamps, byte/packet counts, classification, and any additional enrichment fields.

Download the raw PCAP capture for a single GreyNoise sensor session. Saves the binary PCAP file to a temporary directory and returns the file path. The file can be opened with Wireshark, tshark, or tcpdump.

Export a PCAP file containing packets from multiple GreyNoise sensor sessions matching query criteria. Saves the binary PCAP to a temporary directory and returns the file path. The file can be opened with Wireshark, tshark, or tcpdump.

Use Lucene query syntax to filter sessions (e.g., "destination.port:443", "source.ip:1.2.3.4").

Query and filter GreyNoise sensor network sessions over a time range. Returns a paginated list with source/destination IPs and ports, timestamps, byte/packet counts, and classification. Use Lucene query syntax (e.g. destination.port:443).

Discover the queryable session field schema: field identifiers, types, groups, and whether each is sortable. Use these field names when building session queries, counts, connections, timeseries, and unique-value requests.

Aggregate session counts grouped by one or more fields over a time range. Multiple fields produce nested (drill-down) buckets.

Build a connection graph (nodes + links) between a source field and a destination field over a time range. Useful for visualizing communication relationships.

Return session volume over time, optionally grouped by a field. Without a field, returns a single timeseries; with a field, returns per-group timeseries.

Return the distinct values of a single session field over a time range (server produces a CSV). Optionally include per-value counts. Useful for extracting distinct IPs, ports, or other field values matching a query.

Download a single session's data for a given session ID as a PCAP or raw payload (type: pcap | rawSource | rawDestination; default pcap). Saves the binary to a temp file and returns its path. Not available when scope=demo.

Look up a single callback/C2 IP: attack stage, scanner associations, RIOT status, geo/network enrichment, and downloaded malware files.

Paginated list of callback/C2 IPs filtered by attack stage, first/last seen date ranges, file attributes, and scanner associations. Dates are YYYY-MM-DD.

Export callback/C2 IPs matching the filters as a plain list. Same filters as List Callback IPs. Dates are YYYY-MM-DD.

Aggregate statistics for callback/C2 IPs matching the filters: counts by attack stage, file analysis status, RIOT trust levels, scanner associations, and top threat names. Bounded to a recent window (days: 1-7, default 1) — wider ranges overload the aggregation.

Look up Business Service Intelligence provider matches for a single IPv4 address. Returns providers whose CIDRs contain the IP, in ascending precedence order (lower = higher priority). IPv6 is rejected. Requires a BSI license.

Look up BSI provider matches for up to 1,000 IPv4 addresses. Results preserve request order; any IPv6 address fails the whole request with HTTP 400. Requires a BSI license.

Counts of BSI IPs and CIDRs grouped by trust level. Requires BSI entitlements.

Counts of BSI IPs and CIDRs grouped by company name. Requires BSI entitlements.

Counts of BSI IPs and CIDRs grouped by category. Requires BSI entitlements.

Create a dynamic blocklist from a GNQL query. The blocklist auto-populates with IPs matching the query. Requires a plan entitled to blocklists.

List the blocklists in a workspace.

Retrieve a single blocklist's configuration by ID.

Update a blocklist's query, name, IP limit, or enabled state.

Permanently delete a blocklist. This cannot be undone.

Retrieve the current list of IPs in a blocklist.

Create a scheduled alert that runs a GNQL query and notifies recipients (email/webhook) when it matches. Requires a plan entitled to alerts.

List the alerts configured in a workspace.

Retrieve a single alert's configuration by ID.

Update an alert's query, schedule, recipients, name, or enabled state.

Permanently delete an alert. This cannot be undone.

Enable (resume) a previously disabled alert.

Disable (pause) an alert without deleting it.

Send a test payload to a webhook URL to verify delivery before wiring it to an alert.