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.

PathDescription
actorThe benign actor the device has been associated with (e.g. Shodan, Censys, GoogleBot)
callback_ipsIP addresses observed in HTTP payloads
classificationThe classification of the IP: malicious, suspicious, unknown, or benign
cveA list of CVEs the IP has been associated with over the past 90 days
destination_countryThe full name of a country the IP has been observed scanning toward
destination_country_codeThe two-character code of a country the IP has been observed scanning toward
first_seenThe date GreyNoise first observed the device
ipThe IP address or CIDR block to match
last_seenThe date GreyNoise most recently observed the device
last_seen_benignThe date GreyNoise last observed this IP exhibiting benign behavior
last_seen_maliciousThe date GreyNoise last observed this IP exhibiting malicious behavior
last_seen_suspiciousThe date GreyNoise last observed this IP exhibiting suspicious behavior
last_seen_timestampThe timestamp GreyNoise most recently observed the device
metadata.asnThe autonomous system the IP address belongs to
metadata.asn_subnetThe most recent ASN subnet GreyNoise observed for the IP
metadata.carrierThe carrier associated with the IP
metadata.categoryWhether the device belongs to a business, ISP, hosting, education, or mobile network
metadata.datacenterThe datacenter associated with the IP
metadata.destination_asnsList of ASNs of destination IPs
metadata.destination_citiesList of destination cities the IP has been observed scanning toward
metadata.destination_countryList of full country names the IP has been observed scanning toward
metadata.destination_country_codeList of two-character country codes for scanning destinations
metadata.domainThe domain associated with the IP
metadata.latitudeThe latitude of the device's geographic location
metadata.longitudeThe longitude of the device's geographic location
metadata.mobileWhether the IP belongs to a mobile network
metadata.organizationThe organization that owns the network the IP address belongs to
metadata.osThe operating system of the device
metadata.rdnsThe reverse DNS pointer of the IP
metadata.rdns_parentThe parent domain of the reverse DNS pointer
metadata.rdns_validatedWhether the reverse DNS record has been validated
metadata.regionThe region the device is geographically located in
metadata.sensor_countThe number of GreyNoise sensors that observed the IP
metadata.sensor_hitsThe number of times the IP was observed across GreyNoise sensors
metadata.single_destinationWhether the IP has only been observed scanning a single destination country
metadata.source_cityThe city the device is geographically located in
metadata.source_countryThe full name of the country the device is geographically located in
metadata.source_country_codeThe two-character country code of the country the device is located in
raw_data.hassh.fingerprintHASSH SSH fingerprint
raw_data.hassh.portThe TCP port the HASSH fingerprint was observed on
raw_data.http.cookie_keysHTTP cookie keys observed in requests
raw_data.http.hostHost header observed in HTTP requests
raw_data.http.ja4hJA4H HTTP fingerprint
raw_data.http.md5MD5 hash of observed HTTP content
raw_data.http.methodHTTP method observed (e.g. GET, POST)
raw_data.http.pathHTTP paths the device has been observed crawling
raw_data.http.request_authorizationAuthorization header observed in HTTP requests
raw_data.http.request_cookiesCookies observed in HTTP requests
raw_data.http.request_headerHeaders observed in HTTP requests
raw_data.http.request_originOrigin header observed in HTTP requests
raw_data.http.request_refererReferer header observed in HTTP requests
raw_data.http.uriURIs observed in HTTP requests
raw_data.http.useragentHTTP user-agents the device has been observed using
raw_data.ja3.fingerprintJA3 TLS/SSL fingerprint
raw_data.ja3.portThe TCP port the JA3 fingerprint was observed on
raw_data.scan.portThe port number in the first scan entry
raw_data.scan.protocolThe protocol in the first scan entry
raw_data.source.bytesNumber of bytes observed from the source IP
raw_data.source.sessionsNumber of sessions observed from the source IP
raw_data.ssh.ja4sshJA4SSH fingerprint
raw_data.ssh.keySSH host key observed
raw_data.tcp.ja4lJA4L TCP latency fingerprint
raw_data.tcp.ja4tJA4T TCP fingerprint
raw_data.tls.cipherTLS cipher suite observed
raw_data.tls.ja4JA4 TLS fingerprint
seenWhether GreyNoise has observed the IP
spoofableWhether the IP has failed to complete a full TCP connection; reported activity could be spoofed
tag_idsThe unique IDs of the tags the device has been assigned. Use tags to match by name
tagsA list of tags the device has been assigned over the past 90 days
torWhether the device is a known Tor exit node
vpnWhether the IP is associated with a VPN service
vpn_serviceThe VPN service the IP is associated with
workspace_labelDetermines 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, and last_seen_suspicious fields differ from the top-level classification field. 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 nameField
asnmetadata.asn
asn_subnetmetadata.asn_subnet
categorymetadata.category
citymetadata.source_city
countrymetadata.country
country_codemetadata.country_code
org or organizationmetadata.organization
osmetadata.os
rdnsmetadata.rdns
cvescve
portraw_data.scan.port
protocolraw_data.scan.protocol
pathraw_data.http.path
useragentraw_data.http.useragent
sessionsraw_data.source.sessions
ja3raw_data.ja3.fingerprint
ja4raw_data.tls.ja4
ja4hraw_data.http.ja4h
ja4lraw_data.tcp.ja4l
ja4traw_data.tcp.ja4t
ja4sshraw_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 ports
  • raw_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 day
  • raw_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_ips
  • destination_country, destination_country_code
  • metadata.destination_asns, metadata.destination_cities
  • raw_data.hassh.fingerprint, raw_data.hassh.port
  • raw_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.useragent
  • raw_data.ja3.fingerprint, raw_data.ja3.port
  • raw_data.scan.port, raw_data.scan.protocol
  • raw_data.ssh.ja4ssh, raw_data.ssh.key
  • raw_data.tcp.ja4l, raw_data.tcp.ja4t
  • raw_data.tls.cipher, raw_data.tls.ja4

A few fields work differently:

  • tags, tag_ids, and cve support last-seen only. Use tags_last_seen with tags or tag_ids, and cve_last_seen with cve.
  • raw_data.scan.port and raw_data.scan.protocol share one last-seen field: raw_data.scan.last_seen.
  • raw_data.ja3.fingerprint and raw_data.ja3.port share raw_data.ja3.last_seen.
  • raw_data.hassh.fingerprint and raw_data.hassh.port share raw_data.hassh.last_seen.

Behavior

  • Terms separated by a space are combined with AND. You can also write AND, OR, and NOT, and group terms with parentheses
  • You can subtract facets by prefacing the query with a minus character. -classification:benign and NOT classification:benign return 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 offered
  • community - 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 directly
  • personal - 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 sensors
  • raw_data.scan.port:[8000-8100] - A range. Returns all IPs observed scanning any port from 8000 to 8100
  • raw_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 TCP
  • ONLY(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 ONLY operator 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_country OR metadata.country - The full name of the country the scanning device is geographically located in
  • metadata.source_country_code OR metadata.country_code - The two-character country code of the country the device is geographically located in
  • metadata.destination_country - The full name of the IP scanning destination country
  • metadata.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 with metadata.destination_country or metadata.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)
AfghanistanAland IslandsAlbaniaAlgeria
AngolaArgentinaArmeniaAustralia
AustriaAzerbaijanBahrainBangladesh
BelarusBelgiumBoliviaBosnia and Herzegovina
BrazilBulgariaCambodiaCameroon
CanadaChileChinaColombia
Costa RicaCroatiaCyprusCzech Republic
DenmarkEcuadorEgyptEl Salvador
EstoniaEthiopiaFinlandFrance
GeorgiaGermanyGhanaGreece
GuadeloupeGuamGuatemalaHonduras
Hong KongHungaryIcelandIndia
IndonesiaIraqIrelandIsrael
ItalyIvory CoastJapanJordan
KazakhstanKenyaKuwaitKyrgyzstan
LaosLatviaLebanonLithuania
LuxembourgMacaoMalaysiaMalta
MartiniqueMauritiusMexicoMoldova
MongoliaMontenegroMoroccoMyanmar
NepalNetherlandsNew ZealandNigeria
NorwayOmanPakistanPalestine
PanamaParaguayPeruPhilippines
PolandPortugalPuerto RicoQatar
Republic of the CongoRomaniaRussiaRwanda
Saudi ArabiaSenegalSerbiaSingapore
SlovakiaSloveniaSouth AfricaSouth Korea
SpainSwedenSwitzerlandTaiwan
TajikistanThailandTogoTurkey
UkraineUnited Arab EmiratesUnited KingdomUnited States
UruguayUzbekistanVenezuelaVietnam

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 day
  • last_seen_suspicious:7d - IPs that were seen doing something suspicious in the last 7 days
📘

Time-Based Queries are based on UTC Timestamps

When 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 today
  • tags:Mirai - Returns all devices with the "Mirai" tag
  • tags:"RDP Bruteforce Attempt" - Returns all devices with the "RDP Bruteforce Attempt" 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: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
  • ip: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 Wildcards

When 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"


Did this page help you?