Splunk® Phantom

REST API Reference for Splunk Phantom

Acrobat logo Download manual as PDF


This documentation does not apply to the most recent version of Phantom. Click here for the latest version.
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 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.
Last modified on 16 November, 2020
PREVIOUS
REST Roles and Permissions
  NEXT
REST Run Playbook

This documentation applies to the following versions of Splunk® Phantom: 4.8, 4.9, 4.10, 4.10.1, 4.10.2, 4.10.3, 4.10.4, 4.10.6, 4.10.7


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