# GreyNoise (Beta)
## Overview
{% hint style="info" %}
GreyNoise enrichment is in open beta starting with Panther version 1.117, and is available to all customers. Please share any bug reports and feature requests with your Panther support team.
{% endhint %}
[GreyNoise](https://www.greynoise.io) provides real-time intelligence about internet-wide scan and attack activity. GreyNoise helps security teams filter out background noise by identifying and labeling IPs conducting mass scanning, enabling faster, more accurate threat detection.
Learn how to [view stored enrichment data here](https://docs.panther.com/enrichment/..#viewing-and-managing-enrichments), and how to [view log events with enrichment data here](https://docs.panther.com/enrichment#viewing-log-events-with-enrichment-data).
{% hint style="warning" %}
GreyNoise enrichment in Panther requires a GreyNoise API key.
{% endhint %}
## How GreyNoise enrichment works in Panther
By default, GreyNoise is configured to run against every log source in your Panther environment ([yet is possible to disable for a log type, if desired](#enabling-disabling-or-modifying-greynoise-enrichment-for-a-log-type)). Panther will attempt to match each incoming log event, across all log types, against the GreyNoise Panther-managed enrichment before it passes through the detection engine.
If Panther [identifies a match](#how-a-match-between-a-log-event-and-greynoise-is-made) between an incoming event and GreyNoise entry, GreyNoise data is appended to the matching log event under a top-level `p_enrichment` key. It can then be referenced in detection logic and searches.
For more information on detection writing using an enrichment source, see [Writing a detection using custom enrichment data](https://docs.panther.com/custom#writing-a-detection-using-custom-enrichment-data).
### How a match between a log event and GreyNoise is made
A log event is enriched with GreyNoise Panther-managed enrichment data (under `p_enrichment`) if a match is found between:
* Any of the values of the Selector field(s) configured for each associated log type.
* For each log type, the default Selectors are the [Indicator Fields](https://docs.panther.com/search/panther-fields) (represented by `p_any_*`) associated with the enrichment table's primary key's indicator field designations (though the Selectors are configurable). [Learn more about this auto-mapping here](https://docs.panther.com/custom#option-2-let-log-types-and-selectors-be-automatically-mapped-by-indicator-fields).
* The value of the `ip` key in a GreyNoise table entry in Panther.
* `ip` is the primary key of the GreyNoise table and is preset by Panther.
* See an example of `ip` in the [Example GreyNoise enrichment table entry](#example-greynoise-enrichment-table-entry) below.
See the complete GreyNoise.API.V3 schema below.
## Setting up GreyNoise enrichment
### Step 1: Create an API key in GreyNoise
* Follow the [GreyNoise documentation](https://docs.greynoise.io/docs/using-the-greynoise-api) to generate an API key for use in Panther.
### Step 2: Create the GreyNoise enrichment in Panther
To configure GreyNoise enrichment in Panther:
1. In the left-hand navigation bar of your Panther Console, click **Configure** > **Enrichments**.
2. In the upper-right corner, click **Create New**.
3. Click **GreyNoise**.
4. In the **Enrichment Settings** form, provide values for the following fields:
* **Name**: enter a descriptive name for your integration.
* **API Key**: enter the API key you generated in Step 1.
* **Refresh period (minutes)**: configure how often Panther will refresh GreyNoise data. The default refresh period is 360 minutes and the minimum refresh period is 60 minutes.
5. Click **Setup**.
* Your new GreyNoise configuration will be visible in the **Configure** > **Enrichments** page.
{% hint style="info" %}
After adding a GreyNoise enrichment, there may be a delay of up to 45 minutes before incoming log data begins to be enriched. This allows time for the initial data synchronization to complete.
{% endhint %}
## Enabling, disabling, or modifying GreyNoise enrichment for a log type
GreyNoise enrichment is enabled by default for each log type in your Panther instance.
If you'd like to disable (or later enable) GreyNoise enrichment for a certain log type, or alter a log type's selectors:
1. In the left-hand navigation bar in your Panther Console, click **Configure** > **Enrichments**.
2. In the list of Enrichments, locate the GreyNoise source you'd like to modify, and click its name.
3. Click on the **Enriched Log Types** tab.
4. On the right-hand side, click **Edit Log Types**.
* If you'd like to enable this enrichment for a new log type, click **Add Log Type**.
* In the new row that populates, select a **Log Type** and, in the **Selectors** field, at least one event field.
* If you'd like to disable this enrichment for a log type, locate that log type's row, and click the trash icon.
* If you don't see a log type listed, click on the drop-down arrow next to **Auto-mapped Log Types**. Locate the log type's row and click the edit icon.
* If you'd like to alter the selectors for a log type, click into the **Selectors** field and add or remove selections for event fields.
5. In the upper-right corner, click **Save**.
## Understanding GreyNoise classifications
GreyNoise classifies IP addresses into the following categories:
* **Benign**: IPs exhibiting common internet behavior that is not malicious
* **Malicious**: IPs with known malicious intent
* **Unknown**: IPs observed by GreyNoise but not yet classified
## Example of using GreyNoise tags in detections
GreyNoise provides detailed tags about scanning behavior. The `recommend_block` field within tags indicates whether GreyNoise recommends blocking traffic from the IP address. This can be particularly useful in detection logic:
```python
def rule(event):
enrichment = event.get('p_enrichment', {})
greynoise_data = enrichment.get('greynoise_your_integration_name', {})
if not greynoise_data:
return False
# Check if any tags recommend blocking
tags = greynoise_data.get('internet_scanner_intelligence', {}).get('tags', [])
for tag in tags:
if tag.get('recommend_block'):
return True
return False
```
## Example GreyNoise enrichment table entry
The below is an example of a GreyNoise API response normalized by Panther, showing an IP address identified as part of a known CDN service with benign scanning behavior:
```json
{
"business_service_intelligence": {
"category": "CDN",
"description": "Content delivery network service",
"explanation": "This IP is part of a known CDN infrastructure",
"found": true,
"last_updated": "2023-09-15T10:30:00Z",
"name": "Cloudflare",
"reference": "https://www.cloudflare.com",
"trust_level": 3
},
"internet_scanner_intelligence": {
"actor": "unknown",
"bot": true,
"classification": "benign",
"cves": [],
"first_seen": "2023-01-15",
"found": true,
"last_seen": "2023-09-20",
"last_seen_timestamp": "2023-09-20 14:25:30",
"metadata": {
"asn": "AS13335",
"category": "hosting",
"datacenter": "Cloudflare",
"destination_countries": ["US", "GB", "DE"],
"domain": "cloudflare.com",
"latitude": 37.7749,
"longitude": -122.4194,
"mobile": false,
"organization": "Cloudflare, Inc.",
"os": "Linux 3.11+",
"rdns": "one.one.one.one",
"rdns_validated": true,
"region": "California",
"sensor_count": 150,
"sensor_hits": 2500,
"single_destination": false,
"source_city": "San Francisco",
"source_country": "United States",
"source_country_code": "US"
},
"spoofable": false,
"tags": [
{
"category": "tool",
"created": "2023-01-15",
"cves": [],
"description": "HTTP scanner behavior detected",
"id": "web_scanner_http",
"intention": "benign",
"name": "Web Scanner (HTTP)",
"recommend_block": false,
"references": [],
"slug": "web-scanner-http",
"updated_at": "2023-09-01T12:00:00Z"
}
],
"tor": false,
"vpn": false,
"vpn_service": ""
},
"ip": "198.51.100.42"
}
```
## GreyNoise data structure
Business Service Intelligence
Business Service Intelligence helps identify whether an IP address belongs to a known business service (like CDNs, cloud providers, or other commercial services). This information can be crucial for filtering false positives and understanding the context of network traffic.
* `found`: whether the IP was found in GreyNoise's business service database
* `category`: the type of business service (e.g., CDN, hosting, cloud provider)
* `name`: the name of the business service (e.g., Cloudflare, AWS, Google)
* `description`: a description of the business service
* `explanation`: additional context about why this IP is associated with the service
* `last_updated`: timestamp of when this business service information was last updated
* `reference`: a URL reference for more information about the service
* `trust_level`: a numeric trust level indicating the reliability of the service (higher values indicate more trustworthy services)
Internet Scanner Intelligence
Internet Scanner Intelligence provides detailed information about IPs observed conducting internet-wide scanning or attack activity. This is the core threat intelligence data from GreyNoise.
* `found`: whether internet scanner intelligence data was found for the IP
* `first_seen`: the first date this IP was observed by GreyNoise
* `last_seen`: the last date this IP was observed by GreyNoise
* `last_seen_timestamp`: a detailed timestamp of the last observation
* `actor`: the threat actor or entity associated with the scanning activity
* `spoofable`: whether the observed traffic is easily spoofable
* `classification`: the classification of the IP (benign, malicious, or unknown)
* `cves`: an array of CVE identifiers associated with scanning activity from this IP
* `bot`: whether the IP is identified as a bot
* `vpn`: whether the IP is associated with a VPN service
* `vpn_service`: the name of the VPN service, if identified
* `tor`: whether the IP is a known Tor exit node
* `tags`: an array of behavioral tags describing the scanning activity (see Using GreyNoise tags in detections)
* `metadata`: detailed metadata about the IP including ASN, geolocation, organization, and scanning patterns
Metadata
The metadata object within Internet Scanner Intelligence provides detailed context about the scanning IP:
* `asn`: the Autonomous System Number
* `carrier`: the mobile carrier, if applicable
* `category`: the IP category (e.g., hosting, business, isp)
* `datacenter`: the datacenter provider, if applicable
* `destination_asns`: an array of ASNs targeted by scanning from this IP
* `destination_cities`: an array of cities targeted by scanning from this IP
* `destination_countries`: an array of countries targeted by scanning from this IP
* `destination_country_codes`: an array of country codes targeted by scanning from this IP
* `domain`: the domain associated with the IP
* `latitude` / `longitude`: geographic coordinates
* `mobile`: whether the IP is associated with mobile networks
* `organization`: the organization that owns the IP
* `os`: the detected operating system
* `rdns`: reverse DNS lookup result
* `rdns_parent`: the parent domain from reverse DNS
* `rdns_validated`: whether the reverse DNS has been validated
* `region`: the geographic region
* `sensor_count`: the number of GreyNoise sensors that observed this IP
* `sensor_hits`: the total number of times this IP was observed across all sensors
* `single_destination`: whether the IP targets only a single destination
* `source_city` / `source_country` / `source_country_code`: the source location information
Tags
Tags within Internet Scanner Intelligence represent specific behavioral patterns identified by GreyNoise:
* `id`: a unique identifier for the tag
* `name`: the display name of the tag
* `slug`: a URL-friendly identifier
* `category`: the tag category (e.g., activity, tool, worm)
* `description`: a detailed explanation of what this tag represents
* `intention`: the intent classification (benign, malicious, or unknown)
* `recommend_block`: whether GreyNoise recommends blocking traffic from IPs with this tag
* `created`: the date this tag was created
* `updated_at`: timestamp of the last update to this tag
* `cves`: an array of CVE identifiers associated with this tag
* `references`: external references or citations related to this tag
### `GreyNoise.API.V3` schema
The following is the Panther-managed `GreyNoise.API.V3` schema, representing how GreyNoise intelligence data is stored in Panther. See an event that has been parsed with this schema above.
```yaml
schema: GreyNoise.API.V3
description: GreyNoise Intelligence helps security teams filter out internet-wide scan and attack noise by identifying and labeling IPs conducting mass scanning, enabling faster, more accurate threat detection. We provide real-time, verifiable threat intelligence powered by the largest and most sophisticated internet sensor network.
referenceURL: https://docs.greynoise.io/docs/api-v3-response
fields:
- name: business_service_intelligence
description: Business service intelligence data about the IP, including category, description, explanation, trust level, and metadata about the business service associated with the IP address
type: object
fields:
- name: category
description: Category classification of the business service
type: string
- name: description
description: Description of the business service
type: string
- name: explanation
description: Detailed explanation about the business service intelligence
type: string
- name: found
description: Indicates whether business service intelligence data was found for the IP
type: boolean
- name: last_updated
description: Timestamp when the business service intelligence data was last updated
type: timestamp
timeFormats:
- rfc3339
- name: name
description: Name of the business service
type: string
- name: reference
description: Reference URL or identifier for the business service
type: string
- name: trust_level
description: Trust level score for the business service
type: bigint
- name: internet_scanner_intelligence
description: Internet scanner intelligence data about the IP, including actor information, bot detection, classification, CVEs, tags, VPN/Tor status, and metadata about the IP's scanning behavior and characteristics
type: object
fields:
- name: actor
description: Actor or organization associated with the scanning activity
type: string
- name: bot
description: Indicates whether the IP is identified as a bot
type: boolean
- name: classification
description: Classification of the IP's scanning behavior
type: string
- name: cves
description: List of Common Vulnerabilities and Exposures (CVEs) associated with the IP
type: array
element:
type: string
indicators:
- cve
- name: first_seen
description: Date when the IP was first seen by GreyNoise sensors
type: timestamp
timeFormats:
- '%Y-%m-%d'
- name: found
description: Indicates whether internet scanner intelligence data was found for the IP
type: boolean
- name: last_seen
description: Date when the IP was last seen by GreyNoise sensors
type: timestamp
timeFormats:
- '%Y-%m-%d'
- name: last_seen_timestamp
description: Timestamp when the IP was last seen by GreyNoise sensors
type: timestamp
timeFormats:
- '%Y-%m-%d %H:%M:%S'
isEventTime: true
- name: metadata
description: Geographic and network metadata about the IP address
type: object
fields:
- name: asn
description: Autonomous System Number (ASN) associated with the IP
type: string
- name: carrier
description: Carrier or ISP name associated with the IP
type: string
- name: category
description: Category classification of the IP
type: string
- name: datacenter
description: Datacenter name if the IP is hosted in a datacenter
type: string
- name: destination_asns
description: List of destination ASNs that the IP has been observed scanning
type: array
element:
type: string
- name: destination_cities
description: List of destination cities that the IP has been observed scanning
type: array
element:
type: string
- name: destination_countries
description: List of destination countries that the IP has been observed scanning
type: array
element:
type: string
- name: destination_country_codes
description: List of destination country codes that the IP has been observed scanning
type: array
element:
type: string
- name: domain
description: Domain name associated with the IP
type: string
indicators:
- domain
- name: latitude
description: Geographic latitude of the IP address
type: float
- name: longitude
description: Geographic longitude of the IP address
type: float
- name: mobile
description: Indicates whether the IP is associated with a mobile carrier
type: boolean
- name: organization
description: Organization name associated with the IP
type: string
- name: os
description: Operating system detected for the IP
type: string
- name: rdns
description: Reverse DNS (PTR) record for the IP address
type: string
- name: rdns_parent
description: Parent domain of the reverse DNS record
type: string
- name: rdns_validated
description: Indicates whether the reverse DNS record has been validated
type: boolean
- name: region
description: Geographic region of the IP address
type: string
- name: sensor_count
description: Number of GreyNoise sensors that have observed the IP
type: bigint
- name: sensor_hits
description: Total number of times the IP has been observed by GreyNoise sensors
type: bigint
- name: single_destination
description: Indicates whether the IP targets a single destination
type: boolean
- name: source_city
description: City where the IP is located
type: string
- name: source_country
description: Country where the IP is located
type: string
- name: source_country_code
description: ISO country code where the IP is located
type: string
- name: spoofable
description: Indicates whether the IP address is spoofable
type: boolean
- name: tags
description: List of tags describing the IP's behavior and characteristics
type: array
element:
type: object
fields:
- name: category
description: Category classification of the tag
type: string
- name: created
description: Date when the tag was created
type: timestamp
timeFormats:
- '%Y-%m-%d'
- name: cves
description: List of Common Vulnerabilities and Exposures (CVEs) associated with the tag
type: array
element:
type: string
indicators:
- cve
- name: description
description: Description of the tag
type: string
- name: id
description: Unique identifier for the tag
type: string
- name: intention
description: Intention classification of the tag (e.g., malicious, suspicious, unknown)
type: string
- name: name
description: Name of the tag
type: string
- name: recommend_block
description: Indicates whether blocking is recommended for IPs with this tag
type: boolean
- name: references
description: List of reference URLs or hostnames related to the tag
type: array
element:
type: string
indicators:
- hostname
- name: slug
description: URL-friendly identifier (slug) for the tag
type: string
- name: updated_at
description: Timestamp when the tag was last updated
type: timestamp
timeFormats:
- rfc3339
- name: tor
description: Indicates whether the IP is associated with the Tor network
type: boolean
- name: vpn
description: Indicates whether the IP is associated with a VPN service
type: boolean
- name: vpn_service
description: Name of the VPN service if the IP is associated with a VPN
type: string
- name: ip
required: true
description: The IP address being analyzed by GreyNoise
type: string
indicators:
- ip
```