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	Request the playbook to be run. One of the following: 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.