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