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:

Get System Info

This is a set of REST APIs that return information about the system. These endpoints are read-only and don't take POST requests. Access to these APIs requires authentication, but doesn't require special permissions.

/rest/version

Syntax 

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

GET

Determine the product version.

Example request

curl -k -u uname:pwd https://localhost/rest/version -G -X GET

Example response
A successful GET returns the version. 

{
    "version": "X.Y.ZZZ"
}

/rest/system_info

Syntax 

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

GET

Returns the timezone of your instance and the base URL configured in the system settings user interface for your instance. The base URL can be blank if it's not configured.

Example request

curl -k -u uname:pwd https://localhost/rest/system_info -G -X GET

Example response
A successful GET returns the base url and timezone of the instance. 

{
    "base_url": "https://phantom.example.com",
    "time_zone": "UTC"
}

/rest/license

Syntax 

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

GET

Returns license key configuration values and current usage counters. A License Info value of "0" indicates unlimited.

Example request

curl -k -u uname:pwd https://localhost/rest/license -G -X GET

Example response
A successful GET returns the status and license information. 

{
	"status": "valid",
	"license_info": {
		"case_management": true,
		"issue_date": 1490227200000,
		"maximum_apps": 0,
		"expiration_date": 1521763200000,
		"maximum_users": 0,
		"contact_information": "soc@example.com",
		"company_name": "example",
		"maximum_assets": 0,
		"license_number": "6bcff42b-4988-4951-9efa-371364102b11",
		"license_type": "standard",
		"maximum_actions_per_day": 0,
		"maximum_containers": 0
	},
	"current_usage": {
		"recent_playbook_run_count": 40,
		"recent_app_run_count": 60,
		"recent_debug_run_count": 60
	}
}

/rest/health

Syntax 

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

GET

Get memory and CPU usage information for services and the overall system.

Example request

curl -k -u uname:pwd https://localhost/rest/health -G -X GET

Example response
A successful GET returns the status and license information. 

{
    "all_running": true,
    "db_data": [
        {
            "label": "Free",
            "value": 95413
        },
        {
            "label": "Used",
            "value": 128
        }
    ],
    "last_snapshot_time": "2017-01-28T01:24:40.751000Z",
    "load_data": [
        {
            "load": 0.07,
            "time": "1 minute"
        },
        {
            "load": 0.03,
            "time": "5 minutes"
        },
        {
            "load": 0.0,
            "time": "15 minutes"
        }
    ],
    "memory_data": [
        {
            "label": "Free",
            "value": 3276
        },
        {
            "label": "Used",
            "value": 403
        },
        {
            "label": "Cached",
            "value": 152
        }
    ],
    "services": {
        "actiond": [
            {
                "id": 638,
                "name": "actiond",
                "num_instances": 1,
                "pid": 2465,
                "rs_kb": 2604,
                "stime": 0,
                "time": "2017-01-28T01:24:40.741000Z",
                "utime": 0,
                "vm_kb": 308000
            },
            {
                "id": 631,
                "name": "actiond",
                "num_instances": 1,
                "pid": 2465,
                "rs_kb": 2604,
                "stime": 0,
                "time": "2017-01-28T01:24:10.722000Z",
                "utime": 0,
                "vm_kb": 308000
            },
			...
		],
        "decided": [
            {
                "id": 639,
                "name": "decided",
                "num_instances": 1,
                "pid": 2421,
                "rs_kb": 30500,
                "stime": 6,
                "time": "2017-01-28T01:24:40.744000Z",
                "utime": 47,
                "vm_kb": 510932
            },
        ],
        "nginx": [
            {
                "id": 643,
                "name": "nginx",
                "num_instances": 10,
                "pid": 0,
                "rs_kb": 201196,
                "stime": 112,
                "time": "2017-01-28T01:24:40.750000Z",
                "utime": 470,
                "vm_kb": 1363432
            },
        ],
        "ingestd": [
            {
                "id": 641,
                "name": "ingestd",
                "num_instances": 1,
                "pid": 2399,
                "rs_kb": 2776,
                "stime": 0,
                "time": "2017-01-28T01:24:40.747000Z",
                "utime": 0,
                "vm_kb": 162592
            },
        ],
        "postgres": [
            ...
        ],
        "workflowd": [
			...
        ]
    },
    "status": {
        "actiond": "running",
        "decided": "running",
        "nginx": "running",
        "ingestd": "running",
        "postgres": "running",
        "watchdogd": "running",
        "workflowd": "running"
    },
    "swap_data": [
        {
            "label": "Free",
            "value": 3967
        },
        {
            "label": "Used",
            "value": 0
        }
    ],
    "vault_data": [
        {
            "label": "Free",
            "value": 95481
        },
        {
            "label": "Used",
            "value": 59
        }
    ]
}

The return values of note follow:

Key Type Description
all_running boolean True if all services are running.
db_data JSON array Contains information on free and used space on the /data partition. Values in megabytes.
last_snapshot_time timestamp Time when last snapshot was taken in UTC. Snapshots taken every 30 seconds (can vary slightly depending on system load).
load_data JSON array Load average information as seen when running "uptime" command.
memory_data JSON array Contains 3 values: Used, Free, and Cached memory. Values in megabytes. Does not count swap space.
services JSON object One key each for phantom_actiond, phantom_decided, phantom_ingestd, phantom_workflowd, nginx and postgres. Detail infomation below.
status JSON object One key each for phantom_actiond, phantom_decided, phantom_ingestd, phantom_workflowd, nginx and postgres. Values either "running" or "stopped" depending on status of each service.
swap_data JSON array Contains information on free and used swap space. Values in megabytes.
vault_data JSON array Contains information on free and used space on the /opt/phantom/vault partition. Values in megabytes.

The service snapshot details follow:

Key Type Description
id integer Internal ID of snapshot.
name string Name of service.
num_instances integer Number of processes for this service.
pid integer Process ID of the services (0 for multi-process services).
rs_kb integer KB of resident memory used by all instances of the service.
stime integer System time used by all instances of the service (in clock ticks). (Kernel processor time)
time timestamp Time when snapshot was taken.
utime integer User time used by all instances of the service (in clock ticks). (Non kernel processor time)
kb_vm integer KB of virtual memory used by all instances of the service.

/rest/app_status

Syntax 

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

GET

Get test connectivity status for each asset.

Example request

curl -k -u uname:pwd https://localhost/rest/app_status -G -X GET

Example response
A successful GET returns a default paging size of 10. In the example shown, there are 93 assets, so it will take 10 pages. As with other REST API calls, you can request ?page=N to get a particular page, or ?page_size=N to request a different number of items per page. 

{
  "count": 93,
  "data": [
    {
      "app": 104,
      "asset": 4,
      "create_time": "2017-07-15T21:20:45.113000Z",
      "id": 1,
      "message": "Testing asset connectivity for 'domainctrl1' using app 'LDAP' ",
      "status": "success"
    },
    {
      "app": 57,
      "asset": 5,
      "create_time": "2017-07-15T21:20:50.888000Z",
      "id": 2,
      "message": "Testing asset connectivity for 'alexa' using app 'Alexa' ",
      "status": "success"
    },
    {
      "app": 12,
      "asset": 7,
      "create_time": "2017-07-15T21:21:01.300000Z",
      "id": 3,
      "message": "Testing asset connectivity for 'archer' using app 'RSA Archer' ",
      "status": "success"
    },
    {
      "app": 4,
      "asset": 8,
      "create_time": "2017-07-15T21:21:06.620000Z",
      "id": 4,
      "message": "Testing asset connectivity for 'arcsight_esm' using app 'ArcSight ESM' 1 action succeeded. ",
      "status": "success"
    },
    {
      "app": 88,
      "asset": 9,
      "create_time": "2017-07-15T21:21:16.851000Z",
      "id": 5,
      "message": "Testing asset connectivity for 'ciscoasa' using app 'Cisco ASA' Could not establish ssh connection to Cisco IOS device. Error reading SSH protocol banner. Connectivity test failed. No action executions found.. Connectivity test failed",
      "status": "failed"
    },
    {
      "app": 11,
      "asset": 10,
      "create_time": "2017-07-15T21:21:27.048000Z",
      "id": 6,
      "message": "Testing asset connectivity for 'autofocus' using app 'AutoFocus' 1 action failed. Making a request to PAN AutoFocus. handle_action exception occurred. Error string: 'session_post() takes at least 1 argument (0 given)'",
      "status": "failed"
    },
    {
      "app": 26,
      "asset": 11,
      "create_time": "2017-07-15T21:21:32.626000Z",
      "id": 7,
      "message": "Testing asset connectivity for 'mas' using app 'Malware Analysis Service' 1 action succeeded. ",
      "status": "success"
    },
    {
      "app": 26,
      "asset": 12,
      "create_time": "2017-07-15T21:21:37.861000Z",
      "id": 8,
      "message": "Testing asset connectivity for 'mas_apikey' using app 'Malware Analysis Service' 1 action succeeded. ",
      "status": "success"
    },
    {
      "app": 21,
      "asset": 13,
      "create_time": "2017-07-15T21:21:43.067000Z",
      "id": 9,
      "message": "Testing asset connectivity for 'bmcremedy' using app 'BMC Remedy' ",
      "status": "success"
    },
    {
      "app": 63,
      "asset": 14,
      "create_time": "2017-07-15T21:21:48.298000Z",
      "id": 10,
      "message": "Testing asset connectivity for 'carbonblack' using app 'Carbon Black Response' ",
      "status": "success"
    }
  ],
  "num_pages": 10
}

As a convenience, there is a ?pretty parameter you can add that will provide additional _pretty_* values that are more human-readable, and give extra information so that you do not have to take the app and asset IDs and call their APIs to get the names. The following truncated example shows a single asset.

Example request

curl -k -u uname:pwd https://localhost/rest/app_status?pretty -G -X GET

Example response

{
  "count": 93,
  "data": [
    {
      "_pretty_app": "LDAP",
      "_pretty_asset": "domainctrl1",
      "_pretty_create_time": "13 minutes ago",
      "_pretty_icon": "/app_resource/ldap_84110F27-6602-4DC8-A6F2-0311B1720BF8/microsoft_logo.png",
      "app": 104,
      "asset": 4,
      "create_time": "2017-07-17T18:00:05.546000Z",
      "id": 1,
      "message": "Testing asset connectivity for 'domainctrl1' using app 'LDAP' ",
      "status": "success"
    },
...
  ],
  "num_pages": 10
}

Besides the paging and pretty parameters, the other standard query parameters and filters apply. See REST Query Data.

/rest/widget_data

Syntax 

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

GET

Get data used to populate the home page widgets.

Example request

curl -k -u uname:pwd https://localhost/rest/widget_data -G -X GET

Example response
The following example is a snippet of all widget data. 

{
  "artifact_stats": [
    [
      3,
      "Malicious URL Request Attempt",
      2,
      "100.00"
    ],
    [
      2,
      "Malicious URL Request Attempt",
      7,
      "66.67"
    ],
    [
      1,
      "Malicious URL Request Attempt",
      1,
      "33.33"
    ],
    [
      1,
      "Malicious URL Request Attempt",
      3,
      "33.33"
    ],
    [
      1,
      "Malicious URL Request Attempt",
      10,
      "33.33"
    ],
    [
      1,
      "Malicious URL Request Attempt",
      6,
      "33.33"
    ],
    [
      1,
      "Malicious URL Request Attempt",
      4,
      "33.33"
    ]
  ],
  "container_stats": {
    "groups": [
      {
        "name": "severity",
        "parts": [
          {
            "name": "high",
            "value": 3
          },
          {
            "name": "medium",
            "value": 5
          },
          {
            "name": "low",
            "value": 2
          }
        ]
      },
...
  "top_playbooks_actions": {
    "actions": [
      {
        "action_name": "url reputation",
        "average_duration": 35.6,
        "total": 7
      }
    ],
    "playbooks": []
  }
}

The general form of the URL to receive data for a specific widget is /rest/widget_data/<widget-name>. The following table shows the full list of widgets available, and optional parameters for each.

URL QUERY PARAMETERS DESCRIPTION
/rest/widget_data/playbook_stats label Returns the total number of playbooks and the number of active playbooks. The "label" parameter will cause it to return only the set of playbooks designated to operate on the supplied container label.
/rest/widget_data/sla_trend start_time

end_time
label
user_id

Provides averages for container resolution SLAs.
/rest/widget_data/containers_new start_time

end_time
label
user_id

Returns how many new containers were created per day.
/rest/widget_data/container_stats start_time

end_time
label
user_id

Provides various information (i.e. severity, sensitivity, closed, etc.) for returned containers.
/rest/widget_data/label_stats start_time

end_time
label
user_id

Provides the number of events per day.
/rest/widget_data/containers_open label

sla

Provides information (i.e. sensitivity, severity, times, owner, name, service level agreement breaches by percentage, etc.) for returned open containers.
/rest/widget_data/containers_workload label

user_id

Provides the number of open containers owned per user returned.
/rest/widget_data/pending_approvals start_time

end_time
user_id

Provides information about the pending approvals per user returned.
/rest/widget_data/containers_filtered_by_status start_time

end_time
label
user_id

Returns priority information for containers in the sets resolved, unresolved, and all.
/rest/widget_data/top_playbooks_actions action_filter

playbook_category
start_time
end_time
label
user_id

Returns the top actions used by playbooks. The action_filter value can be "manual" or "automated". The playbook_category parameter will cause playbooks with only the given category to be returned.
/rest/widget_data/playbooks_actions_stats start_time

end_time
label

Returns the number of playbooks and actions executed per day.
/rest/widget_data/containers_resolved start_time

end_time
label
user_id

Returns number of containers resolved per day.
/rest/widget_data/roi_summary start_time

end_time
label
user_id

Returns ROI summary information. Note: This API returns only whole numbers dropping any decimals. Use roi_stats if you need the decimals.
/rest/widget_data/roi_stats start_time

end_time
label
user_id

Returns ROI and time saved information per day.
/rest/widget_data/sla_stats start_time

end_time
label

Returns number of SLA breaches per day.
/rest/widget_data/containers_performance start_time

end_time
label
user_id

Provides averages times for triage, resolution, and dwell for the returned containers.
/rest/widget_data/artifact_stats start_time

end_time
label
user_id

Provides information about the top artifacts per container.

Most widgets take label and user_id as optional parameters, where the label is a container label and user_id is an integer. Widgets can also take the optional parameters start_time and end_time, which must be specified in ISO 8601 format and provided together, else they will default to the last 7 days.

Last modified on 26 January, 2024
Delete Records   Use a Custom Script

This documentation applies to the following versions of Splunk® SOAR (On-premises): 5.1.0, 5.2.1, 5.3.1, 5.3.2, 5.3.3, 5.3.4, 5.3.5, 5.3.6, 5.4.0, 5.5.0, 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

Acrobat logo Download manual
Acrobat logo Download this page

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