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
Running playbooks are modified with the following parameters. No other fields can be updated at this time.

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.
run	required	Boolean true.	Request the playbook to be run.

Example request
Run the container Id "my_playbook" against container 42.

curl -k -u admin:changeme https://localhost/rest/playbook_run \
-d '{
	"container_id": 42,
	"playbook_id": "my_playbook",
	"scope": "new",
	"run": true
}'

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 admin:changeme 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,
	"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.
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	Request the playbook to be run. One of the following: failed running success
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 admin:changeme 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>"
}