--- updatedAt: 2026-04-29T22:56:06.000Z agentTools: projectIndex: https://docs.greynoise.io/llms.txt --- # GNQL V3 Query GreyNoise Query Language GNQL (GreyNoise Query Language) is a domain-specific query language that uses Lucene deep under the hood. GNQL aims to enable GreyNoise Enterprise and Research users to make complex and one-off queries against the GreyNoise dataset as new business cases arise. GNQL is built with self-defeat and fully featured product lines in mind. If we do our job correctly, each individual GNQL query that brings our users and customers sufficient value will eventually be transitioned into it's own individual offering. _License: The `business_service_intelligence` response field requires the BSI Module. Without it, every result returns an empty `business_service_intelligence` object; all other fields are returned normally._ 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 * `tor` - Whether or not the device is a known Tor exit node * `cve` - A list of CVEs that the device has been associated with * `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.carrier` - The Internet Service Provider (ISP) or telecommunications carrier associated with the source IP address * `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.datacenter` - The datacenter or hosting provider from which the activity originates. This could indicate the use of cloud services, managed hosting, or enterprise datacenter infrastructure. * `metadata.domain` - The domain name associated with the source IP address * `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.asn_subnet` - Exact match on the latest-observed ASN subnet for the IP in GreyNoise scan data * `metadata.destination_cities` - The city where the GreyNoise sensor is geographically located * `metadata.destination_asns` - The ASN associated with the destination IP address * `metadata.destination_countries` - The full country name where the GreyNoise sensors are physically located * `metadata.destination_country_codes` - The country code where the GreyNoise sensors are physically located * `metadata.destination_country` - The full country name where the GreyNoise sensors are physically located * `metadata.destination_country_code` - The country code where the GreyNoise sensors are physically located * `metadata.latitude` - The geographic latitude of the source IP address * `metadata.longitude` - The geographic longitude of the source IP address * `metadata.rdns_parent` - The parent domain retrieved through reverse DNS (RDNS) lookup of the source IP address * `metadata.rdns_validated` - A validation status that confirms whether the reverse DNS (RDNS) record correctly maps to the source domain * `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 being targeted on a GreyNoise sensor * `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 * `raw_data.http.md5` - An MD5 hash of the body content. This compact, unique representation of the data allows for quick comparisons and deduplication of payloads without storing the raw content. * `raw_data.http.cookie_keys` - The keys or names of cookies exchanged in the communication. These can reveal session identifiers, tracking mechanisms, or other metadata used in web interactions, providing clues about application behavior or vulnerabilities. * `raw_data.http.request_authorization` - The contents of the Authorization header in a request, typically containing authentication credentials or tokens (e.g., Basic Auth, Bearer tokens). Analyzing this helps verify authorization mechanisms and detect credential misuse or token abuse. * `raw_data.http.request_cookie` - Key-value pairs stored in cookies sent with an HTTP request. These cookies often contain session identifiers, user preferences, or tracking data, which can be analyzed to detect unauthorized access or manipulation. * `raw_data.http.request_header` - Request Headers are the keys (names) of HTTP headers that a client sends to a server. * `raw_data.http.request_method` - The HTTP method used in the request, such as GET, POST, PUT, or DELETE. Analyzing methods can reveal the intent of the request, such as retrieving or modifying resources, and identify unexpected or suspicious activity. * `raw_data.http.request_origin` - Indicates the origin of the request, typically used in cross-origin resource sharing (CORS) to specify where the request originated. This helps identify unauthorized or potentially malicious cross-origin requests. * `raw_data.tls.cipher` - The encryption algorithm or cipher suite used during the secure communication. Identifying the cipher helps assess the security of the connection, particularly in TLS/SSL traffic. * `raw_data.tls.ja4` - JA4 TLS fingerprint. JA4 captures distinctive characteristics of TLS client behavior, useful for identifying and clustering malicious or anomalous clients. * `raw_data.http.ja4h` - JA4H HTTP client fingerprint. Captures characteristics of HTTP client behavior including method, headers, and cookie fields, useful for identifying and tracking HTTP clients. * `raw_data.ssh.ja4ssh` - JA4SSH fingerprint. Captures SSH traffic patterns including packet lengths and directions, useful for identifying SSH client behavior and detecting anomalous sessions. * `raw_data.tcp.ja4t` - JA4T TCP fingerprint. Captures TCP connection characteristics such as window size, options, and MSS, useful for OS fingerprinting and identifying network stacks. * `raw_data.tcp.ja4l` - JA4L light distance/latency fingerprint. Captures TCP TTL and window size characteristics, useful for estimating client-server distance and identifying proxied connections. Behavior: * `raw_data.ssh.key` - This is the SSH key used. * You can subtract facets by prefacing the query with a minus character * Numeric facets such as `raw_data.scan.port` take inclusive ranges and lists: `raw_data.scan.port:[1-1024]` (or `[1 TO 1024]`), `raw_data.scan.port:[1024 TO *]`, `raw_data.scan.port:[22,23,2323]` and `raw_data.scan.port:[22, 80-90]`. For example, `raw_data.scan.port:502 -raw_data.scan.port:[0-501] -raw_data.scan.port:[503-65535]` returns IPs that scanned port 502 and no other port * `first_seen` and `last_seen` take day values (`today`, `yesterday`, `7d`, `2w`, `3m`, `1y` or a date such as `2026-07-01`) and hour values such as `last_seen:24h`. A day value covers whole UTC days, so `last_seen:1d` returns IPs last seen since the start of yesterday (UTC). An hour value counts back from the moment of the request, so `last_seen:24h` returns IPs last seen in the past 24 hours. Note that `m` means months; there is no minutes unit * Both kinds of value take the comparison operators `>=` (the default), `>`, `<=` and `<`: `last_seen:<=48h` returns IPs not seen for at least 48 hours, and `last_seen:>=72h last_seen:<48h` returns IPs last seen between 72 and 48 hours ago. A quoted UTC timestamp such as `last_seen:">=2026-07-01T12:30:00Z"` also counts as an hour value * An hour value must reach back at least 24 hours: `last_seen:24h`, `last_seen:48h` and quoted timestamps at least a day old are allowed, while `last_seen:23h` returns `400` with the code `UNSUPPORTED_DATE_RESOLUTION`. Select plans may reach closer to now: with a one-hour limit `last_seen:1h` is allowed; with a six-hour limit `last_seen:6h` is allowed but `last_seen:2h` returns `400` * GreyNoise moves an IP's recorded `last_seen` forward at most about once an hour, so an IP last seen near the start of an hour-value window can carry a `last_seen` from up to an hour earlier and be left out of it * 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 * `classification:malicious last_seen:24h` - Returns malicious IPs last seen in the past 24 hours, counted back from the request rather than from midnight UTC * `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.tls.ja4:t13d1516h2_8daaf6152771_02713d6af862` - Returns all devices with a matching JA4 TLS fingerprint * `raw_data.http.ja4h:ge11cn060000_4e59edc1297a_4da5efaf0cbd` - Returns all devices with a matching JA4H HTTP fingerprint * `raw_data.ssh.ja4ssh:c76s76_c71s59_c0s0` - Returns all devices with a matching JA4SSH fingerprint * `raw_data.tcp.ja4t:64240_2-1-3-1-1-4_1460_8` - Returns all devices with a matching JA4T TCP fingerprint * `raw_data.tcp.ja4l:1460_64` - Returns all devices with a matching JA4L light distance/latency 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 # OpenAPI definition ```json { "openapi": "3.0.0", "info": { "description": "GreyNoise is a cybersecurity company that collects and analyzes Internet-wide scan and attack traffic. Use GreyNoise to contextualize existing alerts, filter false-positives, identify compromised devices, and track emerging threats.", "version": "3.0.0", "title": "GreyNoise API", "contact": { "email": "hello@greynoise.io" }, "license": { "name": "Proprietary", "url": "https://www.greynoise.io/terms" } }, "tags": [ { "name": "GNQL", "description": "Calls to interface with GNQL (GreyNoise Query Language)." } ], "security": [ { "APIKeyHeaderAuth": [] } ], "paths": { "/v3/gnql": { "get": { "tags": [ "GNQL" ], "summary": "GNQL V3 Query", "operationId": "gnqlV3Query", "description": "GreyNoise Query Language\nGNQL (GreyNoise Query Language) is a domain-specific query language\nthat uses Lucene deep under the hood. GNQL aims to enable GreyNoise\nEnterprise and Research users to make complex and one-off queries\nagainst the GreyNoise dataset as new business cases arise. GNQL is\nbuilt with self-defeat and fully featured product lines in mind. If\nwe do our job correctly, each individual GNQL query that brings our\nusers and customers sufficient value will eventually be transitioned\ninto it's own individual offering.\n_License: The `business_service_intelligence` response field\nrequires the BSI Module. Without it, every result returns an empty\n`business_service_intelligence` object; all other fields are\nreturned normally._\nFacets:\n* `ip` - The IP address of the scanning device IP\n* `classification` - Whether the device has been categorized as\nunknown, benign, or malicious\n* `first_seen` - The date the device was first observed by GreyNoise\n* `last_seen` - The date the device was most recently observed\nby GreyNoise\n* `actor` - The benign actor the device has been associated with,\nsuch as Shodan, Censys, GoogleBot, etc\n* `tags` - A list of the tags the device has been assigned over the\npast 90 days\n* `spoofable` - This IP address has been opportunistically scanning the\nInternet, however has failed to complete a full TCP connection. Any\nreported activity could be spoofed.\n* `vpn` - This IP is associated with a VPN service. Activity, malicious\nor otherwise, should not be attributed to the VPN service provider.\n* `vpn_service` - The VPN service the IP is associated with\n* `tor` - Whether or not the device is a known Tor exit node\n* `cve` - A list of CVEs that the device has been associated with\n* `single_destination` - A boolean parameter that filters source country\nIPs that have only been observed in a single destination country\n* `metadata.category` - Whether the device belongs to a business, isp,\nhosting, education, or mobile network\n* `metadata.carrier` - The Internet Service Provider (ISP) or telecommunications carrier\nassociated with the source IP address\n* `metadata.country` - The full name of the country the device is\ngeographically located in (This is the same data as\n`metadata.source_country`. `metadata.source_country` is preferred)\n* `metadata.country_code` - The two-character country code of the\ncountry the device is geographically located in (This is the same data\nas `metadata.source_country_code`. `metadata.source_country_code`\nis preferred)\n* `metadata.datacenter` - The datacenter or hosting provider from which the activity originates.\nThis could indicate the use of cloud services, managed hosting,\nor enterprise datacenter infrastructure.\n* `metadata.domain` - The domain name associated with the source IP address\n* `metadata.sensor_hits` - The amount of unique data that has been recorded by the sensor\n* `metadata.sensor_count` - The number of sensors the IP Address has been observed on\n* `metadata.city` - The city the device is geographically located in\n* `metadata.region` - The region the device is geographically located in\n* `metadata.organization` - The organization that owns the network that\nthe IP address belongs to\n* `metadata.rdns` - The reverse DNS pointer of the IP\n* `metadata.asn` - The autonomous system the IP address belongs to\n* `metadata.asn_subnet` - Exact match on the latest-observed ASN subnet for the IP in GreyNoise scan data\n* `metadata.destination_cities` - The city where the GreyNoise sensor is geographically located\n* `metadata.destination_asns` - The ASN associated with the destination IP address\n* `metadata.destination_countries` - The full country name where the GreyNoise\nsensors are physically located\n* `metadata.destination_country_codes` - The country code where the GreyNoise\nsensors are physically located\n* `metadata.destination_country` - The full country name where the GreyNoise\nsensors are physically located\n* `metadata.destination_country_code` - The country code where the GreyNoise\nsensors are physically located\n* `metadata.latitude` - The geographic latitude of the source IP address\n* `metadata.longitude` - The geographic longitude of the source IP address\n* `metadata.rdns_parent` - The parent domain retrieved through reverse DNS (RDNS)\nlookup of the source IP address\n* `metadata.rdns_validated` - A validation status that confirms whether the\nreverse DNS (RDNS) record correctly maps to the source domain\n* `metadata.source_country_code` - The two-character country code of the\ncountry the device is geographically located in\n* `metadata.source_country` - The full name of the country the device is\ngeographically located in\n* `raw_data.scan.port` - The port being targeted on a GreyNoise sensor\n* `raw_data.scan.protocol` - The protocol of the port the device has\nbeen observed scanning\n* `raw_data.web.paths` - Any HTTP paths the device has been observed\ncrawling the Internet for\n* `raw_data.web.useragents` - Any HTTP user-agents the device has been\nobserved using while crawling the Internet\n* `raw_data.ja3.fingerprint` - The JA3 TLS/SSL fingerprint\n* `raw_data.ja3.port` - The corresponding TCP port for the given JA3\nfingerprint\n* `raw_data.hassh.fingerprint` - The HASSH fingerprint\n* `raw_data.hassh.port` - The corresponding TCP port for the given HASSH\nfingerprint\n* `raw_data.http.md5` - An MD5 hash of the body content. This compact,\nunique representation of the data allows for quick comparisons and\ndeduplication of payloads without storing the raw content.\n* `raw_data.http.cookie_keys` - The keys or names of cookies exchanged in the\ncommunication. These can reveal session identifiers, tracking mechanisms,\nor other metadata used in web interactions,\nproviding clues about application behavior or vulnerabilities.\n* `raw_data.http.request_authorization` - The contents of the Authorization header in a request,\ntypically containing authentication credentials or tokens (e.g., Basic Auth, Bearer tokens).\nAnalyzing this helps verify authorization mechanisms and detect credential misuse or token abuse.\n* `raw_data.http.request_cookie` - Key-value pairs stored in cookies sent with an HTTP request.\nThese cookies often contain session identifiers, user preferences, or tracking data,\nwhich can be analyzed to detect unauthorized access or manipulation.\n* `raw_data.http.request_header` - Request Headers are the keys (names) of HTTP headers that a\nclient sends to a server.\n* `raw_data.http.request_method` - The HTTP method used in the request, such as GET, POST, PUT, or DELETE.\nAnalyzing methods can reveal the intent of the request, such as retrieving or modifying resources,\nand identify unexpected or suspicious activity.\n* `raw_data.http.request_origin` - Indicates the origin of the request, typically used in\ncross-origin resource sharing (CORS) to specify where the request originated.\nThis helps identify unauthorized or potentially malicious cross-origin requests.\n* `raw_data.tls.cipher` - The encryption algorithm or cipher suite used during\nthe secure communication. Identifying the cipher helps assess the\nsecurity of the connection, particularly in TLS/SSL traffic.\n* `raw_data.tls.ja4` - JA4 TLS fingerprint. JA4 captures distinctive\ncharacteristics of TLS client behavior, useful for identifying and\nclustering malicious or anomalous clients.\n* `raw_data.http.ja4h` - JA4H HTTP client fingerprint. Captures\ncharacteristics of HTTP client behavior including method, headers,\nand cookie fields, useful for identifying and tracking HTTP clients.\n* `raw_data.ssh.ja4ssh` - JA4SSH fingerprint. Captures SSH traffic\npatterns including packet lengths and directions, useful for\nidentifying SSH client behavior and detecting anomalous sessions.\n* `raw_data.tcp.ja4t` - JA4T TCP fingerprint. Captures TCP\nconnection characteristics such as window size, options, and MSS,\nuseful for OS fingerprinting and identifying network stacks.\n* `raw_data.tcp.ja4l` - JA4L light distance/latency fingerprint.\nCaptures TCP TTL and window size characteristics, useful for\nestimating client-server distance and identifying proxied connections.\nBehavior:\n* `raw_data.ssh.key` - This is the SSH key used.\n* You can subtract facets by prefacing the query with a minus character\n* Numeric facets such as `raw_data.scan.port` take inclusive ranges and\nlists: `raw_data.scan.port:[1-1024]` (or `[1 TO 1024]`),\n`raw_data.scan.port:[1024 TO *]`, `raw_data.scan.port:[22,23,2323]`\nand `raw_data.scan.port:[22, 80-90]`. For example,\n`raw_data.scan.port:502 -raw_data.scan.port:[0-501] -raw_data.scan.port:[503-65535]`\nreturns IPs that scanned port 502 and no other port\n* `first_seen` and `last_seen` take day values (`today`, `yesterday`,\n`7d`, `2w`, `3m`, `1y` or a date such as `2026-07-01`) and hour values\nsuch as `last_seen:24h`. A day value covers whole UTC days, so\n`last_seen:1d` returns IPs last seen since the start of yesterday\n(UTC). An hour value counts back from the moment of the request, so\n`last_seen:24h` returns IPs last seen in the past 24 hours. Note that\n`m` means months; there is no minutes unit\n* Both kinds of value take the comparison operators `>=` (the\ndefault), `>`, `<=` and `<`: `last_seen:<=48h` returns IPs not seen\nfor at least 48 hours, and `last_seen:>=72h last_seen:<48h` returns\nIPs last seen between 72 and 48 hours ago. A quoted UTC timestamp\nsuch as `last_seen:\">=2026-07-01T12:30:00Z\"` also counts as an hour\nvalue\n* An hour value must reach back at least 24 hours: `last_seen:24h`,\n`last_seen:48h` and quoted timestamps at least a day old are\nallowed, while `last_seen:23h` returns `400` with the code\n`UNSUPPORTED_DATE_RESOLUTION`. Select plans may reach closer to now:\nwith a one-hour limit `last_seen:1h` is allowed; with a six-hour\nlimit `last_seen:6h` is allowed but `last_seen:2h` returns `400`\n* GreyNoise moves an IP's recorded `last_seen` forward at most about\nonce an hour, so an IP last seen near the start of an hour-value\nwindow can carry a `last_seen` from up to an hour earlier and be\nleft out of it\n* The data that this endpoint queries refreshes once per hour\nShortcuts:\n* You can find interesting hosts by using the GNQL query term\n`interesting`\n* You can use the keyword `today` in the `first_seen` and\n`last_seen` parameters: `last_seen:today` or `first_seen:today`\nExamples:\n* `last_seen:today` - Returns all IPs scanning/crawling the\nInternet today\n* `classification:malicious last_seen:24h` - Returns malicious IPs\nlast seen in the past 24 hours, counted back from the request rather\nthan from midnight UTC\n* `tags:Mirai` - Returns all devices with the \"Mirai\" tag\n* `tags:\"RDP Scanner\"` - Returns all devices with the \"RDP\nScanner\" tag\n* `classification:malicious metadata.country:Belgium`\n- Returns all compromised devices located in Belgium\n* `classification:malicious metadata.rdns:*.gov*` - Returns\nall compromised devices that include .gov in their reverse DNS records\n* `metadata.organization:Microsoft classification:malicious`\n- Returns all compromised devices that belong to Microsoft\n* `(raw_data.scan.port:445 and raw_data.scan.protocol:TCP)\nmetadata.os:Windows*` - Return all devices scanning the Internet\nfor port 445/TCP running Windows operating systems\n(Conficker/EternalBlue/WannaCry)\n* `raw_data.scan.port:554` - Returns all devices scanning the\nInternet for port 554\n* `-metadata.organization:Google raw_data.web.useragents:GoogleBot`\n- Returns all devices crawling the Internet with \"GoogleBot\" in\ntheir useragent from a network that does NOT belong to Google\n* `tags:\"Siemens PLC Scanner\" -classification:benign` - Returns\nall devices scanning the Internet for SCADA devices who ARE\nNOT tagged by GreyNoise as \"benign\"\n(Shodan/Project Sonar/Censys/Google/Bing/etc)\n* `classification:benign` - Returns all \"good guys\" scanning\nthe Internet\n* `raw_data.ja3.fingerprint:795bc7ce13f60d61e9ac03611dd36d90`\n- Returns all devices crawling the Internet with a matching\nclient JA3 TLS/SSL fingerprint\n* `raw_data.hassh.fingerprint:51cba57125523ce4b9db67714a90bf6e`\n- Returns all devices crawling the Internet with a matching\nclient HASSH fingerprint\n* `raw_data.tls.ja4:t13d1516h2_8daaf6152771_02713d6af862`\n- Returns all devices with a matching JA4 TLS fingerprint\n* `raw_data.http.ja4h:ge11cn060000_4e59edc1297a_4da5efaf0cbd`\n- Returns all devices with a matching JA4H HTTP fingerprint\n* `raw_data.ssh.ja4ssh:c76s76_c71s59_c0s0`\n- Returns all devices with a matching JA4SSH fingerprint\n* `raw_data.tcp.ja4t:64240_2-1-3-1-1-4_1460_8`\n- Returns all devices with a matching JA4T TCP fingerprint\n* `raw_data.tcp.ja4l:1460_64`\n- Returns all devices with a matching JA4L light\ndistance/latency fingerprint\n* `raw_data.web.paths:\"/HNAP1/\"` -Returns all devices crawling\nthe Internet for the HTTP path \"/HNAP1/\"\n* `8.0.0.0/8` - Returns all devices scanning the Internet from\nthe CIDR block 8.0.0.0/8\n* `cve:CVE-2021-30461` - Returns all devices associated with the\nsupplied CVE\n* `source_country:Iran` - Returns all results originating from Iran\n* `destination_country:Ukraine single_destination:true`\n- Returns all results scanning in only Ukraine\n", "parameters": [ { "$ref": "#/components/parameters/query" }, { "in": "query", "name": "size", "description": "The number of results provided per page for paginating through all results of a query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 10000 } }, { "in": "query", "name": "scroll", "description": "Scroll token to paginate through results. Incompatible with `format=csv`.", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "quick", "description": "If true, the response will only include the IP address and the classification or trust level.", "required": false, "schema": { "type": "boolean", "default": false } }, { "in": "query", "name": "format", "description": "Specifies the desired format of the results. Must be either csv or json.", "required": false, "schema": { "type": "string", "enum": [ "csv", "json" ], "default": "json" } }, { "in": "query", "name": "exclude", "description": "Comma-separated list of fields to exclude from the response.\nRecognized top-level response fields (e.g. `tags`, `cves`, `vpn`, `tor`, `raw_data`, `metadata`),\n`metadata.` paths (e.g. `metadata.organization`, `metadata.source_country`,\n`metadata.destination_countries`), and `raw_data.` paths (e.g. `raw_data.ja3`,\n`raw_data.http.useragent`) are accepted. The special value `tags.details` preserves tag\nidentity (id, slug) and strips only the enriched details. Unknown field names return 400.\n", "required": false, "schema": { "type": "string", "example": "metadata.organization,metadata.city,raw_data.ja3" } } ], "responses": { "200": { "description": "OK - request successful.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/GNQLV3Response" }, { "$ref": "#/components/schemas/QuickGNQLV3Response" } ] } } } }, "206": { "description": "Partial content - request partially successful.\nDue to plan limitations, your request only returned a subset of\nfields and/or data. Contact sales@greynoise.io to upgrade your\nplan and unlock full results.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GNQLV3Response" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/ExceededLimit" } } } } }, "servers": [ { "url": "https://api.greynoise.io" }, { "url": "http://api.greynoise.io" } ], "components": { "securitySchemes": { "APIKeyHeaderAuth": { "type": "apiKey", "in": "header", "name": "key" } }, "responses": { "BadRequest": { "description": "Bad request - request syntax is invalid for the specified endpoint.\nVerify request syntax and try again.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" }, "example": { "message": "Invalid parameter" } } } }, "Unauthorized": { "description": "Unauthorized. Please check your API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" }, "example": { "message": "Unauthorized" } } } }, "Forbidden": { "description": "Forbidden - request is not authorized due to an invalid API key or plan limitations.\nIf due to plan limitations, contact sales@greynoise.io to upgrade your plan and unlock full results.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" }, "example": { "message": "Forbidden" } } } }, "ExceededLimit": { "description": "Too many requests. You've hit the rate-limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" }, "example": { "message": "You've hit the rate limit for this endpoint." } } } } }, "parameters": { "query": { "name": "query", "in": "query", "description": "GNQL query string", "required": true, "schema": { "type": "string" } } }, "schemas": { "ErrorMessage": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "MetadataV3": { "properties": { "mobile": { "type": "boolean", "description": "Defines if the IP is part of a known cellular network.", "example": false }, "source_country": { "type": "string", "description": "Country where the IP address is registered or operates.", "example": "United States" }, "source_country_code": { "type": "string", "description": "Country code of the IP address based on ISO 3166-1 alpha-2.", "example": "US" }, "source_city": { "type": "string", "description": "The city where the device is geographically located.", "example": "Seattle" }, "region": { "type": "string", "description": "The region where the device is geographically located.", "example": "Seattle" }, "organization": { "type": "string", "description": "The name of organization that owns the IP address.", "example": "DigitalOcean, LLC" }, "rdns": { "type": "string", "description": "The reverse DNS pointer.", "example": "crawl-66-249-79-17.googlebot.com" }, "asn": { "type": "string", "description": "The autonomous system identification number.", "example": "AS521" }, "asn_subnet": { "type": "string", "description": "The latest-observed ASN subnet for the IP in GreyNoise scan data, not authoritative current BGP state.", "example": "203.0.113.0/24" }, "category": { "type": "string", "description": "The subset of network types the IP address belongs to.", "enum": [ "isp", "business", "hosting", "mobile", "education" ], "example": "education" }, "os": { "type": "string", "description": "An approximate guess of the operating system of the device, based on the TCP stack fingerprint.", "example": "Windows 7/8" }, "destination_countries": { "type": "array", "items": { "type": "string", "description": "The full name or country code where GreyNoise sensor\nis physically located.\n", "example": "Germany" } }, "destination_country_codes": { "type": "array", "items": { "type": "string", "description": "The country codes where GreyNoise sensor is\nphysically located.\n", "example": "Germany" } }, "destination_cities": { "type": "array", "items": { "type": "string", "description": "The city where the GreyNoise sensor is geographically located.\n", "example": "Berlin" } }, "destination_asns": { "type": "array", "items": { "type": "string", "description": "The ASN associated with the destination IP address.\n", "example": "AS1234" } }, "single_destination": { "type": "boolean", "description": "A Boolean parameter indicating whether the source IP address\nhas only been observed in a single destination country.\n", "example": true }, "carrier": { "type": "string", "description": "The Internet Service Provider (ISP) or telecommunications\ncarrier associated with the source IP address.\n", "example": "AIS" }, "datacenter": { "type": "string", "description": "The datacenter or hosting provider from which the activity originates.\nThis could indicate the use of cloud services,\nmanaged hosting, or enterprise datacenter infrastructure.\n", "example": "us-west-1" }, "domain": { "type": "string", "description": "The domain name associated with the source IP address.\n", "example": "example.com" }, "rdns_parent": { "type": "string", "description": "The parent domain retrieved through reverse DNS (RDNS)\nlookup of the source IP address.\n", "example": "example.com" }, "rdns_validated": { "type": "boolean", "description": "A validation status that confirms whether the reverse DNS (RDNS)\nrecord correctly maps to the source domain.\n", "example": true }, "latitude": { "type": "number", "description": "The geographic latitude of the source IP address.\n", "example": 37.7749 }, "longitude": { "type": "number", "description": "The geographic longitude of the source IP address.\n", "example": -122.4194 }, "sensor_count": { "type": "integer", "description": "Number of sensors with events observed.\n", "example": 10 }, "sensor_hits": { "type": "integer", "description": "Number of scanning events observed.\n", "example": 10 } } }, "GNQLIPContextV3": { "properties": { "ip": { "type": "string", "description": "IP address that the information is about.", "example": "71.6.135.131" }, "internet_scanner_intelligence": { "$ref": "#/components/schemas/InternetScannerIntelligence" }, "business_service_intelligence": { "$ref": "#/components/schemas/BusinessServiceIntelligence" } } }, "InternetScannerIntelligence": { "properties": { "classification": { "type": "string", "description": "The classification of the IP address, either \"benign\", \"malicious\", or \"unknown\", based on the activity observed by GreyNoise.", "enum": [ "benign", "malicious", "unknown" ], "example": "benign" }, "first_seen": { "type": "string", "description": "The earliest date GreyNoise observed any activity from this IP.", "format": "date", "example": "2018-01-28" }, "last_seen": { "type": "string", "description": "The most recent date GreyNoise observed any activity from this IP.", "format": "date", "example": "2018-02-28" }, "last_seen_timestamp": { "type": "string", "description": "The timestamp of the last observed activity from this IP.", "format": "date-time", "example": "2025-01-15T12:30:45Z" }, "last_seen_malicious": { "type": "string", "format": "date-time", "description": "Timestamp of the most recent activity classified as malicious. Empty if never observed.", "example": "2026-08-14T18:45:30Z" }, "last_seen_suspicious": { "type": "string", "format": "date-time", "description": "Timestamp of the most recent activity classified as suspicious. Empty if never observed.", "example": "2026-08-14T19:23:31Z" }, "last_seen_benign": { "type": "string", "format": "date-time", "description": "Timestamp of the most recent activity classified as benign. Empty if never observed.", "example": "2026-08-14T19:24:57Z" }, "found": { "type": "boolean", "description": "Indicates if the IP was observed scanning the GreyNoise sensor network. Also referred to as 'noise'.", "example": true }, "actor": { "type": "string", "description": "The overt actor this IP is associated with.", "example": "Shodan.io" }, "spoofable": { "type": "boolean", "description": "This IP address has been opportunistically scanning the Internet, however has failed to complete a full TCP connection. Any reported activity could be spoofed.", "example": true }, "cves": { "type": "array", "items": { "type": "string" }, "description": "A list of CVEs associate with this IP.", "example": [ "CVE-2020-1234", "CVE-2021-2345" ] }, "callback_ips": { "type": "array", "items": { "type": "string" }, "description": "IPs observed as callback destinations for this IP's activity." }, "source_workspaces": { "type": "array", "items": { "type": "string", "enum": [ "greynoise", "community", "personal" ] }, "description": "Which datasets this IP was found in, matching the workspace_labels selected on the request. Omitted when no workspace_labels were selected.", "example": [ "greynoise", "community" ] }, "tor": { "type": "boolean", "description": "Whether or not the device is a known Tor exit node.", "example": false }, "vpn": { "type": "boolean", "description": "This IP is associated with a VPN service. Activity, malicious or otherwise, should not be attributed to the VPN service provider.", "example": true }, "vpn_service": { "type": "string", "description": "Name of associated VPN Service.", "example": "IPVANISH_VPN" }, "metadata": { "$ref": "#/components/schemas/MetadataV3" }, "tags": { "type": "array", "description": "Activity tags associated with this IP.", "items": { "$ref": "#/components/schemas/IPResponseV3Tags" } }, "tag_volumes": { "type": "array", "description": "Per-tag session counts observed for this IP. Omitted when no tag activity has been recorded.", "items": { "type": "object", "properties": { "tag_id": { "type": "string", "format": "uuid", "description": "The ID of the tag." }, "session_count": { "type": "integer", "format": "int64", "description": "Number of sessions associated with this tag for this IP." } } } }, "raw_data": { "type": "object", "description": "Raw data observed directly by GreyNoise.", "properties": { "scan": { "type": "array", "items": { "type": "object", "properties": { "port": { "type": "integer", "description": "Port number", "example": 80 }, "protocol": { "type": "string", "description": "Protocol", "example": "TCP" } } } }, "ja3": { "type": "array", "items": { "type": "object", "properties": { "fingerprint": { "type": "string", "example": "c3a6cf0bf2e690ac8e1ecf6081f17a50", "description": "JA3 hash fingerprint string" }, "port": { "type": "integer", "example": 443, "description": "TCP port connection that the SSL/TLS communication occurred over" } } } }, "hassh": { "type": "array", "items": { "type": "object", "properties": { "fingerprint": { "type": "string", "example": "51cba57125523ce4b9db67714a90bf6e", "description": "HASSH hash fingerprint string" }, "port": { "type": "integer", "example": 2222, "description": "TCP port connection where the HASSH hash was identified\n" } } } }, "http": { "type": "object", "properties": { "md5": { "type": "string", "description": "An MD5 hash of the body content. This compact,\nunique representation of the data allows for quick\ncomparisons and deduplication of payloads without\nstoring the raw content.\n", "example": "9764955b67107eeb9edfae76f429e783" }, "cookie_keys": { "type": "array", "description": "The keys or names of cookies exchanged in the communication.\nThese can reveal session identifiers, tracking mechanisms,\nor other metadata used in web interactions,\nproviding clues about application behavior or vulnerabilities.\n", "example": [ "expremotekey" ], "items": { "type": "string" } }, "request_authorization": { "type": "array", "description": "The contents of the Authorization header in a request,\nwhich can include credentials, tokens, or other authentication\ninformation.\n", "example": [ "Bearer exampletoken", "Basic username:password" ], "items": { "type": "string" } }, "request_cookies": { "type": "array", "description": "Key-value pairs stored in cookies sent with an HTTP request.\nThese cookies often contain session identifiers, user preferences,\nor tracking data, which can be analyzed to detect unauthorized\naccess or manipulation.\n", "example": [ "session_id=1234567890" ], "items": { "type": "string" } }, "request_header": { "type": "array", "description": "Request Headers are the keys (names) of HTTP headers\nthat a client sends to a server.\n", "example": [ "Content-Type: application/json", "Accept: application/json" ], "items": { "type": "string" } }, "method": { "type": "array", "description": "The HTTP method used in the request, such as GET, POST, PUT, or DELETE.\nAnalyzing methods can reveal the intent of the request,\nsuch as retrieving or modifying resources,\nand identify unexpected or suspicious activity.\n", "example": [ "GET", "POST", "PUT", "DELETE" ], "items": { "type": "string" } }, "request_origin": { "type": "array", "description": "Indicates the origin of the request,\ntypically used in cross-origin resource sharing (CORS)\nto specify where the request originated.\nThis helps identify unauthorized or potentially\nmalicious cross-origin requests.\n", "example": [ "111.111.1.1" ], "items": { "type": "string" } }, "host": { "type": "array", "description": "The host of the request, which can include the domain name\nand port number. These values can provide insight into the services or\nendpoints the actor may have been attempting to interact with.\n", "example": [ "example.com", "example.com:8080" ], "items": { "type": "string" } }, "uri": { "type": "array", "items": { "type": "string", "description": "The URI of the request, which can include the path and query parameters.\nThis can provide insight into the specific resource or data being requested.\n" } }, "path": { "type": "array", "items": { "type": "string", "description": "Observed scanning activity traversed this web path.", "example": "/robots.txt" } }, "useragent": { "type": "array", "items": { "type": "string", "description": "Observed scanning activity used these user agents.", "example": "Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)\n" } }, "ja4h": { "type": "array", "items": { "type": "string", "description": "List of JA4H HTTP client fingerprints observed in network traffic from the IP.\nJA4H captures characteristics of HTTP client behavior including method,\nheaders, and cookie fields, useful for identifying and tracking HTTP clients.\n" }, "example": [ "ge11cn060000_4e59edc1297a_4da5efaf0cbd" ] } } }, "tls": { "type": "object", "properties": { "cipher": { "type": "string", "description": "The encryption algorithm or cipher suite used during the\nsecure communication. Identifying the cipher helps assess\nthe security of the connection, particularly in TLS/SSL traffic.\n", "example": "TLS_AES_128_GCM_SHA256" }, "ja4": { "type": "array", "items": { "type": "string", "description": "List of JA4 TLS fingerprints observed in network traffic from the IP.\nJA4 is a modern fingerprinting method that captures distinctive\ncharacteristics of TLS client behavior,\nuseful for identifying and clustering malicious or anomalous clients.\n" }, "example": [ "t13d1516h2_8daaf6152771_02713d6af862" ] } } }, "ssh": { "type": "object", "properties": { "key": { "type": "array", "description": "This is the SSH key used.\n", "example": [ "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC1234567890" ], "items": { "type": "string" } }, "ja4ssh": { "type": "array", "items": { "type": "string", "description": "List of JA4SSH fingerprints observed in network traffic from the IP.\nJA4SSH captures SSH traffic patterns including packet lengths and\ndirections, useful for identifying SSH client behavior and detecting\nanomalous sessions.\n" }, "example": [ "c76s76_c71s59_c0s0" ] } } }, "tcp": { "type": "object", "properties": { "ja4t": { "type": "array", "items": { "type": "string", "description": "List of JA4T TCP fingerprints observed in network traffic from the IP.\nJA4T captures TCP connection characteristics such as window size,\noptions, and MSS, useful for OS fingerprinting and identifying\nnetwork stacks.\n" }, "example": [ "64240_2-1-3-1-1-4_1460_8" ] }, "ja4l": { "type": "string", "description": "JA4L light distance/latency fingerprint observed in network traffic\nfrom the IP. Captures TCP TTL and window size characteristics, useful\nfor estimating client-server distance and identifying proxied\nconnections.\n", "example": "1460_64" } } }, "source": { "properties": { "bytes": { "type": "integer", "description": "The total amount of data transferred (in bytes) during the observed session or connection.\n", "example": 1024 } } } } } } }, "BusinessServiceIntelligence": { "properties": { "found": { "type": "boolean", "description": "Indicates if an IP is part of the RIOT dataset or not.\n", "example": true }, "category": { "type": "string", "description": "RIOT category the provider belongs to, identifying the type of service provided.\n", "example": "hosting" }, "name": { "type": "string", "description": "The name of the provider and/or service.\n", "example": "example.com" }, "description": { "type": "string", "description": "A description of the provider and what they do.\n", "example": "example.com" }, "explanation": { "type": "string", "description": "An explanation of the category type and what may be expected from this provider and category.\n" }, "last_updated": { "type": "string", "description": "Date and time when this record was last updated from its source (format: YYYY-MM-DDTHH:MM:SSZ).\n", "example": "2025-01-15T12:30:45Z" }, "reference": { "type": "string", "description": "Reference URL for information about this provider and/or service.\n", "example": "https://example.com" }, "trust_level": { "type": "string", "description": "Trust level assigned to this IP/provider. One of:\n - \"1\" — high trust; broadly used legitimate provider where end-user attribution is high.\n - \"2\" — moderate trust; common business service infrastructure where end-user attribution is limited.\n - \"3\" — label only; cloud compute or bulk hosting provider with no inherent trust signal.\n", "example": "1" } } }, "QuickBusinessServiceIntelligence": { "type": "object", "properties": { "found": { "type": "boolean", "description": "Indicates if an IP is part of the RIOT dataset or not.\n" }, "trust_level": { "type": "string", "description": "Trust level assigned to this IP/provider. One of:\n - \"1\" — high trust; broadly used legitimate provider where end-user attribution is high.\n - \"2\" — moderate trust; common business service infrastructure where end-user attribution is limited.\n - \"3\" — label only; cloud compute or bulk hosting provider with no inherent trust signal.\n", "example": "1" } } }, "QuickInternetScannerIntelligence": { "type": "object", "properties": { "found": { "type": "boolean", "description": "Indicates if the IP was observed scanning the GreyNoise sensor network. Also referred to as 'noise'.\n" }, "classification": { "type": "string", "description": "The classification of the IP address, either \"benign\", \"malicious\",\nor \"unknown\", based on the activity observed by GreyNoise.\n", "enum": [ "benign", "malicious", "unknown" ], "example": "benign" } } }, "QuickIpProfile": { "type": "object", "properties": { "ip": { "type": "string", "example": "8.8.8.8", "description": "IP address that the information is about." }, "business_service_intelligence": { "$ref": "#/components/schemas/QuickBusinessServiceIntelligence" }, "internet_scanner_intelligence": { "$ref": "#/components/schemas/QuickInternetScannerIntelligence" } } }, "IPResponseV3Tags": { "type": "object", "properties": { "id": { "type": "string", "example": "ef0cc90d-d80c-436f-92c5-3d8f8665c9ac", "description": "The unique identifier for the tag.\n" }, "slug": { "type": "string", "example": "mirai", "description": "The slugified version of the tag name.\n" }, "name": { "type": "string", "example": "Mirai", "description": "The human-readable name for the tag.\n" }, "category": { "type": "string", "example": "worm", "description": "Category of the IP address such as hosting or ISP.\n" }, "intention": { "type": "string", "example": "malicious", "description": "The intent of the tag, either suspicious, malicious, benign, or unknown.\n" }, "description": { "type": "string", "example": "This IP address exhibits behavior that indicates it is infected with Mirai or a Mirai-like variant of malware.", "description": "A detailed description of the tag, including the observed activity\nand any relevant context or details.\n" }, "references": { "type": "array", "items": { "type": "string", "example": "https://en.wikipedia.org/wiki/Mirai_(malware)", "description": "A list of URLs or references that provide additional information\nabout the tag and its associated activity.\n" } }, "recommend_block": { "type": "boolean", "example": false, "description": "A boolean value indicating whether the tag should be recommended\nfor blocking or filtering purposes.\n" }, "cves": { "type": "array", "items": { "type": "string", "example": "CVE-2020-1234", "description": "A list of CVEs associated with the tag.\n" } }, "created": { "type": "string", "example": "2020-04-07", "description": "The date the tag was created. May be empty.\n" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-02-10T15:59:49Z", "description": "The timestamp when the tag was last updated.\n" } } }, "QuickGNQLV3Response": { "type": "object", "properties": { "request_metadata": { "$ref": "#/components/schemas/GNQLV3ResponseMetadata" }, "data": { "type": "array", "description": "The relevant IP records requested by the user", "items": { "$ref": "#/components/schemas/QuickIpProfile" } } } }, "GNQLV3Response": { "type": "object", "properties": { "request_metadata": { "$ref": "#/components/schemas/GNQLV3ResponseMetadata" }, "data": { "type": "array", "description": "The relevant IP records requested by the user", "items": { "$ref": "#/components/schemas/GNQLIPContextV3" } } } }, "GNQLV3ResponseMetadata": { "type": "object", "properties": { "complete": { "type": "boolean", "example": false, "description": "Whether all records have been delivered or not. `false` means there's another page" }, "scroll": { "type": "string", "example": "DnF1ZXJ5VGhlbkZldGNoBQAAAAAAeygtFkFKSExEdUc4VEtta2syaGg2R3kzNGcAAAAAAH soLhZBSkhMRHVHOFRLbWtrMmhoNkd5MzRnAAAAAAB7KC8WQUpITER1RzhUS21razJoaDZH eTM0ZwAAAAAAeygxFkFKSExEdUc4VEtta2syaGg2R3kzNGcAAAAAAHsoMBZBSkhMRHVHOF RLbWtrMmhoNkd5MzRn\n", "description": "Scroll token to use for pagination" }, "query": { "type": "string", "example": "last_seen:2019-07-28 classification:malicious", "description": "The GNQL query string the requester queried" }, "adjusted_query": { "type": "string", "example": "last_seen:2019-07-28 classification:malicious", "description": "When certain query parameters are not specified or incompatible\nwith your current plan, GreyNoise automatically adjusts params on your\nquery prior to execution.\n" }, "count": { "type": "integer", "example": 1, "description": "The number of total results for the given GNQL query" }, "message": { "type": "string", "example": "ok", "description": "A status message indicating if there were issues with the request" }, "restricted_fields": { "type": "array", "description": "The fields that were restricted due to plan limitations", "example": [ "ip", "asn", "organization", "country", "city", "region" ], "items": { "type": "string" } } } } } } } ```