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 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.

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 "file reputation" against container Id 42 .

curl -k -u admin:changeme https://localhost/rest/action_run \
-d '{
	"action": "file reputation",
	"container_id": 42,
	"name": "my action",
	"targets": [{
		"assets": [
			"my_reversinglabs_asset"
		],
		"parameters": [{
			"hash": "98dbaeb6d46bd09eca002e1f2b6f3e76fd3222cd"
		}],
		"app_id": 12
	}],
	"type": "investigative"
}'

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 admin:changeme 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 admin:changeme 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:
  • failed
  • pending
  • running
  • success
targets JSON See targets section above.
type String The type of action. Types include...
  • contain
  • correct
  • investigate
  • manual
  • etc.
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 admin:changeme 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 admin:changeme 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 JSON array of strings. The assets to run the command on. Can be asset names or asset IDs.
app Integer The numeric ID of the app the action was run on.
app_name String Name of the app.
app_version Integer 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:
  • failed
  • pending
  • running
  • success
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.
Last modified on 05 August, 2022
PREVIOUS
REST Roles and Permissions
  NEXT
REST Run Playbook

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


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