GreyNoise Helper Function Usage and Methods

Overview

Panther has integrated Python helper functions to streamline the use of GreyNoise data in Python detections. This page describes how to use these functions, and what methods are available in the objects they create.

The helper functions described in this documentation act as proxies for accessing the p_enrichment field of the event object. None of the following methods directly query the GreyNoise API.

If you are writing YAML detections, you will not need the helper functions on this page. Instead, you will access GreyNoise enrichment fields using the Enrichment: key. Learn more about using enrichment in YAML here.

Creating GreyNoise objects in a rule

There are individual helpers for both GreyNoise datasets (Noise and RIOT). These functions create objects with methods that can be called to return relevant data from the dataset. Below is an example code snippet that shows the creation of these objects:

from panther_greynoise_helpers import (
    GetGreyNoiseObject, GetGreyNoiseRiotObject
    )

def rule(event):
    global noise
    global riot
    noise = GetGreyNoiseObject(event)
    riot = GetGreyNoiseRiotObject(event)

The global keyword is only needed if you intend to use the objects outside of the function in which they are declared.

Calling methods on the GreyNoise objects

The various components of the GreyNoise datasets are available via methods on the Noise and RIOT objects. It's possible for one event that your rule is processing to have multiple fields (such as IP addresses, source and destination IP in a network log). When calling the GreyNoise objects, make sure to specify which field you are looking for.

The example below demonstrates calling the classification method on the noise object we created in the previous example, to determine if the source IP address (src) is malicious and if the destination ip (dest) is in the RIOT dataset (meaning it is a known safe entity).

if noise.classification('src') == 'malicious':
    return True
if riot.is_riot('dest'):
    return False

If the event field being referenced is an array, then the helper function will return an array of the matching values. For example:

for classification in noise.classification('p_any_ip_addresses'):
    if classification == 'malicious':
        return True

Available methods

Noise Dataset

The following table shows the available methods for the GreyNoise Noise Object, their expected return values, and if they are available in the Basic or Advanced GreyNoise subscriptions.

All methods take the argument of the field you are searching for (src or dest in the example above) unless otherwise noted.

Noise Method	Basic or Advanced?	Noise Return Type and Description
subscription_level	Both	Takes no arguments Returns String "advanced" or "basic" depending on Subscription level
ip_address	Both	Returns String IP address that was matched
ip_addresses	Both	Returns List A List of IP Addresses and associated information
actor	Both	The confirmed owner/operator of this IP address
classification	Both	Returns String IP Classification - possible options: benign, unknown, malicious
url	Both	Returns String Url to the GreyNoise entry for this IP
is_bot	Advanced	Returns Boolean IP is associated with known bot activity
cve_string	Advanced	Returns String Additional, Optional Argument: limit Default value: 10 Space separated string of CVEs the IP has been observed scanning for or exploiting
cve_list	Advanced	Returns List Returns all CVEs the IP has been observed scanning for or exploiting
first_seen	Advanced	Returns Datetime.date object Date of the first observed behavior on the GreyNoise Sensor network
last_seen_timestamp	Advanced	Returns Datetime.date object Date of last observed behavior on the GreyNoise Sensor network
asn	Advanced	Returns String ASN number of IP
category	Advanced	Returns String Category of service that IP falls into, such as "hosting"
city	Advanced	Returns String City where IP is physically located
country	Advanced	Returns String Country where IP is Physically located
country_code	Advanced	Returns String Two letter Country Code where IP is Physically located
organization	Advanced	Returns String Organization that owns the IP
operating_system	Advanced	Returns String Operating System that has been observed using the IP
region	Advanced	Returns String State, Province, or other Regional identifier associated with the IP
is_tor	Advanced	Returns Boolean If IP is a part of the TOR network, usually an exit node
tags_list	Advanced	Returns List GreyNoise tags associated with IP
tags_string	Advanced	Returns String Optional Argument: limit Default: 10 Space separated string of GreyNoise tags associated with the IP
is_vpn	Advanced	Returns Boolean If IP is associated with a VPN service
vpn_service	Advanced	Returns String VPN service associated with IP, if any

RIOT Dataset

The following table shows the available methods for the GreyNoise RIOT object, their expected return values, and if they are available in the Basic or Advanced GreyNoise subscriptions.

All methods take the argument of the field you are searching for (src or dest in the example above) unless otherwise noted.

RIOT Method	Basic or Advanced?	RIOT Return Type and Description
subscription_level	Both	Takes no Arguments Returns String "advanced" or "basic" depending on Subscription level
is_riot	Both	Returns Boolean Indicates if an IP is part of the Riot dataset
ip_address	Both	Returns String IP that was matched
name	Both	Returns String The name of the Provider or service associated with the IP
url	Both	Returns String Url to the GreyNoise entry for this IP
last_updated	Both	Returns Datetime.date object Date and time when this record was last updated from its source
description	Advanced	Returns String A description of the provider and what they do
explanation	Advanced	Returns String An explanation of the category type and what may be expected from this provider and category
reference	Advanced	Returns String Reference URL for information about this provider and/or service
trust_level	Advanced	Returns Integer Defines the trust level assigned to this IP/provider, either 1 or 2. Additional information on trust levels can be found here