About the connector
GreyNoise is a system that collects, analyzes, and labels omnidirectional Internet scan and attack activity.
This document provides information about the GreyNoise connector, which facilitates automated interactions, with a GreyNoise server using FortiSOAR™ playbooks. Add the GreyNoise connector as a step in FortiSOAR™ playbooks and perform automated investigative operations, such as performing a lookup for IP addresses and querying the GreyNoise GNQL API endpoint.
Version information
Connector Version: 2.0.0
Authored By: GreyNoise
Certified: No
Release Notes for version 2.0.0
The following enhancements have been made to the GreyNoise Connector in version 2.0.0:
- Rebuilt the GreyNoise connector to meet GreyNoise official standards using GreyNoise Python SDK.
- Added support for both Enterprise (Paid) and Community (Free) API Keys.
- Included IP lookups for Noise, RIOT, Quick, and Community endpoints.
- Included Full IP lookup that combines responses for consolidated output.
- Included GNQL searches and stats commands.
- Includes GreyNoise compromised device CIDR block monitoring using playbook scheduling.
- Included a basic playbook for IP enrichment using the GreyNoise Full IP Lookup command.
Installing the connector
From FortiSOAR™ 5.0.0 onwards, use the Connector Store to install the connector. For the detailed procedure to install a connector, click here.
You can also use the following yum command as a root user to install connectors from an SSH session:
yum install cyops-connector-greynoise
Prerequisites to configuring the connector
- You should know your API key type, i.e., Enterprise or Community and must have the API token that you will use to access GreyNoise's REST API to perform the operations.
- The FortiSOAR™ server should have outbound connectivity to port 443 on the GreyNoise server.
Configuring the connector
For the procedure to configure a connector, click here.
Configuration parameters
In FortiSOAR™, on the Connectors page, click the GreyNoise connector row (if you are in the Grid view on the Connectors page), and in the Configurations tab enter the required configuration details:
| Parameter |
Description |
| API Key Type |
API key type that you will use to access GreyNoise's REST APIs to perform the operations. You can choose between Enterprise or Community. |
| API Token |
API token that you will use to access GreyNoise's REST APIs to perform the operations. |
Actions supported by the connector
The following automated operations can be included in playbooks and you can also use the annotations to access operations from version 4.10.0 onwards:
| Function |
Description |
Annotation and Category |
| Lookup GreyNoise IP Context Information |
Performs a lookup for the specified IP address in the GreyNoise Context. |
ip_reputation
Investigation |
| Lookup GreyNoise IP Information (Noise, RIOT, Tags) |
Performs a lookup for the specified IP address in the GreyNoise Context and RIOT API endpoint, and also includes the expanded 'Tag' Metadata. |
ip_reputation
Investigation |
| Lookup GreyNoise IP RIOT Information |
Performs a lookup for the specified IP address in the GreyNoise RIOT API endpoint, |
ip_reputation
Investigation |
| Lookup GreyNoise IP Community Information |
Performs a lookup for the specified IP address in the GreyNoise Community API endpoint |
ip_reputation
Investigation |
| Lookup GreyNoise IP Quick Information |
Performs a lookup for the specified IP address in the GreyNoise Quick API endpoint |
ip_reputation
Investigation |
| GreyNoise GNQL Query |
Queries the GreyNoise GNQL API endpoint based on the query and other input parameters you have specified. |
query
Investigation |
| Stats Query |
Queries the GreyNoise GNQL Stats API endpoint based on the query and other input parameters you have specified. |
query
Investigation |
| Get All GreyNoise Tag Metadata |
Retrieves all the Tag Metadata from GreyNoise. |
query
Investigation |
| Get GreyNoise Tag Details |
Retrieves details of the specified Tag from GreyNoise. |
query
Investigation |
operation: Lookup GreyNoise IP Context Information
Input parameters
| Parameter |
Description |
| IP Address |
IP address that you want to lookup in the GreyNoise Context. |
Output
The output contains the following populated JSON schema:
{
"ip": "",
"seen": "",
"classification": "",
"first_seen": "",
"last_seen": "",
"actor": "",
"tags": "",
"spoofable": "",
"cve": "",
"vpn": "",
"vpn_service": "",
"metadata": "",
"raw_data": "",
"bot": ""
}
operation: Lookup GreyNoise IP Information (Noise, RIOT, Tags)
Input parameters
| Parameter |
Description |
| IP Address |
IP address that you want to lookup in the GreyNoise Context, RIOT API endpoint, and the expanded 'Tag' Metadata. |
Output
The output contains the following populated JSON schema:
{
"ip": "",
"seen": "",
"classification": "",
"first_seen": "",
"last_seen": "",
"actor": "",
"tags": "",
"spoofable": "",
"cve": "",
"vpn": "",
"vpn_service": "",
"metadata": "",
"raw_data": "",
"bot": ""
}
operation: Lookup GreyNoise IP RIOT Information
Input parameters
| Parameter |
Description |
| IP Address |
IP address that you want to lookup in the GreyNoise RIOT API endpoint. |
Output
The output contains the following populated JSON schema:
{
"ip": "",
"riot": "",
"category": "",
"name": "",
"description": "",
"explanation": "",
"last_updated": "",
"reference": "",
"trust_level": ""
}
operation: Lookup GreyNoise IP Community Information
Input parameters
| Parameter |
Description |
| IP Address |
IP address that you want to lookup in the GreyNoise Community API endpoint. |
Output
The output contains the following populated JSON schema:
{
"ip": "",
"noise": "",
"riot": "",
"classification": "",
"name": "",
"link": "",
"last_seen": "",
"message": ""
}
operation: Lookup GreyNoise IP Quick Information
Input parameters
| Parameter |
Description |
| IP Address |
IP address that you want to lookup in the GreyNoise Quick API endpoint. |
Output
The output contains the following populated JSON schema:
{
"ip": "",
"code": "",
"code_message": "",
"riot": "",
"noise": ""
}
operation: GreyNoise GNQL Query
Input parameters
| Parameter |
Description |
| Query |
Query that you want to use to search the GreyNoise GNQL API endpoint. |
| Max Results |
Maximum number of results, per page, that this operation should return. By default, this is set to 10. |
Output
The output contains the following populated JSON schema:
{
"complete": "",
"scroll": "",
"query": "",
"count": "",
"message": "",
"data": ""
}
operation: Stats Query
Input parameters
| Parameter |
Description |
| Query |
Query that you want to use to search the GreyNoise Stats API endpoint. |
Output
The output contains the following populated JSON schema:
{
"query": "",
"count": "",
"stats": ""
}
operation: Get All GreyNoise Tag Metadata
Input parameters
None.
Output
The output contains the following populated JSON schema:
{
"metadata": "",
"vpn_services": ""
}
operation: Get GreyNoise Tag Details
Input parameters
| Parameter |
Description |
| Tag Name |
Name of the 'Tag' whose details you want to retrieve from GreyNoise. |
Output
The output contains the following populated JSON schema:
{
"name": "",
"category": "",
"intention": "",
"description": "",
"references": "",
"recommend_block": "",
"cves": ""
}
Included playbooks
The Sample - GreyNoise - 2.0.0 playbook collection comes bundled with the GreyNoise connector. These playbooks contain steps using which you can perform all supported actions. You can see bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the GreyNoise connector.
- Fetch Alerts from GreyNoise
- Generate GreyNoise Record
- GreyNoise IP Full Lookup
Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection since the sample playbook collection gets deleted during connector upgrade and delete.
