Using the GreyNoise Query Language (GNQL)
The GreyNoise Query Language (GNQL)
The GreyNoise Query Language (GNQL) is a domain-specific query language to search the GreyNoise data set to help analysts, threat hunters, researchers, etc find emerging threats, compromised devices, and other interesting trends.
GNQLs can be used to query data from both the GreyNoise Visualizer and the GreyNoise REST API.
Searchable Fields
The following is a list of all the GreyNoise fields that can be searched with a GNQL. Some fields require the Investigate or Hunt intelligence module; see Intelligence Module Comparison: Internet Scanners.
| Path | Description |
|---|---|
actor | The benign actor the device has been associated with (e.g. Shodan, Censys, GoogleBot) |
callback_ips | IP addresses observed in HTTP payloads |
classification | The classification of the IP: malicious, suspicious, unknown, or benign |
cve | A list of CVEs the IP has been associated with over the past 90 days |
destination_country | The full name of a country the IP has been observed scanning toward |
destination_country_code | The two-character code of a country the IP has been observed scanning toward |
first_seen | The date GreyNoise first observed the device |
ip | The IP address or CIDR block to match |
last_seen | The date GreyNoise most recently observed the device |
last_seen_benign | The date GreyNoise last observed this IP exhibiting benign behavior |
last_seen_malicious | The date GreyNoise last observed this IP exhibiting malicious behavior |
last_seen_suspicious | The date GreyNoise last observed this IP exhibiting suspicious behavior |
last_seen_timestamp | The timestamp GreyNoise most recently observed the device |
metadata.asn | The autonomous system the IP address belongs to |
metadata.asn_subnet | The most recent ASN subnet GreyNoise observed for the IP |
metadata.carrier | The carrier associated with the IP |
metadata.category | Whether the device belongs to a business, ISP, hosting, education, or mobile network |
metadata.datacenter | The datacenter associated with the IP |
metadata.destination_asns | List of ASNs of destination IPs |
metadata.destination_cities | List of destination cities the IP has been observed scanning toward |
metadata.destination_country | List of full country names the IP has been observed scanning toward |
metadata.destination_country_code | List of two-character country codes for scanning destinations |
metadata.domain | The domain associated with the IP |
metadata.latitude | The latitude of the device's geographic location |
metadata.longitude | The longitude of the device's geographic location |
metadata.mobile | Whether the IP belongs to a mobile network |
metadata.organization | The organization that owns the network the IP address belongs to |
metadata.os | The operating system of the device |
metadata.rdns | The reverse DNS pointer of the IP |
metadata.rdns_parent | The parent domain of the reverse DNS pointer |
metadata.rdns_validated | Whether the reverse DNS record has been validated |
metadata.region | The region the device is geographically located in |
metadata.sensor_count | The number of GreyNoise sensors that observed the IP |
metadata.sensor_hits | The number of times the IP was observed across GreyNoise sensors |
metadata.single_destination | Whether the IP has only been observed scanning a single destination country |
metadata.source_city | The city the device is geographically located in |
metadata.source_country | The full name of the country the device is geographically located in |
metadata.source_country_code | The two-character country code of the country the device is located in |
raw_data.hassh.fingerprint | HASSH SSH fingerprint |
raw_data.hassh.port | The TCP port the HASSH fingerprint was observed on |
raw_data.http.cookie_keys | HTTP cookie keys observed in requests |
raw_data.http.host | Host header observed in HTTP requests |
raw_data.http.ja4h | JA4H HTTP fingerprint |
raw_data.http.md5 | MD5 hash of observed HTTP content |
raw_data.http.method | HTTP method observed (e.g. GET, POST) |
raw_data.http.path | HTTP paths the device has been observed crawling |
raw_data.http.request_authorization | Authorization header observed in HTTP requests |
raw_data.http.request_cookies | Cookies observed in HTTP requests |
raw_data.http.request_header | Headers observed in HTTP requests |
raw_data.http.request_origin | Origin header observed in HTTP requests |
raw_data.http.request_referer | Referer header observed in HTTP requests |
raw_data.http.uri | URIs observed in HTTP requests |
raw_data.http.useragent | HTTP user-agents the device has been observed using |
raw_data.ja3.fingerprint | JA3 TLS/SSL fingerprint |
raw_data.ja3.port | The TCP port the JA3 fingerprint was observed on |
raw_data.scan.port | The port number in the first scan entry |
raw_data.scan.protocol | The protocol in the first scan entry |
raw_data.source.bytes | Number of bytes observed from the source IP |
raw_data.source.sessions | Number of sessions observed from the source IP |
raw_data.ssh.ja4ssh | JA4SSH fingerprint |
raw_data.ssh.key | SSH host key observed |
raw_data.tcp.ja4l | JA4L TCP latency fingerprint |
raw_data.tcp.ja4t | JA4T TCP fingerprint |
raw_data.tls.cipher | TLS cipher suite observed |
raw_data.tls.ja4 | JA4 TLS fingerprint |
seen | Whether GreyNoise has observed the IP |
spoofable | Whether the IP has failed to complete a full TCP connection; reported activity could be spoofed |
tag_ids | The unique IDs of the tags the device has been assigned. Use tags to match by name |
tags | A list of tags the device has been assigned over the past 90 days |
tor | Whether the device is a known Tor exit node |
vpn | Whether the IP is associated with a VPN service |
vpn_service | The VPN service the IP is associated with |
workspace_label | Determines which dataset to pull results from. When not provided as an input, defaults to greynoise. Accepted values greynoise, community, or personal |
Note: The
last_seen_benign,last_seen_malicious, andlast_seen_suspiciousfields differ from the top-levelclassificationfield. GreyNoise classifications follow a hierarchy with an age-out period — for example, an IP observed behaving maliciously retains a malicious classification for 30 days before aging off. These fields let you query based on when GreyNoise last saw behavior matching a classification, regardless of what the IP's current top-level classification is.
Short Field Names
Some fields can also be searched with a shorter name. Both forms return the same results.
| Short name | Field |
|---|---|
asn | metadata.asn |
asn_subnet | metadata.asn_subnet |
category | metadata.category |
city | metadata.source_city |
country | metadata.country |
country_code | metadata.country_code |
org or organization | metadata.organization |
os | metadata.os |
rdns | metadata.rdns |
cves | cve |
port | raw_data.scan.port |
protocol | raw_data.scan.protocol |
path | raw_data.http.path |
useragent | raw_data.http.useragent |
sessions | raw_data.source.sessions |
ja3 | raw_data.ja3.fingerprint |
ja4 | raw_data.tls.ja4 |
ja4h | raw_data.http.ja4h |
ja4l | raw_data.tcp.ja4l |
ja4t | raw_data.tcp.ja4t |
ja4ssh | raw_data.ssh.ja4ssh |
Count and Last-Seen Fields
Fields that hold a list of values can also be searched by how many values an IP has, and by how recently a value was seen.
Count fields
Add _count to the field name to search by the number of distinct values an IP has for that field. A count field takes a number, a comparison, or a range.
raw_data.scan.port_count:>50- Returns all IPs observed scanning more than 50 distinct portsraw_data.http.path_count:[2-10]- Returns all IPs observed requesting between 2 and 10 distinct HTTP paths
Last-seen fields
Add _last_seen to the field name to limit a match to values seen within a time window. A last-seen field takes a date or a relative interval such as 3d, and must be used together with a filter on the field it belongs to.
tags:Mirai tags_last_seen:1d- Returns all IPs that were tagged Mirai in the last dayraw_data.scan.port:22 raw_data.scan.last_seen:3d- Returns all IPs observed scanning port 22 in the last 3 days
Supported fields
The following fields support both _count and _last_seen:
callback_ipsdestination_country,destination_country_codemetadata.destination_asns,metadata.destination_citiesraw_data.hassh.fingerprint,raw_data.hassh.portraw_data.http.cookie_keys,raw_data.http.host,raw_data.http.ja4h,raw_data.http.md5,raw_data.http.method,raw_data.http.path,raw_data.http.request_authorization,raw_data.http.request_header,raw_data.http.request_origin,raw_data.http.request_referer,raw_data.http.uri,raw_data.http.useragentraw_data.ja3.fingerprint,raw_data.ja3.portraw_data.scan.port,raw_data.scan.protocolraw_data.ssh.ja4ssh,raw_data.ssh.keyraw_data.tcp.ja4l,raw_data.tcp.ja4traw_data.tls.cipher,raw_data.tls.ja4
A few fields work differently:
tags,tag_ids, andcvesupport last-seen only. Usetags_last_seenwithtagsortag_ids, andcve_last_seenwithcve.raw_data.scan.portandraw_data.scan.protocolshare one last-seen field:raw_data.scan.last_seen.raw_data.ja3.fingerprintandraw_data.ja3.portshareraw_data.ja3.last_seen.raw_data.hassh.fingerprintandraw_data.hassh.portshareraw_data.hassh.last_seen.
Behavior
- Terms separated by a space are combined with
AND. You can also writeAND,OR, andNOT, and group terms with parentheses - You can subtract facets by prefacing the query with a minus character.
-classification:benignandNOT classification:benignreturn the same results - To match any of several values for one field, group them after the field name:
metadata.organization:(Microsoft OR Google) - The data that this endpoint queries refreshes once per hour
Accessing Results from different datasets
When searching for a query, the workspace_label parameter can be added to the query to return results from different datasets within the product.
Currently, the following datasets are available:
greynoise- this includes all data directly collected by the GreyNoise Global Observation Grid (GOG), the default and historical dataset that has always been offeredcommunity- this includes aggregated data that is collected by ALL users who are running GreyNoise sensors within their own workspaces. These results are still collected by GreyNoise sensors and data pipeline, but are not managed by GreyNoise directlypersonal- this includes data that is collected by sensors running in your assigned workspace only
Examples
To pull all malicious IPs from the GreyNoise dataset and the community dataset:
last_seen_malicious:1d AND (workspace_label:greynoise OR workspace_label:community)
To pull all IPs from your personal sensors:
last_seen:1d AND workspace_label:personal
To pull all IPs from the community dataset observed with the Mirai tag:
tags:Mirai AND workspace_label:community
Using Wildcards in GreyNoise Query Language (GNQL)
When searching fields using wildcards in GNQL, it's important to understand how each wildcard operates:
Wildcard Types
- ? - Matches exactly one character.
*- Matches zero or more characters, including an empty string.?*- Matches one or more characters, excluding empty strings.
Examples:
-
metadata.rdns:"*example.com"- Returns all records with an rDNS entry ending in "example.com" (including "sub.example.com", "test.example.com", etc.).
-
metadata.rdns:?*- Returns records that have at least one character in the rDNS field, effectively filtering out entries where the field is empty.
Searching Numeric Fields
Numeric fields, such as raw_data.scan.port and metadata.sensor_count, accept more than a single value:
metadata.sensor_count:>5- A comparison. Returns all IPs observed by more than 5 sensorsraw_data.scan.port:[8000-8100]- A range. Returns all IPs observed scanning any port from 8000 to 8100raw_data.scan.port:[22, 80, 443]- A list. Returns all IPs observed scanning port 22, 80, or 443
The ONLY Operator
ONLY(...) returns IPs that match the query inside the parentheses and have no other values for that field.
ONLY(raw_data.scan.protocol:tcp)- Returns all IPs that have only been observed scanning over TCPONLY(tags:Mirai OR tags:"Mirai TCP Scanner")- Returns all IPs whose only tags are Mirai, Mirai TCP Scanner, or both
ONLY works on fields that hold a list of values, such as tags, ports, and protocols. A field that holds one value per IP, such as actor, returns an error.
Note: The
ONLYoperator is included with the Elite Platform plan.
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
IP Geo Destination
The GNQL language supports IP source and destination queries. This will help you to understand how scanning behavior impacts different countries.
metadata.source_countryORmetadata.country- The full name of the country the scanning device is geographically located inmetadata.source_country_codeORmetadata.country_code- The two-character country code of the country the device is geographically located inmetadata.destination_country- The full name of the IP scanning destination countrymetadata.destination_country_code- The two-character country code of the IP scanning destination country.metadata.single_destination- A boolean parameter that filters source country IPs observed only in a single destination country. This has to be used in conjunction withmetadata.destination_countryormetadata.destination_country_code.
If your search of the destination country doesn’t return any results, please ensure that you have entered a valid country name or code. It is possible that the destination country is not in the GreyNoise sensor network; therefore, we don’t have any data in that country.
Here is a list of countries that are part of the GreyNoise sensor network:
Supported destination countries (120)
| Afghanistan | Aland Islands | Albania | Algeria |
| Angola | Argentina | Armenia | Australia |
| Austria | Azerbaijan | Bahrain | Bangladesh |
| Belarus | Belgium | Bolivia | Bosnia and Herzegovina |
| Brazil | Bulgaria | Cambodia | Cameroon |
| Canada | Chile | China | Colombia |
| Costa Rica | Croatia | Cyprus | Czech Republic |
| Denmark | Ecuador | Egypt | El Salvador |
| Estonia | Ethiopia | Finland | France |
| Georgia | Germany | Ghana | Greece |
| Guadeloupe | Guam | Guatemala | Honduras |
| Hong Kong | Hungary | Iceland | India |
| Indonesia | Iraq | Ireland | Israel |
| Italy | Ivory Coast | Japan | Jordan |
| Kazakhstan | Kenya | Kuwait | Kyrgyzstan |
| Laos | Latvia | Lebanon | Lithuania |
| Luxembourg | Macao | Malaysia | Malta |
| Martinique | Mauritius | Mexico | Moldova |
| Mongolia | Montenegro | Morocco | Myanmar |
| Nepal | Netherlands | New Zealand | Nigeria |
| Norway | Oman | Pakistan | Palestine |
| Panama | Paraguay | Peru | Philippines |
| Poland | Portugal | Puerto Rico | Qatar |
| Republic of the Congo | Romania | Russia | Rwanda |
| Saudi Arabia | Senegal | Serbia | Singapore |
| Slovakia | Slovenia | South Africa | South Korea |
| Spain | Sweden | Switzerland | Taiwan |
| Tajikistan | Thailand | Togo | Turkey |
| Ukraine | United Arab Emirates | United Kingdom | United States |
| Uruguay | Uzbekistan | Venezuela | Vietnam |
Examples:
- Search for all IPs in China that are ONLY scanning sensors located in Brazil:
source_country:"China" AND destination_country:"Brazil" AND metadata.single_destination:true AND spoofable:false
- Search for all IPs scanning sensors located in Germany:
destination_country:"Germany"
Time-Based Query Options
The GNQL language allows time-based queries, based on the last_seen and first_seen dates. The following options are supported for both:
last_seen:1d- last seen in the previous day plus today (includes the previous full day and partial current day).last_seen:1w- last seen in the last week.last_seen:1m- last seen in the last month.last_seen:1y- last seen in the last year.last_seen:today- last seen on this date.last_seen:2026-10-15- last seen on or after this date.last_seen_malicious:1d- IPs that were seen doing something malicious in the last daylast_seen_suspicious:7d- IPs that were seen doing something suspicious in the last 7 days
Time-Based Queries are based on UTC TimestampsWhen using time-based query options, please note that the time query is based on the current date and time in UTC.
Examples
last_seen:today- Returns all IPs scanning/crawling the Internet todaytags:Mirai- Returns all devices with the "Mirai" tagtags:"RDP Bruteforce Attempt"- Returns all devices with the "RDP Bruteforce Attempt" tagclassification:malicious metadata.country:Belgium- Returns all compromised devices located in Belgiumclassification:malicious metadata.rdns:"*.gov*"- Returns all compromised devices that include .gov in their reverse DNS recordsmetadata.organization:Microsoft classification:malicious- Returns all compromised devices that belong to Microsoftraw_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 Googletags:"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 Internetraw_data.ja3.fingerprint:795bc7ce13f60d61e9ac03611dd36d90- Returns all devices crawling the Internet with a matching client JA3 TLS/SSL fingerprintraw_data.hassh.fingerprint:51cba57125523ce4b9db67714a90bf6e- Returns all devices crawling the Internet with a matching client HASSH fingerprintraw_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/8ip:8.8.8.0-8.8.8.255- Returns all devices scanning the Internet from the IP range 8.8.8.0 to 8.8.8.255
Use Quotes with WildcardsWhen performing complex GNQL searches that include wildcards, be sure to use quotes around the appropriate term to ensure the most relevant results are returned:
ex: rdns:"*.ant.isi.edu"
Updated 3 days ago
