Fortinet Document Library

Version:


Table of Contents

AlienVault USM Central

1.0.1
Copy Link

About the connector

MSSPs and MSPs that use the AlienVault Unified Security Management platform to provide security monitoring services to their end customers can collect and investigate alarms within AlienValut USM Central.

This document provides information about the AlienValut USM Central connector, which facilitates automated interactions, with AlienValut USM Central server using FortiSOAR™ playbooks. Add the AlienValut USM Central connector as a step in FortiSOAR™ playbooks and perform automated operations, such as searching for alarms in AlienValut USM Central, or retrieving details of specific alarms from AlienValut USM Central.

Version information

Connector Version: 1.0.1

Authored By: Fortinet

Certified: No

Release Notes for version 1.0.1

Following enhancements have been made to the AlienValut USM Central connector in version 1.0.1:

  • Fixed the authentication issue which used to display the connector as "Disconnected" even for a valid configuration. Now, the connector that has a valid configuration will display as "Available".

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-alienvault-usm-central

Prerequisites to configuring the connector

  • You must have the URL of Alienvault USM Central server to which you will connect and perform automated operations and credentials (username-password pair) 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, click the Alienvault USM Central 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 Address of AlienVault USM server to which you will connect and perform automated operations.
Username Username to access AlienVault USM server to which you will connect and perform automated operations.
Password Password to access AlienVault USM server to which you will connect and perform automated operations.
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 versuion 4.10.0 onwards:

Function Description Annotation and Category
Search Alarms Searches for all alarms or specific alarms in the AlienVault USM Central server based on the input parameters you have specified. search_alarms
Investigation
Get Alarm Details Retrieves details of an alarm from AlienVault USM Central based on the alarm ID (UUID) you have specified. get_alarm_details
Investigation
Search Assets Searches for all assets or specific assets in the AlienVault USM Central server based on the input parameters you have specified. search_assets
Investigation
Get Deployments Retrieve all deployments from AlienVault USM Central. get_deployments
Investigation

operation: Search Alarms

Input parameters

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list is returned.

Parameter Description
Page Page number (zero-based) from which you want the operation to return results of the operation.
Number of Results to Return Maximum number of results per page, that this operation should return.
Sort Order to sort the results returned from AlienVault USM Central. For example, timestamp_occured, asc, etc.
Status Status based on which you want to search for alarms in AlienVault USM Central.
Suppressed Select this option to filter alarms by the suppressed flag.
Priority Label Priority Label based on which you want to search for alarms in AlienVault USM Central.
After Time Timestamp based on which you will filter results to include only those alarms that occurred after the specified timestamp.
Before Time Timestamp based on which you will filter results to include only those alarms that occurred before the specified timestamp.

Output

The output contains the following populated JSON schema:
{
     "results": [
         {
             "alarm": {
                 "alarm_labels": [],
                 "priority_label": "",
                 "app_id": "",
                 "app_type": "",
                 "priority": "",
                 "destination_name": "",
                 "timestamp_received": "",
                 "error_message": "",
                 "source_username": "",
                 "alarm_source_asset_ids": [],
                 "authentication_type": "",
                 "uuid": "",
                 "alarm_sensor_sources": [],
                 "highlight_fields": [],
                 "transient": "",
                 "has_alarm": "",
                 "sensor_uuid": "",
                 "alarm_destination_zones": [],
                 "alarm_destination_names": [],
                 "event_name": "",
                 "number_of_events": "",
                 "source_asset_id": "",
                 "source_name": "",
                 "packet_type": "",
                 "needs_enrichment": "",
                 "rule_method": "",
                 "alarm_destinations": [],
                 "rule_id": "",
                 "status": "",
                 "timestamp_occured": "",
                 "rule_intent": "",
                 "event_action": "",
                 "alarm_source_names": [],
                 "rule_strategy": "",
                 "suppressed": "",
                 "event_type": "",
                 "packet_data": [],
                 "rule_dictionary": "",
                 "alarm_sources": []
             },
             "events": [
                 {
                     "request_user_agent": "",
                     "was_guessed": "",
                     "timestamp_received_iso8601": "",
                     "destination_address": "",
                     "error_message": "",
                     "plugin_device_type": "",
                     "destination_infrastructure_type": "",
                     "highlight_fields": [],
                     "source_userid": "",
                     "event_description": "",
                     "destination_hostname": "",
                     "received_from": "",
                     "plugin_version": "",
                     "source_name": "",
                     "packet_type": "",
                     "was_fuzzied": "",
                     "needs_enrichment": "",
                     "source_fqdn": "",
                     "customfield_0": "",
                     "timestamp_occured_iso8601": "",
                     "has_alarm": "",
                     "event_description_url": "",
                     "plugin": "",
                     "uuid": "",
                     "source_canonical": "",
                     "source_address": "",
                     "app_id": "",
                     "app_type": "",
                     "destination_name": "",
                     "timestamp_received": "",
                     "source_username": "",
                     "source_hostname": "",
                     "account_name": "",
                     "app_name": "",
                     "rep_device_rule_id": "",
                     "used_hint": "",
                     "transient": "",
                     "destination_canonical": "",
                     "sensor_uuid": "",
                     "authentication_type": "",
                     "event_name": "",
                     "rep_device_version": "",
                     "account_id": "",
                     "plugin_device": "",
                     "destination_infrastructure_name": "",
                     "log": "",
                     "access_control_outcome": "",
                     "destination_userid": "",
                     "sensor_name": "",
                     "timestamp_occured": "",
                     "event_action": "",
                     "destination_zone": "",
                     "error_code": "",
                     "suppressed": "",
                     "event_type": "",
                     "customheader_0": ""
                 }
             ],
             "tenantId": "",
             "assets": [
                 {
                     "country": "",
                     "fqdn": "",
                     "id": "",
                     "latitude": "",
                     "longitude": "",
                     "ip_addresses": [],
                     "operating_system": "",
                     "url": "",
                     "name": ""
                 }
             ],
             "timestamp": ""
         }
     ],
     "total": ""
}

operation: Get Alarm Details

Input parameters

Parameter Description
Alarm ID ID of the alarm whose details you want to retrieve from AlientValut USM Central.

Output

The output contains the following populated JSON schema:
{
     "alarm": {
         "alarm_labels": [],
         "priority_label": "",
         "app_id": "",
         "app_type": "",
         "priority": "",
         "destination_name": "",
         "timestamp_received": "",
         "error_message": "",
         "source_username": "",
         "alarm_source_asset_ids": [],
         "authentication_type": "",
         "uuid": "",
         "alarm_sensor_sources": [],
         "highlight_fields": [],
         "transient": "",
         "has_alarm": "",
         "sensor_uuid": "",
         "alarm_destination_zones": [],
         "alarm_destination_names": [],
         "event_name": "",
         "number_of_events": "",
         "source_asset_id": "",
         "source_name": "",
         "packet_type": "",
         "needs_enrichment": "",
         "rule_method": "",
         "alarm_destinations": [],
         "rule_id": "",
         "status": "",
         "timestamp_occured": "",
         "rule_intent": "",
         "event_action": "",
         "alarm_source_names": [],
         "rule_strategy": "",
         "suppressed": "",
         "event_type": "",
         "packet_data": [],
         "rule_dictionary": "",
         "alarm_sources": []
     },
     "events": [
         {
             "request_user_agent": "",
             "was_guessed": "",
             "timestamp_received_iso8601": "",
             "destination_address": "",
             "error_message": "",
             "plugin_device_type": "",
             "destination_infrastructure_type": "",
             "highlight_fields": [],
             "source_userid": "",
             "event_description": "",
             "destination_hostname": "",
             "received_from": "",
             "plugin_version": "",
             "source_name": "",
             "packet_type": "",
             "was_fuzzied": "",
             "needs_enrichment": "",
             "source_fqdn": "",
             "customfield_0": "",
             "timestamp_occured_iso8601": "",
             "has_alarm": "",
             "event_description_url": "",
             "plugin": "",
             "uuid": "",
             "source_canonical": "",
             "source_address": "",
             "app_id": "",
             "app_type": "",
             "destination_name": "",
             "timestamp_received": "",
             "source_username": "",
             "source_hostname": "",
             "account_name": "",
             "app_name": "",
             "rep_device_rule_id": "",
             "used_hint": "",
             "transient": "",
             "destination_canonical": "",
             "sensor_uuid": "",
             "authentication_type": "",
             "event_name": "",
      nbsp;       "source_asset_id": "",
             "rep_device_version": "",
             "account_id": "",
             "plugin_device": "",
             "destination_infrastructure_name": "",
             "log": "",
             "access_control_outcome": "",
             "destination_userid": "",
             "sensor_name": "",
             "timestamp_occured": "",
             "event_action": "",
             "destination_zone": "",
             "error_code": "",
             "suppressed": "",
             "event_type": "",
             "customheader_0": ""
         }
     ],
     "tenantId": "",
     "assets": [
         {
             "country": "",
             "fqdn": "",
             "id": "",
             "latitude": "",
             "longitude": "",
             "ip_addresses": [],
             "operating_system": "",
             "url": "",
             "name": ""
         }
     ],
     "timestamp": ""
}

operation: Search Assets

Input parameters

Parameter Description
Page Page number (zero-based) from which you want the operation to return results of the operation.
Number of Results to Return Maximum number of results per page, that this operation should return.
Sort Order to sort the results returned from AlienVault USM Central. For example, timestamp_occured, asc, etc.
After Time Timestamp based on which you will filter results to include only those alarms that occurred after the specified timestamp.
Before Time Timestamp based on which you will filter results to include only those alarms that occurred before the specified timestamp.

Output

The output contains the following populated JSON schema:
{
     "results": [
         {
             "asset": {
                 "hostname": "",
                 "assetOriginType": "",
                 "configurationCount": "",
                 "deviceType": "",
                 "knownAsset": "",
                 "name": "",
                 "externalId": "",
                 "id": "",
                 "pci": "",
                 "rootDeviceType": "",
                 "alarmCount": "",
                 "assetOriginName": "",
                 "hipaa": "",
                 "dateUpdated": "",
                 "logo": "",
                 "assetOriginUUID": "",
                 "nmapExcludeFromScan": "",
                 "operatingSystemSource": "",
                 "region": "",
                 "dateCreated": "",
                 "operatingSystem": "",
                 "eventCount": "",
                 "dateFound": "",
                 "powerShellVersion": "",
                 "vulnerabilityCount": ""
             },
             "tenantId": "",
             "timestamp": ""
         }
     ],
     "total": ""
}

operation: Get Deployments

Input parameters

None.

Output

The output contains the following populated JSON schema:
{
     "authorized": "",
     "type": "",
     "id": "",
     "displayName": "",
     "connectionStatus": "",
     "name": "",
     "joinedSince": ""
}

Included playbooks

The Sample - AlienVault USM Central - 1.0.1 playbook collection comes bundled with the Alienvault USM Central 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 Alienvault USM Central connector.

  • Get Alarm Details
  • Get Deployments
  • Search Alarms
  • Search Assets

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

MSSPs and MSPs that use the AlienVault Unified Security Management platform to provide security monitoring services to their end customers can collect and investigate alarms within AlienValut USM Central.

This document provides information about the AlienValut USM Central connector, which facilitates automated interactions, with AlienValut USM Central server using FortiSOAR™ playbooks. Add the AlienValut USM Central connector as a step in FortiSOAR™ playbooks and perform automated operations, such as searching for alarms in AlienValut USM Central, or retrieving details of specific alarms from AlienValut USM Central.

Version information

Connector Version: 1.0.1

Authored By: Fortinet

Certified: No

Release Notes for version 1.0.1

Following enhancements have been made to the AlienValut USM Central connector in version 1.0.1:

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-alienvault-usm-central

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 Alienvault USM Central 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 Address of AlienVault USM server to which you will connect and perform automated operations.
Username Username to access AlienVault USM server to which you will connect and perform automated operations.
Password Password to access AlienVault USM server to which you will connect and perform automated operations.
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 versuion 4.10.0 onwards:

Function Description Annotation and Category
Search Alarms Searches for all alarms or specific alarms in the AlienVault USM Central server based on the input parameters you have specified. search_alarms
Investigation
Get Alarm Details Retrieves details of an alarm from AlienVault USM Central based on the alarm ID (UUID) you have specified. get_alarm_details
Investigation
Search Assets Searches for all assets or specific assets in the AlienVault USM Central server based on the input parameters you have specified. search_assets
Investigation
Get Deployments Retrieve all deployments from AlienVault USM Central. get_deployments
Investigation

operation: Search Alarms

Input parameters

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list is returned.

Parameter Description
Page Page number (zero-based) from which you want the operation to return results of the operation.
Number of Results to Return Maximum number of results per page, that this operation should return.
Sort Order to sort the results returned from AlienVault USM Central. For example, timestamp_occured, asc, etc.
Status Status based on which you want to search for alarms in AlienVault USM Central.
Suppressed Select this option to filter alarms by the suppressed flag.
Priority Label Priority Label based on which you want to search for alarms in AlienVault USM Central.
After Time Timestamp based on which you will filter results to include only those alarms that occurred after the specified timestamp.
Before Time Timestamp based on which you will filter results to include only those alarms that occurred before the specified timestamp.

Output

The output contains the following populated JSON schema:
{
     "results": [
         {
             "alarm": {
                 "alarm_labels": [],
                 "priority_label": "",
                 "app_id": "",
                 "app_type": "",
                 "priority": "",
                 "destination_name": "",
                 "timestamp_received": "",
                 "error_message": "",
                 "source_username": "",
                 "alarm_source_asset_ids": [],
                 "authentication_type": "",
                 "uuid": "",
                 "alarm_sensor_sources": [],
                 "highlight_fields": [],
                 "transient": "",
                 "has_alarm": "",
                 "sensor_uuid": "",
                 "alarm_destination_zones": [],
                 "alarm_destination_names": [],
                 "event_name": "",
                 "number_of_events": "",
                 "source_asset_id": "",
                 "source_name": "",
                 "packet_type": "",
                 "needs_enrichment": "",
                 "rule_method": "",
                 "alarm_destinations": [],
                 "rule_id": "",
                 "status": "",
                 "timestamp_occured": "",
                 "rule_intent": "",
                 "event_action": "",
                 "alarm_source_names": [],
                 "rule_strategy": "",
                 "suppressed": "",
                 "event_type": "",
                 "packet_data": [],
                 "rule_dictionary": "",
                 "alarm_sources": []
             },
             "events": [
                 {
                     "request_user_agent": "",
                     "was_guessed": "",
                     "timestamp_received_iso8601": "",
                     "destination_address": "",
                     "error_message": "",
                     "plugin_device_type": "",
                     "destination_infrastructure_type": "",
                     "highlight_fields": [],
                     "source_userid": "",
                     "event_description": "",
                     "destination_hostname": "",
                     "received_from": "",
                     "plugin_version": "",
                     "source_name": "",
                     "packet_type": "",
                     "was_fuzzied": "",
                     "needs_enrichment": "",
                     "source_fqdn": "",
                     "customfield_0": "",
                     "timestamp_occured_iso8601": "",
                     "has_alarm": "",
                     "event_description_url": "",
                     "plugin": "",
                     "uuid": "",
                     "source_canonical": "",
                     "source_address": "",
                     "app_id": "",
                     "app_type": "",
                     "destination_name": "",
                     "timestamp_received": "",
                     "source_username": "",
                     "source_hostname": "",
                     "account_name": "",
                     "app_name": "",
                     "rep_device_rule_id": "",
                     "used_hint": "",
                     "transient": "",
                     "destination_canonical": "",
                     "sensor_uuid": "",
                     "authentication_type": "",
                     "event_name": "",
                     "rep_device_version": "",
                     "account_id": "",
                     "plugin_device": "",
                     "destination_infrastructure_name": "",
                     "log": "",
                     "access_control_outcome": "",
                     "destination_userid": "",
                     "sensor_name": "",
                     "timestamp_occured": "",
                     "event_action": "",
                     "destination_zone": "",
                     "error_code": "",
                     "suppressed": "",
                     "event_type": "",
                     "customheader_0": ""
                 }
             ],
             "tenantId": "",
             "assets": [
                 {
                     "country": "",
                     "fqdn": "",
                     "id": "",
                     "latitude": "",
                     "longitude": "",
                     "ip_addresses": [],
                     "operating_system": "",
                     "url": "",
                     "name": ""
                 }
             ],
             "timestamp": ""
         }
     ],
     "total": ""
}

operation: Get Alarm Details

Input parameters

Parameter Description
Alarm ID ID of the alarm whose details you want to retrieve from AlientValut USM Central.

Output

The output contains the following populated JSON schema:
{
     "alarm": {
         "alarm_labels": [],
         "priority_label": "",
         "app_id": "",
         "app_type": "",
         "priority": "",
         "destination_name": "",
         "timestamp_received": "",
         "error_message": "",
         "source_username": "",
         "alarm_source_asset_ids": [],
         "authentication_type": "",
         "uuid": "",
         "alarm_sensor_sources": [],
         "highlight_fields": [],
         "transient": "",
         "has_alarm": "",
         "sensor_uuid": "",
         "alarm_destination_zones": [],
         "alarm_destination_names": [],
         "event_name": "",
         "number_of_events": "",
         "source_asset_id": "",
         "source_name": "",
         "packet_type": "",
         "needs_enrichment": "",
         "rule_method": "",
         "alarm_destinations": [],
         "rule_id": "",
         "status": "",
         "timestamp_occured": "",
         "rule_intent": "",
         "event_action": "",
         "alarm_source_names": [],
         "rule_strategy": "",
         "suppressed": "",
         "event_type": "",
         "packet_data": [],
         "rule_dictionary": "",
         "alarm_sources": []
     },
     "events": [
         {
             "request_user_agent": "",
             "was_guessed": "",
             "timestamp_received_iso8601": "",
             "destination_address": "",
             "error_message": "",
             "plugin_device_type": "",
             "destination_infrastructure_type": "",
             "highlight_fields": [],
             "source_userid": "",
             "event_description": "",
             "destination_hostname": "",
             "received_from": "",
             "plugin_version": "",
             "source_name": "",
             "packet_type": "",
             "was_fuzzied": "",
             "needs_enrichment": "",
             "source_fqdn": "",
             "customfield_0": "",
             "timestamp_occured_iso8601": "",
             "has_alarm": "",
             "event_description_url": "",
             "plugin": "",
             "uuid": "",
             "source_canonical": "",
             "source_address": "",
             "app_id": "",
             "app_type": "",
             "destination_name": "",
             "timestamp_received": "",
             "source_username": "",
             "source_hostname": "",
             "account_name": "",
             "app_name": "",
             "rep_device_rule_id": "",
             "used_hint": "",
             "transient": "",
             "destination_canonical": "",
             "sensor_uuid": "",
             "authentication_type": "",
             "event_name": "",
      nbsp;       "source_asset_id": "",
             "rep_device_version": "",
             "account_id": "",
             "plugin_device": "",
             "destination_infrastructure_name": "",
             "log": "",
             "access_control_outcome": "",
             "destination_userid": "",
             "sensor_name": "",
             "timestamp_occured": "",
             "event_action": "",
             "destination_zone": "",
             "error_code": "",
             "suppressed": "",
             "event_type": "",
             "customheader_0": ""
         }
     ],
     "tenantId": "",
     "assets": [
         {
             "country": "",
             "fqdn": "",
             "id": "",
             "latitude": "",
             "longitude": "",
             "ip_addresses": [],
             "operating_system": "",
             "url": "",
             "name": ""
         }
     ],
     "timestamp": ""
}

operation: Search Assets

Input parameters

Parameter Description
Page Page number (zero-based) from which you want the operation to return results of the operation.
Number of Results to Return Maximum number of results per page, that this operation should return.
Sort Order to sort the results returned from AlienVault USM Central. For example, timestamp_occured, asc, etc.
After Time Timestamp based on which you will filter results to include only those alarms that occurred after the specified timestamp.
Before Time Timestamp based on which you will filter results to include only those alarms that occurred before the specified timestamp.

Output

The output contains the following populated JSON schema:
{
     "results": [
         {
             "asset": {
                 "hostname": "",
                 "assetOriginType": "",
                 "configurationCount": "",
                 "deviceType": "",
                 "knownAsset": "",
                 "name": "",
                 "externalId": "",
                 "id": "",
                 "pci": "",
                 "rootDeviceType": "",
                 "alarmCount": "",
                 "assetOriginName": "",
                 "hipaa": "",
                 "dateUpdated": "",
                 "logo": "",
                 "assetOriginUUID": "",
                 "nmapExcludeFromScan": "",
                 "operatingSystemSource": "",
                 "region": "",
                 "dateCreated": "",
                 "operatingSystem": "",
                 "eventCount": "",
                 "dateFound": "",
                 "powerShellVersion": "",
                 "vulnerabilityCount": ""
             },
             "tenantId": "",
             "timestamp": ""
         }
     ],
     "total": ""
}

operation: Get Deployments

Input parameters

None.

Output

The output contains the following populated JSON schema:
{
     "authorized": "",
     "type": "",
     "id": "",
     "displayName": "",
     "connectionStatus": "",
     "name": "",
     "joinedSince": ""
}

Included playbooks

The Sample - AlienVault USM Central - 1.0.1 playbook collection comes bundled with the Alienvault USM Central 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 Alienvault USM Central 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.