Fortinet Document Library

Version:


Table of Contents

2.0.0
Copy Link

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.

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:

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

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.

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.