Splunk® SOAR (On-premises)

REST API Reference for Splunk SOAR (On-premises)

Acrobat logo Download manual as PDF


This documentation does not apply to the most recent version of Splunk® SOAR (On-premises). For documentation on the most recent version, go to the latest release.
Acrobat logo Download topic as PDF

REST Asset

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

/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.
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 who is 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".

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 admin:changeme 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 admin:changeme 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
}

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.

Last modified on 08 March, 2023
PREVIOUS
REST Artifact
  NEXT
REST Audit

This documentation applies to the following versions of Splunk® SOAR (On-premises): 5.2.1, 5.3.1, 5.3.2, 5.3.3, 5.3.4, 5.3.5, 5.3.6


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