# GreyNoise Helper Function Usage and Methods ## Overview 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. ## 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: ```python 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). ```python 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: ```python 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

| | | | |