Reference

Code

GreyNoise API client and tools.

greynoise.api

GreyNoise API client.

class greynoise.api.APIConfig(api_key: str, api_server: str | None = 'https://api.greynoise.io', timeout: int | None = 60, proxy: str | None = None, offering: str | None = 'enterprise', integration_name: str | None = None, cache_max_size: int | None = 1000000, cache_ttl: int | None = 3600, use_cache: bool | None = True)[source]: Configuration for API client.

class greynoise.api.BaseAPIClient(config: APIConfig)[source]

Base class for API clients with common functionality.

_process_batch_parallel(items: List[Any], process_func: Callable[[List[Any]], List[Any] | Dict[str, Any]], batch_size: int = 1000, max_workers: int = 10) → List[Any] | Dict[str, List[Any]][source]

Process items in parallel batches.

Args:: items: List of items to process process_func: Function to process each batch batch_size: Size of each batch max_workers: Maximum number of parallel workers
Returns:: Accumulated list or dict with values grouped by key.

_request(endpoint: str, params: Dict[str, Any] | None = None, json: Dict[str, Any] | None = None, files: Dict[str, Any] | None = None, method: str = 'get', include_headers: bool = False, proxy: str | None = None) → Dict[str, Any] | tuple[source]: Handle API requests with proper error handling and logging.

_setup_cache() → None[source]: Initialize cache with configured parameters.

_setup_session() → Session[source]: Set up a session with retry logic and connection pooling.

class greynoise.api.GreyNoise(config: APIConfig)[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

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

cve(cve_id=None)[source]

Get CVE details by CVE ID

Parameters:: cve_id (str) – ID of CVE

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

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

persona_details(persona_id=None)[source]

Get persona details by ID

Parameters:: persona_id (str) – ID of Persona

query(query, size=None, scroll=None, exclude_raw=False, quick=False)[source]: Run GNQL query.

quick(ip_addresses: str | List[str], include_invalid: bool = False) → List[Dict[str, Any]][source]

Get activity associated with one or more IP addresses.

Args:: ip_addresses: One or more IP addresses to look up include_invalid: Whether to include invalid IPs in results
Returns:: List of results for each IP address

request(endpoint: str, method: str = 'get', params: Dict[str, Any] | None = None, json: Dict[str, Any] | None = None, files: Dict[str, Any] | None = None, headers: Dict[str, Any] | None = None, proxy: str | None = None) → Dict[str, Any][source]

Make a request to the GreyNoise API.

Args:: endpoint: API endpoint to request method: HTTP method to use params: URL parameters to include json: JSON data to include files: Files to include headers: Headers to include proxy: Proxy URL to use for the request
Returns:: API response data

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

sensor_activity(workspace_id, file_format=None, start_time=None, end_time=None, persona_id=None, source_ip=None, size=None, scroll=None, include_headers=False)[source]: Get session data from sensors

sensor_activity_ips(workspace_id, file_format=None, start_time=None, end_time=None, persona_id=None, source_ip=None, size=None, scroll=None)[source]: Get session data from sensors

sensor_list(workspace_id=None)[source]

Get list of current sensors for Workspace

Parameters:: workspace_id (str) – ID of Workspace

similar(ip_address, limit=None, min_score=None)[source]

Query IP on the IP Similarity API

Parameters:

ip_address (str) – IP address to use in the look-up.
limit (str) – Limit the number of matches returned by the endpoint
limit – Limit the number of matches returned by the endpoint

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.

timeline(ip_address, field='classification', days=None, granularity=None)[source]

Query IP on the IP TimeSeries API

Parameters:

ip_address (str) – IP address to use in the look-up.
field (str) – field name to use to retrieve timeline information
days (int) – Number of days to show data for
granularity (str) – Granularity of activity date ranges

Returns:

Context for the IP address.

Return type:

dict

timelinedaily(ip_address, days=None, cursor=None, limit=50)[source]

Query IP on the IP TimeSeries API

Parameters:

ip_address (str) – IP address to use in the look-up.
cursor (str) – The cursor is a pointer from which to start returning results up to the limit
days (int) – Number of days to show data for
limit (str) – The total number of events to return in the response

Returns:

Context for the IP address.

Return type:

dict

timelinehourly(ip_address, days=None, cursor=None, limit=100)[source]

Query IP on the IP TimeSeries API

Parameters:

ip_address (str) – IP address to use in the look-up.
cursor (str) – The cursor is a pointer from which to start returning results up to the limit
days (int) – Number of days to show data for
limit (str) – The total number of events to return in the response

Returns:

Context for the IP address.

Return type:

dict

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.cvedetails_formatter(results, verbose)[source]: Convert CVE Details to human-readable text.

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_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.personadetails_formatter(results, verbose)[source]: Convert Persona Details to human-readable text.

greynoise.cli.formatter.riot_formatter(results, verbose)[source]: Convert RIOT to human-readable text.

greynoise.cli.formatter.sensoractivity_formatter(results, verbose)[source]: Convert Sensor Activity to human-readable text.

greynoise.cli.formatter.sensorlist_formatter(results, verbose)[source]: Convert Sensor List to human-readable text.

greynoise.cli.formatter.similar_formatter(results, verbose)[source]: Convert IP Sim to human-readable text.

greynoise.cli.formatter.timeline_formatter(results, verbose)[source]: Convert Timeline to human-readable text.

greynoise.cli.formatter.timelinehourly_formatter(results, verbose)[source]: Convert Timeline hourly/daily 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

Command implementation.

greynoise.util

Utility functions.

greynoise.util.load_config()[source]

Load configuration.

Returns:: Current configuration based on configuration file and environment variables.
Return type:: dict

greynoise.util.load_template(template_name: str) → str[source]

Load a template from the templates directory.

Args:: template_name: Name of the template to load
Returns:: Template content as a string

greynoise.util.save_config(config)[source]

Save configuration.

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

greynoise.util.validate_cve_id(cve_id)[source]

Check if provided value is a valid CVE ID

Parameters:: cve_id (str) – field value to validate.

greynoise.util.validate_ip(ip, 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

greynoise.util.validate_similar_min_score(min_score)[source]

Check if the Similarity min_score value is valid.

Parameters:: min_score (str) – field value to validate.

greynoise.util.validate_timeline_days(days)[source]

Check if the Timeline Days value is valid.

Parameters:: days (str) – field value to validate.

greynoise.util.validate_timeline_field_value(field)[source]

Check if the Timeline Field value is valid.

Parameters:: field (str) – field value to validate.

greynoise.util.validate_timeline_granularity(granularity)[source]

Check if the Timeline granularity value is valid.

Parameters:: granularity (str) – field value to validate.

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

cve

Retrieve Details of a CVE.

greynoise cve [OPTIONS] CVE_ID

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

CVE_ID: Required argument

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]

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)

persona-details

Retrieve Details of a Sensor Persona.

greynoise persona-details [OPTIONS] PERSONA_ID

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

PERSONA_ID: Required argument

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.PromptSession().

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)

sensor-activity

Retrieve Sensor Activity.

greynoise sensor-activity [OPTIONS] WORKSPACE_ID

Options

--start_time <start_time>: Earliest session start time to return

--end_time <end_time>: Latest session start time to return

--file_format <file_format>: Format for output file

--persona_id <persona_id>: Id for the desired persona

--source_ip <source_ip>: Ip for the desired source

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

WORKSPACE_ID: Required argument

sensor-list

Retrieve list of current Sensors in Workspace.

greynoise sensor-list [OPTIONS] WORKSPACE_ID

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

WORKSPACE_ID: Required argument

setup

Configure API client.

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

--cache-max-size <cache_max_size>: Maximum size of the cache

--cache-ttl <cache_ttl>: Cache time-to-live in seconds

signature

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

greynoise signature [OPTIONS]

similar

Query GreyNoise IP to identify Similar IPs.

greynoise similar [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

-l, --limit <limit>: Limit the number of results

-s, --min_score <min_score>: Return results where score is above min

Arguments

IP_ADDRESS: Optional argument(s)

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

timeline

Query GreyNoise IP Timeline for events based on a single field.

greynoise timeline [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

-d, --days <days>: Number of Days to display

-F, --field_name <field_name>: Field name to display data for

Arguments

IP_ADDRESS: Optional argument(s)

timelinedaily

Query GreyNoise IP Timeline to get daily event details.

greynoise timelinedaily [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

-d, --days <days>: Number of Days to display

-F, --field_name <field_name>: Field name to display data for

Arguments

IP_ADDRESS: Optional argument(s)

timelinehourly

Query GreyNoise IP Timeline to get hourly event details.

greynoise timelinehourly [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

-d, --days <days>: Number of Days to display

-F, --field_name <field_name>: Field name to display data for

Arguments

IP_ADDRESS: Optional argument(s)

version

Get version and OS information for your GreyNoise commandline installation.

greynoise version [OPTIONS]