REST Asset

Assets are specific instances of physical or virtual devices within your organization such as servers, endpoints, routers, and firewalls. See About Splunk SOAR (Cloud).

/rest/asset

Syntax

https://<username>:<password>@<host>/rest/asset

POST

Create a new asset.

Request string

An argument string must include one of the following sets of fields:

app_id
app_guid
name, product_name, product_vendor

For polling an asset, an argument string must include the following sets of fields:

Either:
- app_id
- app_guid
- name, product_name, product_vendor
And:
- container_label
- interval_mins
- poll
- start_time_epoch_utc


Field	Required	Type	Description
app_id	required	string	The unique id for the App used by the asset. Used when invoking an action on this asset. Required unless you specify the `app_guid` or the `name`, `product_name`, `product_vendor`.
app_guid	required	string	The GUID for the App used by the asset. Used when invoking an action on this asset. Required unless you specify the `app_id` or the `name`, `product_name`, `product_vendor`.
automation_broker_id	optional	integer	Provide the ID of an automation broker to link action execution for this asset with a specific automation broker. Providing a null value removes the link. Not including this field will leave any existing link unchanged. For GET requests, the current value is returned in the `automation_broker` field.
configuration	optional	JSON Object	Key value pairs for asset configuration. Required and optional values are defined by Apps which support this asset. See individual App documentation for more information.
container_label	required for polling	string	Label for containers created by this asset. This will determine where the container will be found from the main menu. For example, using "incident" here will allow you to find the container by going to Home -> Incidents.
description	optional	string	Description of the asset.
interval_mins	required for polling	number	Polling frequency for new containers/artifacts in minutes. Not specified or null for assets that do not poll.
name	required	string	Short name for the asset. Used when invoking an action on this asset.
poll	required for polling	boolean	Set to "true" to enable polling.
primary_owners	optional	Array of integers	Contains the list of user IDs which are the primary owners of this asset.
primary_voting	optional	integer	Number of "approve" votes required for action to be executed. Use 0 to require all votes.
product_name	required	string	Name of the product which this asset describes. Must match the product_name provided by one or more Apps. Example: If this asset refers to a Windows Server 2008 machine and an App supports a product_name of "Server 2008" then that is the correct value.
product_vendor	required	string	Name of the vendor of the product which this asset describes. Must match the product_vendor provided by one or more Apps. Example: If this asset refers to a Windows Server 2008 machine and an App supports a product_vendor of "Windows" then that is the correct value.
secondary_users	optional	Array of integers	Contains the list of user IDs which are the secondary (backup) owners of this asset.
secondary_voting	optional	integer	Number of "approve" votes required for action to be executed for secondary users. Use 0 to require all votes.
start_time_epoch_utc	required for polling	number	First poll time as seconds since epoch UTC. Use null to poll immediately.
tags	optional	Array of strings	0 or more tags associated with the asset. A simple string can also be used for a single tag.
type	optional	string	A brief categorization of this asset.
action_whitelist	optional	dictionary	A dictionary object which contains actions and that is allowed (whitelisted) to run the action. A star may be used in place of action name, users, or roles to indicate all. `;{"action": {"roles": ["7"]}} : indicates users in role 7 are approved to : run 'action'. ; {"": {"roles": ["7"], "users": ["6"]} : indicates users in role 7 and user 6 are : approved to run all actions. ; {"action": {"users": [""]} : indicates all users are approved to : run 'action'.`
tenants	optional	Array of integers	Contains the list of tenant IDs which are to be associated with this asset. Only one tenant is allowed on ingestion assets, trying to add more will return an error. Tenants will only be added or removed based on the acting user's permissions, i.e. passing an empty list will remove all tenants from an asset for which the user has permission to edit.
_reserved_jitc	optional	JSON Object	This key should reside under "configuration". Keys in this object are the names of configuration parameters. These configuration parameters will not be stored in the database and must be provided each time actions are run by an asset owner or the action will fail. The values are always a literal "true". Note: This can be used for sensitive asset credentials. At least one asset owner must be selected for actions to succeed if this feature is used. Cannot be used on assets that perform ingestion.

Response

A success or failure message.

Example request

Add a new asset as follows:

curl -k -u username:password https://localhost/rest/asset \
-d '{
	"configuration": {
		"foo": "bar"
	},
	"description": "My Generic/Product asset.",
	"name": "my asset",
	"primary_owners": [12],
	"primary_voting": 0,
	"product_name": "Product",
	"product_vendor": "Generic",
	"secondary_users": [],
	"secondary_voting": 0,
	"tags": ["tag1", "tag2"],
	"type": "information service",
	"action_whitelist": {
		"generic action": {
			"roles": ["7"],
			"users": ["6"]
		}
	},
	"tenants": [23, 10, 9]
}'

Example response

A successful POST will return back a success indicator and the ID of the newly created asset.

{
    "id": 34,
    "success": true
}

Example request

Create an asset preconfigured and enabled for polling to ingest data:

curl -k -u username:password https://localhost/rest/asset \
-d '{
  "configuration": {
    "foo": "bar",
    "ingest": {
        "container_label": incident",
        "interval_mins": 120,
        "poll":  true,
        "start_time_epoch_utc": null
    },
    ...
  },
  "description": "My Generic/Product asset.",
  ...
}'

Example response

A successful POST will return back a success indicator and the ID of the newly created asset.

{
    "id": 34,
    "success": true
}

CAUTION: If you use this API to update an asset, any value you do not submit in your POST is reset to its default value. Partial updates are not recommended.

Documentation

REST Asset

/rest/asset

POST