Splunk® SOAR (On-premises)

REST API Reference for Splunk SOAR (On-premises)

Acrobat logo Download manual as PDF


Acrobat logo Download topic as PDF

REST Playbook

/rest/playbook/<id>

Updates a playbook.

Syntax

https://<username>:<password>@<host>/rest/playbook/<id>

POST

Toggle the status of a playbook between active and inactive. This determines whether or not the playbook will start automatically when an event is ingested with a label matching the playbook's label.

Request parameters
Playbooks are modified with the following parameters. No other fields can be updated.

Field Required Type Description
active Optional boolean Sets the playbook as active or inactive, when active, the playbook will run on ingested events with a corresponding label. Playbooks in draft mode cannot be marked active.
cancel_runs Optional boolean Setting this to true when transitioning from active to inactive will cancel any current playbook runs associated with the playbook.

Example request
Set playbook Id 42 as inactive and cancel the playbook runs.

curl -k -u admin:changeme https://localhost/rest/playbook/42 \
-d '{
  "active": false,
  "cancel_runs": true
}'

Example response
A successful POST returns a descriptive message and success indicator.

{
    "message": "Operation successful",
    "success": true
}

/rest/import_playbook

POST

Imports a playbook.

Request parameters

Field Required Type Description
playbook Required String The base64 encoded playbook TAR file that you want to import.
scm/scm_id Required Name or ID of the repository The repository where the playbook is saved.
force Optional boolean Set to true to override an existing playbook in the same repository with the same name.

Example request
Imports a playbook.

curl -k -u admin:changeme https://localhost/rest/import_playbook \
-d '{
  "playbook": "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",
	"scm": "local",
	"force": "true"
}'

Example response
A successful POST returns a success indicator and an import message.

{
    "success": true,
    "message": [
        true,
        "Playbook \"example_playbook\" imported"
    ]
}


/rest/playbook/<id>/export

GET

Exports a playbook.

Example request
Export a playbook.

curl -k -u admin:changeme --output <FILE> https://localhost/rest/playbook/1/export 

Example response
A successful GET returns an x-gzip file to the location set in the --output flag.


/rest/playbook_resource_usage/<playbook_id>

GET

Gets the playbook run statistics for a specific playbook.

Request parameters

Field Required Type Description
block_names Optional List Filters on specified list of block names.
playbook_run_ids Optional List Calculates the playbook run statistics for the specified playbook using only the specified list of playbook run IDs.
playbook_run_ids and time_range are mutually exclusive.
time_range Optional List with 2 elements: start_time and end_time Calculates the playbook run statistics for a given playbook only for playbook runs in that time range. Express the start and end of the time_range with only dates (['2022-09-13', '2022-09-14']) or with both dates and times (['2022-09-13T17:00', '2022-09-14T17:00']).
time_range and playbook_run_ids are mutually exclusive.



The following requests return similar responses. A sample response is provided at the end of this list.

Example request using playbook ID
Get the playbook run statistics for playbook 27.

curl -k -u admin:changeme https://localhost/rest/playbook_resource_usage/27

Example request using time_range
Get the playbook run statistics for playbook 27 between 5:00pm on September 13, 2022 and 5:00pm on September 14, 2022.

curl -k -u admin:changeme https://localhost/rest/playbook_resource_usage/27?time_range=['2022-09-13T17:00', '2022-09-14T17:00']

Example request using playbook ID and specific playbook run IDs
Get the playbook run statistics for playbook 27 for playbook runs 40 and 41.

curl -k -u admin:changeme https://localhost/rest/playbook_resource_usage/27?playbook_run_id=[40,41]


Example response using any of the previously mentioned example requests
Depending on the request used, the exact response might differ from this example response.
Each top-level name, like geolocate_ip_1 and on_finish, corresponds to the name of a function in the playbook.

{
    "filter_1": {
        "avg_http_bytes_in_requests": 0,
        "avg_http_bytes_in_responses": 0,
        "avg_http_number_requests": 0,
        "avg_http_latency": "0:00:00",
        "avg_db_number_queries": 16,
        "avg_db_query_latency": "0:00:00.039000",
        "avg_duration": "0:00:00.025333",
        "times_called": 3,
        "times_succeeded": 3,
        "custom_function_scores": []
    },
    "geolocate_ip_1": {
        "avg_http_bytes_in_requests": 0,
        "avg_http_bytes_in_responses": 0,
        "avg_http_number_requests": 0,
        "avg_http_latency": "0:00:00",
        "avg_db_number_queries": 7,
        "avg_db_query_latency": "0:00:00.018000",
        "avg_duration": "0:00:00.022333",
        "times_called": 3,
        "times_succeeded": 3,
        "custom_function_scores": []
    },
    "join_random_get_requests": {
        "avg_http_bytes_in_requests": 0,
        "avg_http_bytes_in_responses": 0,
        "avg_http_number_requests": 0,
        "avg_http_latency": "0:00:00",
        "avg_db_number_queries": 5,
        "avg_db_query_latency": "0:00:00.008500",
        "avg_duration": "0:00:00.121833",
        "times_called": 6,
        "times_succeeded": 6,
        "custom_function_scores": []
    },
    "on_finish": {
        "avg_http_bytes_in_requests": 0,
        "avg_http_bytes_in_responses": 0,
        "avg_http_number_requests": 0,
        "avg_http_latency": "0:00:00",
        "avg_db_number_queries": 1,
        "avg_db_query_latency": "0:00:00.002000",
        "avg_duration": "0:00:00.002000",
        "times_called": 3,
        "times_succeeded": 3,
        "custom_function_scores": []
    },
    "on_start": {
        "avg_http_bytes_in_requests": 0,
        "avg_http_bytes_in_responses": 0,
        "avg_http_number_requests": 0,
        "avg_http_latency": "0:00:00",
        "avg_db_number_queries": 8,
        "avg_db_query_latency": "0:00:00.004000",
        "avg_duration": "0:00:00.058000",
        "times_called": 3,
        "times_succeeded": 3,
        "custom_function_scores": []
    },
    "random_get_requests": {
        "avg_http_bytes_in_requests": 0,
        "avg_http_bytes_in_responses": 14868,
        "avg_http_number_requests": 2,
        "avg_http_latency": "0:00:00.200000",
        "avg_db_number_queries": 3,
        "avg_db_query_latency": "0:00:00.007000",
        "avg_duration": "0:00:00.231000",
        "times_called": 3,
        "times_succeeded": 3,
        "custom_function_scores": []
    },
    "resource_score_cf_1": {
        "avg_http_bytes_in_requests": 0,
        "avg_http_bytes_in_responses": 0,
        "avg_http_number_requests": 0,
        "avg_http_latency": "0:00:00",
        "avg_db_number_queries": 3,
        "avg_db_query_latency": "0:00:00.006000",
        "avg_duration": "0:00:00.026000",
        "times_called": 3,
        "times_succeeded": 3,
        "custom_function_scores": [
            {
                "avg_http_bytes_in_requests": 0,
                "avg_http_bytes_in_responses": 0,
                "avg_http_number_requests": 0,
                "avg_http_latency": "0:00:00",
                "avg_db_number_queries": 0,
                "avg_db_query_latency": "0:00:00",
                "avg_duration": "0:00:00.000667",
                "times_called": 3,
                "times_succeeded": 3,
                "custom_function_id": 85,
                "custom_function_name": "resource_score_cf",
                "custom_function_scm": "local"
            }
        ]
    }
}


Example request using playbook ID and specific playbook block names
Get the playbook run statistics for all runs of playbook 27 between 5:00pm on September 13, 2022 and 5:00pm on September 14, 2022 for playbook block names on_start and geolocate_ip_1.

curl -k -u admin:changeme https://localhost/rest/playbook_resource_usage/27?time_range=['2022-09-13T17:00', '2022-09-14T17:00']&block_names=['on_start', 'geolocate_ip_1']


You can also combine the block names with specific playbook run IDs or with a time_range.

  • Example request using playbook ID, specific playbook run IDs, and specific playbook block names
    Get the playbook run statistics for playbook 27, run IDs 40 and 41, for playbook block names on_start and geolocate_ip_1.
    curl -k -u admin:changeme https://localhost/rest/playbook_resource_usage/27?playbook_run_id=[40,41]&block_names=['on_start', 'geolocate_ip_1']
    
  • Example request using playbook ID, a specific time_frame, and specific playbook block names
    Get the playbook run statistics for all runs of playbook 27 between 5:00pm on September 13, 2022 and 5:00pm on September 14, 2022 for playbook block names on_start and geolocate_ip_1.
    curl -k -u admin:changeme https://localhost/rest/playbook_resource_usage/27?time_range=['2022-09-13T17:00', '2022-09-14T17:00']&block_names=['on_start', 'geolocate_ip_1']
    

Example response using time_range and specific playbook block names
A successful GET returns all of the playbook run statistics for the specified playbook within the specified date/time span, for the specific block names.

{
    "on_start": {
        "avg_http_bytes_in_requests": 0,
        "avg_http_bytes_in_responses": 0,
        "avg_http_number_requests": 0,
        "avg_http_latency": "0:00:00",
        "avg_db_number_queries": 8,
        "avg_db_query_latency": "0:00:00.004000",
        "avg_duration": "0:00:00.058000",
        "times_called": 3,
        "times_succeeded": 3,
        "custom_function_scores": []
    },
     "geolocate_ip_1": {
        "avg_http_bytes_in_requests": 0,
        "avg_http_bytes_in_responses": 0,
        "avg_http_number_requests": 0,
        "avg_http_latency": "0:00:00",
        "avg_db_number_queries": 7,
        "avg_db_query_latency": "0:00:00.018000",
        "avg_duration": "0:00:00.022333",
        "times_called": 3,
        "times_succeeded": 3,
        "custom_function_scores": []
    }
}

Notes:

  • Custom functions have section titles including _cf and are associated with the blocks that call them. Statistics can show custom code that includes multiple, consecutive phantom.custom_function() calls.
  • Statistics are not provided for action/app runs, but are provided for the playbook block that runs the action/apps. Statistics show the time taken for the block to complete, not for the action to complete. Even if the action fails, the statistics might show the block as a success because the block successfully started the action.
Last modified on 22 July, 2022
PREVIOUS
REST Notification
  NEXT
REST Roles and Permissions

This documentation applies to the following versions of Splunk® SOAR (On-premises): 5.3.1, 5.3.2, 5.3.3, 5.3.4, 5.3.5


Was this documentation topic helpful?


You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters