# Splunk Connector
The Splunk Connector assists in the integration between the workflow engine and the Splunk Enterprise REST API.
# Splunk Connector Configuration
The Splunk connector uses a combination of credential authentication and session tokens to access the REST API endpoints. It calls the Splunk login endpoint using a username and password to retrieve a session token which it stores in memory for a length of time determined by the environment's configured session timeout value. It then uses this session token to access the REST endpoints and retrieves a new token when the current token expires.
The authentication data is stored in an XML format. The XML format is shown below.
<connector>
<scenarios>
<scenario name="_scenario_name_" baseurl="_baseurl_" tokenexpireminutes="_#_of_minutes_" username="_username_" password="_method_3_encrypted_password_" tls="true_or_false" tls11="true_or_false" tls12="true_or_false" ssl3="true_or_false"></scenario>
</scenarios>
</connector>
Each action accepts a scenario name which needs to match the given scenario name found in this XML blob. Multiple scenarios can be defined by adding additional scenario nodes to this XML structure. This allows the connector to access multiple environments and/or use different credentials. The based URL attribute should be defined as shown below:
https://<host>:<mPort>
When configuring the baseurl keep in mind that the Splunk REST API uses the splunkd management port, 8089, and secure HTTPS protocol by default.
The password needs to be encrypted using method level 3 encryption. The transport layer security settings can also be set using a scenario. Each TLS version can be enabled by setting the attribute equal to "true" and disabled by setting the attribute equal to "false." For example, to only enable TLS 1.2 the TLS attributes would be configured as such:
tls=\"false\" tls11=\"false\" tls12=\"true \" ssl3=\"false\"
Note that the attribute "tls" corresponds with TLS 1.0, "tls11" corresponds with TLS 1.1, etc.
# Connector Actions
There are currently 9 Splunk actions in the connector palette. 8 of the 9 actions correspond to Splunk REST API endpoints. The "Clear Auth Token" action can be used if an authentication session token if saved in memory and the workflow designer, for whatever reason, decides that it needs to be cleared. It should be used for debugging or troubleshooting situations only and shouldn't be considered a standard or highly used action.
# Acknowledge
Action Function:
The "Acknowledge" action performs a POST request on the API endpoint:
Which acknowledges the saved search alert suppression with the name matching the "Search Name" action property to resume alerting.
Action Outputs:
Success
Failure
Action Properties:
Scenario: The name of the scenario defined in the connector configuration.
Search Name: The name of the saved search.
Suppression Key: The suppression key used in the field-based suppression.
Web Timeout: How long in seconds the HTTP request is given before timing out. Leave blank to use the default timeout setting.
Response Variable: A workflow variable which will hold the response of the request. The data format is JSON
Error Message Variable: A workflow variable which will hold the error message (if any)
Above shows a test configuration of the action which acknowledges the "AlertTest3" search using the scenario configured in the Scenario variable. The Suppression Key property, which is not set in the above example, is the suppression key used in field-based suppression.
The response will be saved to a variable and, if the action has an error, the error message will be saved to a variable. The Web Timeout property allows the workflow designer to provide a number of seconds the REST request will be before it times out. If it is not set, the default endpoint timeout of the Splunk environment will be used. These three properties along with the scenario property are present in all of the 8 Splunk REST API actions.
# Delete Saved Search
Action Function:
The "Delete Saved Search" action sends a DELETE request to the API endpoint:
This deletes the saved search matching the name specified in the "Search Name" property.
Action Outputs:
Success
Failure
Action Properties:
Scenario: The name of the scenario defined in the connector configuration.
Search Name: The name of the saved search.
Web Timeout: How long in seconds the HTTP request is given before timing out. Leave blank to use the default timeout setting.
Response Variable: A workflow variable which will hold the response of the request. The data format is JSON
Error Message Variable: A workflow variable which will hold the error message (if any)
# Dispatch
Action Function:
The "Dispatch" action sends a POST request to the endpoint:
Which dispatches the saved search corresponding to the name specified in the "Search Name" property.
Action Outputs:
Success
Failure
Action Properties:
Scenario: The name of the scenario defined in the connector configuration.
Search Name: The name of the saved search.
Web Timeout: How long in seconds the HTTP request is given before timing out. Leave blank to use the default timeout setting.
Response Variable: A workflow variable which will hold the response of the request. The data format is JSON
Error Message Variable: A workflow variable which will hold the error message (if any)
# Get Alert Actions
Action Function:
The "Get Alert Actions" performs a GET request on the following endpoint:
This lists all of the alert actions in Splunk. The output mode property gives the workflow designer the ability to select the desired response format from the endpoint. A value of "json" will return a JSON format and "xml" will return an XML format.
Action Outputs:
Success
Failure
Action Properties:
Scenario: The name of the scenario defined in the connector configuration.
Output Mode: Defines in what format the results should be returned in (JSON/XML).
Web Timeout: How long in seconds the HTTP request is given before timing out. Leave blank to use the default timeout setting.
Response Variable: A workflow variable which will hold the response of the request. The data format is JSON
Error Message Variable: A workflow variable which will hold the error message (if any)
# Get Fired Alerts
Action Function:
The "Get Fired Alerts" action sends a GET request to the following endpoints:
If the "Alert Name" property is not set, it'll send the request to the first endpoint, which will return a summary list of the fired alerts. If the alert name property is specified, it'll send the request to the second endpoint. The response, in this case, will be a list of unexpired triggered instance of the alert. The Max Alert Count property can be specified to limit the number of fired alerts returned. It is recommended that this property be used to limit the number of results returned.
Action Outputs:
Success
Failure
Action Properties:
Scenario: The name of the scenario defined in the connector configuration.
Alert Name: The name of the fired alert.
Max Alert Count: Sets a limit on the number of fired events returned.
Output Mode: Defines in what format the results should be returned in (JSON/XML).
Web Timeout: How long in seconds the HTTP request is given before timing out. Leave blank to use the default timeout setting.
Response Variable: A workflow variable which will hold the response of the request. The data format is JSON
Error Message Variable: A workflow variable which will hold the error message (if any)
# Get Saved Searches
Action Function:
The "Get Saved Searches" action sends a GET request to the endpoint:
This endpoint returns a list of the saved searches. It is highly recommended that the "Count" property be used to limit the number of saved searches returned. This endpoint can return a very large amount of data.
Action Outputs:
Success
Failure
Action Properties:
Scenario: The name of the scenario defined in the connector configuration.
Count : Limits the number of saved searches that are returned.
Output Mode: Defines in what format the results should be returned in (JSON/XML).
Web Timeout: How long in seconds the HTTP request is given before timing out. Leave blank to use the default timeout setting.
Response Variable: A workflow variable which will hold the response of the request. The data format is JSON
Error Message Variable: A workflow variable which will hold the error message (if any)
# Get Search History
Action Function:
The "Get Search History" sends a GET request to the endpoint:
This endpoint lists the available search jobs created by the saved search with the name specified in the property "Search Name."
Action Outputs:
Success
Failure
Action Properties:
Scenario: The name of the scenario defined in the connector configuration.
Search Name: The name of the saved search.
Output Mode: Defines in what format the results should be returned in (JSON/XML).
Web Timeout: How long in seconds the HTTP request is given before timing out. Leave blank to use the default timeout setting.
Response Variable: A workflow variable which will hold the response of the request. The data format is JSON
Error Message Variable: A workflow variable which will hold the error message (if any)
# Get Suppression State
Action Function:
The "Get Suppression State" action sends a GET request to the endpoint:
Which gets the saved search alert suppression state for the named search.
Action Outputs:
Success
Failure
Action Properties:
Scenario: The name of the scenario defined in the connector configuration.
Search Name: The name of the saved search.
Output Mode: Defines in what format the results should be returned in (JSON/XML).
Web Timeout: How long in seconds the HTTP request is given before timing out. Leave blank to use the default timeout setting.
Response Variable: A workflow variable which will hold the response of the request. The data format is JSON
Error Message Variable: A workflow variable which will hold the error message (if any)
