Query for Data - Splunk Documentation (2024)

allows authorized users to use a REST API to query for several kinds of information. Including any Containers and Artifacts in the system.

General Form for a Query

Querying for information is done using a HTTP GET request. The response will contain JSON data in the body. The result may be a Javascript Array or a single Javascript Object depending on what was queried. The format of the URL follows:

/rest/<type>/[identifier]/[detail]?page=0&page_size=10&pretty&_filter_XXX='YYY'&_exclude_XXX='YYY'&include_expensive

ParameterRequiredDescription
typerequiredThe type of data being queried. Supported types are:
  • action_run
  • artifact
  • asset
  • app
  • app_run
  • container
  • playbook_run
  • cluster_node

Querying for only a type will return a paginated array of objects.

identifieroptionalAdding an identifier to a URL will retrieve a single specific object. Identifiers are integers and are unique for each resource.
detailoptionalAdding a detail can only be done when querying a single object. The result is to return information on a single field of the object.
pageoptionalPositive integer. Returned results are paginated and page numbering starts at 0. This query parameter requests a specific page.
page_sizeoptionalPositive integer. Returned results are paginated. This query parameter determines how many results returned per-page. Use "0" for all results.

Setting page_size to 0 will return all results. Querying a very large data set can have an adverse effect on performance.

prettyoptionalNo value. Adding?pretty (or &pretty) to your query will add related or calculated fields prefixed with _pretty_ to the response. For instance if the record you are looking for has a start_time, the response will have _pretty_start time that is a relative local version of the time. A record that has an "owner" reporting back an id will gain _pretty_owner that shows the owner's display name.

Requesting pretty values is a relatively expensive call since it may involve expensive calculations or additional database lookups. When querying individual records or small numbers of records, this should not cause any performance hit. However if requesting tens of thousands of records it may have an adverse impact on your system depending on your hardware.

_filter_XXXoptionalAdd one or more filters to limit the results. Applies only to lists of objects. See Filtering below.
_exclude_XXXoptionalExclude matching items with syntax similar to filtering. See Excluding below.
include_expensiveoptionalNo value. Adding this flag will cause the REST API to return all fields when returning a list, including large/expensive fields.

The include_expensive parameter will return all fields, just as if you were requesting the individual record. These expensive fields may have megabytes of data for a single record, so use this option with caution as it may have a significant performance impact if returning large amounts of data.

sortoptionalField to sort results with. Can be any "simple" field at the top-level of record, such as a string, boolean, or integer value that is not under a hierarchy. Custom fields for events can also be sorted, using the format custom_fields.field_name.
orderstringEither "asc" or "desc". This is the sorting order for the results.

Requesting a Single Object

The following is a query returning a single Container. The returned value is a single JSON object.

Request URL:/rest/container/42Response body:{ "artifact_count": 14, "artifact_update_time": "2015-11-24T22:45:09.185206+00:00", "asset": 101, ... "start_time": "2014-10-19T14:40:33+00:00", "status": "closed", "tags": [""], "version": 1}

Requesting an Array of Objects

This is an example of querying for all Artifact objects. The result is a JSON Object containing 3 fields.

FieldTypeDescription
countIntegerCount of total number of records.
num_pagesIntegerTotal number of pages available for this query.
dataArrayArray of objects in JSON format. The paginated result of the query. Queries that return a list of objects do not include all data. Some fields may be excessively large and are only returned when a single object is queried. One example is the Artifact data field.
Request URL:/rest/artifact?page=2Response body:{ "count": 40, "data": [ { "asset": 11, "container_id": 5, "create_time": "2014-10-19T12:41:33", ... "start_time": "2014-10-19T14:41:33", "type": "network", "version": "1.0" }, { "asset": 12, "container_id": 5, "create_time": "2014-10-19T12:40:33", ... "start_time": "2014-10-19T14:40:33", "type": "network", "version": "1.0" }, ... { "asset": 20, "container_id": 7, "create_time": "2014-09-04T12:40:33", "end_time": null, ... "start_time": "2014-09-04T14:40:33", "type": "", "version": "1.0" } ], "num_pages": 4}

Filtering

You can add one or more filters that will limit the results you get back on your query. Filters are added as query string parameters and have the following format:

/rest/endpoint?_filter_<field_name>=<value>

Field name can be anything in the top level of the record you are querying. Using the example provided, you could limit the artifacts to only network artifacts by adding &_filter_type="network".

Depending on your filter, you may want to pass various different kinds of data as the value. You can pass strings, numbers, and simple data structures.

TypeFormatExample
stringEnclosed in double or single quotes."myvalue"
numberno formatting10
arrayPython syntax for a literal list.["a string", 2, None]

When filtering for a status, use the status' id, which is a number, rather than its name, which is a string. You can get the status' id using /rest/container_status.

For more information about /rest/container_status, see REST Status.

You can do more than simple comparisons with filters. You can do substring comparisons, inclusion in a collection and relative values for example. You could do this by adding an operator to the filter. For instance to change the above example to a substring search I can do /rest/artifact?_filter_type__contains="net".

A case-insensitive version would be /rest/artifact?_filter_type__icontains="net".

You can also do some limited filtering on fields of related records. For instance if I wanted to filter artifacts for artifacts belonging to containers that have "spyware" in the name, I could use /rest/artifact?_filter_container__name__icontains="spyware".

The filter API resembles the Django filter syntax. You can see documentation on the various operators features available on the Django queryset filter documentation.

You can add multiple filters to a request. However they will be ANDed together. There is no way to do an OR between filters. Not all features of Django querysets are supported.

Excluding

The opposite of filtering is excluding items that match certain criteria. You can use a similar syntax in excluding as you can use in filtering. The simplest format for filtering is the following:

/rest/endpoint?_exclude_<field_name>=<value>

If you want to query for artifacts that do not have the tag preprocessed, use the following URL:

/rest/artifact?_exclude_tags__contains="preprocessed"

See Filtering for more complicated syntax you can use, such as a substring comparison or inclusion in a list. All operators supported for filtering are also supported for excluding.

You can only use one exclude statement. If you use more than one exclude statement, only the final statement is applied.

Requesting Object Detail

The simplest query for object detail to retrieve a field such as the Artifact name or Container close_time etc. The result is a JSON object with a key/value pair for the data queried.

Request URL:/rest/container/5/nameResponse body:{ "name": "CryptoLocker Ransomware Infection (new, SLA breached) (192.168.1.41)"}

A more useful operation is to find objects that are related to a principle object. Such as querying for all actions run in the context of a Container. To facilitate getting the detail information on such queries, pseudo fields are available giving a object list of these related objects.

Request URL:/rest/container/5/actions?page=1Response body:{ "count": 18, "data": [ { "action": "url reputation", "assign_time": "2015-03-21T21:03:57.728000", "cancelled": null, "close_time": "2015-03-21T21:04:00.425000", ... "type": "investigate", "update_time": "2015-03-21T21:04:00.425000", "version": "1.0" }, { "action": "timeliner", "assign_time": "2015-03-21T21:00:12.796000", "cancelled": null, "close_time": "2015-03-21T21:02:46.212000", ... "update_time": "2015-03-21T21:02:46.212000", "version": "1.0" }, ... { "action": "snapshot vm", "assign_time": "2015-03-21T20:57:21.944000", "cancelled": null, "close_time": "2015-03-21T20:58:01.897000", ... "update_time": "2015-03-21T20:58:01.897000", "version": "1.0" } ], "num_pages": 2}

These are the currently defined pseudo fields.

TypePseudo fieldDescription
action_runapp_runsApp runs (app commands) created by the Action.
action_runapprovalsApprovals associated with the Action.
app_runlogGet logs (from spawn.log) pertaining to an app run id. Debug Logging has to be enabled.
containeractionsActions created (both automated and manual) in response to the Container.
containeractivity_feedReturns a record of the activity for the container, such as created notes, comments, playbook runs, action runs, and so on.
containerattachmentsAny files attached to the Container (vault items).
containerplaybook_runsPlaybooks run (both automated and manual) in response to the Container.
containerartifactsAll Artifacts that contribute to the Container.
containerauditAudit information for a container.
containercommentsComments added to the container.
containerrecommended_actionsBrief set of recommendations for appropriate actions for the container.
containerrecommended_playbooksBrief set of recommendations for appropriate playbooks for the container.
playbookauditAudit information for a Playbook.
playbook_runactionsActions created by the Playbook.
playbook_runlogLogged messages from playbook run (logging must have been enabled).
ph_userrolesRoles that the user belongs to.
ph_userauditAudit information for the user.
roleusersUsers that belong to the role.
roleauditAudit information for users that belong to the role.
Query for Data - Splunk Documentation (2024)

References

Top Articles
Latest Posts
Article information

Author: Jamar Nader

Last Updated:

Views: 5773

Rating: 4.4 / 5 (55 voted)

Reviews: 94% of readers found this page helpful

Author information

Name: Jamar Nader

Birthday: 1995-02-28

Address: Apt. 536 6162 Reichel Greens, Port Zackaryside, CT 22682-9804

Phone: +9958384818317

Job: IT Representative

Hobby: Scrapbooking, Hiking, Hunting, Kite flying, Blacksmithing, Video gaming, Foraging

Introduction: My name is Jamar Nader, I am a fine, shiny, colorful, bright, nice, perfect, curious person who loves writing and wants to share my knowledge and understanding with you.