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.