Splunk® SOAR (Cloud)

REST API Reference for Splunk SOAR (Cloud)

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 Indicators

All indicator REST endpoints are accessed with the HTTP GET method.

There are two parameters that can be used with all indicator endpoints:

Parameter: tenant_id

  • default: (multi-tenancy enabled) - none, tenant_id MUST be included in all requests
  • default: (multi-tenancy disabled) - system tenant id ( 0 ), all the examples that follow are with multi-tenancy disabled

Parameter: timerange

  • default: last_30_days
  • options:
    • today
    • yesterday
    • this_week
    • this_month
    • this_year
    • last_7_days
    • last_30_days
    • last_week
    • last_month
    • last_year

When the indicators feature is disabled in /rest/system_settings/features, the response for all indicator endpoints is the HTTP 400 status and "The indicators feature is not enabled." message. See /rest/system_settings/features.

/rest/indicator_stats_indicator_count

Indicator counts

Syntax 

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

GET

Returns the number of unique indicators and total indicators present.

Example request
Return the count of unique indicators and total indicators. 

curl -k -u username:password https://localhost/rest/indicator_stats_indicator_count -G -X GET

Example response
A successful GET will return the count. 

{
    "indicator_count": 182,
    "indicator_instance_count": 4107
}

Example response
Example response with no data. 

{
    "indicator_count": 0,
    "indicator_instance_count": 0
}

/rest/indicator_stats_top_labels

Top event labels

Syntax 

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

GET

Returns the top three event (container) labels that have the most indicators, as well as the count of indicators within each label.

Example request
Return the top three event labels. 

curl -k -u username:password https://localhost/rest/indicator_stats_top_labels -G -X GET

Example response
A successful GET will return the top three event labels and the count of events per label. 

{
    "topLabels": [
        {
            "count": 3981,
            "label": "events"
        },
        {
            "count": 52,
            "label": "campaign"
        },
        {
            "count": 34,
            "label": "generator"
        }
    ]
}

Example response
Example response with no data. 

{
    "topLabels": []
}

/rest/indicator_stats_top_types

Top indicator types

Syntax 

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

GET

Returns the top three indicator types that have the most indicators, as well as the count of indicators within each type.

Example request
Return the top three indicator types. 

curl -k -u username:password https://localhost/rest/indicator_stats_top_types -G -X GET

Example response
A successful GET will return the top three indicator types and the count of events per type. 

{
    "topTypes": [
        {
            "count": 1031,
            "type": "port"
        },
        {
            "count": 1012,
            "type": "ip"
        },
        {
            "count": 453,
            "type": "hash"
        }
    ]
}

Example response
Example response with no data. 

{
    "topTypes": []
}

/rest/indicator_stats_top_values

Top indicator values

Syntax 

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

GET

Returns the top 3 indicator values that appear the most as well as the number of times they appear.

Example request
Return the top three indicator values. 

curl -k -u username:password https://localhost/rest/indicator_stats_top_values -G -X GET

Example response
A successful GET will return the top three indicator values and the number of times they appear. 

{
    "topIndicators": [
        {
            "count": 509,
            "value": "80"
        },
        {
            "count": 504,
            "value": "4286"
        },
        {
            "count": 492,
            "value": "120"
        }
    ]
}

Example response
Example response with no data. 

{
    "topIndicators": []
}

/rest/indicator_by_value

Get details of an indicator by using the indicator value.

Syntax 

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

GET

Returns details of the specific indicator by using the value of the indicator.

Example request
Get the details of an indicator with a value of 80. This example uses the following parameters:

required parameters
  • indicator_value
optional parameters
  • _special_contains
  • _special_fields
  • _special_labels
curl -k -u username:password https://localhost/rest/indicator_by_value?indicator_value=80&_special_fields=true&_special_labels=true&_special_contains=true  -G -X GET

Example response
A successful GET returns the details of the indicator with the value of 80. 

{
    "_special_contains": [
        "port"
    ],
    "_special_fields": [
        "destinationPort"
    ],
    "_special_labels": [
        "events",
        "generator",
        "campaign"
    ],
    "earliest_time": "2018-07-24T05:07:38.589945Z",
    "id": 6,
    "latest_time": "2018-07-24T05:26:34.516600Z",
    "open_events": 347,
    "sc_high": 299,
    "sc_low": 100,
    "sc_medium": 110,
    "tags": [],
    "tenant": 0,
    "total_events": 509,
    "value": "80"
}

/rest/indicator

Multiple indicator data

Syntax 

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

GET

Returns multiple indicators, with the ability to filter based on specific fields or time range.

Example request
Example without any query parameters. 

curl -k -u username:password https://localhost/rest/indicator  -G -X GET

Example response
A successful GET without any query parameters returns the count, data, and number of pages. 

{
	"count": 0,
	"data": [],
	"num_pages": 0
}

Example request
Example using query parameters to returns multiple indicators. This example uses the following parameters:

required parameters
  • _special_fields
  • _special_labels
  • _special_contains
  • pretty
optional parameters
  • sort
    • values: _pretty_earliest_time, _pretty_latest_time, severity, id, value
  • page_size
  • page
  • order=desc
  • filter
curl -k -u username:password https://localhost/rest/indicator?_special_fields=true&_special_labels=true&_special_contains=true&_special_severity=true&pretty=true&page_size=10&page=0&sort=id&order=desc&timerange=last_30_days -G -X GET

Example response
A successful GET returns multiple indicators, with the output pretty and sorted. 

{
    "count": 182,
    "data": [
        {
            "_special_labels": [
                "events"
            ],
            "total_events": 1,
            "_pretty_tenant": "_default_",
            "tags": [],
            "_special_fields": [
                "fileHash"
            ],
            "value": "00b3199ed932f084f50b6a4df9124132",
            "_pretty_latest_time": "0 minutes ago",
            "latest_time": "2019-05-07T19:09:29.778556Z",
            "_pretty_earliest_time": "0 minutes ago",
            "open_events": 1,
            "_special_contains": [
                "hash"
            ],
            "severity_counts": [
                {
                    "count": 1,
                    "name": "high"
                }
            ],
            "earliest_time": "2019-05-07T19:09:29.778556Z",
            "id": 323,
            "tenant": 0
        }        
    ],
    "num_pages": 182
}

/rest/indicator/<indicator_id>

Single indicator data

Syntax 

https://<username>:<password>@<host>/rest/indicator/<indicator_id>


GET

Returns details of the specific indicator by its indicator Id.

Example request
Get the details of indicator Id 6. This example uses the following parameters:

optional parameters
  • _special_contains
  • _special_fields
  • _special_labels
curl -k -u username:password https://localhost/rest/indicator/6?_special_fields=true&_special_labels=true&_special_contains=true  -G -X GET

Example response
A successful GET returns the details of indicator Id 6. 

{
    "_special_contains": [
        "port"
    ],
    "_special_fields": [
        "destinationPort"
    ],
    "_special_labels": [
        "events",
        "generator",
        "campaign"
    ],
    "earliest_time": "2018-07-24T05:07:38.589945Z",
    "id": 6,
    "latest_time": "2018-07-24T05:26:34.516600Z",
    "open_events": 347,
    "sc_high": 299,
    "sc_low": 100,
    "sc_medium": 110,
    "tags": [],
    "tenant": 0,
    "total_events": 509,
    "value": "80"
}

/rest/indicator_artifact

Artifacts by indicator

Syntax 

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

GET

Returns all artifacts that share a specific indicator id or value.

Example request
Get the artifacts with indicator Id 159. This example uses the following parameters:

required parameters
  • indicator_id
    OR
  • indicator_value
optional parameters
  • sort
  • page_size
  • page
  • order=desc
  • filter
curl -k -u username:password https://localhost/rest/indicator_artifact?indicator_id=159&_special_fields=true&_special_labels=true&_special_contains=true&_special_severity=true&page=0&page_size=10&sort=id&order=desc&timerange=last_30_days  -G -X GET

Example response
A successful GET returns the details of indicator Id 159 for the last 30 days. 

{
    "count": 509,
    "data": [
        {
            "cef": {
                "baseEventCount": "120",
                "destinationPort": "80",
                "sourceAddress": "208.98.63.226",
                "sourcePort": "4286"
            },
            "cef_types": {},
            "container": 265,
            "container_name": "Zeus Infection on 10.17.1.201",
            "create_time": "2018-07-24T05:26:34.516600Z",
            "description": null,
            "end_time": "2018-07-24T05:26:33.742265Z",
            "has_note": false,
            "hash": "e7943930260daf75c2846e0a5a9aa2d8",
            "id": 730,
            "in_case": false,
            "ingest_app": null,
            "kill_chain": null,
            "label": "event",
            "name": null,
            "owner": null,
            "parent_artifact": null,
            "parent_container": null,
            "playbook_run": null,
            "severity": "low",
            "source_data_identifier": "qqHS6NWIAQLgVUVz85cNCY7WcB",
            "start_time": "2018-07-24T05:26:33.741621Z",
            "tags": [],
            "type": "network",
            "update_time": "2018-07-24T05:26:34.516648Z",
            "version": 1
        }
    ],
    "num_pages": 509
}

/rest/indicator_artifact_timeline

Indicator timeline by value

Syntax 

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

GET

Returns the timeline for a given indicator value.

Example request
Get the timeline for the indicator value of povvvodos.org. This example uses the following parameters:

required parameters
  • indicator_value
  • timeline_width
  • timerange
optional parameters margin_size 
curl -k -u username:password https://localhost/rest/indicator_artifact_timeline?indicator_value=povvvodos.org&timeline_width=951&timerange=last_30_days&margin_size=35 -G -X GET

Example response
A successful GET returns the details of indicator value povvvodos.org for the last 30 days. 

{
    "data": [
        {
            "containerId": null,
            "count": 510,
            "didInjectThisDataPoint": true,
            "eventName": null,
            "id": null,
            "readableTime": "6/22",
            "severity": null,
            "time": "2018-06-22T19:00:11.430074Z",
            "type": "node",
            "unixTime": 1529694011.430074
        },
        {
            "count": 510,
            "nodeCount": 509,
            "nodeSeverityCount": {
                "high": 299,
                "low": 100,
                "medium": 110
            },
            "readableTime": "7/23",
            "time": "2018-07-23T03:59:59.363828Z",
            "type": "group",
            "unixTime": 1532318399.3638277
        },
        {
            "containerId": null,
            "count": 510,
            "didInjectThisDataPoint": true,
            "eventName": null,
            "id": null,
            "readableTime": "7/27",
            "severity": null,
            "time": "2018-07-27T04:59:47.569926Z",
            "type": "node",
            "unixTime": 1532667587.569926
        }
    ],
    "domain": [
        1529884800,
        1532476799
    ]
}

/rest/indicator_common_container

Containers by indicator

Syntax 

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

GET

Returns every event (container) that the specified indicators appear inside of.

Example request
Get the events for the indicator Ids of 1 and 2. This example uses the following parameters:

required parameters indicator_ids (comma-separated string of indicator ids), for example: '1,2,3' 
curl -k -u username:password https://localhost/rest/indicator_common_container?indicator_ids=1,2 -G -X GET

Example response
A successful GET returns the details of indicator Ids 1 and 2. 

[
    {
        "container_id": 81,
        "container_name": "koov4rra2ree5p6fzt1bcnjusu"
    },
    {
        "container_id": 61,
        "container_name": "6r8cm1798gq5hrb8e8t3ujw01m"
    }
]
Last modified on 06 November, 2024
REST HUD   REST Lists

This documentation applies to the following versions of Splunk® SOAR (Cloud): current

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