NAV Navbar
Curl Python Go Node

GreyNoise API v1.0.0

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

GreyNoise is a cybersecurity company that collects and analyzes Internet-wide scan and attack traffic. Use GreyNoise contextualize existing alerts, filter false-positives, identify compromised devices, and track emerging threats.

Base URLs:

Email: Support

Authentication

IP Lookup

Calls to identify whether or not an IP address is noise, or get more information about a given IP address.

IP Context

Code samples

# You can also use wget
curl -X GET https://api.greynoise.io/v2/noise/context/{ip} \
  -H 'Accept: application/json' \
  -H 'key: API_KEY'

import requests
headers = {
  'Accept': 'application/json',
  'key': 'API_KEY'
}

r = requests.get('https://api.greynoise.io/v2/noise/context/{ip}', params={

}, headers = headers)

print r.json()

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "key": []string{"API_KEY"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.greynoise.io/v2/noise/context/{ip}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'key':'API_KEY'

};

fetch('https://api.greynoise.io/v2/noise/context/{ip}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /v2/noise/context/{ip}

Get more information about a given IP address. Returns time ranges, IP metadata (network owner, ASN, reverse DNS pointer, country), associated actors, activity tags, and raw port scan and web request information.

Parameters

Name In Type Required Description
ip path string true IP address to query

Example responses

200 Response

{
  "ip": "71.6.135.131",
  "seen": true,
  "classification": "benign",
  "first_seen": "2018-01-28",
  "last_seen": "2018-2-28",
  "actor": "Shodan.io",
  "tags": [
    "Mirai",
    "Telnet Worm"
  ],
  "metadata": {
    "country": "United States",
    "country_code": "US",
    "city": "Seattle",
    "organization": "DigitalOcean, LLC",
    "rdns": "crawl-66-249-79-17.googlebot.com",
    "asn": "AS521",
    "tor": false,
    "category": "education",
    "os": "Windows 7/8"
  },
  "raw_data": {
    "scan": [
      {
        "port": 80,
        "protocol": "TCP"
      }
    ],
    "web": {
      "paths": [
        "/robots.txt"
      ],
      "useragents": [
        "Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)"
      ]
    },
    "ja3": [
      {
        "fingerprint": "c3a6cf0bf2e690ac8e1ecf6081f17a50",
        "port": 443
      }
    ]
  }
}

Responses

Status Meaning Description Schema
200 OK Query successful. NoiseContext
400 Bad Request Bad request. None
401 Unauthorized Unauthorized. Please check your API key. None
429 Too Many Requests Too many requests. You've hit the rate-limit. None

IP Quick Check

Code samples

# You can also use wget
curl -X GET https://api.greynoise.io/v2/noise/quick/{ip} \
  -H 'Accept: application/json' \
  -H 'key: API_KEY'

import requests
headers = {
  'Accept': 'application/json',
  'key': 'API_KEY'
}

r = requests.get('https://api.greynoise.io/v2/noise/quick/{ip}', params={

}, headers = headers)

print r.json()

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "key": []string{"API_KEY"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.greynoise.io/v2/noise/quick/{ip}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'key':'API_KEY'

};

fetch('https://api.greynoise.io/v2/noise/quick/{ip}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /v2/noise/quick/{ip}

Check whether a given IP address is “Internet background noise”, or has been observed scanning or attacking devices across the Internet.

Notes

Code

Parameters

Name In Type Required Description
ip path string true The IP address to query

Example responses

200 Response

{
  "code": "0x01",
  "ip": "71.6.135.131",
  "noise": true
}

Responses

Status Meaning Description Schema
200 OK Query successful. NoiseQuick
400 Bad Request Bad request. None
401 Unauthorized Unauthorized. Please check your API key. None
429 Too Many Requests Too many requests. You've hit the rate-limit. None

IP Multi Quick Check

Code samples

# You can also use wget
curl -X GET https://api.greynoise.io/v2/noise/multi/quick?ips=string \
  -H 'Accept: application/json' \
  -H 'key: API_KEY'

import requests
headers = {
  'Accept': 'application/json',
  'key': 'API_KEY'
}

r = requests.get('https://api.greynoise.io/v2/noise/multi/quick', params={
  'ips': 'string'
}, headers = headers)

print r.json()

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "key": []string{"API_KEY"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.greynoise.io/v2/noise/multi/quick", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'key':'API_KEY'

};

fetch('https://api.greynoise.io/v2/noise/multi/quick?ips=string',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /v2/noise/multi/quick

Check whether a set of IP addresses are "Internet background noise", or have been observed scanning or attacking devices across the Internet. This endpoint is functionality identical to the /v2/noise/quick/{ip} endpoint, except it processes more than one checks simultaneously. This endpoint is useful for filtering through large log files.

Notes

Code

Parameters

Name In Type Required Description
ips query string true Comma-delimited list of up to 1,000 IP addresses to query

Example responses

200 Response

[
  {
    "code": "0x01",
    "ip": "71.6.135.131",
    "noise": true
  }
]

Responses

Status Meaning Description Schema
200 OK Query successful. Inline
400 Bad Request Bad request. None
401 Unauthorized Unauthorized. Please check your API key. None
429 Too Many Requests Too many requests. You've hit the rate-limit. None

Response Schema

Status Code 200

Name Type Required Restrictions Description
anonymous [NoiseQuick] false none none
» code string false none none
» ip string false none none
» noise boolean false none none

Enumerated Values

Property Value
code 0x00
code 0x01
code 0x02
code 0x03
code 0x04
code 0x05
code 0x06
code 0x07
code 0x08

GNQL

Calls to interface with GNQL (GreyNoise Query Language).

GNQL Query

Code samples

# You can also use wget
curl -X GET https://api.greynoise.io/v2/experimental/gnql?query=string \
  -H 'Accept: application/json' \
  -H 'key: API_KEY'

import requests
headers = {
  'Accept': 'application/json',
  'key': 'API_KEY'
}

r = requests.get('https://api.greynoise.io/v2/experimental/gnql', params={
  'query': 'string'
}, headers = headers)

print r.json()

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "key": []string{"API_KEY"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.greynoise.io/v2/experimental/gnql", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'key':'API_KEY'

};

fetch('https://api.greynoise.io/v2/experimental/gnql?query=string',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /v2/experimental/gnql

GreyNoise Query Language

GNQL (GreyNoise Query Language) is a domain-specific query language that uses Lucene deep under the hood. GNQL aims to enable GreyNoise Enterprise and Research users to make complex and one-off queries against the GreyNoise dataset as new business cases arise. GNQL is built with self-defeat and fully featured product lines in mind. If we do our job correctly, each individual GNQL query that brings our users and customers sufficient value will eventually be transitioned into it's own individual offering.

Facets

Behavior

Shortcuts

Examples

Parameters

Name In Type Required Description
query query string true GNQL query string
size query integer false Maximum amount of results to grab
scroll query string false Scroll token to paginate through results

Example responses

200 Response

{
  "complete": false,
  "scroll": "DnF1ZXJ5VGhlbkZldGNoBQAAAAAAeygtFkFKSExEdUc4VEtta2syaGg2R3kzNGcAAAAAAHsoLhZBSkhMRHVHOFRLbWtrMmhoNkd5MzRnAAAAAAB7KC8WQUpITER1RzhUS21razJoaDZHeTM0ZwAAAAAAeygxFkFKSExEdUc4VEtta2syaGg2R3kzNGcAAAAAAHsoMBZBSkhMRHVHOFRLbWtrMmhoNkd5MzRn",
  "query": "last_seen:2019-07-28 classification:malicious",
  "count": 1,
  "message": "ok",
  "data": [
    {
      "ip": "71.6.135.131",
      "seen": true,
      "classification": "benign",
      "first_seen": "2018-01-28",
      "last_seen": "2018-2-28",
      "actor": "Shodan.io",
      "tags": [
        "Mirai",
        "Telnet Worm"
      ],
      "metadata": {
        "country": "United States",
        "country_code": "US",
        "city": "Seattle",
        "organization": "DigitalOcean, LLC",
        "rdns": "crawl-66-249-79-17.googlebot.com",
        "asn": "AS521",
        "tor": false,
        "category": "education",
        "os": "Windows 7/8"
      },
      "raw_data": {
        "scan": [
          {
            "port": 80,
            "protocol": "TCP"
          }
        ],
        "web": {
          "paths": [
            "/robots.txt"
          ],
          "useragents": [
            "Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)"
          ]
        },
        "ja3": [
          {
            "fingerprint": "c3a6cf0bf2e690ac8e1ecf6081f17a50",
            "port": 443
          }
        ]
      }
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK Query successful. Inline
400 Bad Request Bad request. None
401 Unauthorized Unauthorized. Please check your API key. None
429 Too Many Requests Too many requests. You've hit the rate-limit. None

Response Schema

Status Code 200

Name Type Required Restrictions Description
» complete boolean false none Whether all records have been delivered or not. false means there's another page
» scroll string false none Scroll token to use for pagination
» query string false none The GNQL query string the requester queried
» count integer false none The number of total results for the given GNQL query
» message string false none An encouraging status message
» data [NoiseContext] false none The relevant IP records requested by the user
»» ip string false none The IP address queried
»» seen boolean false none Whether or not the IP address has been observed by the GreyNoise sensor network.
»» classification string false none The classification of the IP address, either "benign", "malicious", or "unknown", based on the activity observed by GreyNoise.
»» first_seen string(date) false none The earliest date GreyNoise observed any activity from this IP.
»» last_seen string(date) false none The most recent date GreyNoise observed any activity from this IP.
»» actor string false none The overt actor this IP is associated with.
»» tags [string] false none A list of activity/malware tags GreyNoise has applied to this IP.
»» metadata object false none none
»»» country string false none The country where the device is geographically located.
»»» country_code string false none The two-letter (ISO 3166-1 alpha-2) country code where the device is geographically located.
»»» city string false none The city where the device is geographically located.
»»» organization string false none The name of organization that owns the IP address.
»»» rdns string false none The reverse DNS pointer.
»»» asn string false none The autonomous system identification number.
»»» tor boolean false none Whether or not the device is a known Tor exit node.
»»» category string false none The subset of network types the IP address belongs to.
»»» os string false none An approximate guess of the operating system of the device, based on the TCP stack fingerprint.
»» raw_data object false none Raw data observed directly by GreyNoise.
»»» scan [object] false none none
»»»» port integer false none Port number
»»»» protocol string false none Protocol
»»» web object false none none
»»»» paths [string] false none none
»»»» useragents [string] false none none
»»» ja3 [object] false none none
»»»» fingerprint string false none JA3 hash fingerprint string
»»»» port integer false none TCP port connection that the SSL/TLS communication occurred over

Enumerated Values

Property Value
classification benign
classification malicious
classification unknown
category isp
category business
category hosting
category mobile
category education

GNQL Stats

Code samples

# You can also use wget
curl -X GET https://api.greynoise.io/v2/experimental/gnql/stats?query=string \
  -H 'Accept: application/json' \
  -H 'key: API_KEY'

import requests
headers = {
  'Accept': 'application/json',
  'key': 'API_KEY'
}

r = requests.get('https://api.greynoise.io/v2/experimental/gnql/stats', params={
  'query': 'string'
}, headers = headers)

print r.json()

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "key": []string{"API_KEY"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.greynoise.io/v2/experimental/gnql/stats", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'key':'API_KEY'

};

fetch('https://api.greynoise.io/v2/experimental/gnql/stats?query=string',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /v2/experimental/gnql/stats

Get aggregate statistics for the top organizations, actors, tags, ASNs, countries, classifications, and operating systems of all the results of a given GNQL query.

Parameters

Name In Type Required Description
query query string true GNQL query string
count query integer false Number of top aggregates to grab

Example responses

200 Response

{
  "query": "last_seen:2019-07-28 classification:malicious",
  "count": 50000,
  "stats": {
    "classifications": [
      {
        "classification": "malicious",
        "count": 5000
      }
    ],
    "organizations": [
      {
        "organization": "DigitalOcean, LLC",
        "count": 5000
      }
    ],
    "actors": [
      {
        "actor": "Shodan.io",
        "count": 5000
      }
    ],
    "tags": [
      {
        "tag": "SSH Bruteforcer",
        "count": 5000
      }
    ],
    "operating_systems": [
      {
        "operating_system": "Windows 7/8",
        "count": 5000
      }
    ],
    "categories": [
      {
        "category": "education",
        "count": 5000
      }
    ],
    "asn": [
      {
        "asn": "AS4134",
        "count": 5000
      }
    ]
  }
}

Responses

Status Meaning Description Schema
200 OK Query successful. Inline
400 Bad Request Bad request. None
401 Unauthorized Unauthorized. Please check your API key. None
429 Too Many Requests Too many requests. You've hit the rate-limit. None

Response Schema

Status Code 200

Name Type Required Restrictions Description
» query string false none The GNQL query string the requester queried
» count integer false none The number of total results for the given GNQL query
» stats object false none none
»» classifications [object] false none Most common classifications
»»» classification string false none none
»»» count integer false none none
»» organizations [object] false none Most common organizations
»»» organization string false none none
»»» count integer false none none
»» actors [object] false none Most common actors
»»» actor string false none none
»»» count integer false none none
»» tags [object] false none Most common tags
»»» tag string false none none
»»» count integer false none none
»» operating_systems [object] false none Most common operating systems
»»» operating_system string false none none
»»» count integer false none none
»» categories [object] false none Most common categories
»»» category string false none none
»»» count integer false none none
»» asn [object] false none Most common ASNs
»»» asn string false none none
»»» count integer false none none

Metadata

Calls to get metadata on tags and analytics

Tag Metadata

Code samples

# You can also use wget
curl -X GET https://api.greynoise.io/v2/meta/metadata \
  -H 'Accept: application/json' \
  -H 'key: API_KEY'

import requests
headers = {
  'Accept': 'application/json',
  'key': 'API_KEY'
}

r = requests.get('https://api.greynoise.io/v2/meta/metadata', params={

}, headers = headers)

print r.json()

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "key": []string{"API_KEY"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.greynoise.io/v2/meta/metadata", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'key':'API_KEY'

};

fetch('https://api.greynoise.io/v2/meta/metadata',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /v2/meta/metadata

Get a list of tags and their respective metadata

Example responses

200 Response

{
  "metadata": [
    {
      "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": [
        "https://en.wikipedia.org/wiki/Mirai_(malware)"
      ]
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK Query successful. Inline
400 Bad Request Bad request. None
401 Unauthorized Unauthorized. Please check your API key. None
429 Too Many Requests Too many requests. You've hit the rate-limit. None

Response Schema

Status Code 200

Name Type Required Restrictions Description
» metadata [object] false none none
»» name string false none none
»» category string false none none
»» intention string false none none
»» description string false none none
»» references [string] false none none

Schemas

Metadata

{
  "country": "United States",
  "country_code": "US",
  "city": "Seattle",
  "organization": "DigitalOcean, LLC",
  "rdns": "crawl-66-249-79-17.googlebot.com",
  "asn": "AS521",
  "tor": false,
  "category": "education",
  "os": "Windows 7/8"
}

Properties

Name Type Required Restrictions Description
country string false none The country where the device is geographically located.
country_code string false none The two-letter (ISO 3166-1 alpha-2) country code where the device is geographically located.
city string false none The city where the device is geographically located.
organization string false none The name of organization that owns the IP address.
rdns string false none The reverse DNS pointer.
asn string false none The autonomous system identification number.
tor boolean false none Whether or not the device is a known Tor exit node.
category string false none The subset of network types the IP address belongs to.
os string false none An approximate guess of the operating system of the device, based on the TCP stack fingerprint.

Enumerated Values

Property Value
category isp
category business
category hosting
category mobile
category education

NoiseContext

{
  "ip": "71.6.135.131",
  "seen": true,
  "classification": "benign",
  "first_seen": "2018-01-28",
  "last_seen": "2018-2-28",
  "actor": "Shodan.io",
  "tags": [
    "Mirai",
    "Telnet Worm"
  ],
  "metadata": {
    "country": "United States",
    "country_code": "US",
    "city": "Seattle",
    "organization": "DigitalOcean, LLC",
    "rdns": "crawl-66-249-79-17.googlebot.com",
    "asn": "AS521",
    "tor": false,
    "category": "education",
    "os": "Windows 7/8"
  },
  "raw_data": {
    "scan": [
      {
        "port": 80,
        "protocol": "TCP"
      }
    ],
    "web": {
      "paths": [
        "/robots.txt"
      ],
      "useragents": [
        "Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)"
      ]
    },
    "ja3": [
      {
        "fingerprint": "c3a6cf0bf2e690ac8e1ecf6081f17a50",
        "port": 443
      }
    ]
  }
}

Properties

Name Type Required Restrictions Description
ip string false none The IP address queried
seen boolean false none Whether or not the IP address has been observed by the GreyNoise sensor network.
classification string false none The classification of the IP address, either "benign", "malicious", or "unknown", based on the activity observed by GreyNoise.
first_seen string(date) false none The earliest date GreyNoise observed any activity from this IP.
last_seen string(date) false none The most recent date GreyNoise observed any activity from this IP.
actor string false none The overt actor this IP is associated with.
tags [string] false none A list of activity/malware tags GreyNoise has applied to this IP.
metadata Metadata false none none
raw_data object false none Raw data observed directly by GreyNoise.
» scan [object] false none none
»» port integer false none Port number
»» protocol string false none Protocol
» web object false none none
»» paths [string] false none none
»» useragents [string] false none none
» ja3 [object] false none none
»» fingerprint string false none JA3 hash fingerprint string
»» port integer false none TCP port connection that the SSL/TLS communication occurred over

Enumerated Values

Property Value
classification benign
classification malicious
classification unknown

NoiseQuick

{
  "code": "0x01",
  "ip": "71.6.135.131",
  "noise": true
}

Properties

Name Type Required Restrictions Description
code string false none none
ip string false none none
noise boolean false none none

Enumerated Values

Property Value
code 0x00
code 0x01
code 0x02
code 0x03
code 0x04
code 0x05
code 0x06
code 0x07
code 0x08