After the future removal of the classic playbook editor, your existing classic playbooks will continue to run, However, you will no longer be able to visualize or modify existing classic playbooks.
For details, see:
REST Run Playbook
Run a playbook against a container or check the playbook status.
/rest/playbook_run
Run a playbook against a container.
Syntax
https://<username>:<password>@<host>/rest/playbook_run
POST
Run a playbook against a container.
Request parameters
You can use the REST API to run a playbook against a container.
Field | Required | Type | Description |
---|---|---|---|
container_id | required | integer | Id of the container to run the playbook on. |
playbook_id | required | integer or string | The name of the playbook in the form "/". Also can be the Id of the playbook to run. |
scope | optional | list of integers or string | Can be a string containing "all" or "new" or a list of integers containing artifact Ids. This allows the playbook to be run against a specific set of artifacts. |
inputs | optional | JSON-encoded string | If specified, this value must be a JSON-encoded string with one or more key/value pairs, passed as an input for the child playbook that is called, specified by the "playbook_id" field. Be sure both of the following are true:
|
run | required | Boolean true. | Request the playbook to be run. |
Example request
This is a request to run the playbook "file_analysis" against the container with id 42. You can infer that the "file_analysis" playbook is an input playbook by the presence of the "inputs" key in the request.
curl -k -u username:password https://localhost/rest/playbook_run \ -d '{ "container_id": 42, "playbook_id": "local/file_analysis", "scope": "new", "run": true, "inputs": { "file_hash": "09ca7e4eaa6e8ae9c7d261167129184883644d07dfba7cbfbc4c8a2e08360d5b", "file_name": "hello.txt" } }'
Example response
A successful POST will return back an acknowledgement indicator and the ID of the newly created playbook run. Note that this API will only queue the playbook to run. The result indicates that the request is received, however the playbook may not successfully run (if there is a problem with the playbook, for example).
{ "playbook_run_id": "1", "received": true }
/rest/playbook_run/<id>
Check the status of a playbook run.
Syntax
https://<username>:<password>@<host>/rest/playbook_run/<id>
GET
Check the status of a playbook run.
Example request
Get the status of playbook run Id 46.
curl -k -u username:password https://localhost/rest/playbook_run/46 -G -X GET
Example response
A successful request returns a 200 response and a JSON object containing the status for the playbook.
{ "action_exec": [], "cancelled": "", "container": 24, "id": 46, "inputs": [ "{\"username\": \"mjj\"}" ], "outputs": [ "{\"user_id\": [23]}" ], "last_artifact": 160, "log_level": 1, "message": "{\"message\":\"\",\"playbook_run_id\":46,\"result\":[{\"action\":\"whois ip\",\"app_runs\":[{\"action\":\"whois ip\",\"action_run_id\":46,\"app_message\":\"Registry: arin\\nASN: 8075\\nCountry: US\\nNets:\\nRange: 134.170.0.0 - 134.170.255.255\\nAddress: One Microsoft Way\",\"app_name\":\"WHOIS\",\"app_run_id\":55,\"asset_name\":\"whois\",\"parameter\":\"{\\\"ip\\\": \\\"134.170.188.221\\\"}\",\"per_parameter_status\":\"success\"}],\"close_time\":\"2016-01-15T22:15:58.05319+00:00\",\"create_time\":\"2016-01-15T22:15:55.252+00:00\",\"id\":46,\"message\":\"1 actions succeeded\",\"status\":\"success\",\"type\":\"investigate\"},{\"action\":\"whois domain\",\"app_runs\":[{\"action\":\"whois domain\",\"action_run_id\":47,\"app_message\":\"Organization: Amazon Technologies, Inc.\\nDomain: amazon.com\\nCity: Reno\\nName: Hostmaster, Amazon Legal Dept.\\nCountry: US\",\"app_name\":\"WHOIS\",\"app_run_id\":56,\"asset_name\":\"whois\",\"parameter\":\"{\\\"domain\\\": \\\"amazon.com\\\"}\",\"per_parameter_status\":\"success\"}],\"close_time\":\"2016-01-15T22:16:00.798179+00:00\",\"create_time\":\"2016-01-15T22:15:58.062+00:00\",\"id\":47,\"message\":\"1 actions succeeded\",\"status\":\"success\",\"type\":\"investigate\"}],\"status\":\"success\"}\n", "owner": 4, "playbook": 42, "start_time": "2016-01-15T22:15:55.171000Z", "status": "success", "test_mode": false, "update_time": "2016-01-15T22:16:00.813027Z", "version": 1 }
The return values follow:
Field | Type | Description |
---|---|---|
action_exec | JSON | For internal use. |
cancelled | String | If the playbook was cancelled, this field will contain a message indicating why. |
container | Integer | ID of the container used in this run. |
id | Integer | ID of this playbook run. |
last_artifact | Integer | For internal use. |
log_level | Integer | Indicates if logging was enabled for this playbook run. |
message | String | Message. The string value contains a JSON object with details about the results of the action run. NOTE: Contents and/or data type of this field is likely to change in the future. |
owner | Integer | ID of the user who ran the playbook or null if there is no owner. |
inputs | JSON-encoded string | If this optional parameter is specified, this value must be a JSON-encoded string with one or more key/value pairs, passed as an input for the child playbook that is called, specified by the "playbook_id" field. Be sure both of the following are true:
|
outputs | JSON-encoded string | JSON-encoded string with the outputs of the playbook run. Applicable only to input type playbooks. This value will always be null for automation playbooks. |
playbook | Integer | ID of the playbook used for this run. |
start_time | ISO 8601 formatted timestamp | Timestamp (UTC) of when the playbook run was started. |
status | String | Status of the playbook. One of the following:
|
test_mode | Boolean | Request the playbook to be run. |
update_time | ISO 8601 formatted timestamp | Timestamp (UTC) of when the playbook run was last active. |
version | Integer | For internal use. Schema version. |
POST
Cancel a running playbook.
Example request
Cancel playbook run Id 46.
curl -k -u username:password https://localhost/rest/playbook_run/46 \ -d '{ "cancel": true }'
Example response
A successful POST will return a descriptive message and success indicator.
Success response body: { "cancelled": true, "message": "<detail>" } Error response body: { "failed": true, "message": "<reason>" }
REST Run Action | REST Severity |
This documentation applies to the following versions of Splunk® SOAR (On-premises): 6.0.0, 6.0.1, 6.0.2, 6.1.0, 6.1.1, 6.2.0, 6.2.1, 6.2.2, 6.3.0
Feedback submitted, thanks!