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: hello@greynoise.io 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., you@company.com) 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 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* 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* `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' examples: GnqlV3Query200Example: summary: Default gnqlV3Query 200 response x-microcks-default: true value: request_metadata: complete: false scroll: "DnF1ZXJ5VGhlbkZldGNoBQAAAAAAeygtFkFKSExEdUc4VEtta2syaGg2R3kzNGcAAAAAAH soLhZBSkhMRHVHOFRLbWtrMmhoNkd5MzRnAAAAAAB7KC8WQUpITER1RzhUS21razJoaDZH eTM0ZwAAAAAAeygxFkFKSExEdUc4VEtta2syaGg2R3kzNGcAAAAAAHsoMBZBSkhMRHVHOF RLbWtrMmhoNkd5MzRn\n" query: last_seen:2019-07-28 classification:malicious adjusted_query: last_seen:2019-07-28 classification:malicious count: 1 message: ok restricted_fields: &id004 - ip - asn - organization - country - city - region data: &id005 [] '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' examples: GnqlV3Query206Example: summary: Default gnqlV3Query 206 response x-microcks-default: true value: request_metadata: complete: false scroll: "DnF1ZXJ5VGhlbkZldGNoBQAAAAAAeygtFkFKSExEdUc4VEtta2syaGg2R3kzNGcAAAAAAH soLhZBSkhMRHVHOFRLbWtrMmhoNkd5MzRnAAAAAAB7KC8WQUpITER1RzhUS21razJoaDZH eTM0ZwAAAAAAeygxFkFKSExEdUc4VEtta2syaGg2R3kzNGcAAAAAAHsoMBZBSkhMRHVHOF RLbWtrMmhoNkd5MzRn\n" query: last_seen:2019-07-28 classification:malicious adjusted_query: last_seen:2019-07-28 classification:malicious count: 1 message: ok restricted_fields: *id004 data: *id005 '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\nThis endpoint provides the same functionality as the main GNQL endpoint\nbut with additional field filtering capabilities. It automatically excludes\nraw data from responses and allows you to specify additional fields to exclude.\n\nThe metadata endpoint is designed for use cases where you need to retrieve\nIP intelligence data without the raw scan data, making it more efficient\nfor metadata-focused queries.\n\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._\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 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.\n`raw_data` is always excluded by this endpoint; specifying it is redundant.\nRecognized top-level response fields (e.g. `tags`, `cves`, `vpn`, `tor`, `metadata`)\nand `metadata.` paths (e.g. `metadata.organization`, `metadata.source_country`,\n`metadata.destination_countries`) are accepted. The special value `tags.details`\npreserves tag identity (id, slug) and strips only the enriched details. Unknown\nfield names return 400.\n" 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\n" query: last_seen:2019-07-28 classification:malicious adjusted_query: last_seen:2019-07-28 classification:malicious count: 1 message: ok restricted_fields: *id004 data: *id005 '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' examples: GnqlV3MetadataQuery206Example: summary: Default gnqlV3MetadataQuery 206 response x-microcks-default: true value: request_metadata: complete: false scroll: "DnF1ZXJ5VGhlbkZldGNoBQAAAAAAeygtFkFKSExEdUc4VEtta2syaGg2R3kzNGcAAAAAAH soLhZBSkhMRHVHOFRLbWtrMmhoNkd5MzRnAAAAAAB7KC8WQUpITER1RzhUS21razJoaDZH eTM0ZwAAAAAAeygxFkFKSExEdUc4VEtta2syaGg2R3kzNGcAAAAAAHsoMBZBSkhMRHVHOF RLbWtrMmhoNkd5MzRn\n" query: last_seen:2019-07-28 classification:malicious adjusted_query: last_seen:2019-07-28 classification:malicious count: 1 message: ok restricted_fields: *id004 data: *id005 '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,\nASNs, countries, classifications, and operating systems of all the\nresults of a given GNQL query.\n" 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.\nDue to plan limitations, your request only returned a subset of\nfields and/or data. The `adjusted_query` field in the response\nindicates how the original query was modified. Contact\nsales@greynoise.io to upgrade your plan and unlock full results.\n" 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 /v3/gnql/timeseries: get: tags: - Recall summary: GNQL V3 Recall operationId: gnqlTimeSeries description: "Get hourly GNQL records for a given time range.\n" parameters: - $ref: '#/components/parameters/query' - in: query name: start description: Start date for the desired time range required: false schema: type: string format: date-time example: '2025-01-01T00:00:00Z' - in: query name: end description: End date for the desired time range required: false schema: type: string format: date-time example: '2025-01-07T23:59:59Z' - 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: limit description: Specifies the number of records desired from the backend query. For example, if you specify a limit of 100, you will get the first 100 records for your query, divided up by hour. required: false schema: type: integer - in: query name: offset description: Specifies the offset at which to apply the limit. With limit, can be used to paginate through a large response. For example, if you specify a limit of 100 and and an offset of 200, you will get the next 100 records starting at the 200th record. required: false schema: type: integer responses: '200': description: Query successful. content: application/json: schema: $ref: '#/components/schemas/TimeSeriesResponse' examples: GnqlTimeSeries200Example: summary: Default gnqlTimeSeries 200 response x-microcks-default: true value: &id006 2025-11-10-14: - ip: 203.0.113.45 internet_scanner_intelligence: first_seen: '2018-01-28' last_seen: '2018-02-28' found: true tags: - Mirai - Telnet Worm actor: Shodan.io spoofable: true classification: benign cves: - CVE-2020-1234 - CVE-2021-2345 vpn: true vpn_service: IPVANISH_VPN tor: false last_seen_timestamp: '2025-01-15T12:30:45Z' metadata: asn: AS13335 source_country: United States source_country_code: US organization: Example Hosting raw_data: scan: - port: 22 protocol: tcp '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/TimeSeriesResponse' examples: GnqlTimeSeries206Example: summary: Default gnqlTimeSeries 206 response x-microcks-default: true value: *id006 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/ExceededLimit' x-microcks-operation: delay: 0 dispatcher: FALLBACK /v3/gnql/timeseries/stats: get: tags: - Recall summary: GNQL V3 Recall Stats operationId: gnqlTimeSeriesStats description: "Get the number of unique IPs that match a GNQL query\nper hour/day over a given time range.\n" parameters: - $ref: '#/components/parameters/query' - in: query name: start description: Start date for the desired time range required: false schema: type: string format: date-time example: '2025-01-01T00:00:00Z' - in: query name: end description: End date for the desired time range required: false schema: type: string format: date-time example: '2025-01-07T23:59:59Z' - 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: interval description: Specifies the time interval over which to aggregate unique IPs that return the given GNQL query. required: true schema: type: string enum: - hour - day responses: '200': description: Query successful. content: application/json: schema: $ref: '#/components/schemas/TimeSeriesStatsResponse' examples: GnqlTimeSeriesStats200Example: summary: Default gnqlTimeSeriesStats 200 response x-microcks-default: true value: &id007 count: 1500 min: 10 max: 250 data: - date: '2025-11-10 14:00:00.000' count: 125 - date: '2025-11-10 15:00:00.000' count: 250 - date: '2025-11-10 16:00:00.000' count: 180 '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/TimeSeriesStatsResponse' examples: GnqlTimeSeriesStats206Example: summary: Default gnqlTimeSeriesStats 206 response x-microcks-default: true value: *id007 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/ExceededLimit' x-microcks-operation: delay: 0 dispatcher: FALLBACK /v3/ip: post: tags: - IP Lookup summary: IP Lookup - Multi operationId: V3MultiIP description: "Retrieves information about the submitted set of IP addresses\nfrom the Internet Scanner and Business Service intelligence datasets\n(consolidated response based on subscription entitlements).\nReturns time ranges, IP metadata (network owner, ASN, reverse DNS pointer, country),\nassociated actors, tags, raw port scan data, web request information,\nclassification and/or trust level, and provider information.\n\nUse the `quick` parameter to return a subset of the response fields, for a faster response time.\n\nCan process up to 10,000 IPs per request.\n" requestBody: $ref: '#/components/requestBodies/MultiIpRequest' parameters: - 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 - $ref: '#/components/parameters/workspaceLabels' responses: '200': description: OK - request successful. content: application/json: schema: oneOf: - $ref: '#/components/schemas/MultiIPResponseV3' - $ref: '#/components/schemas/QuickMultiIPResponseV3' examples: V3MultiIP200Example: summary: Default V3MultiIP 200 response x-microcks-default: true value: data: - ip: 8.8.8.8 business_service_intelligence: found: true category: hosting name: example.com description: example.com explanation: string last_updated: '2025-01-15T12:30:45Z' reference: https://example.com trust_level: '1' internet_scanner_intelligence: ip: 71.6.135.131 seen: true classification: benign first_seen: '2018-01-28' last_seen: '2018-02-28' last_seen_timestamp: '2025-01-15T12:30:45Z' found: true actor: Shodan.io spoofable: true cves: &id008 - CVE-2020-1234 - CVE-2021-2345 tor: false vpn: true vpn_service: IPVANISH_VPN metadata: mobile: false source_country: United States source_country_code: US source_city: Seattle region: Seattle organization: DigitalOcean, LLC rdns: crawl-66-249-79-17.googlebot.com asn: AS521 category: education os: Windows 7/8 destination_countries: &id009 - string destination_country_codes: &id010 - US destination_cities: &id011 - string destination_asns: &id012 - string single_destination: true carrier: AIS datacenter: us-west-1 domain: example.com rdns_parent: example.com rdns_validated: true latitude: 37.7749 longitude: -122.4194 sensor_count: 10 sensor_hits: 10 tags: id: ef0cc90d-d80c-436f-92c5-3d8f8665c9ac slug: mirai name: Mirai category: worm intention: malicious description: This IP address exhibits behavior that indicates it is infected with Mirai or a Mirai-like variant of malware. references: &id013 - string recommend_block: false cves: &id014 - CVE-2021-44228 created_at: '2020-04-07' updated_at: '2020-04-07' raw_data: scan: - port: 80 protocol: TCP ja3: - fingerprint: c3a6cf0bf2e690ac8e1ecf6081f17a50 port: 443 hassh: - fingerprint: 51cba57125523ce4b9db67714a90bf6e port: 2222 http: md5: 9764955b67107eeb9edfae76f429e783 cookie_keys: &id015 - expremotekey request_authorization: &id016 - Bearer exampletoken - Basic username:password request_cookies: &id017 - session_id=1234567890 request_header: &id018 - 'Content-Type: application/json' - 'Accept: application/json' method: &id019 - GET - POST - PUT - DELETE request_origin: &id020 - 111.111.1.1 host: &id021 - example.com - example.com:8080 uri: &id022 - string path: &id023 - /HNAP1/ useragent: &id024 - Mozilla/5.0 (compatible; GoogleBot/2.1; +http://www.google.com/bot.html) ja4h: &id025 - ge11cn060000_4e59edc1297a_4da5efaf0cbd tls: cipher: TLS_AES_128_GCM_SHA256 ja4: &id026 - t13d1516h2_8daaf6152771_02713d6af862 ssh: key: &id027 - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC1234567890 ja4ssh: &id028 - c76s76_c71s59_c0s0 tcp: ja4t: &id029 - 64240_2-1-3-1-1-4_1460_8 ja4l: '1460_64' source: string request_metadata: restricted_fields: &id030 - ip - cve - destination_cities message: ok ips_not_found: &id031 - string '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: oneOf: - $ref: '#/components/schemas/MultiIPResponseV3' - $ref: '#/components/schemas/QuickMultiIPResponseV3' examples: V3MultiIP206Example: summary: Default V3MultiIP 206 response x-microcks-default: true value: data: - ip: 8.8.8.8 business_service_intelligence: found: true category: hosting name: example.com description: example.com explanation: string last_updated: '2025-01-15T12:30:45Z' reference: https://example.com trust_level: '1' internet_scanner_intelligence: ip: 71.6.135.131 seen: true classification: benign first_seen: '2018-01-28' last_seen: '2018-02-28' last_seen_timestamp: '2025-01-15T12:30:45Z' found: true actor: Shodan.io spoofable: true cves: *id008 tor: false vpn: true vpn_service: IPVANISH_VPN metadata: mobile: false source_country: United States source_country_code: US source_city: Seattle region: Seattle organization: DigitalOcean, LLC rdns: crawl-66-249-79-17.googlebot.com asn: AS521 category: education os: Windows 7/8 destination_countries: *id009 destination_country_codes: *id010 destination_cities: *id011 destination_asns: *id012 single_destination: true carrier: AIS datacenter: us-west-1 domain: example.com rdns_parent: example.com rdns_validated: true latitude: 37.7749 longitude: -122.4194 sensor_count: 10 sensor_hits: 10 tags: id: ef0cc90d-d80c-436f-92c5-3d8f8665c9ac slug: mirai name: Mirai category: worm intention: malicious description: This IP address exhibits behavior that indicates it is infected with Mirai or a Mirai-like variant of malware. references: *id013 recommend_block: false cves: *id014 created_at: '2020-04-07' updated_at: '2020-04-07' raw_data: scan: - port: 80 protocol: TCP ja3: - fingerprint: c3a6cf0bf2e690ac8e1ecf6081f17a50 port: 443 hassh: - fingerprint: 51cba57125523ce4b9db67714a90bf6e port: 2222 http: md5: 9764955b67107eeb9edfae76f429e783 cookie_keys: *id015 request_authorization: *id016 request_cookies: *id017 request_header: *id018 method: *id019 request_origin: *id020 host: *id021 uri: *id022 path: *id023 useragent: *id024 ja4h: *id025 tls: cipher: TLS_AES_128_GCM_SHA256 ja4: *id026 ssh: key: *id027 ja4ssh: *id028 tcp: ja4t: *id029 ja4l: '1460_64' source: string request_metadata: restricted_fields: *id030 message: ok ips_not_found: *id031 '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/ip/{ip}: get: tags: - IP Lookup summary: IP Lookup operationId: V3IP description: "Get more information about a given IP address. Returns time ranges,\nIP metadata (network owner, ASN, reverse DNS pointer, country),\nassociated actors, activity tags, and raw port scan and web\nrequest information.\n\nUse the `quick` parameter to return a subset of the response fields, for a faster response time.\n" parameters: - $ref: '#/components/parameters/ip' - 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 - $ref: '#/components/parameters/workspaceLabels' responses: '200': description: OK - request successful. content: application/json: schema: oneOf: - $ref: '#/components/schemas/IPResponseV3' - $ref: '#/components/schemas/QuickIpProfile' examples: V3IP200Example: summary: Default V3IP 200 response x-microcks-default: true value: ip: 8.8.8.8 business_service_intelligence: found: true category: hosting name: example.com description: example.com explanation: string last_updated: '2025-01-15T12:30:45Z' reference: https://example.com trust_level: '1' internet_scanner_intelligence: ip: 71.6.135.131 seen: true classification: benign first_seen: '2018-01-28' last_seen: '2018-02-28' last_seen_timestamp: '2025-01-15T12:30:45Z' found: true actor: Shodan.io spoofable: true cves: *id008 tor: false vpn: true vpn_service: IPVANISH_VPN metadata: mobile: false source_country: United States source_country_code: US source_city: Seattle region: Seattle organization: DigitalOcean, LLC rdns: crawl-66-249-79-17.googlebot.com asn: AS521 category: education os: Windows 7/8 destination_countries: *id009 destination_country_codes: *id010 destination_cities: *id011 destination_asns: *id012 single_destination: true carrier: AIS datacenter: us-west-1 domain: example.com rdns_parent: example.com rdns_validated: true latitude: 37.7749 longitude: -122.4194 sensor_count: 10 sensor_hits: 10 tags: id: ef0cc90d-d80c-436f-92c5-3d8f8665c9ac slug: mirai name: Mirai category: worm intention: malicious description: This IP address exhibits behavior that indicates it is infected with Mirai or a Mirai-like variant of malware. references: *id013 recommend_block: false cves: *id014 created_at: '2020-04-07' updated_at: '2020-04-07' raw_data: scan: - port: 80 protocol: TCP ja3: - fingerprint: c3a6cf0bf2e690ac8e1ecf6081f17a50 port: 443 hassh: - fingerprint: 51cba57125523ce4b9db67714a90bf6e port: 2222 http: md5: 9764955b67107eeb9edfae76f429e783 cookie_keys: *id015 request_authorization: *id016 request_cookies: *id017 request_header: *id018 method: *id019 request_origin: *id020 host: *id021 uri: *id022 path: *id023 useragent: *id024 ja4h: *id025 tls: cipher: TLS_AES_128_GCM_SHA256 ja4: *id026 ssh: key: *id027 ja4ssh: *id028 tcp: ja4t: *id029 ja4l: '1460_64' source: string request_metadata: restricted_fields: &id032 - ip - cve - destination_cities '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: oneOf: - $ref: '#/components/schemas/IPResponseV3' - $ref: '#/components/schemas/QuickIpProfile' examples: V3IP206Example: summary: Default V3IP 206 response x-microcks-default: true value: ip: 8.8.8.8 business_service_intelligence: found: true category: hosting name: example.com description: example.com explanation: string last_updated: '2025-01-15T12:30:45Z' reference: https://example.com trust_level: '1' internet_scanner_intelligence: ip: 71.6.135.131 seen: true classification: benign first_seen: '2018-01-28' last_seen: '2018-02-28' last_seen_timestamp: '2025-01-15T12:30:45Z' found: true actor: Shodan.io spoofable: true cves: *id008 tor: false vpn: true vpn_service: IPVANISH_VPN metadata: mobile: false source_country: United States source_country_code: US source_city: Seattle region: Seattle organization: DigitalOcean, LLC rdns: crawl-66-249-79-17.googlebot.com asn: AS521 category: education os: Windows 7/8 destination_countries: *id009 destination_country_codes: *id010 destination_cities: *id011 destination_asns: *id012 single_destination: true carrier: AIS datacenter: us-west-1 domain: example.com rdns_parent: example.com rdns_validated: true latitude: 37.7749 longitude: -122.4194 sensor_count: 10 sensor_hits: 10 tags: id: ef0cc90d-d80c-436f-92c5-3d8f8665c9ac slug: mirai name: Mirai category: worm intention: malicious description: This IP address exhibits behavior that indicates it is infected with Mirai or a Mirai-like variant of malware. references: *id013 recommend_block: false cves: *id014 created_at: '2020-04-07' updated_at: '2020-04-07' raw_data: scan: - port: 80 protocol: TCP ja3: - fingerprint: c3a6cf0bf2e690ac8e1ecf6081f17a50 port: 443 hassh: - fingerprint: 51cba57125523ce4b9db67714a90bf6e port: 2222 http: md5: 9764955b67107eeb9edfae76f429e783 cookie_keys: *id015 request_authorization: *id016 request_cookies: *id017 request_header: *id018 method: *id019 request_origin: *id020 host: *id021 uri: *id022 path: *id023 useragent: *id024 ja4h: *id025 tls: cipher: TLS_AES_128_GCM_SHA256 ja4: *id026 ssh: key: *id027 ja4ssh: *id028 tcp: ja4t: *id029 ja4l: '1460_64' source: string request_metadata: restricted_fields: *id032 '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/noise/ips/{ip}/timeline: parameters: - in: path name: ip description: "IPv4 address to look up Noise time series activity timeline for\n" schema: type: string example: 36.32.2.102 required: true - in: query name: days description: Number of days to show data for schema: type: string example: '7' default: '1' required: false - in: query name: field description: Field over which to show activity breakdown schema: type: string enum: - destination_port - http_path - http_user_agent - source_asn - source_org - source_rdns - tag_ids - classification example: classification default: classification required: true - in: query name: granularity description: "Granularity of activity date ranges. This can be in hours (e.g. Xh)\nor days (Xd).\nValid hours are between 1 and 24. Valid days are between 1 and 90.\n" schema: type: string example: 8h default: 1d required: false - $ref: '#/components/parameters/workspaceLabels' get: operationId: getIPTimelineFieldSummary tags: - IP Timeline summary: IP Timeline Field Summary description: "Retrieve an IP address' summary of noise activity for a specific field.\n\n_License: This endpoint requires an additional subscription\nlicense to use._\n" responses: '200': description: Success - returns activity data content: application/json: schema: $ref: '#/components/schemas/IPTimelineResponse' examples: GetIPTimelineFieldSummary200Example: summary: Default getIPTimelineFieldSummary 200 response x-microcks-default: true value: results: - data: 1 label: unknown timestamp: '2023-01-23T00:00:00Z' metadata: ip: 36.32.2.102 field: classification first_seen: '2022-06-15' start: '2023-01-18T00:00:00Z' end: '2023-01-25T21:55:18.486036894Z' granularity: 1d metric: count '400': $ref: '#/components/responses/BadRequest' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/UnexpectedError' x-microcks-operation: delay: 0 dispatcher: FALLBACK /v3/sessions: get: tags: - Sessions summary: Get Sessions operationId: getSessions description: "Returns a paginated list of network sessions matching the query criteria.\nSessions represent individual network connections captured by GreyNoise sensors.\n" parameters: - $ref: '#/components/parameters/scope' - in: query name: start_time description: Start time for the query range (ISO 8601 format). required: true schema: type: string format: date-time example: '2025-01-01T00:00:00Z' - in: query name: end_time description: End time for the query range (ISO 8601 format). required: true schema: type: string format: date-time example: '2025-01-07T23:59:59Z' - in: query name: query description: Lucene query string to filter sessions. required: false schema: type: string - in: query name: page description: Page number for pagination. required: false schema: type: integer default: 1 minimum: 1 - in: query name: page_size description: Number of results per page. required: false schema: type: integer default: 25 minimum: 1 maximum: 100 - in: query name: sort_by description: Field to sort results by. required: false schema: type: string default: lastPacket - in: query name: sort_desc description: Whether to sort in descending order. required: false schema: type: string default: 'true' enum: - 'true' - 'false' responses: '200': description: OK - request successful. content: application/json: schema: $ref: '#/components/schemas/SessionsResponse' examples: GetSessions200Example: summary: Default getSessions 200 response x-microcks-default: true value: sessions: &id043 [] total: 150 pagination: page: 1 page_size: 25 sort_by: lastPacket sort_desc: true request_metadata: start_time: '2025-01-01T00:00:00Z' end_time: '2025-01-07T23:59:59Z' query: tags:Mirai '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/ExceededLimit' '500': $ref: '#/components/responses/UnexpectedError' x-microcks-operation: delay: 0 dispatcher: FALLBACK /v3/sessions/connections: get: tags: - Sessions summary: Get Session Connections operationId: getSessionConnections description: "Returns a graph of connections between source and destination fields.\nUseful for visualizing network relationships and communication patterns.\n" parameters: - $ref: '#/components/parameters/scope' - in: query name: start_time description: Start time for the query range (ISO 8601 format). required: true schema: type: string format: date-time example: '2025-01-01T00:00:00Z' - in: query name: end_time description: End time for the query range (ISO 8601 format). required: true schema: type: string format: date-time example: '2025-01-07T23:59:59Z' - in: query name: query description: Lucene query string to filter sessions. required: false schema: type: string - in: query name: src_field description: Source field to aggregate on. required: false schema: type: string default: source.ip - in: query name: dest_field description: Destination field to aggregate on. required: false schema: type: string default: destination.ip - in: query name: max_nodes description: Maximum number of nodes to return. required: false schema: type: integer default: 100 minimum: 1 maximum: 10000 - in: query name: min_connections description: Minimum number of connections to include a node. required: false schema: type: integer default: 1 minimum: 1 responses: '200': description: OK - request successful. content: application/json: schema: $ref: '#/components/schemas/SessionConnectionsResponse' examples: GetSessionConnections200Example: summary: Default getSessionConnections 200 response x-microcks-default: true value: nodes: &id038 [] links: &id039 [] total: 250 request_metadata: start_time: string end_time: string query: tags:Mirai src_field: string dest_field: string max_nodes: 1 min_connections: 1 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/ExceededLimit' '500': $ref: '#/components/responses/UnexpectedError' x-microcks-operation: delay: 0 dispatcher: FALLBACK /v3/sessions/counts: get: tags: - Sessions summary: Get Session Counts operationId: getSessionCounts description: "Returns aggregated counts of sessions grouped by the specified fields.\nUseful for building dashboards and understanding traffic distribution.\n" parameters: - $ref: '#/components/parameters/scope' - in: query name: start_time description: Start time for the query range (ISO 8601 format). required: true schema: type: string format: date-time example: '2025-01-01T00:00:00Z' - in: query name: end_time description: End time for the query range (ISO 8601 format). required: true schema: type: string format: date-time example: '2025-01-07T23:59:59Z' - in: query name: fields description: Comma-separated list of fields to aggregate on. required: true schema: type: string example: source.ip,destination.port - in: query name: query description: Lucene query string to filter sessions. required: false schema: type: string - in: query name: size description: Number of buckets per aggregation level. required: false schema: type: integer default: 10 minimum: 1 maximum: 100 responses: '200': description: OK - request successful. content: application/json: schema: $ref: '#/components/schemas/SessionCountsResponse' examples: GetSessionCounts200Example: summary: Default getSessionCounts 200 response x-microcks-default: true value: items: &id040 [] total: 5000 request_metadata: start_time: string end_time: string query: tags:Mirai fields: &id041 - string '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/ExceededLimit' '500': $ref: '#/components/responses/UnexpectedError' x-microcks-operation: delay: 0 dispatcher: FALLBACK /v3/sessions/export: get: tags: - Sessions summary: Export PCAP for Multiple Sessions operationId: exportSessionsPcap description: "Returns a PCAP file containing packets from sessions matching the query criteria.\nThe response is a binary PCAP file suitable for analysis with tools like Wireshark.\n\nNot available when `scope=demo` (returns 403).\n" parameters: - $ref: '#/components/parameters/scope' - in: query name: start_time description: Start time for the query range (ISO 8601 format). required: true schema: type: string format: date-time example: '2025-01-01T00:00:00Z' - in: query name: end_time description: End time for the query range (ISO 8601 format). required: true schema: type: string format: date-time example: '2025-01-07T23:59:59Z' - in: query name: query description: Lucene query string to filter sessions. required: false schema: type: string - in: query name: size description: Maximum number of sessions to include in the export. required: false schema: type: integer default: 100 - in: query name: sort_by description: Field to sort results by. required: false schema: type: string default: lastPacket - in: query name: sort_desc description: Whether to sort in descending order. required: false schema: type: string default: 'true' enum: - 'true' - 'false' responses: '200': description: PCAP file containing matching session packets. content: application/vnd.tcpdump.pcap: schema: type: string format: binary headers: Content-Disposition: schema: type: string example: attachment; filename="sessions.pcap" '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/ExceededLimit' '500': $ref: '#/components/responses/UnexpectedError' x-microcks-operation: delay: 0 dispatcher: FALLBACK /v3/sessions/fields: get: tags: - Sessions summary: Get Session Fields operationId: getSessionFields description: "Returns the list of available session fields for querying and display.\nUse this to discover which fields can be used in queries, sorting, and aggregations.\n" parameters: - $ref: '#/components/parameters/scope' responses: '200': description: OK - request successful. content: application/json: schema: $ref: '#/components/schemas/SessionFieldsResponse' examples: GetSessionFields200Example: summary: Default getSessionFields 200 response x-microcks-default: true value: fields: &id042 [] '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/ExceededLimit' '500': $ref: '#/components/responses/UnexpectedError' x-microcks-operation: delay: 0 dispatcher: FALLBACK /v3/sessions/timeseries: get: tags: - Sessions summary: Get Session Timeseries operationId: getSessionTimeseries description: "Returns timeseries data for sessions, optionally grouped by a field.\nUseful for visualizing session volume over time and identifying trends.\n" parameters: - $ref: '#/components/parameters/scope' - in: query name: start_time description: Start time for the query range (ISO 8601 format). required: true schema: type: string format: date-time example: '2025-01-01T00:00:00Z' - in: query name: end_time description: End time for the query range (ISO 8601 format). required: true schema: type: string format: date-time example: '2025-01-07T23:59:59Z' - in: query name: query description: Lucene query string to filter sessions. required: false schema: type: string - in: query name: field description: Field to group timeseries by. required: false schema: type: string - in: query name: size description: Number of groups to return when field is provided. required: false schema: type: integer default: 10 minimum: 1 maximum: 100 - in: query name: interval description: Time interval for bucketing. required: false schema: type: string default: auto enum: - auto - 1s - 1m - 1h - 1d responses: '200': description: OK - request successful. content: application/json: schema: $ref: '#/components/schemas/SessionTimeseriesResponse' examples: GetSessionTimeseries200Example: summary: Default getSessionTimeseries 200 response x-microcks-default: true value: timeseries: &id044 [] items: &id045 [] total: 1000 request_metadata: start_time: string end_time: string query: tags:Mirai field: string interval: string '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/ExceededLimit' '500': $ref: '#/components/responses/UnexpectedError' x-microcks-operation: delay: 0 dispatcher: FALLBACK /v3/sessions/unique: get: tags: - Sessions summary: Get Unique Field Values operationId: getSessionUniqueValues description: "Returns unique values for a session field as a CSV download, optionally with counts.\nUseful for extracting distinct IPs, ports, or other field values matching a query.\n" parameters: - $ref: '#/components/parameters/scope' - in: query name: start_time description: Start time for the query range (ISO 8601 format). required: true schema: type: string format: date-time example: '2025-01-01T00:00:00Z' - in: query name: end_time description: End time for the query range (ISO 8601 format). required: true schema: type: string format: date-time example: '2025-01-07T23:59:59Z' - in: query name: field description: Field to get unique values for. required: true schema: type: string example: source.ip - in: query name: query description: Lucene query string to filter sessions. required: false schema: type: string - in: query name: include_counts description: Whether to include counts in the output. required: false schema: type: string default: 'false' enum: - 'true' - 'false' responses: '200': description: CSV file with unique values. content: text/csv: schema: type: string '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/ExceededLimit' '500': $ref: '#/components/responses/UnexpectedError' x-microcks-operation: delay: 0 dispatcher: FALLBACK /v3/sessions/{session_id}: get: tags: - Sessions summary: Get Session by ID operationId: getSessionById description: "Returns a single session by its ID, including full session metadata\nand connection details.\n" parameters: - $ref: '#/components/parameters/scope' - in: path name: session_id description: The unique session identifier. required: true schema: type: string responses: '200': description: OK - request successful. content: application/json: schema: $ref: '#/components/schemas/Session' examples: GetSessionById200Example: summary: Default getSessionById 200 response x-microcks-default: true value: _id: 2505-abcdef123456 firstPacket: '2025-01-15T10:30:00Z' lastPacket: '2025-01-15T10:30:05Z' source.ip: 203.0.113.45 source.port: 54321 destination.ip: 198.51.100.10 destination.port: 443 source.bytes: 1024 source.packets: 10 destination.bytes: 2048 destination.packets: 8 classification: malicious '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/ExceededLimit' '500': $ref: '#/components/responses/UnexpectedError' x-microcks-operation: delay: 0 dispatcher: FALLBACK /v3/sessions/{session_id}/export: get: tags: - Sessions summary: Export Session Data operationId: exportSessionData description: "Downloads session data as PCAP or raw payload for a single session.\nUse the `type` parameter to select the export format.\n\nNot available when `scope=demo` (returns 403).\n" parameters: - $ref: '#/components/parameters/scope' - in: path name: session_id description: The unique session identifier. required: true schema: type: string - in: query name: type description: Export format type. required: false schema: type: string default: pcap enum: - pcap - rawSource - rawDestination responses: '200': description: Session data file in the requested format. content: application/octet-stream: schema: type: string format: binary '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/ExceededLimit' '500': $ref: '#/components/responses/UnexpectedError' x-microcks-operation: delay: 0 dispatcher: FALLBACK /v3/sessions/{session_id}/frames: get: tags: - Sessions summary: Get Session PCAP operationId: getSessionPcap description: "Returns raw PCAP bytes for a single session. The response is a binary\nPCAP file suitable for analysis with tools like Wireshark.\n" parameters: - $ref: '#/components/parameters/scope' - in: path name: session_id description: The unique session identifier. required: true schema: type: string responses: '200': description: PCAP file for the requested session. content: application/vnd.tcpdump.pcap: schema: type: string format: binary headers: Content-Disposition: schema: type: string example: attachment; filename="session-{session_id}.pcap" '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/ExceededLimit' '500': $ref: '#/components/responses/UnexpectedError' x-microcks-operation: delay: 0 dispatcher: FALLBACK /v3/tags: get: operationId: listTags tags: - Tags summary: List Tags description: "Retrieve a list of tags with their metadata. Supports filtering by name, slug, and CVE.\n\nThis endpoint returns tag information including ID, name, slug, category, intention,\ndescription, references, CVEs, and related tags.\n" parameters: - in: query name: name description: Filter tags by name (partial match) required: false schema: type: string example: Mirai - in: query name: slug description: Filter tags by slug (exact match) required: false schema: type: string example: mirai - in: query name: cve description: Filter tags by associated CVE required: false schema: type: string example: CVE-2020-1234 responses: '200': description: OK - request successful. content: application/json: schema: $ref: '#/components/schemas/TagsMetadata' examples: ListTags200Example: summary: Default listTags 200 response x-microcks-default: true value: tags: - id: ef0cc90d-d80c-436f-92c5-3d8f8665c9ac label: MIRAI slug: mirai name: Mirai category: worm intention: malicious description: This IP address exhibits behavior that indicates it is infected with Mirai or a Mirai-like variant of malware. references: &id046 - string recommend_block: false cves: &id047 - CVE-2021-44228 created_at: '2020-04-07' related_tags: - id: da78f2eb-fe6b-4e84-913c-cdab4ff067c2 name: Oracle WebLogic RCE CVE-2020-14882 intention: malicious category: activity slug: oracle-weblogic-rce-cve-2020-14882 '401': $ref: '#/components/responses/Unauthorized' '500': $ref: '#/components/responses/UnexpectedError' x-microcks-operation: delay: 0 dispatcher: FALLBACK components: securitySchemes: APIKeyHeaderAuth: type: apiKey in: header name: key description: GreyNoise API key passed via the 'key' HTTP header. schemas: Error: type: object properties: message: type: string example: Success required: - message CVEAdvancedResponse: type: object properties: id: type: string description: The CVE identifier. example: CVE-2024-12345 details: $ref: '#/components/schemas/CVEDetails' timeline: $ref: '#/components/schemas/CVETimeline' exploitation_details: $ref: '#/components/schemas/CVEExploitationDetails' exploitation_stats: $ref: '#/components/schemas/CVEExploitationStats' exploitation_activity: $ref: '#/components/schemas/CVEExploitationActivity' CVEBasicResponse: type: object properties: id: type: string description: The CVE identifier. example: CVE-2024-12345 details: $ref: '#/components/schemas/CVEDetails' timeline: $ref: '#/components/schemas/CVETimeline' exploitation_details: $ref: '#/components/schemas/CVEExploitationDetails' CVEMinimalResponse: type: object properties: id: type: string description: The CVE identifier. example: CVE-2024-12345 details: $ref: '#/components/schemas/CVEDetails' CVEDetails: type: object properties: vulnerability_name: type: string description: The name of the vulnerability. example: Sample Vulnerability vulnerability_description: type: string description: Description of the vulnerability. example: This vulnerability allows remote attackers to execute arbitrary code. cve_cvss_score: type: number description: The CVSS score of the CVE. example: 7.5 product: type: string description: The product affected by the vulnerability. example: Sample Product vendor: type: string description: The vendor of the affected product. example: Sample Vendor published_to_nist_nvd: type: boolean description: Whether the CVE is published to the NIST National Vulnerability Database. example: true CVETimeline: type: object properties: cve_published_date: type: string format: date description: The date the CVE was published. example: '2024-01-01' cve_last_updated_date: type: string format: date description: The date the CVE was last updated. example: '2024-01-02' first_known_published_date: type: string format: date description: The first known published date of the CVE. example: '2024-01-01' cisa_kev_date_added: type: string format: date description: The date the CVE was added to the CISA KEV list. example: '2024-01-03' CVEExploitationDetails: type: object properties: attack_vector: type: string description: The attack vector for the CVE. example: Network exploit_found: type: boolean description: Whether an exploit has been found for this CVE. example: true exploitation_registered_in_kev: type: boolean description: Whether the exploitation is registered in KEV. example: true epss_score: type: number description: The EPSS score for the CVE. example: 0.8 CVEExploitationStats: type: object properties: number_of_available_exploits: type: integer description: The number of available exploits for the CVE. example: 5 number_of_threat_actors_exploiting_vulnerability: type: integer description: The number of threat actors exploiting the vulnerability. example: 3 number_of_botnets_exploiting_vulnerability: type: integer description: The number of botnets exploiting the vulnerability. example: 2 CVEExploitationActivity: type: object properties: activity_seen: type: boolean description: Whether exploitation activity has been observed. example: true benign_ip_count_1d: type: integer description: The count of benign IPs in the last day. example: 100 benign_ip_count_10d: type: integer description: The count of benign IPs in the last 10 days. example: 500 benign_ip_count_30d: type: integer description: The count of benign IPs in the last 30 days. example: 1000 threat_ip_count_1d: type: integer description: The count of threat IPs in the last day. example: 10 threat_ip_count_10d: type: integer description: The count of threat IPs in the last 10 days. example: 50 threat_ip_count_30d: type: integer description: The count of threat IPs in the last 30 days. example: 100 CallbackFilterFields: type: object description: Common filter fields for callback IP queries. properties: is_stage_1: type: boolean description: "Filter by stage 1 status. true = file downloaded from this IP.\n" example: false is_stage_2: type: boolean description: "Filter by stage 2 status. true = suspected C2 based on VT/sandbox analysis.\n" example: false first_seen_after: type: string format: date description: Only include IPs first seen after this date (YYYY-MM-DD). example: '2026-05-01' first_seen_before: type: string format: date description: Only include IPs first seen before this date (YYYY-MM-DD). example: '2026-05-01' last_seen_after: type: string format: date description: Only include IPs last seen after this date (YYYY-MM-DD). example: '2026-05-01' last_seen_before: type: string format: date description: Only include IPs last seen before this date (YYYY-MM-DD). example: '2026-05-01' has_files: type: boolean description: If true, only include IPs with associated malware files. If false, only IPs without files. example: false file_type: type: string description: Filter by file MIME type (e.g. "application/x-executable"). example: string file_name: type: string description: Filter by file name substring match. example: Google Public DNS file_hash: type: string description: Filter by file SHA256 hash. example: 795bc7ce13f60d61e9ac03611dd36d90 scanner_ips: type: array items: type: string description: Filter to IPs associated with these scanner IPs. example: *id001 ips: type: array items: type: string description: Filter to this specific set of callback IPs. example: *id002 CallbackFileResponse: type: object description: Malware file associated with a callback IP. properties: sha256: type: string description: SHA-256 hash of the file. example: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 md5: type: string description: MD5 hash of the file. example: 795bc7ce13f60d61e9ac03611dd36d90 sha1: type: string description: SHA-1 hash of the file. example: string threat_name: type: string description: VirusTotal threat name, if available. example: Trojan.GenericKD.46542 vt_detection_count: type: integer description: Number of VirusTotal engines that flagged the file as malicious. example: 42 vt_engine_count: type: integer description: Total number of VirusTotal engines that scanned the file. example: 71 file_name: type: string description: Original file name, if known. example: payload.bin size: type: integer format: int64 description: File size in bytes. example: 24576 type: type: string description: File MIME type. example: application/x-executable CallbackIPDetailResponse: type: object description: Detailed information about a single callback IP. properties: ip: type: string description: The callback IP address. example: 198.51.100.42 source_workspaces: type: array items: type: string description: "Labeled workspace sources where this IP was observed.\nValues are \"GreyNoise\", \"UserWorkspace\", or \"Community\".\n" example: *id033 is_stage_1: type: boolean description: Whether a file was successfully downloaded from this IP (stage 1). example: false is_stage_2: type: boolean description: Whether this IP is suspected C2 based on VT/sandbox analysis (stage 2). example: false first_seen: type: string nullable: true description: ISO 8601 timestamp of when this IP was first observed. example: '2025-03-01T00:00:00Z' last_seen: type: string nullable: true description: ISO 8601 timestamp of when this IP was most recently observed. example: '2025-03-15T12:30:00Z' scanner_ips: type: array items: type: string description: Scanner IPs that delivered payloads referencing this callback IP. example: *id034 scanner_count: type: integer description: Number of distinct scanners associated with this IP. example: 5 file_count: type: integer description: Number of malware files associated with this IP. example: 3 active_files: type: array items: $ref: '#/components/schemas/CallbackFileResponse' description: Malware files associated with this callback IP. example: *id035 CallbackListIPsRequest: allOf: - $ref: '#/components/schemas/CallbackFilterFields' - type: object properties: page: type: integer minimum: 0 default: 0 description: Zero-indexed page number. example: 100 page_size: type: integer minimum: 1 maximum: 100 default: 20 description: Number of results per page (1-100). example: 100 CallbackFileSummary: type: object description: Lightweight file reference returned with IP list results. properties: sha256: type: string description: SHA-256 hash of the file. example: string file_name: type: string description: Original file name. example: Google Public DNS type: type: string description: File MIME type. example: string vt_threat_name: type: string description: VirusTotal threat name. example: Google Public DNS vt_detection_count: type: integer description: Number of VirusTotal engines that flagged the file. example: 42 CallbackIPSummary: type: object description: Summary representation of a callback IP in list results. properties: ip: type: string example: 198.51.100.42 source_workspaces: type: array items: type: string example: - GreyNoise is_stage_1: type: boolean example: false is_stage_2: type: boolean example: false first_seen: type: string nullable: true example: '2025-12-01' last_seen: type: string nullable: true example: '2026-05-01' scanner_ips: type: array items: type: string example: - string scanner_count: type: integer example: 42 file_count: type: integer example: 42 files: type: array items: $ref: '#/components/schemas/CallbackFileSummary' description: Lightweight file references for this IP. example: [] CallbackListIPsResponse: type: object description: Paginated list of callback IPs. properties: items: type: array items: $ref: '#/components/schemas/CallbackIPSummary' example: *id036 total: type: integer description: Total number of matching callback IPs. example: 142 page: type: integer description: Current page number (zero-indexed). example: 0 page_size: type: integer description: Number of results per page. example: 20 CallbackThreatNameStat: type: object properties: threat_name: type: string description: VirusTotal threat name. example: Trojan.GenericKD.46542 file_count: type: integer description: Number of files with this threat name. example: 12 ip_count: type: integer description: Number of IPs associated with files of this threat name. example: 8 CallbackOverviewResponse: type: object description: Aggregate statistics for callback IPs matching the given filters. properties: total_ips: type: integer description: Total number of callback IPs. example: 142 stage_1_ips: type: integer description: Number of stage 1 (initial payload delivery) IPs. example: 98 stage_2_ips: type: integer description: Number of stage 2 (post-exploitation callback) IPs. example: 44 total_files: type: integer description: Total number of associated malware files. example: 230 files_with_vt: type: integer description: Files that have been analyzed by VirusTotal. example: 180 files_without_vt: type: integer description: Files pending VirusTotal analysis. example: 50 total_cross_refs: type: integer description: Total IP-to-file associations. example: 312 total_scanner_links: type: integer description: Total scanner-to-callback-IP associations. example: 456 ips_with_files: type: integer description: Number of IPs that have associated files. example: 110 ips_without_files: type: integer description: Number of IPs with no associated files. example: 32 ips_with_scanners: type: integer description: Number of IPs with known scanner associations. example: 130 ips_without_scanners: type: integer description: Number of IPs with no known scanner associations. example: 12 distinct_scanners: type: integer description: Total number of unique scanner IPs. example: 89 top_threat_names: type: array items: $ref: '#/components/schemas/CallbackThreatNameStat' description: Top VirusTotal threat names by file count. example: *id037 CommunityResponse: type: object properties: ip: type: string example: 1.2.3.4 noise: type: boolean example: false riot: type: boolean example: true classification: type: string example: benign name: type: string example: Cloudflare link: type: string example: https://viz.greynoise.io/riot/1.2.3.4 last_seen: type: string example: '2020-01-01' message: type: string example: Success IPTimelineResponse: type: object properties: results: type: array items: type: object properties: data: type: integer description: Hourly activity count for the field value in this time bucket example: 1 label: type: string description: "A label that corresponds to a distinct value for the\ngiven field\n" example: unknown timestamp: type: string description: "Time range bucket based on granularity - the timestamp\nrepresents the start of the bucket\n" format: date-time example: '2023-01-23T00:00:00Z' metadata: type: object properties: ip: type: string description: IP queried example: 36.32.2.102 field: type: string description: Field over which to show change example: classification first_seen: type: string description: "The earliest date GreyNoise observed any activity from this IP.\n" example: '2022-06-15' start: type: string format: date-time description: Start of time range for data example: '2023-01-18T00:00:00Z' end: type: string format: date-time description: End of time range for data example: '2023-01-25T21:55:18.486036894Z' granularity: type: string description: Granularity at which to show data example: 1d metric: type: string description: The metric used within the data field example: count Session: type: object description: "A network session captured by GreyNoise sensors. Sessions contain network\nflow data, protocol details, and enrichment metadata. The full set of fields\nis dynamic and can be discovered via the `/v3/sessions/fields` endpoint.\n" additionalProperties: true properties: _id: type: string description: Unique session identifier. example: 2505-abcdef123456 firstPacket: type: string format: date-time description: Timestamp of the first packet in the session. example: '2025-01-15T10:30:00Z' lastPacket: type: string format: date-time description: Timestamp of the last packet in the session. example: '2025-01-15T10:30:05Z' source.ip: type: string description: Source IP address. example: 203.0.113.45 source.port: type: integer description: Source port number. example: 54321 destination.ip: type: string description: Destination IP address. example: 198.51.100.10 destination.port: type: integer description: Destination port number. example: 443 source.bytes: type: integer description: Total bytes sent from source. example: 1024 source.packets: type: integer description: Total packets sent from source. example: 10 destination.bytes: type: integer description: Total bytes sent from destination. example: 2048 destination.packets: type: integer description: Total packets sent from destination. example: 8 classification: type: string description: GreyNoise classification of the source IP. example: malicious SessionConnectionsResponse: type: object properties: nodes: type: array description: Network nodes in the connection graph. items: $ref: '#/components/schemas/SessionConnectionNode' example: *id038 links: type: array description: Connections between nodes. items: $ref: '#/components/schemas/SessionConnectionLink' example: *id039 total: type: integer description: Total number of connections. example: 250 request_metadata: type: object properties: start_time: type: string example: string end_time: type: string example: string query: type: string example: tags:Mirai src_field: type: string example: string dest_field: type: string example: string max_nodes: type: integer example: 1 min_connections: type: integer example: 1 SessionConnectionNode: type: object properties: id: type: string description: Node identifier (field value). example: 192.168.1.1 type: type: string description: Whether this is a source or destination node. example: source SessionConnectionLink: type: object properties: source: type: string description: Source node identifier. example: 192.168.1.1 target: type: string description: Target node identifier. example: 10.0.0.1 value: type: integer description: Number of connections between source and target. example: 15 SessionCountsResponse: type: object properties: items: type: array description: Aggregated count items. items: $ref: '#/components/schemas/SessionCountItem' example: *id040 total: type: integer description: Total number of sessions matching the query. example: 5000 request_metadata: type: object properties: start_time: type: string example: string end_time: type: string example: string query: type: string example: tags:Mirai fields: type: array items: type: string example: *id041 SessionCountItem: type: object properties: label: type: string description: The value of the aggregated field. example: 192.168.1.1 count: type: integer description: Number of sessions for this value. example: 42 children: type: array description: Nested aggregation results for multi-field queries. items: $ref: '#/components/schemas/SessionCountItem' example: [] SessionFieldsResponse: type: object properties: fields: type: array description: List of available session fields. items: $ref: '#/components/schemas/SessionField' example: *id042 SessionField: type: object properties: value: type: string description: The field identifier used in queries. example: source.ip label: type: string description: Human-readable label for the field. example: Source IP description: type: string description: Description of the field. example: The source IP address of the session. type: type: string description: Data type of the field. example: ip group: type: string description: Logical grouping of the field. example: source sortable: type: boolean description: Whether the field can be used for sorting. example: true SessionsResponse: type: object properties: sessions: type: array description: Array of session objects matching the query. items: $ref: '#/components/schemas/Session' example: *id043 total: type: integer description: Total number of sessions matching the query. example: 150 pagination: $ref: '#/components/schemas/SessionPagination' request_metadata: $ref: '#/components/schemas/SessionRequestMetadata' SessionPagination: type: object properties: page: type: integer description: Current page number. example: 1 page_size: type: integer description: Number of results per page. example: 25 sort_by: type: string description: Field used for sorting. example: lastPacket sort_desc: type: boolean description: Whether results are sorted in descending order. example: true SessionRequestMetadata: type: object properties: start_time: type: string description: Start time of the query range. example: '2025-01-01T00:00:00Z' end_time: type: string description: End time of the query range. example: '2025-01-07T23:59:59Z' query: type: string description: The Lucene query string used. example: tags:Mirai SessionTimeseriesResponse: type: object properties: timeseries: type: array description: Timeseries data points (when no field grouping is used). items: $ref: '#/components/schemas/SessionTimeseriesPoint' example: *id044 items: type: array description: Grouped timeseries data (when field grouping is used). items: $ref: '#/components/schemas/SessionTimeseriesItem' example: *id045 total: type: integer description: Total number of sessions in the time range. example: 1000 request_metadata: type: object properties: start_time: type: string example: string end_time: type: string example: string query: type: string example: tags:Mirai field: type: string example: string interval: type: string example: string SessionTimeseriesPoint: type: object properties: timestamp: type: string description: Timestamp for this data point. example: '2025-01-01T00:00:00Z' count: type: integer description: Number of sessions in this time bucket. example: 42 SessionTimeseriesItem: type: object properties: label: type: string description: The field value for this group. example: 192.168.1.1 count: type: integer description: Total sessions for this group. example: 150 timeseries: type: array description: Timeseries data for this group. items: $ref: '#/components/schemas/SessionTimeseriesPoint' example: [] 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 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 example: *id009 destination_country_codes: type: array items: type: string description: "The country codes where GreyNoise sensor is\nphysically located.\n" example: Germany example: *id010 destination_cities: type: array items: type: string description: "The city where the GreyNoise sensor is geographically located.\n" example: Berlin example: *id011 destination_asns: type: array items: type: string description: "The ASN associated with the destination IP address.\n" example: AS1234 example: *id012 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 TimeSeriesResponse: type: object description: "Response object for the timeseries endpoint. The response is a map\nwhere keys are time intervals and values are arrays of IP records\nobserved in that interval.\n\nTime interval keys are formatted as YYYY-MM-DD-HH (e.g., \"2025-01-15-14\")\n" additionalProperties: description: "Time interval key (format: YYYY-MM-DD-HH)\n" type: array items: $ref: '#/components/schemas/TimeSeriesRecord' example: *id006 TimeSeriesRecord: type: object description: A single IP record in a timeseries response properties: ip: type: string description: The IP address example: 203.0.113.45 internet_scanner_intelligence: $ref: '#/components/schemas/TimeSeriesIntelligence' TimeSeriesIntelligence: type: object description: Intelligence data for an IP in the timeseries dataset properties: 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' found: type: boolean description: Indicates if the IP was observed scanning the GreyNoise sensor network. Also referred to as 'noise'. example: true tags: type: array items: type: string description: "A list of activity/malware tags GreyNoise has applied to this\nIP.\n" example: - Mirai - Telnet Worm 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 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 cves: type: array items: type: string description: A list of CVEs associate with this IP. example: - CVE-2020-1234 - CVE-2021-2345 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 tor: type: boolean description: Whether or not the device is a known Tor exit node. example: false 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' metadata: $ref: '#/components/schemas/MetadataV3' raw_data: $ref: '#/components/schemas/TimeSeriesRawData' TimeSeriesRawData: type: object description: Raw data collected about the IP's scanning activity properties: scan: type: array items: $ref: '#/components/schemas/TimeSeriesScanEntry' description: Observed scan activity example: [] ja3: type: array items: $ref: '#/components/schemas/TimeSeriesJA3Entry' description: JA3 TLS fingerprints observed example: [] hassh: type: array items: $ref: '#/components/schemas/TimeSeriesHASSHEntry' description: HASSH SSH fingerprints observed example: [] http: $ref: '#/components/schemas/TimeSeriesHTTPData' source: $ref: '#/components/schemas/TimeSeriesSourceData' tls: $ref: '#/components/schemas/TimeSeriesTLSData' ssh: $ref: '#/components/schemas/TimeSeriesSSHData' tcp: $ref: '#/components/schemas/TimeSeriesTCPData' TimeSeriesScanEntry: type: object properties: port: type: integer description: Port number example: 80 protocol: type: string description: Protocol example: TCP TimeSeriesJA3Entry: 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 TimeSeriesHASSHEntry: 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" TimeSeriesHTTPData: type: object description: HTTP-related data observed properties: md5: type: array items: type: string description: "MD5 hashes of the body content. These compact,\nunique representations of the data allow for quick\ncomparisons and deduplication of payloads without\nstoring the raw content.\n" example: - 9764955b67107eeb9edfae76f429e783 cookie_keys: type: array items: type: string 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 request_authorization: type: array items: type: string 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 request_cookies: type: array items: type: string 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 request_header: type: array items: type: string 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' method: type: array items: type: string 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 path: type: array items: type: string description: Observed scanning activity traversed this web path. example: - /robots.txt request_origin: type: array items: type: string 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 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 TimeSeriesSourceData: type: object description: Source traffic metadata properties: bytes: type: integer format: int64 description: "The total amount of data transferred (in bytes) during the\nobserved session or connection.\n" example: 1024 TimeSeriesTLSData: type: object description: TLS-related data properties: cipher: type: array items: type: string description: "The encryption algorithms or cipher suites used during secure\ncommunication. Identifying the ciphers helps assess the security\nof the connection, particularly in TLS/SSL traffic.\n" example: - TLS_AES_128_GCM_SHA256 - TLS_AES_256_GCM_SHA384 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 TimeSeriesSSHData: type: object description: SSH-related data properties: key: type: array items: type: string description: "This is the SSH key used.\n" example: - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC1234567890 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 TimeSeriesTCPData: type: object description: TCP-related data 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' TimeSeriesStatsResponse: type: object description: "Response object for the timeseries stats/aggregation endpoint.\nThis provides aggregated IP counts over time intervals matching\na GNQL query.\n" properties: count: type: integer description: The sum of all IP counts across all time intervals example: 1500 min: type: integer description: The minimum IP count observed in any single time interval example: 10 max: type: integer description: The maximum IP count observed in any single time interval example: 250 data: type: array items: $ref: '#/components/schemas/TimeSeriesStatsRecord' description: Array of aggregated data points, one per time interval example: [] example: *id007 TimeSeriesStatsRecord: type: object description: A single aggregated data point in a timeseries stats response properties: date: type: string description: "The starting timestamp for this time interval in format\n'YYYY-MM-DD HH:mm:ss.SSS'.\nFor hourly intervals, the time component represents the hour.\nFor daily intervals, the time will be 00:00:00.000.\n" example: '2025-11-10 14:00:00.000' count: type: integer description: "The number of unique IPs matching the query in this time\ninterval\n" example: 125 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: ip: type: string description: IP address that the information is about. example: 71.6.135.131 seen: type: boolean description: Whether or not the IP address has been observed by the GreyNoise sensor network. example: true 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' 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: *id008 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: $ref: '#/components/schemas/IPResponseV3Tags' 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: *id015 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: *id016 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: *id017 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: *id018 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: *id019 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: *id020 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: *id021 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" example: *id022 path: type: array items: type: string description: Observed scanning activity traversed this web path. example: /robots.txt example: *id023 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" example: *id024 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: *id025 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: *id026 ssh: type: object properties: key: type: array description: "This is the SSH key used.\n" example: *id027 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: *id028 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: *id029 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 example: string 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" example: string 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" 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-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" example: false 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" example: *id013 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" example: *id014 created_at: type: string example: '2020-04-07' description: "The date and time when the tag was created.\n" updated_at: type: string example: '2020-04-07' description: "The date and time 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' example: [] 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: *id005 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: *id004 items: type: string GNQLStats: type: object properties: query: type: string description: The GNQL query string the requester queried example: last_seen:2019-07-28 classification:malicious count: type: integer description: The number of total results for the given GNQL query example: 50000 adjusted_query: type: string description: "If the original query was adjusted due to plan limitations (for\nexample, the requested data reach was reduced), this field\ncontains the query that was actually executed. Empty when the\noriginal query was run unchanged.\n" example: last_seen:2019-07-28 classification:malicious last_seen:7d stats: type: object properties: classifications: type: array description: Most common classifications items: type: object properties: classification: type: string example: malicious count: type: integer example: 5000 spoofable: type: array description: Count of which are spoofable items: type: object properties: spoofable: type: boolean example: false count: type: integer example: 5000 organizations: type: array description: Most common organizations items: type: object properties: organization: type: string example: DigitalOcean, LLC count: type: integer example: 5000 actors: type: array description: Most common actors items: type: object properties: actor: type: string example: Shodan.io count: type: integer example: 5000 countries: type: array description: "Most common countries (Same data as\nmetadata.source_countries. source_countries is preferred)\n" items: type: object properties: country: type: string example: United States count: type: integer example: 5000 source_countries: type: array description: Most common source countries items: type: object properties: country: type: string example: United States count: type: integer example: 5000 destination_countries: type: array description: Most common destination countries items: type: object properties: country: type: string example: United States count: type: integer example: 5000 tags: type: array description: Most common tags items: type: object properties: tag: type: string example: SSH Bruteforcer id: type: string format: uuid description: The unique identifier for the tag example: 4c076d9c-be48-4bd1-bec4-6005e06c0f89 count: type: integer example: 5000 operating_systems: type: array description: Most common operating systems items: type: object properties: operating_system: type: string example: Windows 7/8 count: type: integer example: 5000 categories: type: array description: Most common categories items: type: object properties: category: type: string example: education count: type: integer example: 5000 asns: type: array description: Most common ASNs items: type: object properties: asn: type: string example: AS4134 count: type: integer example: 5000 TagsMetadata: type: object properties: tags: type: array items: type: object properties: id: type: string example: ef0cc90d-d80c-436f-92c5-3d8f8665c9ac label: type: string example: MIRAI slug: type: string example: mirai name: type: string example: Mirai category: type: string example: worm intention: type: string example: malicious description: type: string example: This IP address exhibits behavior that indicates it is infected with Mirai or a Mirai-like variant of malware. references: type: array items: type: string example: https://en.wikipedia.org/wiki/Mirai_(malware) example: *id046 recommend_block: type: boolean example: false cves: type: array items: type: string example: CVE-2020-1234 example: *id047 created_at: type: string example: '2020-04-07' related_tags: type: array items: type: object properties: id: type: string example: da78f2eb-fe6b-4e84-913c-cdab4ff067c2 name: type: string example: Oracle WebLogic RCE CVE-2020-14882 intention: type: string example: malicious category: type: string example: activity slug: type: string example: oracle-weblogic-rce-cve-2020-14882 IPResponseV3: type: object properties: ip: type: string example: 8.8.8.8 description: "IP address that the information is about.\n" business_service_intelligence: $ref: '#/components/schemas/BusinessServiceIntelligence' internet_scanner_intelligence: $ref: '#/components/schemas/InternetScannerIntelligence' request_metadata: type: object properties: restricted_fields: type: array description: "The fields that were restricted due to plan limitations.\n" example: *id032 items: type: string QuickMultiIPResponseV3: type: object properties: data: type: array items: 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' request_metadata: $ref: '#/components/schemas/IpResponseMetadataV3' MultiIPResponseV3: type: object properties: data: type: array items: 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/BusinessServiceIntelligence' internet_scanner_intelligence: $ref: '#/components/schemas/InternetScannerIntelligence' request_metadata: $ref: '#/components/schemas/IpResponseMetadataV3' IpResponseMetadataV3: type: object properties: restricted_fields: type: array description: "The fields that were restricted due to plan limitations.\n" example: *id030 items: type: string message: type: string example: ok description: A status message indicating if there were issues with the request ips_not_found: type: array description: "The list of IPs not found\n" items: type: string example: *id031 MultiIpRequest: type: object required: - ips properties: ips: type: array items: type: string example: 8.8.8.8 example: - string parameters: scope: name: scope in: query description: "Controls the data scope for the query.\n- `workspace`: Query data from the current workspace (default). Requires the Sensors entitlement.\n- `demo`: Query demo/sample data. Requires the Swarm entitlement. Not available on export endpoints.\n" required: false schema: type: string default: workspace enum: - workspace - demo example: workspace ip: name: ip in: path description: IP address to query required: true schema: type: string example: 8.8.8.8 workspaceLabels: name: workspace_labels in: query description: "Comma-separated list of dataset scopes to include in the query.\nWhen omitted, only the default GreyNoise global dataset is queried.\n\nAllowed values:\n- `greynoise`: GreyNoise's global dataset.\n- `community`: Aggregated community-contributed data.\n- `personal`: The authenticated caller's own workspace data.\n Requires an authenticated workspace.\n\nEnforcement varies by endpoint; see each operation's response codes:\n- `GET /v3/ip/{ip}` and `POST /v3/ip` return `403 Forbidden` when any\n value is supplied without the Community Dataset entitlement. Values\n are not validated server-side; unrecognized values yield empty\n results rather than an error.\n- `GET /v3/noise/ips/{ip}/timeline` returns `400 Bad Request` for\n unrecognized values and for `personal` without an authenticated\n workspace. The Community Dataset entitlement is not enforced on\n this endpoint.\n" required: false schema: type: string example: greynoise,community example: string query: name: query in: query description: GNQL query string required: true schema: type: string example: tags:Mirai responses: UnexpectedError: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' example: message: Encountered error while performing request 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/Error' example: message: Invalid parameter Unauthorized: description: Unauthorized. Please check your API key. content: application/json: schema: $ref: '#/components/schemas/Error' 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/Error' example: message: Forbidden NotFound: description: Resource not found. content: application/json: schema: $ref: '#/components/schemas/Error' example: message: IP not found 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.