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)[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)[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.

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

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)[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.

Returns

Bulk status information for IP addresses.

Return type

dict

stats(query, count=None)[source]

Run GNQL stats query.

test_connection()[source]

Test the API connection and API key.

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.ip_context_formatter(results, verbose)[source]

Convert IP 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.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)[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.

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

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

-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)

pcap

Get PCAP for a given IP address.

greynoise pcap [OPTIONS]

query

Run a GNQL (GreyNoise Query Language) query.

greynoise query [OPTIONS] [QUERY]

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

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

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

setup

Configure API key.

greynoise setup [OPTIONS]

Options

-k, --api-key <api_key>

Required Key to include in API requests

-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

-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

Arguments

QUERY

Optional argument

version

Get version and OS information for your GreyNoise commandline installation.

greynoise version [OPTIONS]