« 上传文件到主机 事件过滤器 »
Elastic 文档 ›Elastic Security Solution [8.14] ›Elastic Security API ›端点管理 API

受信任的应用程序

编辑

受信任的应用程序编辑

通过 API 创建、检索、更新和删除端点 受信任的应用程序。端点受信任的应用程序通过 Exceptions API 使用 endpoint_trusted_apps 的静态容器 ID (list_id) 进行管理，在添加受信任的应用程序之前必须先创建该 ID。要访问这些 API，用户必须具有管理端点的权限。

创建受信任应用程序容器编辑

POST <kibana 主机>:<端口>/api/exception_lists

请求正文编辑

包含下面所列字段的 JSON 对象。请求必须有以下内容

  • list_id 值必须是 endpoint_trusted_apps。
  • namespace_type 值必须是 agnostic。
  • type 值必须是 endpoint。
名称 类型 说明 是否必填

description

字符串

描述受信任的应用程序容器。

是

list_id

字符串

必须设置为 endpoint_trusted_apps。

是

meta

对象

列表容器元数据的占位符。

否

name

字符串

受信任的应用程序容器的名称。

是

namespace_type

字符串

必须设置为 agnostic。

是

tags

String[]

包含用于帮助对可信应用容器进行分类的单词和短语的字符串数组。

否

type

字符串

必须设置为 endpoint_events。

是

示例请求编辑

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"
}

响应代码编辑

200
表示调用成功。

响应负载编辑

{
  "_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"
}

创建可信应用编辑

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

请求主体编辑

包含下面所列字段的 JSON 对象。请求必须有以下内容

  • list_id 值必须是 endpoint_trusted_apps。
  • namespace_type 值必须是 agnostic。
  • type 值必须是 simple。
名称 类型 说明 是否必填

comments

comment[]

包含 comment 对象的数组。

否，默认为空数组。

description

字符串

描述可信应用项目。

是

entries

entry[]

包含可信应用查询条件的数组。有关更多详细信息，请参见 entry 对象架构。

是。

list_id

字符串

必须设置为 endpoint_trusted_apps。

是

item_id

字符串

异常项的唯一标识符。

否，在未提供时自动创建。

meta

对象

存储有关异常项的元数据的占位符。

否

name

字符串

可信应用名称。

是

namespace_type

字符串

对于端点派生物，必须设置为 agnostic。

是

os_types

os_type[]

使用此字段指定 操作系统。仅输入一个值。

是

tags

String[]

包含用于帮助对异常项进行分类的单词和短语的字符串数组。也可以使用标签来将可信应用定义为全局适用于所有策略或分配给一个或多个策略（针对每个策略）。有关更多详细信息，请参见 范围分配。

否

type

字符串

必须设置为 simple。

是
示例请求编辑
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"
}

响应代码编辑

200
表示调用成功。

响应负载编辑

{
    "_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"
}

更新可信应用编辑

PUT <kibana 主机>:<端口>/api/exception_lists/items

请求主体编辑

包含下面所列字段的 JSON 对象。请求必须有以下内容

  • list_id 值必须是 endpoint_trusted_apps。
  • namespace_type 值必须是 agnostic。
  • type 值必须是 simple。
名称 类型 说明 是否必填

comments

comment[]

包含 comment 对象的数组。

否，默认为空数组。

description

字符串

描述受信任的应用程序。

是

entries

entry[]

包含可信应用查询条件的数组。有关更多详细信息，请参见 entry 对象架构。

是。

id

字符串

项目的唯一标识符。

是，当项目的 item_id 字段未被使用时。

item_id

字符串

要更新的项目的 item_id。

是，当项目的 id 字段未被使用时。

meta

对象

存储有关异常项的元数据的占位符。

否

name

字符串

可信应用名称。

是

namespace_type

字符串

必须设置为 agnostic。

是

os_types

os_type[]

数组 os_type 值。

是

tags

String[]

包含用于帮助对异常项进行分类的单词和短语的字符串数组。也可以使用标签来将可信应用定义为全局适用于所有策略或分配给一个或多个策略（针对每个策略）。有关更多详细信息，请参见 范围分配。

否

type

字符串

必须为 simple。

是

_version

字符串

版本 id，通常在提取项目时由 API 返回。使用它以确保更新对于最新版本进行。

否
示例请求编辑

更新 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"
}

响应代码编辑

200
表示调用成功。

响应负载编辑

{
    "_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 <kibana 主机>:<端口>/api/exception_lists/items

网址查询参数编辑

网址查询必须包含以下一项

  • id - 项目的 id，或
  • item_id - 项目的 item_id

除了上述以外，网址查询参数 namespace_type 还必须存在，且值为 agnostic。

示例请求编辑

删除 item_id 为 29f480e6-6d34-4bc7-9038-f809f11cb679 的受信任应用程序

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

响应代码编辑

200
表示调用成功。

响应负载编辑

被删除的项目

{
  "_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"
}

检索单个受信任的应用程序编辑

GET <kibana 主机>:<端口>/api/exception_lists/items

URL 查询参数编辑

网址查询必须包含以下一项

  • id - 项目的 id，或
  • item_id - 项目的 item_id

除了上述以外，网址查询参数 namespace_type 还必须存在，且值为 agnostic。

示例请求编辑
GET api/exception_lists/items?item_id=29f480e6-6d34-4bc7-9038-f809f11cb679&namespace_type=agnostic

响应代码编辑

200
表示调用成功。

响应有效负载编辑

{
  "_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"
}

查找受信任的应用程序编辑

GET <kibana 主机>:<端口>/api/exception_lists/items/_find

URL 查询参数编辑

名称 类型 说明 是否必填

list_id

字符串

必须设置为 endpoint_trusted_apps。

是

namespace_type

字符串

必须设置为 agnostic。

是

page

整数

要返回的页数。

否

per_page

整数

每页返回的项目数。

否

sort_field

字符串

确定用于对结果进行排序的字段。

否

sort_order

字符串

确定排序顺序，可以是 desc 或 asc。

否

filter

字符串

用于对结果进行过滤的 Kibana 查询语言 (KQL) 字符串。

否
示例请求编辑
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

响应代码编辑

200
表示调用成功。

响应有效负载编辑

{
  "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
}

值类型编辑

以下描述了在使用 创建 或 更新 受信任的应用程序 API 时可以定义的类型

comment 对象模式编辑

注释是包含以下结构的 JSON 对象

{
    "comment": "some comment here"
}

与 _update_ API 配合使用时，可以通过使用相关联的 id 来更新现有注释，而任何没有 id 属性的注释将作为一条新注释添加

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

os_types 值编辑

以下是创建可信应用程序时可用的有效操作系统类型

  • windows
  • linux
  • macos

范围赋值编辑

可信应用程序可以在所有端点策略中全局分配，或分配给特定策略。您可以通过定义一个或多个前缀为 policy: 的标签来分配可信应用程序。请注意，可信应用程序可以是全局的或按策略分配的，但不能 同时 是两种。以下标签可用于控制分配范围

  • policy:all：可信应用程序对于所有策略都是全局的。如果使用，则不允许使用任何其他 policy: 标签。
  • policy:<endpoint-policy-id>：可信应用程序分配给一个策略。多个 每个策略 标签可用于将可信应用程序关联至多个策略。

entry 对象架构编辑

端点可信应用程序最多允许定义 3 个条件。不允许出现重复项。受信任的应用程序支持以下条目

进程哈希编辑

进程哈希受所有 操作系统类型 支持。哈希条目具有以下结构

{
  "field": "process.hash.sha1",
  "value": "aedb279e378bed6c2db3c9dc9e12ba635e0b391c",
  "type": "match",
  "operator": "included"
}
  • field：支持以下值：process.hash.md5、process.hash.sha1 或 process.hash.sha256。
  • value：与 field 关联的哈希值。
  • 类型：必须为 匹配。
  • 运算符：必须为 包含。
进程文件路径编辑

所有 操作系统类型都支持进程文件路径。文件路径条目具有以下结构

{
  "field": "process.executable.caseless",
  "value": "c:/path/to/file.exe",
  "type": "match",
  "operator": "included"
}
  • 字段：必须为 process.executable.caseless。
  • 值：要匹配的文件路径。
  • 类型：可以设置为 匹配（精确匹配）或 通配符。在使用 通配符时，可以在路径 值中使用 *。
  • 运算符：必须为 包含。
进程签名编辑

进程签名仅支持 Windows 操作系统类型。签名条目具有以下结构

{
  "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"
    }
  ]
}
  • 字段：必须设置为 process.Ext.code_signature。
  • 类型：必须设置为 嵌套。
  • 条目：一个包含 2 个 条目项的数组。
  • entries[0]：包含 { "field": "trusted", "value": "true", "type": "match", "operator": "included" } 的条目。

  • entries[1]：定义要匹配的签名的条目

    • 字段：必须设置为 subject_name。
    • 值：要匹配的签名名称。
    • 类型：必须设置为 匹配。
    • 运算符：必须设置为 包含。
Windows 受信任应用程序示例：编辑
[
  {
    "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"
  }
]
« 上传文件到主机 事件过滤器 »