About the connector
AlienVault Open Threat Exchange (OTX) is among our most useful threat intelligence tools. It is an open source of Indicators of Compromise (IOCs) supported by the community. It contributes “pulses” and each pulse contains a collection of IOCs targeted at a particular area.
This document provides information about the AlienVault-OTX connector, which facilitates automated interactions, with an AlienVault-OTX server using FortiSOAR™ playbooks. Add the AlienVault-OTX connector as a step in FortiSOAR™ playbooks and perform automated operations, such as retrieving details for an indicator, creating and retrieving details for a pulse, and running queries on the AlienVault-OTX server.
Version information
Connector Version: 1.0.0
Compatibility with FortiSOAR™ Versions: 4.10.0 and later
Authored By: Fortinet
Certified: Yes
Installing the connector
All connectors provided by FortiSOAR™ are delivered using a FortiSOAR™ repository. Therefore, you must set up your FortiSOAR™ repository and use the yum command to install connectors:
yum install cyops-connector-alienvault-otx
For the detailed procedure to install a connector, click here.
Prerequisites to configuring the connector
- You must have the URL of the AlienVault-OTX server to which you will connect and perform the automated operations and the API key to access that server.
- 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, select the AlienVault-OTX connector and click Configure to configure the following parameters:
| Parameter |
Description |
| Server Address |
Address of the AlienVault-OTX server to which you will connect and perform the automated operations. |
| API Key |
API key configured for your account to access the AlienVault-OTX server. |
| Verify SSL |
Specifies whether the SSL certificate for the server is to be verified or not.
By default, this option is set as True. |
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 FortiSOAR™ release 4.10.0 onwards:
| Function |
Description |
Annotation and Category |
| Create Pulse |
Create new pulse which contains a collection of IOCs targeted at a particular area. |
create_pulse
Investigation |
| Get IP Reputation |
Retrieves the reputation for a specified IP based on parameters such as, the IP address that you have specified. |
get_ip_reputation
Investigation |
| Get Domain Reputation |
Retrieves the reputation for a specified domain based on parameters such as, the domain name that you have specified. |
get_domain_reputation
Investigation |
| Get URL Reputation |
Retrieves the reputation for a specified URL based on the URL that you have specified. |
get_url_reputation
Investigation |
| Get File Reputation |
Retrieves the reputation for a specified file based on parameters such as, the filehash that you have specified. |
get_file_reputation
Investigation |
| Get Hostname Reputation |
Retrieves the reputation for a specified host based on parameters such as, the hostname that you have specified. |
get_hostname_reputation
Investigation |
| Get All Indicators |
Retrieves a list of all indicators based on various parameters such as indicator type and value that you have specified. |
get_indicators
Investigation |
| Get Pulse Indicators |
Retrieves a list of all indicators based on the pulse ID that you have specified. |
get_indicators
Investigation |
| Get Pulse Details |
Retrieves details about a pulse based on the pulse ID that you have specified. |
get_pulse
Investigation |
| Get Related Pulses |
Retrieves a list of pulses that share an indicator with the pulse that you have specified using the pulse ID. |
get_pulses
Investigation |
| Get Subscribed Pulses |
Retrieves a list of all subscribed pulses based on various parameters such as datetime that you have specified.. |
get_pulses
Investigation |
| Run Query |
Runs a query that you have specified and fetches data from your AlienVault-OTX instance, based on the input filters. |
run_query
Investigation |
| Search Pulses |
Searches for pulses that match the text that you have specified in the input parameters. |
search_pulse
Investigation |
| Subscribe to Pulse |
Subscribes to a particular pulse based on the pulse ID that you have specified. |
subscribe_pulse
Investigation |
| Unsubscribe from Pulse |
Unsubscribes from a particular pulse based on the pulse ID that you have specified. |
unsubscribe_pulse
Investigation |
| User Actions |
Allows you to perform actions, such as follow, subscribe, etc for a specified user on the AlienVault-OTX server based on the username that you have specified. |
|
operation: Create Pulse
Input parameters
| Parameter |
Description |
| Name |
Name of the pulse that you want to create. |
| Description |
(Optional) Brief description of the pulse that you want to create and the threat it addresses. |
| Indicators |
(Optional) List of indicators that must be in the dict (dictionary format) and have a Key-Valuepair. Every object in the list must have at least the following three fields:
{“type”: “”, “indicator”: “”, “description”: “”} |
| Tags (CSV/List Format) |
(Optional) List of tags that categorize the pulse that you want to create. For example, malware, phishing, hacking, etc. |
| References (CSV/List Format) |
(Optional) List of external references to associate with the pulse that you want to create. |
| Public |
Select this field to allow other users to see or subscribe to the pulse that you want to create.
By default, this option is set as True. |
Output
The JSON output contains all the details for the newly created pulse on the AlienVault-OTX server.
Following image displays a sample output:
operation: Get IP Reputation
Input parameters
| Parameter |
Description |
| Type |
Type of IP for which you want to retrieve reputation from AlienVault-OTX. Choose between IPv4 or IPv6. |
| IP Address |
IP address for which you want to retrieve reputation from AlienVault-OTX. |
Output
The JSON output retrieves the reputation of the IP address you have specified from the AlienVault-OTX server.
Following image displays a sample output:
operation: Get Domain Reputation
Input parameters
| Parameter |
Description |
| Domain |
Name of the domain for which you want to retrieve reputation from AlienVault-OTX. |
| Section |
(Optional) Section of the indicator, domain in this case, whose details you want to retrieve from AlienVault-OTX.
Choose from the following sections: General, Geo, Malware, URL List, Passive DNS, or Whois. For more information of the sections option, see https://otx.alienvault.com/api. |
Output
The JSON output retrieves the reputation of the domain name you have specified from the AlienVault-OTX server.
Following image displays a sample output:
operation: Get URL Reputation
Input parameters
| Parameter |
Description |
| URL |
URL for which you want to retrieve reputation from AlienVault-OTX. |
Output
The JSON output retrieves the reputation of the URL you have specified from the AlienVault-OTX server.
Following image displays a sample output:
operation: Get File Reputation
Input parameters
| Parameter |
Description |
| Filehash Type |
Type of File for which you want to retrieve reputation from AlienVault-OTX. Choose between FileHash-MD5, FileHash-SHA1, or FileHash-SHA256. |
| Filehash |
Value of the filehash for which you want to retrieve reputation from AlienVault-OTX. |
Output
The JSON output retrieves the reputation of the filehash you have specified from the AlienVault-OTX server.
Following image displays a sample output:
operation: Get Hostname Reputation
Input parameters
| Parameter |
Description |
| Hostname |
Name of the host for which you want to retrieve reputation from AlienVault-OTX. |
| Section |
(Optional) Section of the indicator, the hostname in this case, whose details you want to retrieve from AlienVault-OTX.
Choose from the following sections: General, Geo, Malware, URL List, or Passive DNS. For more information about the sections option, see https://otx.alienvault.com/api. |
Output
The JSON output retrieves the reputation of the hostname you have specified from the AlienVault-OTX server.
Following image displays a sample output:
operation: Get All Indicators
Input parameters
| Parameter |
Description |
| Indicator Type |
(Optional) Type of indicator whose details you want to retrieve from AlienVault-OTX.
Choose from the following indicator types: IPv4, IPv6, CIDR, Domain, Hostname, URL, URI, Email, CVE, FileHash-MD5, FileHash-SHA1, FileHash-SHA256, FileHash-IMPHASH, FileHash-PEHASH, FilePath, or Mutex. |
| Number Of Records |
(Optional) Number of records that the operation should include per page. |
| Page Number |
(Optional) Page number from which you want to retrieve records. |
| From (Eg 2017-01-01T12:35:00+00:00) |
(Optional) Datetime from which you want to retrieve indicators. The datetime must be in the ISO format (UTC). If you specify the datetime then only those indicators that are created or modified later then the specified datetime are retrieved. |
| Export in JSON |
Select this option to export the complete result in the JSON format and save the result in the Attachment module in FortiSOAR™.
By default, this option is set as True. |
Output
The JSON output retrieves a list of all the indicators you have specified, based on the input parameters, from the AlienVault-OTX server.
Following image displays a sample output, when the Export in JSON option is selected (flag is set to True):
Following image displays a sample output, when the Export in JSON option is cleared (flag is set to False):
operation: Get Pulse Indicators
Input parameters
| Parameter |
Description |
| Pulse ID |
ID of the pulse based on which you want to retrieve the list of all indicators from AlienVault-OTX. |
Output
The JSON output retrieves a list of all the indicators based on the pulse ID that you have specified.
Following image displays a sample output:
operation: Get Pulse Details
Input parameters
| Parameter |
Description |
| Pulse ID |
ID of pulse whose details you want to retrieve from AlienVault-OTX. |
Output
The JSON output retrieves the details of the pulse based on the pulse ID that you have specified.
Following image displays a sample output:
operation: Get Related Pulses
Input parameters
| Parameter |
Description |
| Pulse ID |
ID of pulse based on which you want to retrieve related pulses, i.e. pulses that share an indicator, from AlienVault-OTX. |
| Page Number |
(Optional) Page number from which you want to retrieve records. |
Output
The JSON output retrieves a list of pulses that share an indicator with the pulse that you have specified using its pulse ID.
Following image displays a sample output:
operation: Get Subscribed Pulses
Input parameters
| Parameter |
Description |
| Number of records |
(Optional) Number of records that the operation should include per page. |
| Page Number |
(Optional) Page number from which you want to retrieve records. |
| From (Eg 2017-01-01T12:35:00+00:00) |
(Optional) Datetime from which you want to retrieve pulses. The datetime must be in the ISO format (UTC). If you specify the datetime then only those pulses that are created or modified later then the specified datetime are retrieved. |
Output
The JSON output retrieves a list of all the pulses you have subscribed to and which you have specified, based on the input parameters, from the AlienVault-OTX server.
Following image displays a sample output:
operation: Run Query
Input parameters
Output
The JSON output retrieves the data from your AlienVault-OTX instance, based on the input query you have specified.
Following image displays a sample output:
operation: Search Pulses
Input parameters
| Parameter |
Description |
| Text |
Pulses that you want to search for on AlienVault-OTX |
| Number of Records |
(Optional) Number of records that the operation should include per page. |
| Page Number |
(Optional) Page number from which you want to retrieve records. |
Output
The JSON output retrieves a list of all the pulses that match the text that you have specified in the input parameters, from the AlienVault-OTX server.
Following image displays a sample output:
operation: Subscribe to Pulse
Input parameters
| Parameter |
Description |
| Pulse ID |
ID of pulse to which you want to subscribe. |
Output
The JSON output returns a Success message if you could successfully subscribe to the pulse you have specified using the pulse ID or an Error message containing the reason for failure.
Following image displays a sample output:
operation: Unsubscribe from Pulse
Input parameters
| Parameter |
Description |
| Pulse ID |
ID of pulse from which you want to unsubscribe. |
Output
The JSON output returns a Success message if you could successfully unsubscribe from the pulse you have specified using the pulse ID or an Error message containing the reason for failure.
Following image displays a sample output:
operation: User Actions
Input parameters
| Parameter |
Description |
| Username |
Name of the user on whom you want to perform the selected action. |
| Action |
Action that you want to perform on the select user. Choose from the following actions: Subscribe, Unsubscribe, Follow, or Unfollow. |
Output
The JSON output returns a Success message if you could successfully perform the selected action on the selected user or an Error message containing the reason for failure.
Following image displays a sample output:
Included playbooks
The Sample-AlienVault-OTX-1.0.0 playbook collection comes bundled with the AlienVault-OTX connector. This playbook contains steps using which you can perform all supported actions. You can see the bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the AlienVault-OTX connector.
- Create Pulse
- Get All Indicators
- Get Domain Reputation
- Get File Reputation
- Get Hostname Reputation
- Get IP Reputation
- Get Pulse Details
- Get Pulse Indicators
- Get Related Pulses
- Get Subscribed Pulses
- Get URL Reputation
- Run Query
- Search Pulses
- Subscribe to Pulse
- Unsubscribe from Pulse
- User Actions
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.
