IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

› › ›

Trusted applications

edit

Trusted applications

edit

Create, retrieve, update, and delete endpoint Trusted applications via API. Endpoint trusted applications are managed via the Exceptions API using a static container id (list_id) of endpoint_trusted_apps, which must be created prior to adding the trusted applications. Access to these APIs requires that a user has authorization to manage endpoints.

Create trusted applications container

edit

POST <kibana host>:<port>/api/exception_lists

Request body

edit

A JSON object containing the fields listed below. The request must have the following:

The list_id value must be endpoint_trusted_apps.
The namespace_type value must be agnostic.
The type value must be endpoint.

Name	Type	Description	Required
`description`	String	Describes the trusted applications container.	Yes
`list_id`	String	Must be set to `endpoint_trusted_apps`.	Yes
`meta`	Object	Placeholder for metadata about the list container.	No
`name`	String	The trusted applications container’s name.	Yes
`namespace_type`	String	Must be set to `agnostic`.	Yes
`tags`	String[]	String array containing words and phrases to help categorize the trusted applications container.	No
`type`	String	Must be set to `endpoint_events`.	Yes

Example request

edit

POST api/exception_lists
{
  "description": "Elastic Defend Trusted Apps List",
  "name": "Elastic Defend Trusted Apps List",
  "list_id": "endpoint_trusted_apps",
  "type": "endpoint",
  "namespace_type": "agnostic"
}

Response code

edit

200: Indicates a successful call.

Response payload

edit

{
  "_tags": [],
  "created_at": "2020-07-13T09:33:46.187Z",
  "created_by": "elastic",
  "description": "Elastic Defend Trusted Apps List",
  "name": "Elastic Defend Trusted Apps List",
  "list_id": "endpoint_trusted_apps",
  "type": "endpoint",
  "namespace_type": "agnostic",
  "id": "f320c070-c4eb-11ea-80bb-11861bae2798",
  "tags": [],
  "tie_breaker_id": "2c08d5a5-2ecc-4d5a-acfb-0a367f25b3f3",
  "updated_at": "2020-07-13T09:33:46.359Z",
  "updated_by": "elastic"
}

Create trusted application

edit

POST <kibana host>:<port>/api/exception_lists/items

Request body

edit

A JSON object containing the fields listed below. The request must have the following:

The list_id value must be endpoint_trusted_apps.
The namespace_type value must be agnostic.
The type value must be simple.

Name	Type	Description	Required
`comments`	comment[]	Array of `comment` objects.	No, defaults to empty array.
`description`	String	Describes the trusted application item.	Yes
`entries`	entry[]	Array containing the trusted application query conditions. See `entry` object schema for more details.	Yes.
`list_id`	String	Must be set to `endpoint_trusted_apps`.	Yes
`item_id`	String	Unique identifier of the exception item.	No, automatically created when it is not provided.
`meta`	Object	Placeholder for metadata about the exception item.	No
`name`	String	The trusted application name.	Yes
`namespace_type`	String	Must be set to `agnostic` for endpoint artifacts.	Yes
`os_types`	os_type[]	Use this field to specify the operating system. Only enter one value.	Yes
`tags`	String[]	An array of strings containing words and phrases to help categorize exception items. Tags can also be used to define the trusted application as either globally applicable to all policies or assigned to one or more policies (per policy). See Scope assignment for more details.	No
`type`	String	Must be set to `simple`.	Yes

Example request

edit

POST api/exception_lists/items
{
    "comments": [],
    "description": "some description about this entry",
    "entries": [
        {
            "field": "process.executable.caseless",
            "value": "c:\\applications\\elastic\\foo.exe",
            "type": "match",
            "operator": "included"
        }
    ],
    "list_id": "endpoint_trusted_apps",
    "name": "Some name for this item",
    "namespace_type": "agnostic",
    "os_types": [
        "windows"
    ],
    "tags": [
        "policy:all"
    ],
    "type": "simple"
}

Response code

edit

200: Indicates a successful call.

Response payload

edit

{
    "_version": "WzEzNjIsMV0=",
    "comments": [],
    "created_at": "2022-03-01T16:24:39.471Z",
    "created_by": "elastic",
    "description": "some description about this entry",
    "entries": [
        {
            "field": "process.executable.caseless",
            "value": "c:\\applications\\elastic\\foo.exe",
            "type": "match",
            "operator": "included"
        }
    ],
    "id": "17ba1bf0-997c-11ec-b212-9f4ed8b5942f",
    "item_id": "29f480e6-6d34-4bc7-9038-f809f11cb679",
    "list_id": "endpoint_trusted_apps",
    "name": "Some name for this item",
    "namespace_type": "agnostic",
    "os_types": [
        "windows"
    ],
    "tags": [
        "policy:all"
    ],
    "tie_breaker_id": "c6bedf22-2292-4d4a-8eb8-e29a50b5b519",
    "type": "simple",
    "updated_at": "2022-03-01T16:24:39.475Z",
    "updated_by": "elastic"
}

Update trusted application

edit

PUT <kibana host>:<port>/api/exception_lists/items

Request body

edit

A JSON object containing the fields listed below. The request must have the following:

The list_id value must be endpoint_trusted_apps.
The namespace_type value must be agnostic.
The type value must be simple.

Name	Type	Description	Required
`comments`	comment[]	Array of `comment` objects.	No, defaults to empty array.
`description`	String	Describes the trusted application.	Yes
`entries`	entry[]	Array containing the trusted application query conditions. See `entry` object schema for more details.	Yes.
`id`	String	The item’s unique identifier.	Yes, when the item’s `item_id` field is not used.
`item_id`	String	The `item_id` of the item you are updating.	Yes, when the item’s `id` field is not used.
`meta`	Object	Placeholder for metadata about the exception item.	No
`name`	String	The trusted application name.	Yes
`namespace_type`	String	Must be set to `agnostic`.	Yes
`os_types`	os_type[]	Array of os_type values.	Yes
`tags`	String[]	An array of strings containing words and phrases to help categorize exception items. Tags can also be used to define the trusted application as either globally applicable to all policies or assigned to one or more policies (per policy). See Scope assignment for more details.	No
`type`	String	Must be `simple`.	Yes
`_version`	String	The version id, normally returned by the API when the item was retrieved. Use it ensure updates are done against the latest version.	No

Example request

edit

Updates the entries:

PUT api/exception_lists/items
{
    "_version": "WzEzNjIsMV0=",
    "name": "App ABC",
    "description": "This app is good",
    "entries": [
        {
            "field": "process.hash.sha1",
            "value": "aedb279e378bed6c2db3c9dc9e12ba635e0b391c",
            "type": "match",
            "operator": "included"
        }
    ],
    "os_types": [
        "windows"
    ],
    "tags": [
        "policy:all"
    ],
    "id": "17ba1bf0-997c-11ec-b212-9f4ed8b5942f",
    "comments": [],
    "item_id": "29f480e6-6d34-4bc7-9038-f809f11cb679",
    "namespace_type": "agnostic",
    "type": "simple"
}

Response code

edit

200: Indicates a successful call.

Response payload

edit

{
    "_version": "WzEzNjcsMV0=",
    "comments": [],
    "created_at": "2022-03-01T16:24:39.471Z",
    "created_by": "elastic",
    "description": "This app is good",
    "entries": [
        {
            "field": "process.hash.sha1",
            "value": "aedb279e378bed6c2db3c9dc9e12ba635e0b391c",
            "type": "match",
            "operator": "included"
        }
    ],
    "id": "17ba1bf0-997c-11ec-b212-9f4ed8b5942f",
    "item_id": "29f480e6-6d34-4bc7-9038-f809f11cb679",
    "list_id": "endpoint_trusted_apps",
    "name": "App ABC",
    "namespace_type": "agnostic",
    "os_types": [
        "windows"
    ],
    "tags": [
        "policy:all"
    ],
    "tie_breaker_id": "c6bedf22-2292-4d4a-8eb8-e29a50b5b519",
    "type": "simple",
    "updated_at": "2022-03-01T17:21:07.273Z",
    "updated_by": "elastic"
}

Delete trusted application

edit

DELETE <kibana host>:<port>/api/exception_lists/items

URL query parameters

edit

The URL query must include one of the following:

id - the id of the item, or
item_id - the item_id of the item

In addition to the above, namespace_type URL query parameter is also required with a value of agnostic.

Example request

edit

Deletes the trusted application with item_id of 29f480e6-6d34-4bc7-9038-f809f11cb679:

DELETE api/exception_lists/items?item_id=29f480e6-6d34-4bc7-9038-f809f11cb679&namespace_type=agnostic

Response code

edit

200: Indicates a successful call.

Response payload

edit

The item that was deleted:

{
  "_version": "WzEzNjcsMV0=",
  "comments": [],
  "created_at": "2022-03-01T16:24:39.471Z",
  "created_by": "elastic",
  "description": "This app is good",
  "entries": [
    {
      "field": "process.hash.sha1",
      "type": "match",
      "value": "aedb279e378bed6c2db3c9dc9e12ba635e0b391c",
      "operator": "included"
    }
  ],
  "id": "17ba1bf0-997c-11ec-b212-9f4ed8b5942f",
  "item_id": "29f480e6-6d34-4bc7-9038-f809f11cb679",
  "list_id": "endpoint_trusted_apps",
  "name": "App ABC",
  "namespace_type": "agnostic",
  "os_types": [
    "windows"
  ],
  "tags": [
    "policy:all"
  ],
  "tie_breaker_id": "c6bedf22-2292-4d4a-8eb8-e29a50b5b519",
  "type": "simple",
  "updated_at": "2022-03-01T17:21:07.273Z",
  "updated_by": "elastic"
}

Retrieve single trusted application

edit

GET <kibana host>:<port>/api/exception_lists/items

URL query parameters

edit

The URL query must include one of the following:

id - the id of the item, or
item_id - the item_id of the item

In addition to the above, namespace_type URL query parameter is also required with a value of agnostic.

Example request

edit

GET api/exception_lists/items?item_id=29f480e6-6d34-4bc7-9038-f809f11cb679&namespace_type=agnostic

Response code

edit

200: Indicates a successful call.

Response payload

edit

{
  "_version": "WzEzNjcsMV0=",
  "comments": [],
  "created_at": "2022-03-01T16:24:39.471Z",
  "created_by": "elastic",
  "description": "This app is good",
  "entries": [
    {
      "field": "process.hash.sha1",
      "type": "match",
      "value": "aedb279e378bed6c2db3c9dc9e12ba635e0b391c",
      "operator": "included"
    }
  ],
  "id": "17ba1bf0-997c-11ec-b212-9f4ed8b5942f",
  "item_id": "29f480e6-6d34-4bc7-9038-f809f11cb679",
  "list_id": "endpoint_trusted_apps",
  "name": "App ABC",
  "namespace_type": "agnostic",
  "os_types": [
    "windows"
  ],
  "tags": [
    "policy:all"
  ],
  "tie_breaker_id": "c6bedf22-2292-4d4a-8eb8-e29a50b5b519",
  "type": "simple",
  "updated_at": "2022-03-01T17:21:07.273Z",
  "updated_by": "elastic"
}

Find trusted applications

edit

GET <kibana host>:<port>/api/exception_lists/items/_find

URL query parameters

edit

Name	Type	Description	Required
`list_id`	String	Must be set to `endpoint_trusted_apps`.	Yes
`namespace_type`	String	Must be set to `agnostic`.	Yes
`page`	Integer	The page number to return.	No
`per_page`	Integer	The number of items to return per page.	No
`sort_field`	String	Determines which field is used to sort the results.	No
`sort_order`	String	Determines the sort order, which can be `desc` or `asc`.	No
`filter`	String	A Kibana Query Language (KQL) string to filter the results down.	No

Example request

edit

GET api/exception_lists/items/_find?page=1&per_page=10&sort_field=name&sort_order=asc&list_id=endpoint_trusted_apps&namespace_type=agnostic

Response code

edit

200: Indicates a successful call.

Response payload

edit

{
  "data": [
    {
      "_version": "WzEzNjcsMV0=",
      "comments": [],
      "created_at": "2022-03-01T16:24:39.471Z",
      "created_by": "elastic",
      "description": "This app is good",
      "entries": [
        {
          "field": "process.hash.sha1",
          "type": "match",
          "value": "aedb279e378bed6c2db3c9dc9e12ba635e0b391c",
          "operator": "included"
        }
      ],
      "id": "17ba1bf0-997c-11ec-b212-9f4ed8b5942f",
      "item_id": "29f480e6-6d34-4bc7-9038-f809f11cb679",
      "list_id": "endpoint_trusted_apps",
      "name": "App ABC",
      "namespace_type": "agnostic",
      "os_types": [
        "windows"
      ],
      "tags": [
        "policy:all"
      ],
      "tie_breaker_id": "c6bedf22-2292-4d4a-8eb8-e29a50b5b519",
      "type": "simple",
      "updated_at": "2022-03-01T17:21:07.273Z",
      "updated_by": "elastic"
    }
  ],
  "page": 1,
  "per_page": 10,
  "total": 1
}

Value types

edit

The following describes the types that can be defined when using the create or update trusted applications APIs:

`comment` object schema

edit

Comments are JSON objects containing the following structure:

{
    "comment": "some comment here"
}

When used with the update API, existing comments can be updated by using their associated id, while any comment without the id attribute will be added as a new comment:

{
    "comment": "some comment here - updated",
    "id": "1078cf59-5893-4143-acf7-40a40af16bee"
}

`os_types` values

edit

The following are the valid OS types that can be used when creating trusted applications:

windows
linux
macos

Scope assignment

edit

Trusted applications can be assigned globally across all endpoint policies, or assigned to specific policies. You can assign the trusted application by defining one or more tags with a prefix of policy:. Note that the trusted application can be either global or per policy, but not both. The following tags are available for use in order to control the assignment scope:

policy:all : Trusted application is global to all policies. If used, no other policy: tag is allowed.
policy:<endpoint-policy-id> : Trusted application is assigned to a policy. Multiple per policy tags can be used to associate the trusted application to multiple policies.

`entry` object schema

edit

Endpoint trusted applications allow for at most 3 conditions to be defined. No duplicates are allowed. The following entries are supported by trusted applications:

Process hashes

edit

Process hashes are supported by all OS types. A hash entry has the following structure:

{
  "field": "process.hash.sha1",
  "value": "aedb279e378bed6c2db3c9dc9e12ba635e0b391c",
  "type": "match",
  "operator": "included"
}

field : The following values are supported: process.hash.md5, process.hash.sha1 or process.hash.sha256.
value : The hash value associated with the field.
type : Must be match.
operator : Must be included.

Process file path

edit

Process file paths are supported by all OS types. A file path entry has the following structure:

{
  "field": "process.executable.caseless",
  "value": "c:/path/to/file.exe",
  "type": "match",
  "operator": "included"
}

field : Must be process.executable.caseless.
value : The file path to match on.
type : Can be set to match (exact match) or wildcard. When using wildcard, the * can be used in the path value.
operator : Must be included.

Process signature

edit

Process signature is supported only for Windows OS type. A signature entry has the following structure:

{
  "field": "process.Ext.code_signature",
  "type": "nested",
  "entries": [
    {
      "field": "trusted",
      "value": "true",
      "type": "match",
      "operator": "included"
    },
    {
      "field": "subject_name",
      "value": "elastic",
      "type": "match",
      "operator": "included"
    }
  ]
}

field : Must be set to process.Ext.code_signature.
type : Must be set to nested.
entries: An array with 2 entry items.
entries[0] : An entry with { "field": "trusted", "value": "true", "type": "match", "operator": "included" }.
entries[1] : The entry defining the signature to be matched upon:
- field: Must be set to subject_name.
- value : The signature name to match on.
- type : Must be set to match.
- operator : Must be set to included.

Example for a Windows trusted application:

edit

[
  {
    "field": "process.hash.sha1",
    "value": "aedb279e378bed6c2db3c9dc9e12ba635e0b391c",
    "type": "match",
    "operator": "included"
  },
  {
    "field": "process.executable.caseless",
    "value": "c:/path/to/file.exe",
    "type": "match",
    "operator": "included"
  },
  {
    "field": "process.Ext.code_signature",
    "entries": [
      {
        "field": "trusted",
        "value": "true",
        "type": "match",
        "operator": "included"
      },
      {
        "field": "subject_name",
        "value": "elastic",
        "type": "match",
        "operator": "included"
      }
    ],
    "type": "nested"
  }
]

« Upload file to host Event filters »

Trusted applications

Trusted applications

Create trusted applications container

Request body

Example request

Response code

Response payload

Create trusted application

Request body

Example request

Response code

Response payload

Update trusted application

Request body

Example request

Response code

Response payload

Delete trusted application

URL query parameters

Example request

Response code

Response payload

Retrieve single trusted application

URL query parameters

Example request

Response code

Response payload

Find trusted applications

URL query parameters

Example request

Response code

Response payload

Value types

comment object schema

os_types values

Scope assignment

entry object schema

Process hashes

Process file path

Process signature

Example for a Windows trusted application:

`comment` object schema

`os_types` values

`entry` object schema