Fortinet Document Library

Version:


Table of Contents

1.4.0
Copy Link

About the connector

Splunk is a SIEM software that allows searching, monitoring and analyzing machine-generated big data, using a web-style interface. For more information, see the Splunk website.

This document provides information about the Splunk connector, which facilitates automated interactions, with a Splunk server using FortiSOAR™playbooks. Add the Splunk connector as a step in FortiSOAR™playbooks and perform automated operations, such as retrieving details and events for a Splunk alert, and running a search query on the Splunk server.

 

Version information

Connector Version: 1.4.0

Compatibility with FortiSOAR™Versions: 4.10.3-161 and later

Compatibility with Splunk Versions: 6.3 and later

 

Release Notes for version 1.4.0

Following changes have been made to the Splunk Connector in version 1.4.0:

  • Enhanced the playbooks bundled with the connector. See the Included Playbooks section for details on the bundled playbooks.

Installing the connector

For the procedure to install a connector, click here.

 

Prerequisites to configuring the connector

  • You must have the URL and credentials of the Splunk server on which you will perform the automated operations. You must also have the credentials of a user, who has a right to configure custom applications on the Splunk server.
  • To access the FortiSOAR™UI, ensure that port 443 is open through the firewall for the FortiSOAR™instance.
  • To automatically forward events and alerts from Splunk to CyOPs™, you must install and configure CyberSponse Splunk Technology Add-on. See the Installing and configuring the Cybersponse Splunk Technology Add-on section.

Configuring the connector

For the procedure to configure a connector, click here.

 

Configuration parameters

In CyOPs™, on the Connectors page, select the Splunk connector and click Configure to configure the following parameters:

 

Parameter Description
Address IP or FQDN of the Splunk server to which you will connect and perform automated operations.
For example, mySplunkServer.
Splunk API Port REST API port of the Splunk server.
Defaults to 8089.
Username Username to access the endpoint.
Password Password to access the endpoint.
Verify SSL Specifies whether the SSL certificate for the server is to be verified or not.
Defaults to True.
Application Namespace Namespace that will be used for invoking all of the Splunk APIs.
For more information about namespaces, see Splunk Documentation.

 

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
Invoke Search Invokes a search on the Splunk server. search_query
Investigation
Get Details for a Search Retrieves the details for a Splunk search. get_result
Investigation
Get Events for a Search Retrieves the event details for a Splunk search. get_events
Investigation
Get Results for a Search Retrieves the results for a Splunk search. get_result
Investigation
Get Splunk Action Retrieves details of the available Splunk alert actions or adaptive response actions. get_command
Investigation
Run Splunk Action Runs an alert action or an adaptive response action on a search result or a notable. run_command
Investigation
Update Splunk Notables Updates Splunk notables when FortiSOAR™is updated. update_record
Investigation
Sync Splunk user to CyOPs™ Synchronizes a Splunk Enterprise Security (ES) user to FortiSOAR™for co-relation between FortiSOAR™and Splunk.
Note: Synchronize only those users who are allowed to be assigned to notable events.
sync_users
Miscellaneous
Get List Of Triggered Alerts Retrieves a list of alerts that are triggered on Splunk based on the parameters you have specified. get_alerts
Investigation
Get Details Of Triggered Alerts Retrieves information of an alert triggered on Splunk based on the name of the alert you have specified. get_alert
Investigation
Add Comment to Notables Adds a comment to the Splunk notable event ID(s) that are specified by a comma-separated list in case of multiple events. update_record
Investigation

 

operation: Invoke Search

Input parameters

 

Parameter Description
Query Query for the search that you want to run on the Splunk server.
Defaults to {"value": "search host="{{vars.result.data.host}}"}.
Additional Search Arguments Additional parameters for the search. You can specify additional parameters, such as time windows and execution mode, to your search query to get specific search results. For more information, see the Splunk REST API Reference Manual.
Note: To run a search in the verbose mode, add the following parameter: {“adhoc_search_level”:“verbose”}.

 

Output

The JSON output that contains the data retrieved based on the search query. The search results depend on the additional parameters specified in the search. If the search is run in a blocking or normal mode, the sid is returned. For example, {“sid”: “1496222688.33”}.

Following image displays a sample output of a successful one-shot search:

 

Sample output of the Invoke Search operation

 

operation: Get Details for a Search

Input parameters

 

Parameter Description
Search Id ID of the Splunk search for which you want to retrieve details.
Defaults to {"value": "{{vars.request.data.sid}}"}".

 

Output

The JSON output contains all the details based on the specified search ID.

Following image displays a sample output:

 

Sample output of the Get Details for a Search operation

 

operation: Get Events for a Search

Input parameters

 

Parameter Description
Search Id ID of the Splunk search for which you want to retrieve events.
Defaults to {"value": "{{vars.request.data.sid}}"}".
Additional Request Parameters Optional parameter. You can add other request parameters in the JSON format.
For example, {\"output_mode\": \"json\", \"count\": 10}

 

Note: If your search query has additional commands, such as stats, run on the events from the search, the Get Events API returns an empty result, if the search is not run in verbose mode. To set the verbose mode, add the following parameter to the Additional Search Arguments parameter in the Invoke Search operation: {“adhoc_search_level”:“verbose”}.

Output

The JSON output contains all the events for the specified Splunk search in a search result.

Following image displays a sample output:

 

Sample output of the Get Events for a Search operation

 

operation: Get Results for a Search

Input parameters

 

Parameter Description
Search Id ID of the Splunk search as a JSON. For example, {'value': {{vars.sid}}}.
Note: You must add the Search ID as a JSON with the key value as specified in the example, otherwise the operation might fail.
Additional Request Parameters Optional parameter. You can add other request parameters in the JSON format.
For example example, {\"output_mode\": \"json\", \"count\": 10}

 

Output

The JSON output contains the transformed results for the specified Splunk search in a search result.

Following image displays a sample output:

 

Sample output of the Get Results for a Search operation

 

operation: Get Splunk Action

Input parameters

 

Parameter Description
Action Name Name of the action for which the details are to be fetched. A match for this name is looked for in the action name, description and label in a Splunk action. This is an optional parameter and if you do not specify the same then this operation fetches a list of all Splunk actions.

 

Output

The JSON output contains input parameters and other details for all alerts action that match the action name you have specified.

Following image displays a sample output:

 

Sample output of the Get Splunk Action operation

 

operation: Run Splunk Action

Input parameters

 

Parameter Description
Notable Event Id ID of the notable event on which you want to run the action.
Search Id ID of the Splunk search on which you want to run the action.
You must specify either the Notable Event Id or the Search Id.
Action Name Name of the action to be run.
Action Parameters Parameters of the action that you want to run. For example, a parameter in the JSON format would be {\"max_results\":\"1\"} 
Note: You can use the Get Splunk Action operation to get parameter names for a specific action.
Frequency If you are running the operation on search results, this parameter specifies if the action should be run only once for the entire resultset or for each result.

 

Output

This operation executes the action with the help of the sendaction command from Splunk. The JSON output contains the events from execution of the sendalert command and varies for each command. The following image displays the output of execution of the SplunkES Risk Analysis AR action on a notable event:

 

Sample output of the Run Splunk Action operation

 

operation: Update Splunk Notables

Input parameters

None. Include this operation in a Splunk playbook and notables will get updated on Splunk, when they are updated on CyOPs™.

Output

The JSON output returns a Success message if the Splunk notables are updated, or an Error message containing the reason for failure.

Following image displays a sample output of a successful action:

Sample output of the Update Splunk Notables operation

operation: Sync Splunk user to CyOPs™

Input parameters

None. Include this operation in a Splunk playbook and users will get updated on Splunk, when they are updated in CyOPs™.

Output

The JSON output returns a Success message if the Splunk users are synchronized, or an Error message containing the reason for failure. The output also contains names of the users.

Following image displays a sample output of a successful action:

 

Sample output of the Sync Splunk user to CyOPs™ operation

operation: Get List Of Triggered Alerts

Input parameters

 

Parameter Description
Max Number Of Entries To Return Maximum number of triggered alerts that you want the operation to return. Set the value to -1 if you want to retrieve all the triggered alerts.
Offset Index of the first item to return.
Response Filter Filter used to specify which triggered alerts must be returned. The values of the response fields are matched against this search expression.
Examples:
search=foo matches any field that has the string foo in its name.
search=field_name%3Dfield_value restricts the match to a single field. (Requires URI-encoding.)
Sort By Sorting order of the result, choose between asc (ascending) or desc (descending).
Field Name To Use For Sorting Name of the field on which you want to sort the result.
Sort Mode Logical sequencing (collate) of the results. Choose between the following:
auto: If all field values are numeric, collate numerically. Otherwise, collate alphabetically.
alpha = Collate field values alphabetically, not case-sensitive.
alpha_case = Collate field values alphabetically, case-sensitive.
num = Collate field values numerically.

 

Output

The JSON output contains a list of of alerts and other details for all alerts triggered on Splunk based on the parameters you have specified.

Following image displays a sample output:

 

Sample output of the Get List Of Triggered Alerts operation

 

operation: Get Details Of Triggered Alerts

Input parameters

 

Parameter Description
Alert Name Name of the triggered alert for which the details are to be fetched.

 

Output

The JSON output contains details for the triggered alert that match the alert name you have specified.

Following image displays a sample output:

 

Sample output of the Get Details Of Triggered Alerts operation

 

operation: Add Comment to Notables

Input parameters

 

Parameter Description
Notable Event Ids ID(s) of the notable event(s) in which you want to add comments.
Use a comma-separated list of IDs in case of multiple events.
Comment Comment that you want to add to the Splunk notable event(s).

 

Output

The JSON output returns a Success message if the Splunk notable event(s) are updated, or an Errormessage containing the reason for failure.

Following image displays a sample output of a successful action:

 

Sample output of the Add Comment to Notables operation

 

Included playbooks

The Sample-Splunk-1.4.0 playbook collection comes bundled with the Splunk 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 Splunk connector.

  1. Splunk > Inbound Alert
  2. Splunk > Inbound Incident
  3. Splunk > Alert Update
  4. Splunk > Incident Update
  5. Splunk > Incident Post-Update
  6. Splunk > Alert Post-Update
  7. Splunk > Update Notable Fields
  8. Splunk > Sync Splunk Users to CyberSponse
  9. Splunk > Search Actions
  10. Splunk > Alert Action
  11. Splunk > Triggered Alerts Actions

The sample playbooks from 1 to 7 work in conjunction with the TA-Cybersponse Splunk Technology Add-on to invoke CyberSponse actions from the Splunk UI and also to automatically forward Splunk alerts and notable as CyberSponse Alerts and Incidents. For more details, see the Installing and configuring the Cybersponse Splunk Technology Add-on section.

 

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.

 

Installing and configuring the Cybersponse Splunk Technology Add-on

 

Important: Applies to Slunk versions 6.3, 6.4 and 6.5 and FortiSOAR™ versions 4.9 and later.

 

The CyberSponse 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 notable events.

Capabilities of the Cybersponse Splunk Technology Add-on

  • Both Splunk ES and CyberSponse have the ability to track workflow status for incidents or alerts, such as changes to the incident’s estimated urgency, who is investigating the incident, the current status of the investigation, and comments on the incident. This add-on coordinates that status tracking so that both ES and FortiSOAR™follow each other’s status changes and update local status accordingly.
  • This 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 Splunk application

  1. Import the CyberSponse Splunk App TA-cybersponse-X.X.X.tar.gz into Splunk ES Search Head.

  2. Configure the TA-cybersponse-X.X.X.tar.gz.
    TA-CyperSponse Splunk Add-on
    Specify a CyberSponse user who has the permission to view and trigger CyberSponse playbooks.

  3. 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 Cybersponse Splunk Technology Add-on provides the following integration points:

1. Alert Actions

  1. CyberSponse: Create Alert - Creates an alert in CyberSponse with the event data. Triggers the CyberSponse playbook Splunk Inbound Alert with the api/triggers/1/splunkAlert API trigger. Ensure that the playbook is Active for automated Alert creation.
  2. CyberSponse: Create Incident - Creates an incident in CyberSponse with the event data. Triggers the CyberSponse playbook Splunk Inbound Incident with the api/triggers/1/splunkIncident API trigger. Ensure that the playbook is Active for automated Incident creation.
  3. CyberSponse: Run Playbook - Lists all active CyberSponse 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 CyberSponse Splunk Add-on.
    TA-CyperSponse Splunk Add-on: Tags field

2. Event Actions

 

Note

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

 

  1. CyberSponse: Create Alert
  2. CyberSponse: Create Incident

3. Adaptive Response Actions

  1. CyberSponse: Run Playbook

4. Saved Searches

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

  1. Send ES notable events to CyberSponse as alerts
  2. Send ES notable events to CyberSponse 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 CyberSponse
    By default, this search sends the ES notable updates to FortiSOAR™as an alert. If you are ingesting the events as incidents in CyOPs™, edit the macros.conf file in the CyberSponse Splunk Add-on. In this case, edit the macros.conf file to set the update_type macro to incident-update.
    These searches invoke the CyberSponse playbooks: Splunk Alert Update or Splunk Incident Update, whenever Status, Urgency or Asignee is updated for a notable in Splunk so that the corresponding fields are updated in the CyberSponse module, provided that the playbooks are in the Active state.

5. Commands

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

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

Additional configurations required for automatically creating and updating alerts

1. Synchronizing Splunk ES users with CyOPs™

Use the Sync Splunk Users to CyOps connector function in a playbook to synchronize specific Splunk users to CyOPs™. Synchronize only those users who are allowed to be assigned to notable events. Synchronizing the users would enable FortiSOAR™to assign the CyberSponse 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 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. This procedure also assumes that you are using FortiSOAR™version 4.10.1. If you are using a different version of CyOPs™, such as FortiSOAR™4.9, then it is possible that the FortiSOAR™UI navigation is different. Refer to the FortiSOAR™documentation of that particular version for details about FortiSOAR™navigation.

 

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. Perform the following steps to add the Status and Urgency fields to the FortiSOAR™Alerts and Incidents modules:

  1. Log on to FortiSOAR™as an administrator.
  2. To open the Picklist Editor and create a picklist named splunkstatus, click Settings and in the Application Editor section, and click Picklists:
    1. In the Title field, type splunkStatus.
    2. Add status in the following order: Unassigned, New, In Progress, Pending, Resolved, and Closed.
    3. Clear the Assign colors checkbox.
      Adding a Splunk Status picklist
    4. Click Save.
  3. Create another picklist named splunkUrgency as follows:
    1. In the Title field, type splunkUrgency.
    2. Add urgencies in the following order: Informational, Low, Medium, High, and Critical.
    3. Clear the Assign colors checkbox.
      Adding a Splunk Urgency picklist
    4. Click Save.
  4. Update the Alerts Module as follows:
    1. To open the Module Editor, click Settings and then click Modules in the Application Editorsection.
    2. On the Modules page, from the Select a module to edit or create a new module drop-down list, select Alerts.
    3. Click the Fields Editor tab.
    4. To update the alert statuses, in the Fields section, select Status and then from the Picklist drop-down list, select splunkStatus.
      Updating Alerts module with Splunk Status
      Click Apply.
    5. To add the alert urgencies, click the + (Add Field) icon and add a new field with the following properties:
      In the Type field, select Picklist.
      From the Picklist drop-down list, select splunkUrgency.
      In the Name field, type urgency.
      In the Singular Name field, type Urgency.
      Updating Alerts module with Splunk Urgency
      Click Apply and Save.
  5. Update the Incidents Module as follows:
    1. To open the Module Editor, click Settings and then click Modules in the Application Editorsection.
    2. On the Modules page, from the Select a module to edit or create a new module drop-down list, select Incidents.
    3. Click the Fields Editor tab.
    4. To update the incident statuses, in the Fields section, select Status and then from the Picklistdrop-down list, select splunkStatus.
      Updating Incidents module with Splunk Status
      Click Apply.
    5. To add the incident urgencies, click the + (Add Field) icon and add a new field with the following properties:
      In the Field Type field, select Picklist.
      From the Picklist drop-down list, select splunkUrgency.
      In the Name field, type urgency.
      In the Singular Name field, type Urgency.
      Updating Incidents module with Splunk Urgency
      Click Apply and Save.
  6. Once you have completed updating all the FortiSOAR™modules, you must publish the module to enforce the changes. Click Publish All Modules and click OK to publish the modules.

Modifying the default Alert and Incident Creation Behavior

As mentioned in the Integration Points s ection, the actions from the CyberSponse Splunk Add-on invokes playbooks bundled with the CyberSponse 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:

 

S.No. Action API Trigger Default Playbook
1 CyberSponse: Create Alert api/triggers/1/splunkAlert Splunk > Inbound Alert
2 CyberSponse: Create Incident api/triggers/1/splunkIncident Splunk > Inbound Incident
3 For updating the CyberSponse Alert when the corresponding notable event is updated api/triggers/1/splunkAlertUpdate Splunk > Alert Update
4 For updating the CyberSponse Incident when the corresponding notable event is updated api/triggers/1/splunkIncidentUpdate Splunk > Incident Update
5 For Updating Splunk on Alert Post-Update NA Splunk > Alert Post-Update
6 For Updating Splunk on Incident Post-Update NA Splunk > Incident Post-Update

 

The playbooks are installed with the CyberSponse 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.

 

Field Mapping between a Splunk Alert and FortiSOAR™Alert or Incident

 

This topic uses the Splunk> Inbound Alert sample playbook as an example. You can create the one-to-one mapping between a Splunk Alert and FortiSOAR™Alert or Incident directly on the step that creates the Alert record by referring to the Splunk fields under {{vars.request.data }}. Following screenshot shows an example:

 

Mapping between a Splunk Alert and CyOPs™ Alert or Incident

 

Click the Source field and in the Dynamic Values Step Results > Start. Clicking the Start step automatically inserts the {{vars.request.data}} variable in the Source field. See FortiSOAR™for more information on Dynamic Values.

 

Dynamic Values - Source Field Mapping

 

Add the relevant field name the {{vars.request.data}} variable. For example to the Event ID field is added as , {{vars.request.data.event_id}}.

For FortiSOAR™fields that are picklists, mapping can be done by creating a pre-defined map of FortiSOAR™picklist values to corresponding Splunk data. For example, in the Splunk> Inbound Alert sample playbook, value for the Alert Type is identified based on the Splunk Search Name. Following mapping is stored in the Configuration step:

 

{
    'DNS Exfiltration': {{ 'AlertType'| picklist('Data Exfiltration')} },
    'Brute Force': {{ 'AlertType'| picklist('Brute Force Attempts') }}
}

 

Splunk Configuration step

 

These picklist values are consumed while setting the Type on an Alert record as shown in the following image:

 

Setting the Type on an Alert record

 

TA-cybersponse-2.4.10.tar.gz

About the connector

Splunk is a SIEM software that allows searching, monitoring and analyzing machine-generated big data, using a web-style interface. For more information, see the Splunk website.

This document provides information about the Splunk connector, which facilitates automated interactions, with a Splunk server using FortiSOAR™playbooks. Add the Splunk connector as a step in FortiSOAR™playbooks and perform automated operations, such as retrieving details and events for a Splunk alert, and running a search query on the Splunk server.

 

Version information

Connector Version: 1.4.0

Compatibility with FortiSOAR™Versions: 4.10.3-161 and later

Compatibility with Splunk Versions: 6.3 and later

 

Release Notes for version 1.4.0

Following changes have been made to the Splunk Connector in version 1.4.0:

Installing the connector

For the procedure to install a connector, click here.

 

Prerequisites to configuring the connector

Configuring the connector

For the procedure to configure a connector, click here.

 

Configuration parameters

In CyOPs™, on the Connectors page, select the Splunk connector and click Configure to configure the following parameters:

 

Parameter Description
Address IP or FQDN of the Splunk server to which you will connect and perform automated operations.
For example, mySplunkServer.
Splunk API Port REST API port of the Splunk server.
Defaults to 8089.
Username Username to access the endpoint.
Password Password to access the endpoint.
Verify SSL Specifies whether the SSL certificate for the server is to be verified or not.
Defaults to True.
Application Namespace Namespace that will be used for invoking all of the Splunk APIs.
For more information about namespaces, see Splunk Documentation.

 

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
Invoke Search Invokes a search on the Splunk server. search_query
Investigation
Get Details for a Search Retrieves the details for a Splunk search. get_result
Investigation
Get Events for a Search Retrieves the event details for a Splunk search. get_events
Investigation
Get Results for a Search Retrieves the results for a Splunk search. get_result
Investigation
Get Splunk Action Retrieves details of the available Splunk alert actions or adaptive response actions. get_command
Investigation
Run Splunk Action Runs an alert action or an adaptive response action on a search result or a notable. run_command
Investigation
Update Splunk Notables Updates Splunk notables when FortiSOAR™is updated. update_record
Investigation
Sync Splunk user to CyOPs™ Synchronizes a Splunk Enterprise Security (ES) user to FortiSOAR™for co-relation between FortiSOAR™and Splunk.
Note: Synchronize only those users who are allowed to be assigned to notable events.
sync_users
Miscellaneous
Get List Of Triggered Alerts Retrieves a list of alerts that are triggered on Splunk based on the parameters you have specified. get_alerts
Investigation
Get Details Of Triggered Alerts Retrieves information of an alert triggered on Splunk based on the name of the alert you have specified. get_alert
Investigation
Add Comment to Notables Adds a comment to the Splunk notable event ID(s) that are specified by a comma-separated list in case of multiple events. update_record
Investigation

 

operation: Invoke Search

Input parameters

 

Parameter Description
Query Query for the search that you want to run on the Splunk server.
Defaults to {"value": "search host="{{vars.result.data.host}}"}.
Additional Search Arguments Additional parameters for the search. You can specify additional parameters, such as time windows and execution mode, to your search query to get specific search results. For more information, see the Splunk REST API Reference Manual.
Note: To run a search in the verbose mode, add the following parameter: {“adhoc_search_level”:“verbose”}.

 

Output

The JSON output that contains the data retrieved based on the search query. The search results depend on the additional parameters specified in the search. If the search is run in a blocking or normal mode, the sid is returned. For example, {“sid”: “1496222688.33”}.

Following image displays a sample output of a successful one-shot search:

 

Sample output of the Invoke Search operation

 

operation: Get Details for a Search

Input parameters

 

Parameter Description
Search Id ID of the Splunk search for which you want to retrieve details.
Defaults to {"value": "{{vars.request.data.sid}}"}".

 

Output

The JSON output contains all the details based on the specified search ID.

Following image displays a sample output:

 

Sample output of the Get Details for a Search operation

 

operation: Get Events for a Search

Input parameters

 

Parameter Description
Search Id ID of the Splunk search for which you want to retrieve events.
Defaults to {"value": "{{vars.request.data.sid}}"}".
Additional Request Parameters Optional parameter. You can add other request parameters in the JSON format.
For example, {\"output_mode\": \"json\", \"count\": 10}

 

Note: If your search query has additional commands, such as stats, run on the events from the search, the Get Events API returns an empty result, if the search is not run in verbose mode. To set the verbose mode, add the following parameter to the Additional Search Arguments parameter in the Invoke Search operation: {“adhoc_search_level”:“verbose”}.

Output

The JSON output contains all the events for the specified Splunk search in a search result.

Following image displays a sample output:

 

Sample output of the Get Events for a Search operation

 

operation: Get Results for a Search

Input parameters

 

Parameter Description
Search Id ID of the Splunk search as a JSON. For example, {'value': {{vars.sid}}}.
Note: You must add the Search ID as a JSON with the key value as specified in the example, otherwise the operation might fail.
Additional Request Parameters Optional parameter. You can add other request parameters in the JSON format.
For example example, {\"output_mode\": \"json\", \"count\": 10}

 

Output

The JSON output contains the transformed results for the specified Splunk search in a search result.

Following image displays a sample output:

 

Sample output of the Get Results for a Search operation

 

operation: Get Splunk Action

Input parameters

 

Parameter Description
Action Name Name of the action for which the details are to be fetched. A match for this name is looked for in the action name, description and label in a Splunk action. This is an optional parameter and if you do not specify the same then this operation fetches a list of all Splunk actions.

 

Output

The JSON output contains input parameters and other details for all alerts action that match the action name you have specified.

Following image displays a sample output:

 

Sample output of the Get Splunk Action operation

 

operation: Run Splunk Action

Input parameters

 

Parameter Description
Notable Event Id ID of the notable event on which you want to run the action.
Search Id ID of the Splunk search on which you want to run the action.
You must specify either the Notable Event Id or the Search Id.
Action Name Name of the action to be run.
Action Parameters Parameters of the action that you want to run. For example, a parameter in the JSON format would be {\"max_results\":\"1\"} 
Note: You can use the Get Splunk Action operation to get parameter names for a specific action.
Frequency If you are running the operation on search results, this parameter specifies if the action should be run only once for the entire resultset or for each result.

 

Output

This operation executes the action with the help of the sendaction command from Splunk. The JSON output contains the events from execution of the sendalert command and varies for each command. The following image displays the output of execution of the SplunkES Risk Analysis AR action on a notable event:

 

Sample output of the Run Splunk Action operation

 

operation: Update Splunk Notables

Input parameters

None. Include this operation in a Splunk playbook and notables will get updated on Splunk, when they are updated on CyOPs™.

Output

The JSON output returns a Success message if the Splunk notables are updated, or an Error message containing the reason for failure.

Following image displays a sample output of a successful action:

Sample output of the Update Splunk Notables operation

operation: Sync Splunk user to CyOPs™

Input parameters

None. Include this operation in a Splunk playbook and users will get updated on Splunk, when they are updated in CyOPs™.

Output

The JSON output returns a Success message if the Splunk users are synchronized, or an Error message containing the reason for failure. The output also contains names of the users.

Following image displays a sample output of a successful action:

 

Sample output of the Sync Splunk user to CyOPs™ operation

operation: Get List Of Triggered Alerts

Input parameters

 

Parameter Description
Max Number Of Entries To Return Maximum number of triggered alerts that you want the operation to return. Set the value to -1 if you want to retrieve all the triggered alerts.
Offset Index of the first item to return.
Response Filter Filter used to specify which triggered alerts must be returned. The values of the response fields are matched against this search expression.
Examples:
search=foo matches any field that has the string foo in its name.
search=field_name%3Dfield_value restricts the match to a single field. (Requires URI-encoding.)
Sort By Sorting order of the result, choose between asc (ascending) or desc (descending).
Field Name To Use For Sorting Name of the field on which you want to sort the result.
Sort Mode Logical sequencing (collate) of the results. Choose between the following:
auto: If all field values are numeric, collate numerically. Otherwise, collate alphabetically.
alpha = Collate field values alphabetically, not case-sensitive.
alpha_case = Collate field values alphabetically, case-sensitive.
num = Collate field values numerically.

 

Output

The JSON output contains a list of of alerts and other details for all alerts triggered on Splunk based on the parameters you have specified.

Following image displays a sample output:

 

Sample output of the Get List Of Triggered Alerts operation

 

operation: Get Details Of Triggered Alerts

Input parameters

 

Parameter Description
Alert Name Name of the triggered alert for which the details are to be fetched.

 

Output

The JSON output contains details for the triggered alert that match the alert name you have specified.

Following image displays a sample output:

 

Sample output of the Get Details Of Triggered Alerts operation

 

operation: Add Comment to Notables

Input parameters

 

Parameter Description
Notable Event Ids ID(s) of the notable event(s) in which you want to add comments.
Use a comma-separated list of IDs in case of multiple events.
Comment Comment that you want to add to the Splunk notable event(s).

 

Output

The JSON output returns a Success message if the Splunk notable event(s) are updated, or an Errormessage containing the reason for failure.

Following image displays a sample output of a successful action:

 

Sample output of the Add Comment to Notables operation

 

Included playbooks

The Sample-Splunk-1.4.0 playbook collection comes bundled with the Splunk 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 Splunk connector.

  1. Splunk > Inbound Alert
  2. Splunk > Inbound Incident
  3. Splunk > Alert Update
  4. Splunk > Incident Update
  5. Splunk > Incident Post-Update
  6. Splunk > Alert Post-Update
  7. Splunk > Update Notable Fields
  8. Splunk > Sync Splunk Users to CyberSponse
  9. Splunk > Search Actions
  10. Splunk > Alert Action
  11. Splunk > Triggered Alerts Actions

The sample playbooks from 1 to 7 work in conjunction with the TA-Cybersponse Splunk Technology Add-on to invoke CyberSponse actions from the Splunk UI and also to automatically forward Splunk alerts and notable as CyberSponse Alerts and Incidents. For more details, see the Installing and configuring the Cybersponse Splunk Technology Add-on section.

 

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.

 

Installing and configuring the Cybersponse Splunk Technology Add-on

 

Important: Applies to Slunk versions 6.3, 6.4 and 6.5 and FortiSOAR™ versions 4.9 and later.

 

The CyberSponse 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 notable events.

Capabilities of the Cybersponse Splunk Technology Add-on

Installing the Splunk application

  1. Import the CyberSponse Splunk App TA-cybersponse-X.X.X.tar.gz into Splunk ES Search Head.

  2. Configure the TA-cybersponse-X.X.X.tar.gz.
    TA-CyperSponse Splunk Add-on
    Specify a CyberSponse user who has the permission to view and trigger CyberSponse playbooks.

  3. 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 Cybersponse Splunk Technology Add-on provides the following integration points:

1. Alert Actions

  1. CyberSponse: Create Alert - Creates an alert in CyberSponse with the event data. Triggers the CyberSponse playbook Splunk Inbound Alert with the api/triggers/1/splunkAlert API trigger. Ensure that the playbook is Active for automated Alert creation.
  2. CyberSponse: Create Incident - Creates an incident in CyberSponse with the event data. Triggers the CyberSponse playbook Splunk Inbound Incident with the api/triggers/1/splunkIncident API trigger. Ensure that the playbook is Active for automated Incident creation.
  3. CyberSponse: Run Playbook - Lists all active CyberSponse 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 CyberSponse Splunk Add-on.
    TA-CyperSponse Splunk Add-on: Tags field

2. Event Actions

 

Note

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

 

  1. CyberSponse: Create Alert
  2. CyberSponse: Create Incident

3. Adaptive Response Actions

  1. CyberSponse: Run Playbook

4. Saved Searches

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

  1. Send ES notable events to CyberSponse as alerts
  2. Send ES notable events to CyberSponse 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 CyberSponse
    By default, this search sends the ES notable updates to FortiSOAR™as an alert. If you are ingesting the events as incidents in CyOPs™, edit the macros.conf file in the CyberSponse Splunk Add-on. In this case, edit the macros.conf file to set the update_type macro to incident-update.
    These searches invoke the CyberSponse playbooks: Splunk Alert Update or Splunk Incident Update, whenever Status, Urgency or Asignee is updated for a notable in Splunk so that the corresponding fields are updated in the CyberSponse module, provided that the playbooks are in the Active state.

5. Commands

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

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

Additional configurations required for automatically creating and updating alerts

1. Synchronizing Splunk ES users with CyOPs™

Use the Sync Splunk Users to CyOps connector function in a playbook to synchronize specific Splunk users to CyOPs™. Synchronize only those users who are allowed to be assigned to notable events. Synchronizing the users would enable FortiSOAR™to assign the CyberSponse 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 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. This procedure also assumes that you are using FortiSOAR™version 4.10.1. If you are using a different version of CyOPs™, such as FortiSOAR™4.9, then it is possible that the FortiSOAR™UI navigation is different. Refer to the FortiSOAR™documentation of that particular version for details about FortiSOAR™navigation.

 

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. Perform the following steps to add the Status and Urgency fields to the FortiSOAR™Alerts and Incidents modules:

  1. Log on to FortiSOAR™as an administrator.
  2. To open the Picklist Editor and create a picklist named splunkstatus, click Settings and in the Application Editor section, and click Picklists:
    1. In the Title field, type splunkStatus.
    2. Add status in the following order: Unassigned, New, In Progress, Pending, Resolved, and Closed.
    3. Clear the Assign colors checkbox.
      Adding a Splunk Status picklist
    4. Click Save.
  3. Create another picklist named splunkUrgency as follows:
    1. In the Title field, type splunkUrgency.
    2. Add urgencies in the following order: Informational, Low, Medium, High, and Critical.
    3. Clear the Assign colors checkbox.
      Adding a Splunk Urgency picklist
    4. Click Save.
  4. Update the Alerts Module as follows:
    1. To open the Module Editor, click Settings and then click Modules in the Application Editorsection.
    2. On the Modules page, from the Select a module to edit or create a new module drop-down list, select Alerts.
    3. Click the Fields Editor tab.
    4. To update the alert statuses, in the Fields section, select Status and then from the Picklist drop-down list, select splunkStatus.
      Updating Alerts module with Splunk Status
      Click Apply.
    5. To add the alert urgencies, click the + (Add Field) icon and add a new field with the following properties:
      In the Type field, select Picklist.
      From the Picklist drop-down list, select splunkUrgency.
      In the Name field, type urgency.
      In the Singular Name field, type Urgency.
      Updating Alerts module with Splunk Urgency
      Click Apply and Save.
  5. Update the Incidents Module as follows:
    1. To open the Module Editor, click Settings and then click Modules in the Application Editorsection.
    2. On the Modules page, from the Select a module to edit or create a new module drop-down list, select Incidents.
    3. Click the Fields Editor tab.
    4. To update the incident statuses, in the Fields section, select Status and then from the Picklistdrop-down list, select splunkStatus.
      Updating Incidents module with Splunk Status
      Click Apply.
    5. To add the incident urgencies, click the + (Add Field) icon and add a new field with the following properties:
      In the Field Type field, select Picklist.
      From the Picklist drop-down list, select splunkUrgency.
      In the Name field, type urgency.
      In the Singular Name field, type Urgency.
      Updating Incidents module with Splunk Urgency
      Click Apply and Save.
  6. Once you have completed updating all the FortiSOAR™modules, you must publish the module to enforce the changes. Click Publish All Modules and click OK to publish the modules.

Modifying the default Alert and Incident Creation Behavior

As mentioned in the Integration Points s ection, the actions from the CyberSponse Splunk Add-on invokes playbooks bundled with the CyberSponse 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:

 

S.No. Action API Trigger Default Playbook
1 CyberSponse: Create Alert api/triggers/1/splunkAlert Splunk > Inbound Alert
2 CyberSponse: Create Incident api/triggers/1/splunkIncident Splunk > Inbound Incident
3 For updating the CyberSponse Alert when the corresponding notable event is updated api/triggers/1/splunkAlertUpdate Splunk > Alert Update
4 For updating the CyberSponse Incident when the corresponding notable event is updated api/triggers/1/splunkIncidentUpdate Splunk > Incident Update
5 For Updating Splunk on Alert Post-Update NA Splunk > Alert Post-Update
6 For Updating Splunk on Incident Post-Update NA Splunk > Incident Post-Update

 

The playbooks are installed with the CyberSponse 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.

 

Field Mapping between a Splunk Alert and FortiSOAR™Alert or Incident

 

This topic uses the Splunk> Inbound Alert sample playbook as an example. You can create the one-to-one mapping between a Splunk Alert and FortiSOAR™Alert or Incident directly on the step that creates the Alert record by referring to the Splunk fields under {{vars.request.data }}. Following screenshot shows an example:

 

Mapping between a Splunk Alert and CyOPs™ Alert or Incident

 

Click the Source field and in the Dynamic Values Step Results > Start. Clicking the Start step automatically inserts the {{vars.request.data}} variable in the Source field. See FortiSOAR™for more information on Dynamic Values.

 

Dynamic Values - Source Field Mapping

 

Add the relevant field name the {{vars.request.data}} variable. For example to the Event ID field is added as , {{vars.request.data.event_id}}.

For FortiSOAR™fields that are picklists, mapping can be done by creating a pre-defined map of FortiSOAR™picklist values to corresponding Splunk data. For example, in the Splunk> Inbound Alert sample playbook, value for the Alert Type is identified based on the Splunk Search Name. Following mapping is stored in the Configuration step:

 

{
    'DNS Exfiltration': {{ 'AlertType'| picklist('Data Exfiltration')} },
    'Brute Force': {{ 'AlertType'| picklist('Brute Force Attempts') }}
}

 

Splunk Configuration step

 

These picklist values are consumed while setting the Type on an Alert record as shown in the following image:

 

Setting the Type on an Alert record

 

TA-cybersponse-2.4.10.tar.gz