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 System Settings

Update a subset of system settings such as audit trail settings, authentication providers, and mobile.

/rest/system_settings

Update audit trail settings and authentication providers

Syntax

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

POST

Update audit trail and authentication provider settings by replacing the entire configuration or by replacing parts of it.

Request parameters
Audit trail settings and authentication providers are modified with the following parameters.

Field Required Type Description
audit_trail_settings optional Javascript Object Key-value pairs indicating which audit trail sections should be enabled. Possible keys are:
  • administration
  • container
  • playbook
  • user
auth_settings optional Javascript Object A complex data structure containing all authentication providers.

The entirety of "auth_settings" must be submitted in a single post. Partial updates are not supported.

Each section is modified with the following keys at the top level.

Field Required Type Description
enabled required Boolean Flag indicating if this section is enabled (applies to all of each ldap/saml2/openid sections).
providers required Javascript array of objects An array of the provider configurations. JSON for each provider described below.
type required String Type should match the name of the section. One of saml2, openid or ldap.

LDAP providers are modified with the following keys.

Field Required Type Description
name required String The name of the provider configuration entry.
type required String Type of provider, should match the section. One of saml2, openid or ldap.
id required String ID of the provider, this should be a GUID-like entry.
host required String IP or hostname of the provider.
domain required String LDAP domain.
enabled required String Flag indicating if the provider is enabled.
username required String Username for the service account used to query the provider.
force_ssl optional Boolean If set to true, will only connect using ldaps. Otherwise will use ldap.
password optional String The password for the service account used to query the provider. Required if not using a credential manager to store your password.
use_credential_manager optional Boolean Flag indicating if the service account password should be retrieved from the credential manager.
cm_key optional String Key for identifying the password in the credential manager. Required if using a credential manager.
cm_path optional String Path for identifying the password in the credential manager. Required if using a credential manager.
cm_safe optional String Identifies the Safe that contains the credentails in Cyberark. Required if using Cyberark as a credential manager.
test_username optional String Username for testing LDAP access and queries.
test_group optional String Used to verify the test_username is in the expected group. Requires the test_username to be set.
user_attr_map optional JSON Array of JSON Objects Each entry of the array should contain two key-value pairs. The "django_attr" key should have one of the following values.
  • username
  • email
  • first_name
  • last_name
  • title
  • location
  • time_zone

The "external_attr" key should contain the name of the LDAP attribute used to populate the django attribute.

group_role_mappings optional JSON Array of JSON Objects Each entry of the array should contain two key-value pairs. The "role" key should contain the numeric ID of the Phantom role. The "group" key should contain the name of the LDAP group that translates to the Phantom group

SAML2 providers are modified with the following keys.

Field Required Type Description
name required String The name of the provider configuration entry.
type required String Type of provider, should match the section. One of saml2, openid or ldap.
id required String ID of the provider, this should be a GUID-like entry.
issuer_id required String The issuer ID (URI) given by your provider
metadata_url required String The URL to retrieve SAML metadata. This is the preferred method of obtaining provider metadata since it should always be up-to-date.
metadata_xml required String The XML containing the SAML provider metadata. This is used for out-of-band configuration.
single_sign_on_url required String URL used to gain user consent/authorization from the identity provider. Users will be redirected here for login when using SAML2.
enabled required String Flag indicating if the provider is enabled.
phantom_base_url optional String Base URL for the Phantom instance. Not required only if the FQDN has been set in Company Settings.
force_ssl optional Boolean Flag indicating if SSL is required (defaults to FALSE).
group_key optional String Used to locate group data in the SAML assertion, treated as a mapping object, e.g. {"groups": ["group1", "group2", "group3"]} (defaults to "groups").
user_attr_map optional JSON Array of JSON Objects Each entry of the array should contain two key-value pairs. The "django_attr" key should have one of the following values. Can be used if attributes are not auto-populated correctly.
  • username
  • email
  • first_name
  • last_name
  • title
  • location
  • time_zone

The "external_attr" key should contain the name of the LDAP attribute used to populate the django attribute.

group_role_mappings optional JSON Array of JSON Objects Each entry of the array should contain two key-value pairs. The "role" key should contain the numeric ID of the Phantom role. The "group" key should contain the name of the LDAP group that translates to the Phantom group

OpenID providers are modified with the following keys.

Field Required Type Description
name required String The name of the provider configuration entry.
type required String Type of provider, should match the section. One of saml2, openid or ldap.
id required String ID of the provider, this should be a GUID-like entry.
client_id required String Client ID given by the identity provider.
enabled required String Flag indicating if the provider is enabled.
service_discovery_url required String URL where the issuer provides service information.
phantom_base_url optional String Base URL for the Phantom instance. Not required only if the FQDN has been set in Company Settings.
force_ssl optional Boolean Username for the service account used to query the provider.
client_secret optional String The client_secret. Required if not using a credential provider and token_endpoint_auth_method is set to client_secret_post.
use_credential_manager optional Boolean Flag indicating if the service account password should be retrieved from the credential manager.
cm_key optional String Key for identifying the password in the credential manager. Required if using a credential manager (Cyberark/Hashicorp/Thycotic).
cm_path optional String Path for identifying the password in the credential manager. Required if using a credential manager (Cyberark/Hashicorp/Thycotic).
cm_safe optional String Identifies the Safe that contains the credentials in Cyberark. Required only if using Cyberark as a credential manager.
cm_mapping optional String The fieldName in the Thycotic secret which has the credential. Required only if using Thycotic as a credential manager.
scope optional String Comma delimited list of scopes.
resource optional String Used to identify the protected resource which contains user claims, information about the user. Leave blank to use the Userinfo endpoint
user_attr_map optional JSON Array of JSON Objects Each entry of the array should contain two key-value pairs. The "django_attr" key should have one of the follwoing values.
  • username
  • email
  • first_name
  • last_name
  • title
  • location
  • time_zone
The "external_attr" key should contain the name of the LDAP attribute used to populate the django attribute.
group_role_mappings optional JSON Array of JSON Objects Each entry of the array should contain two key-value pairs. The "role" key should contain the numeric ID of the Phantom role. The "group" key should contain the name of the LDAP group that translates to the Phantom group
group_key optional String Used to locate group data in the data returned by the OpenID identity provider, treated as a mapping object, e.g. {"groups": ["group1", "group2", "group3"]} (defaults to "groups").


Example request
Completely replace audit trail and auth settings as follows:

curl -k -u admin:changeme https://localhost/rest/system_settings \
-d '{
	"audit_trail_settings": {
		"administration": false,
		"container": false,
		"playbook": false,
		"user": false
	},
	"auth_settings": {
		"ldap": {
			"enabled": true,
			"providers": [{
				"cm_key": "value",
				"cm_path": "secret/ldap",
				"domain": "example.com",
				"enabled": true,
				"group_role_mappings": [],
				"host": "1.1.1.1",
				"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
				"name": "LDAP Provider 1",
				"password": "<password>",
				"test_group": "HR",
				"test_username": "alice",
				"type": "ldap",
				"use_credential_manager": true,
				"user_attr_map": [],
				"username": "ldap-service-account"
			}],
			"type": "ldap"
		},
		"openid": {
			"enabled": true,
			"providers": [{
					"client_id": "<client id>",
					"client_secret": "<client secret>",
					"enabled": true,
					"force_ssl": false,
					"group_key": "role",
					"group_role_mappings": [{
						"group": "HR",
						"role": "31"
					}],
					"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
					"name": "OpenID - ADFS",
					"phantom_base_url": "http://example.com",
					"resource": "companyresource",
					"scope": "openid",
					"service_discovery_url": "https://example.com",
					"token_endpoint_auth_method": "private_key_jwt",
					"type": "openid",
					"user_attr_map": [{
						"django_attr": "username",
						"external_attr": "given_name"
					}]
				},
				{
					"client_id": "<client id>",
					"client_secret": "<client secret>",
					"enabled": true,
					"group_role_mappings": [{
						"group": "special group",
						"role": "31"
					}],
					"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
					"name": "OpenID - Okta",
					"phantom_base_url": "http://example.com",
					"service_discovery_url": "https://example.com",
					"type": "openid",
					"user_attr_map": []
				}
			],
			"type": "openid"
		},
		"saml2": {
			"enabled": true,
			"providers": [{
				"enabled": true,
				"group_key": "role",
				"group_role_mappings": [{
					"group": "HR",
					"role": "31"
				}],
				"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
				"issuer_id": "http://example.com/provider",
				"metadata_url": "https://example.com/federationmetadata/2007-06/federationmetadata.xml ",
				"metadata_xml": "",
				"name": "SAML2 Provider 1",
				"phantom_base_url": "https://example.com",
				"single_sign_on_url": "https://example.com",
				"type": "saml2",
				"user_attr_map": []
			}],
			"type": "saml2"
		}
	}
}'

Example response
A successful POST returns a success or failure indicator and a message for each command.

{
    "audit_trail_settings": {
        "message": "Audit trail settings have been updated",
        "success": true
    },
    "message": "At least one update operation succeeded. See individual responses.",
    "success": true,
    "auth_settings": {
        "failed": true,
        "message": "ID for ldap provider \"LDAP Provider 1\" does not appear to be a GUID"
    }
}

Example request
Modify parts of a audit trail or auth settings list without replacing the entire thing. If "contents" is given, other operations are ignored. If the individual "cells" of the table are not strings, they are coerced to strings.

curl -k -u admin:changeme https://localhost/rest/system_settings \
-d '{
	"ldap": {
		"enabled": true,
		"providers": [{
			"cm_key": "value",
			"cm_path": "secret/ldap",
			"domain": "example.com",
			"enabled": true,
			"group_role_mappings": [],
			"host": "1.1.1.1",
			"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
			"name": "LDAP Provider 1",
			"password": "<password>",
			"test_group": "HR",
			"test_username": "alice",
			"type": "ldap",
			"use_credential_manager": true,
			"user_attr_map": [],
			"username": "ldap-service-account"
		}],
		"type": "ldap"
	},
	"openid": {
		"enabled": true,
		"providers": [{
				"client_id": "<client id>",
				"client_secret": "<client secret>",
				"enabled": true,
				"force_ssl": false,
				"group_key": "role",
				"group_role_mappings": [{
					"group": "HR",
					"role": "31"
				}],
				"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
				"name": "OpenID - ADFS",
				"phantom_base_url": "http://example.com",
				"resource": "companyresource",
				"scope": "openid",
				"service_discovery_url": "https://example.com",
				"token_endpoint_auth_method": "private_key_jwt",
				"type": "openid",
				"user_attr_map": [{
					"django_attr": "username",
					"external_attr": "given_name"
				}]
			},
			{
				"client_id": "<client id>",
				"client_secret": "<client secret>",
				"enabled": true,
				"group_role_mappings": [{
					"group": "special group",
					"role": "31"
				}],
				"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
				"name": "OpenID - Okta",
				"phantom_base_url": "http://example.com",
				"service_discovery_url": "https://example.com",
				"type": "openid",
				"user_attr_map": []
			}
		],
		"type": "openid"
	},
	"saml2": {
		"enabled": true,
		"providers": [{
			"enabled": true,
			"group_key": "role",
			"group_role_mappings": [{
				"group": "HR",
				"role": "31"
			}],
			"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
			"issuer_id": "http://example.com/provider",
			"metadata_url": "https://example.com/federationmetadata/2007-06/federationmetadata.xml ",
			"metadata_xml": "",
			"name": "SAML2 Provider 1",
			"phantom_base_url": "https://example.com",
			"single_sign_on_url": "https://example.com",
			"type": "saml2",
			"user_attr_map": []
		}],
		"type": "saml2"
	}
}'

Example response
A successful POST returns a success or failure indicator and a message for each command.

{
    "audit_trail_settings": {
        "message": "Audit trail settings have been updated",
        "success": true
    },
    "message": "At least one update operation succeeded. See individual responses.",
    "success": true,
    "auth_settings": {
        "failed": true,
        "message": "ID for ldap provider \"LDAP Provider 1\" does not appear to be a GUID"
    }
}

/rest/system_settings/decided_runner

Set values for DEDCIDED vertical scaling feature.

Syntax

https://<username>:<password>@<host>/rest/system_settings/decided_runner

Usage details
The system setting edit permissions are required to change this setting.

POST

Change system settings for DECIDED. Set the number of runners for Python 2, Python 3, and the number of minutes a runner can process a code block before it times out.

Request parameters
DECIDED settings are modified with the following parameters.

Field Required Type Description
num_py2_runners required Integer The number of Python 2 runners.
num_py3_runners required Integer The number of Python 3 runners.
time_to_live required Integer The number of minutes a runner is allowed to execute a code block before it times out, then is destroyed and respawned by DECIDED.

Example request
Enable mobile as follows:

curl -k -u admin:changeme https://localhost/rest/system_settings/decided_runner \
-d '{
  "num_py2_runners": 1,
  "num_py3_runners": 2,
  "time_to_live": 10
}'

Example response
A successful POST returns a success message.

{
	"message": "Decided Runner Updated",
	"success": true
}

/rest/system_settings/features

Enable or disable system settings features such as mobile.

Syntax

https://<username>:<password>@<host>/rest/system_settings/features

Usage details
The system setting edit permissions are required to change this setting.

POST

Enable system settings features, such as mobile.

Request parameters
Features are modified with the following parameters.

Field Required Type Description
feature required String The feature: mobile, clickable_url, multi_tennancy, whitelist, indicators.
set_feature_enabled required Boolean True or False.

Example request
Enable mobile as follows:

curl -k -u admin:changeme https://localhost/rest/system_settings/features \
-d '{
	"feature": "mobile",
	"set_feature_enabled": "True"
}'

Example response
A successful POST returns a success or failure indicator and a message for each command.

{
	"message": "Updated feature enabled state",
	"enabled": "True",
	"feature": "mobile",
	"success": true
}

/rest/system_settings optional query parameters

/rest/system_settings?sections

Get the status of feature system settings sections.

Syntax

https://<username>:<password>@<host>/rest/system_settings?sections

GET

Get the status of system settings.

Example request
Get the status of the mobile system setting.

curl -k -u admin:changeme https://localhost/rest/system_settings?sections=["mobile"] -G -X GET

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

{
  "mobile": {
    "enabled": false
  }
}


Example request
Get the status of the DECIDED vertical scaling system settings.

curl -k -u admin:changeme https://localhost/rest/system_settings?section=decided_runner_settings

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

{
    "decided_runner_settings": {
        "time_to_live": 10,
        "num_py2_runners": 1,
        "num_py3_runners": 1,
        "max_num_py2_runners": 10,
        "max_num_py3_runners": 10
    }
}
Last modified on 26 January, 2021
PREVIOUS
REST Status
  NEXT
REST User

This documentation applies to the following versions of Splunk® Phantom: 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