GreyNoise Helper Function Usage and Methods

Overview

Panther is sunsetting the GreyNoise Enrichment Provider on June 17, 2024. Starting that date, GreyNoise intelligence data will no longer be natively available in Panther. Please reach out to your Support team with any questions or concerns.

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 Simple 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 Simple Detections 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 MethodBasic 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 MethodBasic 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

Last updated