Splunk Add-on v4.2.0

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 with both normal, and 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.

Refer to the Fortinet FortiSOAR Add-on for Splunk page on Splunkbase™ – at https://splunkbase.splunk.com/app/5392 – for overview, version history, and access to other downloadable versions.

Version Information:

Splunk Technology Add-on Version: 4.2.0

FortiSOAR™ Version Tested on: 7.6.0-5012

Splunk connector Versions Tested on: 2.0.0

Authored By: Fortinet

Certified: Yes

Release Notes for Fortinet FortiSOAR Splunk Add-on version 4.2.0

The following enhancements have been made to the Fortinet FortiSOAR Splunk Add-on in version 4.2.0:

• Fixed an issue where the Splunk Add-on sometimes did not push failed events to FortiSOAR™. Now the Splunk Add-on keeps records of the failed events and attempts to push them to FortiSOAR™ later.
• Upgraded the Splunk SDK library (splunklib) to version 2.0.2.

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 or 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 at https://splunkbase.splunk.com/app/5392/

   

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

   

For steps on upgrading your Fortinet FortiSOAR Splunk Add-on, see the Upgrading the Fortinet FortiSOAR Splunk Add-on topic.

Installing the Splunk application manually

1. Login to your Splunkbase account and search for the Fortinet FortiSOAR Add-on for Splunk.

   It is available at https://splunkbase.splunk.com/app/5392/

2. Download Fortinet FortiSOAR Add-on for Splunk.

3. Import the Splunk App TA-fortinet-fortisoar-x.x.x.tar.gz into Splunk ES Search Head.

   Important: The TA-fortinet-fortisoar-4.2.0.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.

Including SSL certificates to be used with the Splunk platform

Splunk has issued a directive that all Cloud add-ons are required to include SSL certificates for external requests. All Cloud users must therefore perform the following steps to include a certificate on the Splunk server.

1. Exporting the CA certificate using a browser:

   1. Click on the padlock icon next to the FortiSOAR Server URL on your Chrome browser:

      

   2. Click Connection is secure:

      

   3. Click Certificate is valid, which in turn displays a new dialog box:

      

   4. Click the Details tab on the dialog box:

      

   5. Select the certificate to export all the certificates individually (i.e. server certificate, intermediate certificate, certificate authority certificate, etc), and then click Export:

      

   6. Save the certificates and prepare them to be used with the Splunk platform:

      

2. Preparing TLS certificates for use with the Splunk platform:

   1. Combine the server certificate, intermediate certificate, and certificate authority certificate, in this specific order, into a single file. The combined file must be in the Privacy-Enhanced Mail (PEM) format. Use the following Linux command to concat all the certificates:

      cat <server certificate file> <intermediate certificate file> <certificate authority certificate file> > <combined server certificate file>

   2. Use a text editor to review the combined certificate file and ensure that its contents are in the following order:
      1. The server certificate
      2. The intermediate certificate

      3. The certificate authority certificate

         

   3. Once you are satisfied with the review of the combined certificate file, save the file in the Splunk server and provide the path of the file, or provide the FortiSOAR™ server certificate chain in the FortiSOAR Server Certificate field of the Splunk Add-on configuration.

      If you have a Splunk Cloud setup then you need to submit a request to Splunk to add the certificate to the Splunk server and then provide the path of the file in the Splunk Add-on configuration.

3. Deploy the SSL Certificate in on-prem FortiSOAR in case of an on-prem setup:

   Obtain certificates (from a certificate authority or a self-signed certificate) and then run the following steps to deploy the certificate:

   1. SSH to your FortiSOAR VM and log in as a root user.

   2. To deploy your certificate, type the following command:

      # csadm certs --deploy

      At the prompt, specify the following:
      • The complete path of the private key file of your SSL certificate.
      • The complete path to the crt file of your SSL certificate.

For more information, see https://docs.splunk.com/Documentation/Splunk/9.1.1/Security/HowtoprepareyoursignedcertificatesforSplunk.

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 the 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; 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 the Fortinet FortiSOAR Splunk Add-on

To upgrade the Fortinet FortiSOAR Add-on, do the following:

1. Log in to your Splunkbase account and click Apps > Manage:

   

2. Search for Fortinet, which displays the Fortinet FortiSOAR Add-on' row:

   

3. Click Update to 4.2.0 in the Fortinet FortiSOAR Add-on row to display the Update App page.

4. Click the Terms and Conditions checkbox on the Update from Splunkbase dialog, then click Accept and Continue:

   

5. To download the app, enter your Splunk.com account and password in the Login Required dialog, then click Login and Continue:

   

   This downloads and installs the Fortinet FortiSOAR Add-on.

6. Click Set up now on the Install Successfully dialog to configure the Fortinet FortiSOAR Add-on and auto-populate all of the fields based on your previous settings:

   

7. Click Save on the FortiSOAR Configuration dialog, to save the configuration and start using the Fortinet FortiSOAR Add-on:

   

Handling failed Splunk events

Failed events are not automatically ingested in FortiSOAR™. You can create a Splunk alert within Splunk and trigger an appropriate FortiSOAR™ action, or trigger data ingestion in the Splunk connector.

Following are the two methods to ingest failed events in FortiSOAR™:

1. Create a Splunk alert to push failed Splunk events to FortiSOAR™.
2. Enable and configure Splunk Data Ingestion in FortiSOAR™ with a Splunk query. Refer to the section Configuring Data Ingestion in FortiSOAR™ for failed Splunk events in Splunk connector documentation.

Creating a Splunk alert

You can create a Splunk alert and push failed events by running a query, specifying a schedule, trigger actions, and the FortiSOAR action to trigger.

Pushing failed events and creating new incidents in FortiSOAR™

• The following query pushes failed events to FortiSOAR:

  index="_internal" source="/opt/splunk/var/log/splunk/TA-fortinet-fortisoar_fortisoar_common.log_events.log" createFSR Incident

• Add the action step FortiSOAR: Create Incident in When Triggered field under Trigger Actions.
• Specify schedule and trigger conditions to periodically run the query.

Pushing failed events and creating new alerts in FortiSOAR™

• The following query pushes failed events to FortiSOAR:

  index="_internal" source="/opt/splunk/var/log/splunk/TA-fortinet-fortisoar_fortisoar_common.log_events.log" createFSR Alert

• Add the action step FortiSOAR: Create Alert in When Triggered field under Trigger Actions.
• Specify schedule and trigger conditions to periodically run the query.

Troubleshooting

The 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 FortiSOAR 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.