Reference

Code

GreyNoise API client and tools.

greynoise.api

GreyNoise API client.

class greynoise.api.GreyNoise(api_key=None, api_server=None, timeout=None, proxy=None, use_cache=True, integration_name=None, cache_max_size=None, cache_ttl=None, offering=None)[source]

GreyNoise API client.

Parameters
  • api_key (str) – Key use to access the API.

  • timeout (int) – API requests timeout in seconds.

  • proxy (str) – Add URL for proxy to redirect lookups

_request(endpoint, params=None, json=None, method='get')[source]

Handle the requesting of information from the API.

Parameters
  • endpoint (str) – Endpoint to send the request to

  • params – Request parameters

  • json (dict) – Request’s JSON payload

  • method (str) – Request method name

Returns

Response’s JSON payload

Return type

dict

Raises

RequestFailure – when HTTP status code is not 2xx

analyze(text)[source]

Aggregate stats related to IP addresses from a given text.

Parameters

text (file-like | str) – Text input

Returns

Aggregated stats for all the IP addresses found.

Return type

dict

filter(text, noise_only=False, riot_only=False)[source]

Filter lines that contain IP addresses from a given text.

Parameters
  • text (file-like | str) – Text input

  • noise_only (bool) – If set, return only lines that contain IP addresses classified as noise, otherwise, return lines that contain IP addresses not classified as noise.

  • riot_only (bool) – If set, return only lines that contain IP addresses in RIOT, otherwise, return lines that contain IP addresses not in RIOT.

Returns

Iterator that yields lines in chunks

Return type

iterable

interesting(ip_address)[source]

Report an IP as “interesting”.

Parameters

ip_address (str) – IP address to report as “interesting”.

ip(ip_address)[source]

Get context associated with an IP address.

Parameters

ip_address (str) – IP address to use in the look-up.

Returns

Context for the IP address.

Return type

dict

ip_multi(ip_addresses, include_invalid=False)[source]

Get activity associated with one or more IP addresses.

Parameters
  • ip_addresses (str | list) – One or more IP addresses to use in the look-up.

  • include_invalid (bool) – True or False

Returns

Bulk status information for IP addresses.

Return type

dict

metadata()[source]

Get metadata.

not_implemented(subcommand_name)[source]

Send request for a not implemented CLI subcommand.

Parameters

subcommand_name (str) – Name of the CLI subcommand

query(query, size=None, scroll=None)[source]

Run GNQL query.

quick(ip_addresses, include_invalid=False)[source]

Get activity associated with one or more IP addresses.

Parameters
  • ip_addresses (str | list) – One or more IP addresses to use in the look-up.

  • include_invalid (bool) – True or False

Returns

Bulk status information for IP addresses.

Return type

dict

riot(ip_address)[source]

Check if IP is in RIOT data set

Parameters

ip_address (str) – IP address to use in the look-up.

Returns

Context for the IP address.

Return type

dict

stats(query, count=None)[source]

Run GNQL stats query.

test_connection()[source]

Test the API connection and API key.

greynoise.api.initialize_cache(cache_max_size, cache_ttl)[source]

A function to initialize cache

greynoise.cli

GreyNoise command line Interface.

greynoise.cli.formatter

Output formatters.

greynoise.cli.formatter.analyze_formatter(result, verbose)[source]

Conver analyze result into human-readable text.

greynoise.cli.formatter.colored_output(function)[source]

Decorator that converts ansi markup into ansi escape sequences.

Parameters

function (callable) – Function that will return text using ansi markup.

Returns

Wrapped function that converts markup into escape sequences.

Return type

callable

greynoise.cli.formatter.get_location(metadata)[source]

Get location from ip context metadata.

greynoise.cli.formatter.gnql_query_formatter(results, verbose)[source]

Convert GNQL query result into human-readable text.

greynoise.cli.formatter.gnql_stats_formatter(results, verbose)[source]

Convert GNQL stats result into human-readable text.

greynoise.cli.formatter.interesting_formatter(results, verbose)[source]

Convert RIOT to human-readable text.

greynoise.cli.formatter.ip_context_formatter(results, verbose)[source]

Convert IP context result into human-readable text.

greynoise.cli.formatter.ip_multi_context_formatter(results, verbose)[source]

Convert IP multi context result into human-readable text.

greynoise.cli.formatter.ip_quick_check_formatter(results, verbose)[source]

Convert IP quick check result into human-readable text.

greynoise.cli.formatter.json_formatter(result, _verbose)[source]

Format result as json.

greynoise.cli.formatter.riot_formatter(results, verbose)[source]

Convert RIOT to human-readable text.

greynoise.cli.formatter.xml_formatter(result, _verbose)[source]

Format result as xml.

greynoise.cli.parameter

Command line parameter types.

greynoise.cli.parameter.ip_addresses_parameter(_context, _parameter, values)[source]

IPv4 addresses passed from the command line.

Parameters

values – IPv4 address values

Raises

click.BadParameter – when any IP address value is invalid

greynoise.cli.subcommand

CLI subcommands.

greynoise.util

Utility functions.

greynoise.util.configure_logging()[source]

Configure logging.

greynoise.util.load_config()[source]

Load configuration.

Returns

Current configuration based on configuration file and environment variables.

Return type

dict

greynoise.util.save_config(config)[source]

Save configuration.

Parameters

config (dict) – Data to be written to the configuration file.

greynoise.util.validate_ip(ip_address, strict=True, print_warning=True)[source]

Check if the IPv4 address is valid.

Parameters
  • ip_address (str) – IPv4 address value to validate.

  • strict (bool) – Whether to raise exception if validation fails.

Raises
  • ValueError – When validation fails and strict is set to True.

  • ValueError – By default, otherwise returns nothing

CLI

greynoise

GreyNoise CLI.

greynoise [OPTIONS] COMMAND [ARGS]...

account

View information about your GreyNoise account.

greynoise account [OPTIONS]

alerts

List, create, delete, and manage your GreyNoise alerts.

greynoise alerts [OPTIONS]

analyze

Analyze the IP addresses in a log file, stdin, etc.

greynoise analyze [OPTIONS]

Options

-k, --api-key <api_key>

Key to include in API requests

-i, --input <input_file>

Input file

-o, --output <output_file>

Output file

-f, --format <output_format>

Output format

Options

json | txt | xml

-v, --verbose

Verbose output

feedback

Send feedback directly to the GreyNoise team.

greynoise feedback [OPTIONS]

filter

Filter the noise from a log file, stdin, etc.

greynoise filter [OPTIONS]

Options

-k, --api-key <api_key>

Key to include in API requests

-i, --input <input_file>

Input file

-o, --output <output_file>

Output file

--noise-only

Select lines containing noisy addresses

--riot-only

Select lines containing RIOT addresses

help

Show this message and exit.

greynoise help [OPTIONS]

interesting

Report one or more IP addresses as “interesting”.

greynoise interesting [OPTIONS] [IP_ADDRESS]...

Options

-k, --api-key <api_key>

Key to include in API requests

-i, --input <input_file>

Input file

Arguments

IP_ADDRESS

Optional argument(s)

ip

Query GreyNoise for all information on a given IP.

greynoise ip [OPTIONS] [IP_ADDRESS]...

Options

-k, --api-key <api_key>

Key to include in API requests

-O, --offering <offering>

Which API offering to use, enterprise or community, defaults to enterprise

-i, --input <input_file>

Input file

-o, --output <output_file>

Output file

-f, --format <output_format>

Output format

Options

json | txt | xml

-v, --verbose

Verbose output

Arguments

IP_ADDRESS

Optional argument(s)

ip-multi

Perform Context lookup for multiple IPs at once.

Example: greynoise ip-multi 1.1.1.1 2.2.2.2 3.3.3.3

Example: greynoise ip-multi 1.1.1.1,2.2.2.2,3.3.3.3

Example: greynoise ip-multi -i <filename>

greynoise ip-multi [OPTIONS] [IP_ADDRESS]...

Options

-k, --api-key <api_key>

Key to include in API requests

-O, --offering <offering>

Which API offering to use, enterprise or community, defaults to enterprise

-i, --input <input_file>

Input file

-o, --output <output_file>

Output file

-f, --format <output_format>

Output format

Options

json | txt | xml

Arguments

IP_ADDRESS

Optional argument(s)

query

Run a GNQL (GreyNoise Query Language) query.

greynoise query [OPTIONS] [QUERY]

Options

--size <size>

Max number of results to return

--scroll <scroll>

Scroll token for pagination

-k, --api-key <api_key>

Key to include in API requests

-O, --offering <offering>

Which API offering to use, enterprise or community, defaults to enterprise

-i, --input <input_file>

Input file

-o, --output <output_file>

Output file

-f, --format <output_format>

Output format

Options

json | txt | xml

-v, --verbose

Verbose output

Arguments

QUERY

Optional argument

quick

Quickly check whether or not one or many IPs are “noise”.

greynoise quick [OPTIONS] [IP_ADDRESS]...

Options

-k, --api-key <api_key>

Key to include in API requests

-O, --offering <offering>

Which API offering to use, enterprise or community, defaults to enterprise

-i, --input <input_file>

Input file

-o, --output <output_file>

Output file

-f, --format <output_format>

Output format

Options

json | txt | xml

Arguments

IP_ADDRESS

Optional argument(s)

repl

Start an interactive shell. All subcommands are available in it.

param old_ctx

The current Click context.

param prompt_kwargs

Parameters passed to prompt_toolkit.shortcuts.prompt().

If stdin is not a TTY, no prompt will be printed, but only commands read from stdin.

greynoise repl [OPTIONS]

riot

Query GreyNoise IP to see if it is in the RIOT dataset.

greynoise riot [OPTIONS] [IP_ADDRESS]...

Options

-k, --api-key <api_key>

Key to include in API requests

-O, --offering <offering>

Which API offering to use, enterprise or community, defaults to enterprise

-i, --input <input_file>

Input file

-o, --output <output_file>

Output file

-f, --format <output_format>

Output format

Options

json | txt | xml

-v, --verbose

Verbose output

Arguments

IP_ADDRESS

Optional argument(s)

setup

Configure API key.

greynoise setup [OPTIONS]

Options

-k, --api-key <api_key>

Required Key to include in API requests

-O, --offering <offering>

Which API offering to use, enterprise or community, defaults to enterprise

-t, --timeout <timeout>

API client request timeout

-s, --api-server <api_server>

API server

-p, --proxy <proxy>

Proxy URL

signature

Submit an IDS signature to GreyNoise to be deployed to all GreyNoise nodes.

greynoise signature [OPTIONS]

stats

Get aggregate stats from a given GNQL query.

greynoise stats [OPTIONS] [QUERY]

Options

--size <size>

Max number of results to return

--scroll <scroll>

Scroll token for pagination

-k, --api-key <api_key>

Key to include in API requests

-O, --offering <offering>

Which API offering to use, enterprise or community, defaults to enterprise

-i, --input <input_file>

Input file

-o, --output <output_file>

Output file

-f, --format <output_format>

Output format

Options

json | txt | xml

-v, --verbose

Verbose output

Arguments

QUERY

Optional argument

version

Get version and OS information for your GreyNoise commandline installation.

greynoise version [OPTIONS]