# GreyNoise Community Edition

## Description
This enrichment looks up IP addresses using the [GreyNoise Community API](https://docs.greynoise.io/docs/using-the-greynoise-community-api) and adds [the response data](https://docs.greynoise.io/reference/get_v3-community-ip) to your records. It provides an assortment of [intelligence](https://docs.greynoise.io/docs/using-the-greynoise-community-api#ip-lookup-via-community-api) including whether or not an IP has been observed scanning the internet recently and a [proprietary threat-level classification](https://docs.greynoise.io/docs/understanding-greynoise-classifications).

Compatible with all Monad tiers

## Prerequisites

1. Set up a [GreyNoise Visualizer account](https://docs.greynoise.io/docs/setting-up-an-account)
2. Generate an [API key](https://viz.greynoise.io/account/api-key) before using this enrichment.

<img
  src="/docs/img/greynoise/generate-api-key.png"
  className="m-3 rounded-xl"
/>

## Setup Instructions

1. Configure the _IP Address Path_ for your incoming records
2. Set the _Destination Path_ where enrichment results will be added to your records
3. Specify your GreyNoise Community _API Key_ using our Secrets system
4. Optionally configure the no-match response message

## Configuration Options

### Settings
| Setting | Type | Required | Default | Description |
|---------|------|----------|---------|-------------|
| ip_address_path | string | Yes | - | The JSON path to the IP address field in incoming records (e.g., "source.ip", "client_ip"). |
| destination_path | string | Yes | - | The JSON path where greynoise results will be added to the record (e.g., "greynoise", "enrichment.greynoise"). |
| no_match_response | string | No | `"no results found"` | Message returned when an IP address is not found in the database. |
| rate_limit_response | string | No | `"greynoise rate limit reached"` | Message returned when the provided Greynoise api key hits a rate limit. |
| error_on_rate_limit | boolean | No | false | Determines if rate limiting should cause an error (true) or return custom response (false) |

### Secrets
| Secret  | Type | Required | Description |
|---------|------|----------|------------ |
| api_key | string | Yes | The greynoise community api key for an account. |


## Output Format
The enrichment adds greynoise data for an IP Address into a specified json field. For successful lookups, the output contains Greynoise fields such as:

```json
{
  "classification": "unknown",
  "ip": "167.160.160.21",
  "last_seen": "1986-01-03T04:33:51Z",
  "link": "https://viz.greynoise.io/ip/167.160.160.21",
  "message": "Success",
  "name": "Pointdive",
  "noise": true,
  "riot": false
}
```

For IP addresses not found in the database or if the provided path errors, a structured response is returned: 

```json
{
  "join_path": "items[0].ipAddress",
  "message": "IP field doesn't exist or is empty in the incoming record",
  "code": "missing_ip"
}
```

## Error Handling
- **Missing IP field**: Record passed through unchanged `"missing_ip"`
- **IP not in database**: Returns structured response with code `"no_match"`
- **Database lookup failure**: Returns structured error with code `"lookup_failed"`

## Use Cases
- **Threat Detection**: Determine whether an ip address is malignant or not to focus your detections.

## Limitations
This should be used as a testing enrichment only as the [rate limits](https://docs.greynoise.io/docs/using-the-greynoise-community-api#http-code-429---daily-rate-limit-exceeded) for Greynoise are very low.