Fortinet Document Library

Version:


Table of Contents

1.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 checking IP addresses for background noise, and performing a lookup for IP addresses.

Version information

Connector Version: 1.0.0

Authored By: Community

Certified: No

Installing the connector

From version 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 yum command to install connectors. Connectors provided by FortiSOAR™ are delivered using a FortiSOAR™ repository. Therefore, you must set up your FortiSOAR™ repository and run the yum command as a root user to install connectors:

yum install cyops-connector-greynoise

Prerequisites to configuring the connector

  • You must have the URL of the GreyNoise server to which you will connect and perform automated operations.
  • You must have the API token that you will use to access the GreyNoise's REST API to perform the operations.
  • To access the FortiSOAR™ UI, ensure that port 443 is open through the firewall for the FortiSOAR™ instance.

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
Server URL URL of the GreyNoise server to which you will connect and perform automated operations.
API Token API token that you will use to access the GreyNoise's REST API 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
IP Lookup Retrieves information for a specific IP address from GreyNoise based on the IP address you have specified. ip_lookup
Investigation
Check IP Checks whether a specific IP address is creating background noise on the Internet, i.e. whether the specified IP address has been observed scanning or attacking devices across the internet. This operation returns whether the specific IP address is creating any background noise on the Internet from GreyNoise based on the IP address you have specified. check_ip
Investigation
Check Multiple IPs Checks whether a list of specific IP addresses is creating background noise on the Internet, i.e. whether the specified IP addresses have been observed scanning or attacking devices across the internet. This operation returns whether the list of specific IP addresses is creating any background noise on the Internet from GreyNoise based on the list of the comma-separated IP addresses you have specified. check_multiple_ip
Investigation
Get Tag metadata Retrieves a list of tags and their corresponding metadata information from GreyNoise. get_tag_metadata
Investigation
Create Query Retrieves details for IP addresses from GreyNoise based on the query and other input parameters you have specified create_query
Investigation
Get Aggregate Statistics Retrieves aggregate statistics for organizations, actors, tags, countries, etc. from GreyNoise based on the query and other input parameters you have specified. get_aggregate_statistics
Investigation

operation: IP Lookup

Input parameters

Parameter Description
IP Address IP address whose details you want to retrieve from GreyNoise

Output

The output contains the following populated JSON schema:
{
     "actor": "",
     "last_seen": "",
     "classification": "",
     "metadata": {
         "organization": "",
         "os": "",
         "rdns": "",
         "country_code": "",
         "asn": "",
         "tor": "",
         "country": "",
         "city": "",
         "category": ""
     },
     "ip": "",
     "tags": [],
     "first_seen": "",
     "seen": "",
     "raw_data": {
         "ja3": [
             {
                 "port": "",
                 "fingerprint": ""
             }
         ],
         "scan": [
             {
                 "protocol": "",
                 "port": ""
             }
         ],
         "web": {
             "paths": [],
             "useragents": []
         }
     }
}

operation: Check IP

Input parameters

Parameter Description
IP Address IP address that you want to check on GreyNose for whether it is creating background noise on the Internet.

Output

The output contains the following populated JSON schema:
{
     "ip": "",
     "noise": "",
     "code": ""
}

operation: Check Multiple IPs

Input parameters

Parameter Description
IP Address Comma-separated list of IP addresses that you want to check on GreyNose for whether they are creating background noise on the Internet.

Output

The output contains the following populated JSON schema:
{
     "ip": "",
     "noise": "",
     "code": ""
}

operation: Get Tag metadata

Input parameters

None.

Output

The output contains the following populated JSON schema:
{
     "metadata": [
         {
             "description": "",
             "name": "",
             "intention": "",
             "category": "",
             "references": []
         }
     ]
}

operation: Create Query

Input parameters

Parameter Description
Query Query, which is a free-text search term, that you want to use to match applicable attributes (sub-string match) in GreyNoise and retrieve the matched records (IP addresses) from GreyNoise.
Size (Optional) Maximum number of results, per page, that this operation should return.
Scroll (Optional) Retrieves records of a next page from GreyNoise based on the scroll ID you have specified

Output

The output contains the following populated JSON schema:
{
     "scroll": "",
     "message": "",
     "count": "",
     "query": "",
     "complete": "",
     "data": [
         {
             "actor": "",
             "last_seen": "",
             "classification": "",
             "metadata": {
                 "organization": "",
                 "os": "",
                 "rdns": "",
                 "country_code": "",
                 "asn": "",
                 "tor": "",
                 "country": "",
                 "city": "",
                 "category": ""
             },
             "ip": "",
             "tags": [],
             "first_seen": "",
             "seen": "",
             "raw_data": {
                 "ja3": [
                     {
                         "port": "",
                         "fingerprint": ""
                     }
                 ],
                 "scan": [
                     {
                         "protocol": "",
                         "port": ""
                     }
                 ],
                 "web": {
                     "paths": [],
                     "useragents": []
                 }
             }
         }
     ]
}

operation: Get Aggregate Statistics

Input parameters

Parameter Description
Query Query, which is a free-text search term, that you want to use to match applicable attributes (sub-string match) in GreyNoise and retrieve the aggregate statistics from GreyNoise.
Count (Optional) Maximum number of records you want to fetch from GreyNoise.

Output

The output contains the following populated JSON schema:
{
     "stats": {
         "actors": [
             {
                 "actor": "",
                 "count": ""
             }
         ],
         "asn": [
             {
                 "asn": "",
                 "count": ""
             }
         ],
         "tags": [
             {
                 "tag": "",
                 "count": ""
             }
         ],
         "organizations": [
             {
                 "organization": "",
                 "count": ""
             }
         ],
         "operating_systems": [
             {
                 "operating_system": "",
                 "count": ""
             }
         ],
         "classifications": [
             {
                 "classification": "",
                 "count": ""
             }
         ],
         "categories": [
             {
                 "category": "",
                 "count": ""
             }
         ]
     },
     "count": "",
     "query": ""
}

Included playbooks

The Sample - GreyNoise - 1.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.

  • Check IP
  • Check Multiple IPs
  • Create Query
  • Get Aggregate Statistics
  • Get Tag metadata
  • IP 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 the 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 checking IP addresses for background noise, and performing a lookup for IP addresses.

Version information

Connector Version: 1.0.0

Authored By: Community

Certified: No

Installing the connector

From version 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 yum command to install connectors. Connectors provided by FortiSOAR™ are delivered using a FortiSOAR™ repository. Therefore, you must set up your FortiSOAR™ repository and run the yum command as a root user to install connectors:

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
Server URL URL of the GreyNoise server to which you will connect and perform automated operations.
API Token API token that you will use to access the GreyNoise's REST API 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
IP Lookup Retrieves information for a specific IP address from GreyNoise based on the IP address you have specified. ip_lookup
Investigation
Check IP Checks whether a specific IP address is creating background noise on the Internet, i.e. whether the specified IP address has been observed scanning or attacking devices across the internet. This operation returns whether the specific IP address is creating any background noise on the Internet from GreyNoise based on the IP address you have specified. check_ip
Investigation
Check Multiple IPs Checks whether a list of specific IP addresses is creating background noise on the Internet, i.e. whether the specified IP addresses have been observed scanning or attacking devices across the internet. This operation returns whether the list of specific IP addresses is creating any background noise on the Internet from GreyNoise based on the list of the comma-separated IP addresses you have specified. check_multiple_ip
Investigation
Get Tag metadata Retrieves a list of tags and their corresponding metadata information from GreyNoise. get_tag_metadata
Investigation
Create Query Retrieves details for IP addresses from GreyNoise based on the query and other input parameters you have specified create_query
Investigation
Get Aggregate Statistics Retrieves aggregate statistics for organizations, actors, tags, countries, etc. from GreyNoise based on the query and other input parameters you have specified. get_aggregate_statistics
Investigation

operation: IP Lookup

Input parameters

Parameter Description
IP Address IP address whose details you want to retrieve from GreyNoise

Output

The output contains the following populated JSON schema:
{
     "actor": "",
     "last_seen": "",
     "classification": "",
     "metadata": {
         "organization": "",
         "os": "",
         "rdns": "",
         "country_code": "",
         "asn": "",
         "tor": "",
         "country": "",
         "city": "",
         "category": ""
     },
     "ip": "",
     "tags": [],
     "first_seen": "",
     "seen": "",
     "raw_data": {
         "ja3": [
             {
                 "port": "",
                 "fingerprint": ""
             }
         ],
         "scan": [
             {
                 "protocol": "",
                 "port": ""
             }
         ],
         "web": {
             "paths": [],
             "useragents": []
         }
     }
}

operation: Check IP

Input parameters

Parameter Description
IP Address IP address that you want to check on GreyNose for whether it is creating background noise on the Internet.

Output

The output contains the following populated JSON schema:
{
     "ip": "",
     "noise": "",
     "code": ""
}

operation: Check Multiple IPs

Input parameters

Parameter Description
IP Address Comma-separated list of IP addresses that you want to check on GreyNose for whether they are creating background noise on the Internet.

Output

The output contains the following populated JSON schema:
{
     "ip": "",
     "noise": "",
     "code": ""
}

operation: Get Tag metadata

Input parameters

None.

Output

The output contains the following populated JSON schema:
{
     "metadata": [
         {
             "description": "",
             "name": "",
             "intention": "",
             "category": "",
             "references": []
         }
     ]
}

operation: Create Query

Input parameters

Parameter Description
Query Query, which is a free-text search term, that you want to use to match applicable attributes (sub-string match) in GreyNoise and retrieve the matched records (IP addresses) from GreyNoise.
Size (Optional) Maximum number of results, per page, that this operation should return.
Scroll (Optional) Retrieves records of a next page from GreyNoise based on the scroll ID you have specified

Output

The output contains the following populated JSON schema:
{
     "scroll": "",
     "message": "",
     "count": "",
     "query": "",
     "complete": "",
     "data": [
         {
             "actor": "",
             "last_seen": "",
             "classification": "",
             "metadata": {
                 "organization": "",
                 "os": "",
                 "rdns": "",
                 "country_code": "",
                 "asn": "",
                 "tor": "",
                 "country": "",
                 "city": "",
                 "category": ""
             },
             "ip": "",
             "tags": [],
             "first_seen": "",
             "seen": "",
             "raw_data": {
                 "ja3": [
                     {
                         "port": "",
                         "fingerprint": ""
                     }
                 ],
                 "scan": [
                     {
                         "protocol": "",
                         "port": ""
                     }
                 ],
                 "web": {
                     "paths": [],
                     "useragents": []
                 }
             }
         }
     ]
}

operation: Get Aggregate Statistics

Input parameters

Parameter Description
Query Query, which is a free-text search term, that you want to use to match applicable attributes (sub-string match) in GreyNoise and retrieve the aggregate statistics from GreyNoise.
Count (Optional) Maximum number of records you want to fetch from GreyNoise.

Output

The output contains the following populated JSON schema:
{
     "stats": {
         "actors": [
             {
                 "actor": "",
                 "count": ""
             }
         ],
         "asn": [
             {
                 "asn": "",
                 "count": ""
             }
         ],
         "tags": [
             {
                 "tag": "",
                 "count": ""
             }
         ],
         "organizations": [
             {
                 "organization": "",
                 "count": ""
             }
         ],
         "operating_systems": [
             {
                 "operating_system": "",
                 "count": ""
             }
         ],
         "classifications": [
             {
                 "classification": "",
                 "count": ""
             }
         ],
         "categories": [
             {
                 "category": "",
                 "count": ""
             }
         ]
     },
     "count": "",
     "query": ""
}

Included playbooks

The Sample - GreyNoise - 1.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 the connector upgrade and delete.