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 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:
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 the event field being referenced is an array, then the helper function will return an array of the matching values. For example:
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 |
Last updated