openapi: 3.0.0
info:
title: GreyNoise 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: [email protected]
license:
name: Proprietary
url: https://www.greynoise.io/terms
servers:
- url: https://api.greynoise.io
description: Production
security:
- APIKeyHeaderAuth: []
tags:
- name: CVE
description: "Endpoints that are used for retrieving information about Common Vulnerabilities and Exposures (CVEs).\n"
- name: Sessions
description: "Endpoints for querying, analyzing, and exporting raw network session (PCAP)\ndata captured by GreyNoise sensors. Use the `scope` parameter to control\ndata access (workspace or demo). Required entitlements vary by scope.\n"
- name: Community
description: Endpoints for the community level users
- name: IP Timeline
description: "Noise data captures internet scanning activity against GreyNoise sensors\ndeployed globally.\nThe IP Timeline APIs allow temporal analysis and presents the user with a\nview of how this data has changed over the time.\n"
- name: Recall
description: "Endpoint that are used for retrieving GNQL data over time. Allows users\nto view hourly snapshots of IP activity for IPs that return for any\nGNQL query.\n"
- name: GNQL
description: Calls to interface with GNQL (GreyNoise Query Language).
- name: Tags
description: "Endpoints for retrieving tag information, metadata, and associated activity data.\n"
- name: Utility
description: "Endpoints that are used for checking status or retrieving basic metadata\n"
- name: IP Lookup
description: Calls to identify whether or not an IP address is noise, or get more information about a given IP address.
paths:
/ping:
get:
operationId: ping
tags:
- Utility
summary: Ping
description: "Provides a simple endpoint to check GreyNoise status and GreyNoise\nAPI access\n"
responses:
'200':
description: Ping successful
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: pong
expiration:
type: string
description: API key expiration date
example: '2026-12-31'
offering:
type: string
description: Compatibility offering value. Currently always enterprise for authenticated requests.
example: enterprise
address:
type: string
description: Client IP address
example: 3.215.138.152
plan:
type: string
description: Active subscription plan name
example: Elite
modules:
type: string
description: Comma-separated list of active add-on module names
example: Hunt,Vulnerability Prioritization
examples:
Ping200Example:
summary: Default ping 200 response
x-microcks-default: true
value:
message: pong
expiration: '2026-12-31'
offering: enterprise
address: 3.215.138.152
plan: Elite
modules: Hunt,Vulnerability Prioritization
'401':
$ref: '#/components/responses/Unauthorized'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/v1/callback/export-ips:
post:
tags:
- Callback
summary: Export Callback IPs
operationId: CallbackExportIPs
description: "Export callback IPs matching the given filters as a newline-delimited\nplain text list. Supports the same filter parameters as the List\nCallback IPs endpoint.\n"
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/CallbackFilterFields'
examples:
CallbackExportIPsRequestExample:
summary: Default CallbackExportIPs request
x-microcks-default: true
value:
is_stage_1: false
is_stage_2: false
first_seen_after: '2026-05-01'
first_seen_before: '2026-05-01'
last_seen_after: '2026-05-01'
last_seen_before: '2026-05-01'
has_files: false
file_type: string
file_name: Google Public DNS
file_hash: 795bc7ce13f60d61e9ac03611dd36d90
scanner_ips: &id001
- string
ips: &id002
- string
responses:
'200':
description: OK - newline-delimited list of callback IPs.
content:
text/plain:
schema:
type: string
example: "198.51.100.42\n203.0.113.7\n192.0.2.99\n"
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/UnexpectedError'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/v1/callback/ip/{ip}:
get:
tags:
- Callback
summary: Callback IP Lookup
operationId: CallbackGetIP
description: "Retrieve detailed information about a specific callback IP, including\nattack stage, scanner associations, and downloaded malware files.\n"
parameters:
- name: ip
in: path
description: The callback IP address to look up.
required: true
schema:
type: string
example: 198.51.100.42
responses:
'200':
description: OK - callback IP details returned.
content:
application/json:
schema:
$ref: '#/components/schemas/CallbackIPDetailResponse'
examples:
CallbackGetIP200Example:
summary: Default CallbackGetIP 200 response
x-microcks-default: true
value:
ip: 198.51.100.42
source_workspaces: &id033
- GreyNoise
- UserWorkspace
is_stage_1: false
is_stage_2: false
first_seen: '2025-03-01T00:00:00Z'
last_seen: '2025-03-15T12:30:00Z'
scanner_ips: &id034
- 203.0.113.7
- 192.0.2.99
scanner_count: 5
file_count: 3
active_files: &id035 []
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/UnexpectedError'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/v1/callback/ips:
post:
tags:
- Callback
summary: List Callback IPs
operationId: CallbackListIPs
description: "Retrieve a paginated list of callback IPs with filtering by attack\nstage, date ranges, file attributes, and scanner associations.\n"
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/CallbackListIPsRequest'
examples:
CallbackListIPsRequestExample:
summary: Default CallbackListIPs request
x-microcks-default: true
value:
is_stage_1: false
is_stage_2: false
first_seen_after: '2026-05-01'
first_seen_before: '2026-05-01'
last_seen_after: '2026-05-01'
last_seen_before: '2026-05-01'
has_files: false
file_type: string
file_name: Google Public DNS
file_hash: 795bc7ce13f60d61e9ac03611dd36d90
scanner_ips: *id001
ips: *id002
page: 100
page_size: 100
responses:
'200':
description: OK - paginated list of callback IPs returned.
content:
application/json:
schema:
$ref: '#/components/schemas/CallbackListIPsResponse'
examples:
CallbackListIPs200Example:
summary: Default CallbackListIPs 200 response
x-microcks-default: true
value:
items: &id036 []
total: 142
page: 0
page_size: 20
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/UnexpectedError'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/v1/callback/overview:
post:
tags:
- Callback
summary: Callback Overview Statistics
operationId: CallbackOverview
description: "Retrieve aggregate statistics for callback IPs including counts by\nattack stage, file analysis status, scanner associations, and top\nthreat names.\n"
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/CallbackFilterFields'
examples:
CallbackOverviewRequestExample:
summary: Default CallbackOverview request
x-microcks-default: true
value:
is_stage_1: false
is_stage_2: false
first_seen_after: '2026-05-01'
first_seen_before: '2026-05-01'
last_seen_after: '2026-05-01'
last_seen_before: '2026-05-01'
has_files: false
file_type: string
file_name: Google Public DNS
file_hash: 795bc7ce13f60d61e9ac03611dd36d90
scanner_ips: *id001
ips: *id002
responses:
'200':
description: OK - overview statistics returned.
content:
application/json:
schema:
$ref: '#/components/schemas/CallbackOverviewResponse'
examples:
CallbackOverview200Example:
summary: Default CallbackOverview 200 response
x-microcks-default: true
value:
total_ips: 142
stage_1_ips: 98
stage_2_ips: 44
total_files: 230
files_with_vt: 180
files_without_vt: 50
total_cross_refs: 312
total_scanner_links: 456
ips_with_files: 110
ips_without_files: 32
ips_with_scanners: 130
ips_without_scanners: 12
distinct_scanners: 89
top_threat_names: &id037 []
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/UnexpectedError'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/v1/cve/{cve_id}:
get:
operationId: getCVE
tags:
- CVE
summary: Retrieve CVE Information
description: Retrieve details about a specific Common Vulnerabilities and Exposures (CVE).
parameters:
- name: cve_id
in: path
description: The CVE ID to query (e.g., CVE-2024-12345)
required: true
schema:
type: string
pattern: ^CVE-\d{4}-\d+$
responses:
'200':
description: Successful response with CVE details based on entitlements.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/CVEAdvancedResponse'
- $ref: '#/components/schemas/CVEBasicResponse'
- $ref: '#/components/schemas/CVEMinimalResponse'
examples:
GetCVE200Example:
summary: Default getCVE 200 response
x-microcks-default: true
value:
id: CVE-2024-12345
details:
vulnerability_name: Sample Vulnerability
vulnerability_description: This vulnerability allows remote attackers to execute arbitrary code.
cve_cvss_score: 7.5
product: Sample Product
vendor: Sample Vendor
published_to_nist_nvd: true
timeline:
cve_published_date: '2024-01-01'
cve_last_updated_date: '2024-01-02'
first_known_published_date: '2024-01-01'
cisa_kev_date_added: '2024-01-03'
exploitation_details:
attack_vector: Network
exploit_found: true
exploitation_registered_in_kev: true
epss_score: 0.8
exploitation_stats:
number_of_available_exploits: 5
number_of_threat_actors_exploiting_vulnerability: 3
number_of_botnets_exploiting_vulnerability: 2
exploitation_activity:
activity_seen: true
benign_ip_count_1d: 100
benign_ip_count_10d: 500
benign_ip_count_30d: 1000
threat_ip_count_1d: 10
threat_ip_count_10d: 50
threat_ip_count_30d: 100
'400':
description: Invalid CVE ID format or missing CVE ID.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: 'bad query: invalid CVE format'
'404':
description: CVE not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: CVE not found
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: internal server error
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/v3/community/{ip}:
get:
operationId: getCommunityIP
parameters:
- $ref: '#/components/parameters/ip'
tags:
- Community
summary: Community API
description: "The Community API provides community users with a free tool to\nquery IPs in the GreyNoise dataset and retrieve a subset of the full\nIP context data returned by the IP Lookup API.\n"
responses:
'200':
description: Query was successful, Community API found either a RIOT or Noise record for submitted IP address.
content:
application/json:
schema:
$ref: '#/components/schemas/CommunityResponse'
examples:
GetCommunityIP200Example:
summary: Default getCommunityIP 200 response
x-microcks-default: true
value:
ip: 1.2.3.4
noise: false
riot: true
classification: benign
name: Cloudflare
link: https://viz.greynoise.io/riot/1.2.3.4
last_seen: '2020-01-01'
message: Success
'400':
description: "The IP address submitted is not a valid routable IPv4 address.\n"
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Request is not a valid routable IPv4 address
examples:
GetCommunityIP400Example:
summary: Default getCommunityIP 400 response
x-microcks-default: true
value:
message: Request is not a valid routable IPv4 address
'404':
description: The community API was unable to find a record for the requested IP address.
content:
application/json:
schema:
type: object
properties:
ip:
type: string
example: 1.2.3.4
noise:
type: boolean
example: false
riot:
type: boolean
example: false
message:
type: string
example: IP not observed scanning the internet or contained in RIOT data set.
examples:
GetCommunityIP404Example:
summary: Default getCommunityIP 404 response
x-microcks-default: true
value:
ip: 1.2.3.4
noise: false
riot: false
message: IP not observed scanning the internet or contained in RIOT data set.
'429':
description: Predefined rate-limit has been reached
content:
application/json:
schema:
type: object
properties:
plan:
type: string
example: unauthenticated
rate-limit:
type: string
example: 100-lookups/day
plan_url:
type: string
example: https://greynoise.io/pricing
message:
type: string
example: "You have hit your daily rate limit of 100 requests per day. Please create a free account or upgrade your plan at https://greynoise.io/pricing.\n"
examples:
GetCommunityIP429Example:
summary: Default getCommunityIP 429 response
x-microcks-default: true
value:
plan: unauthenticated
rate-limit: 100-lookups/day
plan_url: https://greynoise.io/pricing
message: "You have hit your daily rate limit of 100 requests per day. Please create a free account or upgrade your plan at https://greynoise.io/pricing.\n"
'500':
$ref: '#/components/responses/UnexpectedError'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/v3/cves:
post:
operationId: bulkCVELookup
tags:
- CVE
summary: Bulk CVE Lookup
description: "Retrieve information about multiple CVEs in a single request. Supports up to 10,000 CVEs per request.\n\nThis endpoint requires a business email address and appropriate entitlements.\nResponse type depends on user entitlements (minimal, basic, or advanced).\n"
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- cves
properties:
cves:
type: array
items:
type: string
pattern: ^CVE-\d{4}-\d+$
description: Array of CVE IDs to lookup
example: &id003
- CVE-2024-12345
- CVE-2023-45678
maxItems: 10000
examples:
BulkCVELookupRequestExample:
summary: Default bulkCVELookup request
x-microcks-default: true
value:
cves: *id003
responses:
'200':
description: OK - request successful.
content:
application/json:
schema:
type: array
items:
oneOf:
- $ref: '#/components/schemas/CVEAdvancedResponse'
- $ref: '#/components/schemas/CVEBasicResponse'
- $ref: '#/components/schemas/CVEMinimalResponse'
examples:
BulkCVELookup200Example:
summary: Default bulkCVELookup 200 response
x-microcks-default: true
value:
- id: CVE-2024-12345
details:
vulnerability_name: Sample Vulnerability
vulnerability_description: This vulnerability allows remote attackers to execute arbitrary code.
cve_cvss_score: 7.5
product: Sample Product
vendor: Sample Vendor
published_to_nist_nvd: true
timeline:
cve_published_date: '2024-01-01'
cve_last_updated_date: '2024-01-02'
first_known_published_date: '2024-01-01'
cisa_kev_date_added: '2024-01-03'
exploitation_details:
attack_vector: Network
exploit_found: true
exploitation_registered_in_kev: true
epss_score: 0.8
exploitation_stats:
number_of_available_exploits: 5
number_of_threat_actors_exploiting_vulnerability: 3
number_of_botnets_exploiting_vulnerability: 2
exploitation_activity:
activity_seen: true
benign_ip_count_1d: 100
benign_ip_count_10d: 500
benign_ip_count_30d: 1000
threat_ip_count_1d: 10
threat_ip_count_10d: 50
threat_ip_count_30d: 100
'400':
description: "Bad request - invalid CVE format or too many CVEs requested.\n"
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Maximum number of CVEs per request is 10000
'403':
description: "Forbidden - bulk CVE search requires a business email address.\n"
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Bulk CVE search is only available to users with a business email address. Sign up with your work email (e.g., [email protected]) to continue.
'429':
description: Too many requests. You've hit the rate-limit.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
BulkCVELookup429Example:
summary: Default bulkCVELookup 429 response
x-microcks-default: true
value:
message: Success
'500':
$ref: '#/components/responses/UnexpectedError'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/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.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 s
# --- truncated at 32 KB (187 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/greynoise/refs/heads/main/openapi/greynoise-openapi.yml