Tutorial

API client

Create client object

To interact with the API, a client object needs to be created:

>>> from greynoise import GreyNoise
>>> api_client = GreyNoise(<api_key>)

where api_key is the key you have been given to use the API.

Note

The api_key is an optional parameter and might not be required if it’s been stored in the configuration file using greynose setup –api-key <api_key>.

Check specific IPs

Once the client object has been created, it’s possible to check if a given IP is considered internet noise or has been observed scanning or attacking devices across the Internet as follows:

>>> api_client.get_noise_status('8.8.8.8')
{
  "ip": "8.8.8.8",
  "noise": false,
  "code": "0x05",
  "code_message": "This IP is commonly spoofed in Internet-scan activity"
}

When there’s a list of IP addresses to verify, they can be checked all at once like this:

>>> client.get_noise_status_bulk(['8.8.8.8', '58.220.219.247'])
[
  {
    "ip": "8.8.8.8",
    "noise": false,
    "code": "0x05",
    "code_message": "This IP is commonly spoofed in Internet-scan activity"
  },
  {
    "ip": "58.220.219.247",
    "noise": true,
    "code": "0x01",
    "code_message": "The IP has been observed by the GreyNoise sensor network"
  }
]

Detailed context information for any given IP address is also available:

>>> api_client.get_context('58.220.219.247')
{
  "ip": "58.220.219.247",
  "seen": true,
  "classification": "malicious",
  "first_seen": "2019-04-04",
  "last_seen": "2019-08-21",
  "actor": "unknown",
  "tags": [
    "MSSQL Bruteforcer",
    "MSSQL Scanner",
    "RDP Scanner"
  ],
  "metadata": {
    "country": "China",
    "country_code": "CN",
    "city": "Kunshan",
    "organization": "CHINANET jiangsu province network",
    "asn": "AS4134",
    "tor": false,
    "os": "Windows 7/8",
    "category": "isp"
  },
  "raw_data": {
    "scan": [
      {
        "port": 1433,
        "protocol": "TCP"
      },
      {
        "port": 3389,
        "protocol": "TCP"
      },
      {
        "port": 65529,
        "protocol": "TCP"
      }
    ],
    "web": {
      "paths": [],
      "useragents": []
    },
    "ja3": []
  }
}

GNQL

Run a query

A GNQL (GreyNoise Query Language) query can be executed to dig deeper into the GreyNoise dataset. For example, to get context information related to activity has been classified as malicious and tagged as a Bluekeep Exploit:

>>> api_client.run_query('classification:malicious tags:"Bluekeep Exploit"')
{
  "complete": true,
  "count": 2,
  "data": [
    {
      "ip": "144.217.253.168",
      "seen": true,
      "classification": "malicious",
      "first_seen": "2019-06-04",
      "last_seen": "2019-08-21",
      "actor": "unknown",
      "tags": [
        "RDP Scanner",
        "Bluekeep Exploit"
      ],
      "metadata": {
        "country": "Canada",
        "country_code": "CA",
        "city": "Montréal",
        "organization": "OVH SAS",
        "rdns": "ns541387.ip-144-217-253.net",
        "asn": "AS16276",
        "tor": false,
        "os": "Linux 3.11+",
        "category": "hosting"
      },
      "raw_data": {
        "scan": [
          {
            "port": 3389,
            "protocol": "TCP"
          }
        ],
        "web": {},
        "ja3": []
      }
    },
    {
      "ip": "91.213.112.119",
      "seen": true,
      "classification": "malicious",
      "first_seen": "2019-04-18",
      "last_seen": "2019-06-03",
      "actor": "unknown",
      "tags": [
        "Bluekeep Exploit",
        "RDP Scanner",
        "TLS/SSL Crawler",
        "Tor",
        "VNC Scanner",
        "Web Scanner",
        "Windows RDP Cookie Hijacker CVE-2014-6318"
      ],
      "metadata": {
        "country": "Netherlands",
        "country_code": "NL",
        "city": "",
        "organization": "Onsweb B.V.",
        "rdns": "no-reverse.onlinesystemen.nl",
        "asn": "AS42755",
        "tor": true,
        "os": "Linux 3.11+",
        "category": "business"
      },
      "raw_data": {
        "scan": [
          {
            "port": 443,
            "protocol": "TCP"
          },
          {
            "port": 3389,
            "protocol": "TCP"
          },
          {
            "port": 5900,
            "protocol": "TCP"
          }
        ],
        "web": {},
        "ja3": []
      }
    }
  ],
  "message": "ok",
  "query": "classification:malicious tags:'Bluekeep Exploit'"
}

Get statistics

It’s also possible to get statistics related to a GNQL query to better understand how results are distributed in terms of different information such as organization, country, operating system, etc.:

>>> api_client.run_stats_query('classification:malicious tags:"Bluekeep Exploit"')
{
  "query": "classification:malicious tags:'Bluekeep Exploit'",
  "count": 24,
  "stats": {
    "classifications": [
      {
        "classification": "malicious",
        "count": 24
      }
    ],
    "organizations": [
      {
        "organization": "DigitalOcean, LLC",
        "count": 7
      },
      {
        "organization": "OVH SAS",
        "count": 6
      },
      {
        "organization": "China Unicom Shanghai network",
        "count": 3
      },
      {
        "organization": "Linode, LLC",
        "count": 3
      },
      {
        "organization": "Amarutu Technology Ltd",
        "count": 1
      },
      {
        "organization": "Amazon.com, Inc.",
        "count": 1
      },
      {
        "organization": "CHINANET-BACKBONE",
        "count": 1
      },
      {
        "organization": "INT-NETWORK",
        "count": 1
      },
      {
        "organization": "WideOpenWest Finance LLC",
        "count": 1
      }
    ],
    "actors": null,
    "countries": [
      {
        "country": "Canada",
        "count": 6
      },
      {
        "country": "United States",
        "count": 6
      },
      {
        "country": "China",
        "count": 4
      },
      {
        "country": "Germany",
        "count": 3
      },
      {
        "country": "Netherlands",
        "count": 3
      },
      {
        "country": "France",
        "count": 1
      },
      {
        "country": "United Kingdom",
        "count": 1
      }
    ],
    "tags": [
      {
        "tag": "Bluekeep Exploit",
        "count": 24
      },
      {
        "tag": "RDP Scanner",
        "count": 24
      },
      {
        "tag": "Telnet Scanner",
        "count": 1
      }
    ],
    "operating_systems": [
      {
        "operating_system": "Linux 3.11+",
        "count": 16
      },
      {
        "operating_system": "Windows 7/8",
        "count": 3
      },
      {
        "operating_system": "Mac OS X",
        "count": 2
      },
      {
        "operating_system": "Linux 2.2-3.x",
        "count": 1
      }
    ],
    "categories": [
      {
        "category": "hosting",
        "count": 17
      },
      {
        "category": "isp",
        "count": 6
      },
      {
        "category": "business",
        "count": 1
      }
    ],
    "asns": [
      {
        "asn": "AS14061",
        "count": 7
      },
      {
        "asn": "AS16276",
        "count": 6
      },
      {
        "asn": "AS17621",
        "count": 3
      },
      {
        "asn": "AS63949",
        "count": 3
      },
      {
        "asn": "AS12083",
        "count": 1
      },
      {
        "asn": "AS14618",
        "count": 1
      },
      {
        "asn": "AS202425",
        "count": 1
      },
      {
        "asn": "AS206264",
        "count": 1
      },
      {
        "asn": "AS4134",
        "count": 1
      }
    ]
  }
}

Command line interface

The same operations available through the API client are also available through the command line using the greynoise tool. To get a list of all the available subcommands, use the –help option:

$ greynoise --help
Usage: greynoise [OPTIONS] COMMAND [ARGS]...

Entry point for the greynoise CLI.

:param argv: Command line arguments :type: list

Options:
-k, --api-key TEXT           Key to include in API requests
-f, --format [json|txt|xml]  Output format
-v, --verbose                Verbose output
--help                       Show this message and exit.

Commands:
gnql*   GNQL queries.
actors  Run actors query.
ip      IP lookup.
setup   Configure API key.

Setup

To configure greynoise to use a given API key:

$ greynoise setup --api-key "<api_key>"
Configuration saved to '/home/username/.config/greynoise/config'

Note

This is the default configuration method. Alternatively, the API key can be passed to every command using the -k/–api-key option or through the GREYNOISE_API_KEY environment variable.

Check specific IPs

Once the command line tool has been created, it’s possible to check if a given IP is considered internet noise or has been observed scanning or attacking devices across the Internet as follows:

$ greynoise ip quick-check 58.220.219.247
58.220.219.247 is classified as NOISE.

When there’s a list of IP addresses to verify, they can be checked all at once like this:

$ greynoise ip multi-quick-check 8.8.8.8 58.220.219.247
8.8.8.8 is classified as NOT NOISE.
58.220.219.247 is classified as NOISE.

Detailed context information for any given IP address is also available:

  $ greynoise ip context 58.220.219.247
┌───────────────────────────┐
│       result 1 of 1       │
└───────────────────────────┘

         OVERVIEW:
----------------------------
IP: 58.220.219.247
Classification: malicious
First seen: 2019-07-04
Last seen: 2019-08-21
Actor: unknown
Tags: ['RDP Scanner', 'MSSQL Scanner', 'MSSQL Bruteforcer']

         METADATA:
----------------------------
Location: Kunshan, China (CN)
Organization: CHINANET-BACKBONE
ASN: AS4134
OS: Windows 7/8
Category: isp

         RAW DATA:
----------------------------
Port/Proto: 1433/TCP
Port/Proto: 3389/TCP
Port/Proto: 65529/TCP

GNQL

Run a query

A GNQL (GreyNoise Query Language) query can be executed to dig deeper into the GreyNoise dataset. For example, to get context information related to activity has been classified as malicious and tagged as a Bluekeep Exploit:

  $ greynoise gnql query 'classification:malicious tags:"Bluekeep Exploit"'
┌───────────────────────────┐
│       result 1 of 24      │
└───────────────────────────┘

         OVERVIEW:
----------------------------
IP: 144.217.253.168
Classification: malicious
First seen: 2019-06-04
Last seen: 2019-08-21
Actor: unknown
Tags: ['RDP Scanner', 'Bluekeep Exploit']

         METADATA:
----------------------------
Location: Montréal, Canada (CA)
Organization: OVH SAS
rDNS: ns541387.ip-144-217-253.net
ASN: AS16276
OS: Linux 3.11+
Category: hosting

         RAW DATA:
----------------------------
Port/Proto: 3389/TCP

Note

This is the default command, that is, you can save some typing by just writing greynoise <query> instead of greynose gnql query <query>.

Get statistics

It’s also possible to get statistics related to a GNQL query to better understand how results are distributed in terms of different information such as organization, country, operating system, etc.:

$ greynoise gnql stats 'classification:malicious tags:"Bluekeep Exploit"'
ASNs:
- AS14061: 7
- AS16276: 6
- AS17621: 3
- AS63949: 3
- AS12083: 1
- AS14618: 1
- AS202425: 1
- AS206264: 1
- AS4134: 1

Categories:
- hosting: 17
- isp: 6
- business: 1

Classifications:
- malicious: 24

Countries:
- Canada: 6
- United States: 6
- China: 4
- Germany: 3
- Netherlands: 3
- France: 1
- United Kingdom: 1

Operating systems:
- Linux 3.11+: 16
- Windows 7/8: 3
- Mac OS X: 2
- Linux 2.2-3.x: 1

Organizations:
- DigitalOcean, LLC: 7
- OVH SAS: 6
- China Unicom Shanghai network: 3
- Linode, LLC: 3
- Amarutu Technology Ltd: 1
- Amazon.com, Inc.: 1
- CHINANET-BACKBONE: 1
- INT-NETWORK: 1
- WideOpenWest Finance LLC: 1

Tags:
- Bluekeep Exploit: 24
- RDP Scanner: 24
- ZMap Client: 9
- DNS Scanner: 8
- Web Scanner: 7
- TLS/SSL Crawler: 6
- HTTP Alt Scanner: 4
- SSH Scanner: 4
- VNC Scanner: 3
- FTP Scanner: 2
- Ping Scanner: 2
- SMB Scanner: 2
- SSH Bruteforcer: 2
- Tor: 2
- Web Crawler: 2
- Bitcoin Node Scanner: 1
- Bluekeep Scanner: 1
- CPanel Scanner: 1
- Cassandra Scanner: 1
- CounterStrike Server Scanner: 1
- Dockerd Scanner: 1
- Elasticsearch Scanner: 1
- IPSec VPN Scanner: 1
- IRC Scanner: 1
- LDAP Scanner: 1
- MSSQL Scanner: 1
- Masscan Client: 1
- Minecraft Scanner: 1
- MongoDB Scanner: 1
- MySQL Scanner: 1
- POP3 Scanner: 1
- PPTP VPN Scanner: 1
- Postgres Scanner: 1
- Privoxy Proxy Scanner: 1
- Python Requests Client: 1
- RabbitMQ Scanner: 1
- Redis Scanner: 1
- SMTP Scanner: 1
- SOCKS Proxy Scanner: 1
- SSH Worm: 1
- Telnet Scanner: 1