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 Action
Run an action using a REST request.
/rest/action_run
Run an action against a container.
Syntax
https://<username>:<password>@<host>/rest/action_run
POST
Run an action against a container.
Request parameters
Actions are modified with the following parameters.
Field | Required | Type | Description |
---|---|---|---|
action | required | String. | Name of the action to be run. (e.g. "file reputation", "block ip" etc.) |
container_id | required | integer | Id of the container to run the action on. |
name | required | String. | Name for this action. |
targets | required | JSON Array of Objects. | Specifies one or more combinations of assets/app/parameters. See below for details. |
type | optional | String. | Categorization for the action. |
assets | Optional depending on command. (See the documentation for the App/action being run.) | JSON array of strings. | The assets to run the command on. Can be asset names or asset IDs. |
app_id | required | String. | Identifies the App that will run the command. Can be the app GUID or the app's numeric ID. |
parameters | Optional depending on command (See the documentation for the App/action being run.) | JSON Array of Objects | An array of sets of parameters. Each entry in the list is a JSON Object containing the parameters for action being run. |
exec_delay_secs | Optional | Integer | If action is to be carried out in the future, this is the initial delay before running the action. |
Actions will not always require both assets and parameters, although at least one will be required. If the assets or the parameters value is not required, that value can be an empty array or it can be omitted. To see what is required for an action, see the App documentation for that action.
Example request
Run an action named "whois domain" against container ID 161 .
curl -k -u username:password https://localhost/rest/action_run \ -d '{ "action": "whois domain", "container_id": 1234, "exec_delay_secs": 30, "name": "test my action delay", "targets": [ {"app_id": 161, "assets": [2], "parameters": [{"domain": "splunk.com"}]} ] }
Example response
A successful POST will return back a descriptive message, a success indicator and the ID of the newly created action run.
{ "action_run_id": 2, "message": "New action queued.", "success": true }
Example request
Actions can be run on multiple assets using a specified App. The App will take a specific set of parameters for that action. The targets section of the run action JSON will allow you to run several variations of the same action in one call. For example, to run the same command on 3 different hashes:
curl -k -u username:password https://localhost/rest/action_run \ -d '{ "action": "file reputation", "container_id": 42, "name": "my action", "targets": [{ "assets": [ "my_reversinglabs_asset" ], "parameters": [{ "hash": "<hash 1>" }, { "hash": "<hash 2>" }, { "hash": "<hash 3>" } ], "app_id": 12 }], "type": "investigative" }'
/rest/action_run/<id>
Once you have run an action, you may want to check its status or cancel it.
Syntax
https://<username>:<password>@<host>/rest/action_run/<id>
GET
Check the status of an existing run action.
Request string
An argument string must include the action_run_id
.
Response
A success or failure message.
Example request
Check the status of action run Id 2.
curl -k -u username:password https://localhost/rest/action_run/2 -G -X GET
Example response
A successful GET will return a JSON object with the action details.
{ "action": "whois domain", "assign_time": "2016-01-15T22:15:58.062000Z", "cancelled": "", "cb_fn": "whois_domain_cb", "close_time": "2016-01-15T22:16:00.798179Z", "comment": "", "container": 24, "create_time": "2016-01-15T22:15:58.062000Z", "creator": null, "due_time": "2016-01-12T14:32:30.810000Z", "exec_delay_secs": 0, "exec_order": 0, "handle": "", "id": 47, "message": "1 actions succeeded", "name": "automated action 'whois domain' of 'whois_app' playbook", "owner": null, "playbook": 42, "playbook_run": 46, "status": "success", "targets": [{ "app_id": 23, "assets": [ 119 ], "parameters": [{ "domain": "amazon.com" }] }], "type": "investigate", "update_time": "2016-01-15T22:16:00.798179Z", "version": 1 }
The return values follow:
Field | Type | Description |
---|---|---|
action | String | Action that was run. |
assign_time | ISO 8601 formatted timestamp | For manual actions, this is the time (UTC) at which the action was assigned to the owner. |
cancelled | String | If the playbook was cancelled, this field will contain a message indicating why. |
cb_fn | String | For Internal use. |
close_time | ISO 8601 formatted timestamp | Timestamp (UTC) when this action completed/ended. |
comment | String | For manual actions. Initial comment describing the task. |
container | Integer | ID of the container on which this action was run. |
create_time | ISO 8601 formatted timestamp | Timestamp (UTC) when this action was created. |
creator | Integer | ID of the user who created the action or null if created from automation. |
due_time | ISO 8601 formatted timestamp | Timestamp (UTC) when this action is due ( time at which the SLA expires/expired ). |
exec_delay_secs | Integer | If action is to be carried out in the future, this is the initial delay before running the action. |
exec_order | Integer | For Internal use. |
handle | Integer | For Internal use. |
id | Integer | ID of this action run. |
message | String. | Indicates progress or results of action. |
name | String | Name assigned to this action run. |
owner | Integer | ID of the user who ran the playbook or null if there is no owner. |
playbook | Integer | ID of the playbook used for this run. |
playbook_run | Integer | If run from a playbook, ID of the playbook_run. |
start_time | ISO 8601 formatted timestamp | Timestamp (UTC) of when the playbook run was started. |
status | String | Status of the action run. Status equals one of the following values:
|
targets | JSON | See targets section above. |
type | String | The type of action. Types include...
|
update_time | ISO 8601 formatted timestamp | Timestamp (UTC) of when the action run was last active. |
version | Integer | For internal use. Schema version. |
POST
Cancel a running action.
Example request
Cancel action run Id 2.
curl -k -u username:password https://localhost/rest/action_run/2 \ -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/action_run/<id>/app_runs
Retrieve the app action results.
Syntax
https://<username>:<password>@<host>/rest/action_run/<id>/app_runs
GET
Retrieve the app action results.
Example request
curl -k -u username:password https://localhost/rest/action_run/2/app_runs
Example response
A successful GET returns the action app results if available.
{ "count": 1, "num_pages": 1, "data": [ { "id": 15, "action": "whois domain", "action_run": 2, "asset": 5, "app": 190, "app_name": "WHOIS", "app_version": "2.0.7", "container": 337, "end_time": "2020-07-07T21:35:55.645000Z", "exception_occured": false, "message": "'user initiated whois domain action' on asset 'whois': 1 action succeeded. (1)For Parameter: {\"domain\":\"example.com\"} Message: \"Domain: example.com, Organization: Example, Inc., Name: Host, Example Inc., City: San Jose, Country: US\"", "playbook_run": null, "start_time": "2020-07-07T21:35:53.231000Z", "status": "success", "version": 1 } ] }
The return values follow:
Field | Type | Description |
---|---|---|
id | Integer | ID of this action run. |
action | String | Action that was run. |
action_run | Integer | The number of actions in the action run. |
asset | Integer | The ID of the asset that the action was run on. |
app | Integer | The numeric ID of the app the action was run on. |
app_name | String | Name of the app. |
app_version | String | Version of the app. |
container | Integer | Numeric ID of the container. |
end_time | ISO 8601 formatted timestamp | The time the action run completed. |
exception_occured | Boolean | Whether an exception occurred or not. |
message | String | Indicates progress or results of action. |
playbook_run | Integer | If run from a playbook, ID of the playbook_run. |
start_time | ISO 8601 formatted timestamp | Timestamp (UTC) of when the playbook run was started. |
status | String | Request the playbook to be run. One of the following:
|
version | Integer | For internal use. Schema version. |
/rest/app_run
Get the results of an app's run, based on parameters you specify.
Syntax
https://<username>:<password>@<host>/rest/app_run
GET
Check the app action run result data.
Example request
Check the status of the app action run results.
/rest/app_run/{app_run.id}/action_result
Add pagination query parameters.
/rest/app_run/1/action_result?page=0&page_size=5
Example response
A successful GET will return a JSON object with the app action run results.
{ "count":1, "num_pages":1, "data":[ { "data":[ { "latitude":20, "longitude":77, "time_zone":"Asia/Kolkata", "country_name":"India", "continent_name":"Asia", "country_iso_code":"IN" } ], "status":"success", "message":"Country: India", "summary":{ "country":"India" }, "parameter":{ "ip":"103.230.84.239", "context":{ "guid":"22070b58-353f-4ba7-94ed-b4a8228fe93f", "artifact_id":0, "parent_action_run":[ ] } } } ] }
The return values follow:
Field | Type | Description |
---|---|---|
context | Object | The context around how the app action is executed. For example, the server and artifact the app action is invoked against and the action run using this app. |
count | Integer | The number of app runs. |
data | Object | Contains the data from the app run. |
ip | String | The IP address of the app action run. |
message | String | Indicates progress or results of the action. |
parameter | Object | Parameters that are passed into an app action to be executed. |
num_pages | Integer | Pagination of the app run. |
status | Boolean | Whether or not the app action run was successful or not. Options include either "success" or "failure". |
summary | Object | The summary of the action run result. |
/rest/app_run/{app_run.id}
Check the results of a single app run.
GET
Check the results of a single app run.
Example request
Check the results of a single app run.
/rest/app_run/{app_run.id}
Example response
A successful GET will return a JSON object with the results of a single app run.
{ "id":7, "action":"check python version", "action_run":6, "asset":229, "app":191, "app_name":"QA App Py3", "app_version":"2.0.3", "container":331, "end_time":"2022-01-26T23:49:40.871000Z", "exception_occured":false, "extra_data":[ ], "message":"'check python version' on asset 'qa_app_py3': 1 action succeeded. (1)For Parameter: {\"context\":{\"artifact_id\":0,\"guid\":\"99d948fc-6490-4143-ae2b-f93682fc6e11\",\"parent_action_run\":[]}}None Message: \"Running in python version 3.6.15+, which matches the expected python version 3\"", "result_summary":{ "total_objects":1, "total_objects_successful":1 }, "result_data":[ { "data":[ ], "status":"success", "message":"Running in python version 3.6.15+, which matches the expected python version 3", "summary":{ }, "parameter":{ "context":{ "guid":"99d948fc-6490-4143-ae2b-f93682fc6e11", "artifact_id":0, "parent_action_run":[ ] } } } ], "playbook_run":null, "start_time":"2022-01-26T23:49:40.307000Z", "status":"success", "version":1, "effective_user":1, "node_guid":"ec05c5c5-0e22-4f3e-a48d-48a67f498dc3", "automation_broker":null }
The return values follow:
Field | Type | Description |
---|---|---|
action | String | The description of the action being run on the app. |
action_run | Integer | The ID of the related action run. |
app | Integer | The ID of the related app. |
app_name | String | The name of the related app. |
app_version | Integer | The version of the related app. |
asset | Integer | The ID of the related asset. |
automation_broker | ID | The ID of the automation broker, if applicable. |
container | Integer | The ID of the container that the app ran on. |
context | Object | The context around how the app action is executed. For example, the server and artifact the app action is invoked against and the action run using this app. |
effective_user | Integer | The user ID of the user executing the action. |
end_time | ISO 8601 formatted timestamp | Timestamp (UTC) when the app run ended. |
exception_occurred | Boolean | Whether or not an exception occurred to block the app run. Available options are "true" or "false". |
id | Integer | The ID of the app run. |
message | String | Indicates progress or results of the app run. |
node_guid | String | The unique identifier of the server that is running the action. |
parameter | Object | Parameters that are passed into an app action to be executed. |
playbook_run | Integer | If run from a playbook, the ID of the playbook run. |
result_summary | Object | The summary of the result of the app run. |
start_time | ISO 8601 formatted timestamp | Timestamp (UTC) of when the action run was started. |
status | Boolean | Indicates the status of the action run. Available options are "success" or "failure". |
version | Integer | The version of the app. |
REST Roles and Permissions | REST Run Playbook |
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!