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.
