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

Query for Data

Phantom 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

Parameter Required Description
type required The 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.

identifier optional Adding an identifier to a URL will retrieve a single specific object. Identifiers are integers and are unique for each resource.
detail optional Adding a detail can only be done when querying a single object. The result is to return information on a single field of the object.
page optional Positive integer. Returned results are paginated. This query parameter requests a specific page.
page_size optional Positive 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.

pretty optional No 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_XXX optional Add one or more filters to limit the results. Applies only to lists of objects. See Filtering below.
_exclude_XXX optional Exclude matching items with syntax similar to filtering. See Excluding below.
include_expensive optional No 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.

sort optional Field 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.
order string Either "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/42

Response 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.

Field Type Description
count Integer Count of total number of records.
num_pages Integer Total number of pages available for this query.
data Array Array 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=2

Response 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.

Type Format Example
string Enclosed in double or single quotes. "myvalue"
number no formatting 10
array Python 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.

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.

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/name

Response 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=1

Response 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.

Type Pseudo field Description
action_run app_runs App runs (app commands) created by the Action.
action_run approvals Approvals associated with the Action.
app_run log Get logs (from spawn.log) pertaining to an app run id. Debug Logging has to be enabled.
container actions Actions created (both automated and manual) in response to the Container.
container attachments Any files attached to the Container (vault items).
container playbook_runs Playbooks run (both automated and manual) in response to the Container.
container artifacts All Artifacts that contribute to the Container.
container audit Audit information for a container.
container comments Comments added to the container.
container recommended_actions Brief set of recommendations for appropriate actions for the container.
container recommended_playbooks Brief set of recommendations for appropriate playbooks for the container.
playbook audit Audit information for a Playbook.
playbook_run actions Actions created by the Playbook.
playbook_run log Logged messages from playbook run (logging must have been enabled).
ph_user roles Roles that the user belongs to.
ph_user audit Audit information for the user.
role users Users that belong to the role.
role audit Audit information for users that belong to the role.
Last modified on 21 June, 2021
PREVIOUS
Using the REST API reference for Splunk Phantom
  NEXT
Update Records

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