GreyNoise Helper Function Usage and Methods
Panther has integrated helper functions to streamline the use of GreyNoise data. 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.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)
Note that the
global
statements are only needed if you intend to use the objects outside of the function in which they were declared.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
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 |
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 |
| | |
Last modified 12d ago