Splunk Add-on v3.0.1

About the Fortinet FortiSOAR Splunk Add-on

FortiSOAR provides powerful bi-directional integration with Splunk. While the Splunk connector provides out-of-the-box support for scheduled data ingestion from Splunk using FortiSOAR™'s Data Ingestion Wizard, the FortiSOAR Splunk add-on can be optionally installed on the Splunk Search Head for some additional capabilities such as automatically forwarding events and alerts from Splunk to FortiSOAR™ and invoking FortiSOAR™ playbooks for investigation. The Splunk Add-on is designed to work in conjunction with normal events as well as notable events from Splunk ES. While ES is not a requirement, it is recommended since all bi-directional updates only apply to Splunk's notable events. For more information on using FortiSOAR™'s Data Ingestion Wizard to easily ingest data into FortiSOAR™ by pulling events from Splunk, see the Splunk connector documentation.

Version Information:

Splunk Technology Add-on Version: 3.0.1

FortiSOAR™ Version Tested on: 7.0.1-628

Splunk connector Versions Tested on: 1.6.2

Authored By: Fortinet

Certified: Yes

Release Notes for Fortinet FortiSOAR Splunk Add-on version 3.0.1

Following enhancements have been made to the Fortinet FortiSOAR Splunk Add-on in version 3.0.1:

• Added support for Splunk Cloud.

Fortinet FortiSOAR Splunk Add-on compatibility

Capabilities of the Splunk Add-on

• Both Splunk ES and FortiSOAR can track updates to the workflow status for incidents and alerts, such as changes to their estimated urgency, the addition of comments to the incident or alert, the user who is investigating the incident or alert, and the current status of the investigation. The Splunk add-on synchronizes this status tracking so that both ES and FortiSOAR™ follow changes made to alerts and incidents in either Splunk ES and FortiSOAR and update the local status accordingly. For example, if in Splunk ES the severity of an incident is changed from 'Medium' to 'High', then this add-on will update the severity of this incident in FortiSOAR.
• The Splunk add-on adds workflow actions in both Splunk Search and ES’s Incident Review page allowing users to create FortiSOAR™ alerts or incidents out of arbitrary Splunk events.

Installing the Fortinet FortiSOAR Splunk Add-on

The Splunk Add-on is designed to work in conjunction with normal events as well as notable events from Splunk ES. While ES is not a requirement, it is recommended since all bi-directional updates only apply to Splunk's notable events.

1. In your Splunk Instance, click on Browse more apps and search for Fortinet FortiSOAR Add-on for Splunk App. It is available on https://splunkbase.splunk.com/app/5392/
   

2. Log in to your Splunkbase account and install the Splunk add-on.
   

Installing the Splunk application manually

1. Login to your Splunkbase account and search for the Fortinet FortiSOAR Add-on for Splunk App. It is available on https://splunkbase.splunk.com/app/5392/

2. Download the Fortinet FortiSOAR Add-on for Splunk App.

3. Import the Splunk App TA-fortinet-fortisoar-x.x.x.tar.gz into Splunk ES Search Head.
   Important: The TA-fortinet-fortisoar-3.0.1.tar.gz file can be downloaded from splunkbase.

4. Configure the TA-fortinet-fortisoar-x.x.x.tar.gz.
   
   Specify a FortiSOAR user who has permission to view and trigger FortiSOAR playbooks.

5. Ensure that the Splunk server has connectivity to the FortiSOAR™ server and can send requests to the FortiSOAR™ instance on port 443.

Integration Points

The Splunk Add-on provides the following integration points:

1. Alert Actions

1. FortiSOAR: Create Alert - Creates an alert in FortiSOAR with the event data. Triggers the FortiSOAR playbook Splunk Inbound Alert with the api/triggers/1/splunkAlert API trigger. Ensure that the playbook is Active for automated Alert creation.
2. FortiSOAR: Create Incident - Creates an incident in FortiSOAR with the event data. Triggers the FortiSOAR playbook Splunk Inbound Incident with the api/triggers/1/splunkIncident API trigger. Ensure that the playbook is Active for automated Incident creation.
3. FortiSOAR: Run Playbook - Lists all active FortiSOAR playbooks that have an API Trigger as the starting step. The list of playbooks can additionally be filtered based on the tags. The tags are specified in the Set Up page on the Fortinet Splunk Add-on.
   
   OR
   Specify the FortiSOAR Playbook that will be Invoked to override the FortiSOAR™ endpoint and Appliance Keys, which have been specified in the application configuration.
   Note: To generate APPLIANCE_PRIVATE_KEY and APPLIANCE_PUBLIC_KEY, log on to FortiSOAR™ as an administrator and click Settings > Appliances. Click Add to create a new appliance. On the New Appliance page specify the name of the appliance and select the Team(s) and Role(s). i.e., Application Administrator and Playbook Administrator roles that apply to this appliance and click Save. Once you save the new appliance record, FortiSOAR™ displays a pair of Public / Private cryptographic keys in a modal window. You must keep a copy of these keys and add them to the APPLIANCE_PRIVATE_KEY and APPLIANCE_PUBLIC_KEY fields.
   

2. Event Actions

Note: The actions listed in this section are available for both notable and non-notable events.

1. FortiSOAR: Create Alert
2. FortiSOAR: Create Incident

3. Adaptive Response Actions

1. FortiSOAR: Run Playbook

4. Saved Searches

The Splunk Add-on adds the following searches to Splunk ES. Schedule one of these searches to run every 5 minutes to enable automated creation of FortiSOAR alerts or incidents for every Splunk notable:

1. Send ES notable events to FortiSOAR as alerts
2. Send ES notable events to FortiSOAR as incidents
   To keep the notable status, assignee, and severity updates synchronized between the two products, schedule the following search:
3. Send ES notable updates to FortiSOAR
   By default, this search sends the ES notable updates to FortiSOAR™ as an alert. If you are ingesting the events as incidents in FortiSOAR™, edit the macros.conf file in the Splunk Add-on. In this case, edit the macros.conf file to set the update_type macro to incident-update.
   These searches invoke the FortiSOAR playbooks: Splunk Alert Update or Splunk Incident Update, whenever Status, Urgency or Assignee is updated for a notable in Splunk so that the corresponding fields are updated in the FortiSOAR module, provided that the playbooks are in the Active state.

5. Commands

1. fortisoarsend
   This command can also be used directly to forward any search result to FortiSOAR™ as an alert or incident. For example,
   <search> | fortisoarsend alert
<search> | fortisoarsend incident

Additionally, the add-on also provides an automated update of Splunk notables, if the Status, Assignee or Urgency fields are updated on the corresponding FortiSOAR module. The playbooks Update Splunk on Alert Post-Update and Update Splunk on Incident Post-Update are triggered whenever the FortiSOAR module is updated, provided the playbooks are in the Active state.

Configurations required on your FortiSOAR instance for automatically creating and updating alerts

1. Synchronizing Splunk ES users with FortiSOAR™

Use the Sync Splunk Users to FortiSOAR connector function in a playbook to synchronize specific Splunk users to FortiSOAR™. Synchronize only those users who are allowed to be assigned to notable events. Synchronizing the users would enable FortiSOAR™ to assign the FortiSOAR alert to the same user as the Assignee for the corresponding Splunk notables.

2. Updating the FortiSOAR™ modules

Note: This procedure is optional, and it enables the bidirectional update of notables. Therefore, perform this procedure, only if you require the Splunk notables to be automatically updated if the corresponding FortiSOAR™ incident or alert module is updated and vice-versa.

When a Splunk ES notable event is mapped to a FortiSOAR™ alert or incident, the Status and Urgency of the event can be mapped into the equivalent fields in the FortiSOAR™ modules. The sample playbooks included with Splunk 1.5.0 and later already contain the mapping for the FortiSOAR™ incident and alert modules in their "Configuration" step. The following image is of the Configuration step in the Splunk > Inbound Alert playbook that contains the mapping:

Modifying the default Alert and Incident Creation Behavior

As mentioned in the Integration Points section, the actions from the FortiSOAR Splunk Add-on invokes playbooks bundled with the Splunk connector for the desired automation. If you want to customize the default behavior of the playbooks, you can either modify the existing playbook or create and invoke a new playbook. In case you are creating a new playbook, you must deactivate or delete the corresponding sample playbook and write a new playbook with the same API trigger.

The following table lists the API trigger and the corresponding default playbook for your easy reference:

The playbooks are installed with the FortiSOAR Splunk connector. For integrations 5 and 6 to work, ensure that you have updated the connector steps in the appropriate playbook to point to your Splunk configuration.

It is recommended that you make a copy of these playbooks and then customize them as per your requirements. Once you have a working copy, ensure that you set the state of the sample playbooks to Inactive; otherwise, both the playbooks will be triggered whenever events are forwarded from Splunk.

Upgrading Splunk Add-on

To upgrade to Fortinet FortiSOAR Add-on 3.0.1, select the Upgrade App checkbox to overwrite or upgrade the add-on if it is already present on your system.
Note: It is recommended that you remove the previously stored private key from the /opt/splunk/etc/apps/TA-fortinet-fortisoar/local/fortisoar.conf file.

Troubleshooting

Fingerprint has expired error is observed in the TA-fortinet-fortisoar-x.x.x.tar log

The "Fingerprint has expired” error is seen in the ta-fortinet-fortisoar_fortisoar_common.connection.log file.

Resolution:

This issue could occur in cases where there is a difference between the time of the Splunk Search Head and the FortiSOAR™ instance. Resolve this issue by synchronizing the time of the Splunk Search Head and your FortiSOAR™ instance to a common NTP server.

Error while running the "Splunk > Alert Update" playbook

Note: This error is applicable to version 7.0.1 only.
You see the following error while running the Splunk > Alert Update:
Error message : CS-INTEGRATION-5: Error occurred while executing the connector action ERROR :: 400 Client Error: Bad Request for url: https://localhost/api/auth/users :: {'Error': 'The server encountered an error while handling the request. Please contact the administrator for assistance.'} :: Url: https://localhost/api/auth/users

Resolution:

Update the IRI of the "Get CyOPs Users" step with "/api/auth/users?loginid={{vars.event_owner}}" and enable Ignore Error for this step.