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 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 how many unique indicators and total indicators are present.

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

curl -k -u admin:changeme 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 admin:changeme 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 admin:changeme 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 admin:changeme 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 admin:changeme 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 admin:changeme 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 admin:changeme 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 admin:changeme 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 admin:changeme 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 admin:changeme 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 15 March, 2023
PREVIOUS
REST HUD
  NEXT
REST Lists

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


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