Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: GreyNoise Callback GNQL API
version: 3.0.0
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.
contact:
email: hello@greynoise.io
license:
name: Proprietary
url: https://www.greynoise.io/terms
servers:
- url: https://api.greynoise.io
description: Production
security:
- APIKeyHeaderAuth: []
tags:
- name: GNQL
description: Calls to interface with GNQL (GreyNoise Query Language).
paths:
/v3/gnql:
get:
tags:
- GNQL
summary: GNQL V3 Query
operationId: gnqlV3Query
description: '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.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
* 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.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
'
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.
Recognized top-level response fields (e.g. `tags`, `cves`, `vpn`, `tor`, `raw_data`, `metadata`),
`metadata.<subfield>` paths (e.g. `metadata.organization`, `metadata.source_country`,
`metadata.destination_countries`), and `raw_data.<subfield>` paths (e.g. `raw_data.ja3`,
`raw_data.http.useragent`) are accepted. The special value `tags.details` preserves tag
identity (id, slug) and strips only the enriched details. Unknown field names return 400.
'
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'
examples:
GnqlV3Query200Example:
summary: Default gnqlV3Query 200 response
x-microcks-default: true
value:
request_metadata:
complete: false
scroll: 'DnF1ZXJ5VGhlbkZldGNoBQAAAAAAeygtFkFKSExEdUc4VEtta2syaGg2R3kzNGcAAAAAAH soLhZBSkhMRHVHOFRLbWtrMmhoNkd5MzRnAAAAAAB7KC8WQUpITER1RzhUS21razJoaDZH eTM0ZwAAAAAAeygxFkFKSExEdUc4VEtta2syaGg2R3kzNGcAAAAAAHsoMBZBSkhMRHVHOF RLbWtrMmhoNkd5MzRn
'
query: last_seen:2019-07-28 classification:malicious
adjusted_query: last_seen:2019-07-28 classification:malicious
count: 1
message: ok
restricted_fields:
- ip
- asn
- organization
- country
- city
- region
data: []
'206':
description: 'Partial content - request partially successful.
Due to plan limitations, your request only returned a subset of
fields and/or data. Contact sales@greynoise.io to upgrade your
plan and unlock full results.
'
content:
application/json:
schema:
$ref: '#/components/schemas/GNQLV3Response'
examples:
GnqlV3Query206Example:
summary: Default gnqlV3Query 206 response
x-microcks-default: true
value:
request_metadata:
complete: false
scroll: 'DnF1ZXJ5VGhlbkZldGNoBQAAAAAAeygtFkFKSExEdUc4VEtta2syaGg2R3kzNGcAAAAAAH soLhZBSkhMRHVHOFRLbWtrMmhoNkd5MzRnAAAAAAB7KC8WQUpITER1RzhUS21razJoaDZH eTM0ZwAAAAAAeygxFkFKSExEdUc4VEtta2syaGg2R3kzNGcAAAAAAHsoMBZBSkhMRHVHOF RLbWtrMmhoNkd5MzRn
'
query: last_seen:2019-07-28 classification:malicious
adjusted_query: last_seen:2019-07-28 classification:malicious
count: 1
message: ok
restricted_fields:
- ip
- asn
- organization
- country
- city
- region
data: []
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/ExceededLimit'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/v3/gnql/metadata:
get:
tags:
- GNQL
summary: GNQL V3 Metadata Query
operationId: gnqlV3MetadataQuery
description: 'GreyNoise Query Language Metadata Endpoint
This endpoint provides the same functionality as the main GNQL endpoint
but with additional field filtering capabilities. It automatically excludes
raw data from responses and allows you to specify additional fields to exclude.
The metadata endpoint is designed for use cases where you need to retrieve
IP intelligence data without the raw scan data, making it more efficient
for metadata-focused queries.
_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._
'
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
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: exclude
description: 'Comma-separated list of additional fields to exclude from the response.
`raw_data` is always excluded by this endpoint; specifying it is redundant.
Recognized top-level response fields (e.g. `tags`, `cves`, `vpn`, `tor`, `metadata`)
and `metadata.<subfield>` paths (e.g. `metadata.organization`, `metadata.source_country`,
`metadata.destination_countries`) are accepted. The special value `tags.details`
preserves tag identity (id, slug) and strips only the enriched details. Unknown
field names return 400.
'
required: false
schema:
type: string
example: metadata.organization,metadata.city,metadata.rdns
responses:
'200':
description: OK - request successful.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/GNQLV3Response'
- $ref: '#/components/schemas/QuickGNQLV3Response'
examples:
GnqlV3MetadataQuery200Example:
summary: Default gnqlV3MetadataQuery 200 response
x-microcks-default: true
value:
request_metadata:
complete: false
scroll: 'DnF1ZXJ5VGhlbkZldGNoBQAAAAAAeygtFkFKSExEdUc4VEtta2syaGg2R3kzNGcAAAAAAH soLhZBSkhMRHVHOFRLbWtrMmhoNkd5MzRnAAAAAAB7KC8WQUpITER1RzhUS21razJoaDZH eTM0ZwAAAAAAeygxFkFKSExEdUc4VEtta2syaGg2R3kzNGcAAAAAAHsoMBZBSkhMRHVHOF RLbWtrMmhoNkd5MzRn
'
query: last_seen:2019-07-28 classification:malicious
adjusted_query: last_seen:2019-07-28 classification:malicious
count: 1
message: ok
restricted_fields:
- ip
- asn
- organization
- country
- city
- region
data: []
'206':
description: 'Partial content - request partially successful.
Due to plan limitations, your request only returned a subset of
fields and/or data. Contact sales@greynoise.io to upgrade your
plan and unlock full results.
'
content:
application/json:
schema:
$ref: '#/components/schemas/GNQLV3Response'
examples:
GnqlV3MetadataQuery206Example:
summary: Default gnqlV3MetadataQuery 206 response
x-microcks-default: true
value:
request_metadata:
complete: false
scroll: 'DnF1ZXJ5VGhlbkZldGNoBQAAAAAAeygtFkFKSExEdUc4VEtta2syaGg2R3kzNGcAAAAAAH soLhZBSkhMRHVHOFRLbWtrMmhoNkd5MzRnAAAAAAB7KC8WQUpITER1RzhUS21razJoaDZH eTM0ZwAAAAAAeygxFkFKSExEdUc4VEtta2syaGg2R3kzNGcAAAAAAHsoMBZBSkhMRHVHOF RLbWtrMmhoNkd5MzRn
'
query: last_seen:2019-07-28 classification:malicious
adjusted_query: last_seen:2019-07-28 classification:malicious
count: 1
message: ok
restricted_fields:
- ip
- asn
- organization
- country
- city
- region
data: []
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/ExceededLimit'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/v3/gnql/stats:
get:
tags:
- GNQL
summary: GNQL V3 Stats
operationId: gnqlV3Stats
description: 'Get aggregate statistics for the top organizations, actors, tags,
ASNs, countries, classifications, and operating systems of all the
results of a given GNQL query.
'
parameters:
- $ref: '#/components/parameters/query'
- in: query
name: count
description: Number of top aggregates to grab
required: false
schema:
type: integer
minimum: 1
maximum: 10000
default: 1000
responses:
'200':
description: Query successful.
content:
application/json:
schema:
$ref: '#/components/schemas/GNQLStats'
examples:
GnqlV3Stats200Example:
summary: Default gnqlV3Stats 200 response
x-microcks-default: true
value:
query: last_seen:2019-07-28 classification:malicious
count: 50000
adjusted_query: last_seen:2019-07-28 classification:malicious last_seen:7d
stats:
classifications:
- classification: malicious
count: 5000
spoofable:
- spoofable: false
count: 5000
organizations:
- organization: DigitalOcean, LLC
count: 5000
actors:
- actor: Shodan.io
count: 5000
countries:
- country: United States
count: 5000
source_countries:
- country: United States
count: 5000
destination_countries:
- country: United States
count: 5000
tags:
- tag: SSH Bruteforcer
id: 4c076d9c-be48-4bd1-bec4-6005e06c0f89
count: 5000
operating_systems:
- operating_system: Windows 7/8
count: 5000
categories:
- category: education
count: 5000
asns:
- asn: AS4134
count: 5000
'206':
description: 'Partial content - request partially successful.
Due to plan limitations, your request only returned a subset of
fields and/or data. The `adjusted_query` field in the response
indicates how the original query was modified. Contact
sales@greynoise.io to upgrade your plan and unlock full results.
'
content:
application/json:
schema:
$ref: '#/components/schemas/GNQLStats'
examples:
GnqlV3Stats206Example:
summary: Default gnqlV3Stats 206 response
x-microcks-default: true
value:
query: last_seen:2019-07-28 classification:malicious
count: 50000
adjusted_query: last_seen:2019-07-28 classification:malicious last_seen:7d
stats:
classifications:
- classification: malicious
count: 5000
spoofable:
- spoofable: false
count: 5000
organizations:
- organization: DigitalOcean, LLC
count: 5000
actors:
- actor: Shodan.io
count: 5000
countries:
- country: United States
count: 5000
source_countries:
- country: United States
count: 5000
destination_countries:
- country: United States
count: 5000
tags:
- tag: SSH Bruteforcer
id: 4c076d9c-be48-4bd1-bec4-6005e06c0f89
count: 5000
operating_systems:
- operating_system: Windows 7/8
count: 5000
categories:
- category: education
count: 5000
asns:
- asn: AS4134
count: 5000
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/ExceededLimit'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
responses:
BadRequest:
description: 'Bad request - request syntax is invalid for the specified endpoint.
Verify request syntax and try again.
'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Invalid parameter
Forbidden:
description: 'Forbidden - request is not authorized due to an invalid API key or plan limitations.
If due to plan limitations, contact sales@greynoise.io to upgrade your plan and unlock full results.
'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Forbidden
Unauthorized:
description: Unauthorized. Please check your API key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Unauthorized
ExceededLimit:
description: Too many requests. You've hit the rate-limit.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: You've hit the rate limit for this endpoint.
schemas:
Error:
type: object
properties:
message:
type: string
example: Success
required:
- message
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'
example: []
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'
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'
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'
example: []
QuickBusinessServiceIntelligence:
type: object
properties:
found:
type: boolean
description: 'Indicates if an IP is part of the RIOT dataset or not.
'
example: false
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-
# --- truncated at 32 KB (61 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/greynoise/refs/heads/main/openapi/greynoise-gnql-api-openapi.yml