Splunk® SOAR (On-premises)

REST API Reference for Splunk SOAR (On-premises)

The classic playbook editor will be deprecated in early 2025. Convert your classic playbooks to modern mode.
After the future removal of the classic playbook editor, your existing classic playbooks will continue to run, However, you will no longer be able to visualize or modify existing classic playbooks.
For details, see:

REST Roles and Permissions

With the exception of "container_labels","repository", and "tenant" you can only have one permission of a given name/type per role. You can have multiple of these types of permissions if they specify access to different names (specified in the "extra" field).

Users that have no named object permissions in any role they are assigned to will have access to all of them. As soon as a named object permission is added to any role, then users will be restricted to only the whitelisted objects.

For example, if a user only has roles with the "basic permissions" (no roles containing any container_labels, repository, or tenant permissions) then that user will have access to ALL of the objects for each of those types. The moment the user is given a named object permission (for example, a "container label" of "archer incident") then the access is ONLY to archer incident containers, and none of the others. Though, if only container_labels permissions are specified in one or more of the user's roles, then the user would still have access to ALL repositories and tenants.

Also note that roles are additive, so if a user previously had access to all container labels because none of the roles specified any, and then you grant the user a role that specifies "archer incident", now the user only has archer incident. If you add two roles, one that has "archer incident" and one that has "campaign", then that user now has those two and no others.

/rest/role

Manage roles and permissions.

Syntax

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


POST

Create a new role with permissions.

The body of the request is a JSON object with the following fields.

Field Required Type Description
add_users optional JSON Array An array of integers that are the user IDs for users to be added to this role. (Used to update a record.)
description required string Description of the new role.
immutable read-only boolean True if the role may not be modified. This is true for standard roles shipped with and false for user-created roles.
name required string Name of the new role.
permissions optional JSON Array An array of JSON Objects describing the permissions for the role. This value overrides update_permissions and replaces existing permissions with the provided set. See Permissions below. Note that this is optional but a role with no permissions does not provide any functionality.
remove_users optional JSON Array Array of integers that are user IDs to be removed from the role. (Used to update a record.)
update_permissions optional JSON Array Used to add or modify existing set of permissions. Only one permission can exist with a given name per role. If update_permissions contains an existing name, the matching permission will be updated. Otherwise a new permission will be created with the new name. See Permissions below.
users optional JSON Array Array of integers that are user IDs. This sets or completely replaces the user's assigned to this role. Overrides add_users and remove_users.

Permissions objects are defined by the following JSON object.

Field Required Type Description
edit optional boolean Permission allows modification of the specified part of the system.
execute optional boolean Permission allows execution of actions or playbooks. (Only applies to the "playbooks" permission.)
extra optional boolean Field for specifying additional information about the permission. For the "container_labels", "repository", and "tenant" permissions, the value of the field should be the object name. For example, for the local repository, use "local" as the value for the extra field.
object_id optional integer Used for the "tenant" and "repository" permissions, in which case it is the id corresponding to the name of the tenant or repository provided in extra field. When used to set repository permissions in multi-tenant systems, the object_id is required.
delete optional boolean Permission allows deletion of the specified part of the system.
name required string Name of the permission. This specifies which part of the system the permissions are applied to. Valid values are as follows:
  • "apps": Allows view/modification/install of apps.
  • "assets": Allows view/modification of assets.
  • "containers": Allows view/modification of containers and artifacts. Can also see action and playbook executions.
  • "container_labels": Restricts interaction with containers to whitelisted labels. Makes use of the "extra" field. Can be duplicated.
  • "repository": Restricts users with this role to whitelisted repositories. Makes use of the "extra" field. Can be duplicated.
  • "tenant": Restricts users with this role to whitelisted tenants. Makes use of the "extra" field. Can be duplicated.
  • "playbooks": Allows view/modification/execution of playbooks and execution of actions.
  • "system_settings": Allows view/modification of system settings.
  • "users_roles": Allows view/modification of users and roles.
view optional boolean Permission allows user to view of the specified part of the system.

Example request
Create a new role with permissions and assign it to users.

curl -k -u soar_local_admin:changeme https://localhost/rest/role \
-d '{
    "name": "newrole",
    "description": "Description of newrole",
    "users": [4, 7, 13, 169],
    "permissions": [
        {
            "name": "containers",
            "view": true,
            "edit": false,
            "delete": false,
            "extra": "incidents"
        },
        {
            "name": "playbooks",
            "view": true,
            "edit": true,
            "execute": true
        }
    ]
}'

Example response
A successful POST will return a success indicator and the Id of the newly created role.

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

/rest/role/<role_id>

Manage an existing role or permission.

POST

Update an existing role.

The body of the request is a JSON object with the same fields as /rest/role

Example request
Update role Id 7 with revised users and permissions.

curl -k -u soar_local_admin:changeme https://localhost/rest/role/7 \
-d '{
    "add_users": [20, 38],
    "remove_users": [13, 169],
    "update_permissions": [
        {
            "name": "containers",
            "edit": true
        },
        {
            "name": "playbooks",
            "view": false,
            "edit": false,
            "execute": false
        }
    ]
}'

Example response
A successful POST will return a success indicator and the Id of the revised role.

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

GET

Retrieve data for one role.

Example request
Retrieve role data for role Id 1.

curl -k -u soar_local_admin:changeme https://localhost/rest/role/1 -G -X GET

Example response
A successful GET will return back a JSON formatted list of key names and data.

This example role has delete, edit, and view for "Label Permissions" of "archer incident"; "Repository Permissions" for "local"; and "Tenant Permissions" for "DefaultTenant".

With no additional roles, this user would only be able to see the one specific named object for each of the three types.

{
    execute: "deny",
    name: "container_label",
    extra: "archer incident",
    edit: "allow",
    object_id: null,
    role: 7,
    content_type: null,
    delete: "allow",
    id: 53,
    view: "allow"
},
{
    execute: "deny",
    name: "repository",
    extra: "local",
    edit: "allow",
    object_id: 2,
    role: 7,
    content_type: 51,
    delete: "allow",
    id: 54,
    view: "allow"
},
{
    execute: "deny",
    name: "tenant",
    extra: "DefaultTenant",
    edit: "allow",
    object_id: 0,
    role: 7,
    content_type: 20,
    delete: "allow",
    id: 55,
    view: "allow"
}
Last modified on 17 February, 2023
REST Playbook   REST Run Action

This documentation applies to the following versions of Splunk® SOAR (On-premises): 6.0.0, 6.0.1, 6.0.2, 6.1.0, 6.1.1, 6.2.0, 6.2.1, 6.2.2, 6.3.0


Was this topic useful?







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