› › ›

黑名单

使用 异常 API 创建、检索、更新和删除端点 黑名单 条目。端点黑名单条目使用静态容器 ID (list_id) endpoint_blocklists 管理，必须先创建该容器 ID 才能添加黑名单条目。要使用这些 API，您必须拥有管理端点的权限。有关更多信息，请参考端点。

创建黑名单条目容器

编辑

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

请求体

编辑

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

list_id 值必须为 endpoint_blocklists。
namespace_type 值必须为 agnostic。
type 值必须为 endpoint。

名称	类型	描述	必填
`description`	字符串	描述黑名单条目容器。	是
`list_id`	字符串	必须设置为 `endpoint_blocklists`。	是
`meta`	对象	列表容器元数据的占位符。	否
`name`	字符串	黑名单条目容器的名称。	是
`namespace_type`	字符串	必须设置为 `agnostic`。	是
`tags`	字符串[]	包含单词和短语的字符串数组，用于帮助对黑名单条目容器进行分类。	否
`type`	字符串	必须设置为 `endpoint_events`。	是

示例请求

编辑

POST api/exception_lists
{
  "description": "Elastic Defend Blocklists List",
  "name": "Elastic Defend Blocklists List",
  "list_id": "endpoint_blocklists",
  "type": "endpoint_blocklists",
  "namespace_type": "agnostic"
}

响应代码

编辑

200: 表示调用成功。

响应有效负载

编辑

{
 "_version": "WzcsMV0=",
  "created_at": "2020-07-13T09:33:46.187Z",
  "created_by": "elastic",
  "description": "Elastic Defend Blocklists List",
  "id": "f320c070-c4eb-11ea-80bb-11861bae2798",
  "immutable": false,
  "list_id": "endpoint_blocklists",
  "name": "Elastic Defend Blocklists List",
  "namespace_type": "agnostic",
  "os_types": [],
  "tags": [],
  "tie_breaker_id": "2c08d5a5-2ecc-4d5a-acfb-0a367f25b3f3",
  "type": "endpoint_blocklists",
  "updated_at": "2020-07-13T09:33:46.359Z",
  "updated_by": "elastic",
  "version": 1
}

创建黑名单条目

编辑

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

请求体

编辑

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

list_id 值必须为 endpoint_blocklists。
namespace_type 值必须为 agnostic。
type 值必须为 simple。

名称	类型	描述	必填
`comments`	comment[]	`comment` 对象数组。	否，默认为空数组。
`description`	字符串	描述黑名单条目项。	是
`entries`	entry[]	包含黑名单条目查询条件的数组。有关更多详情，请参见 `entry` 对象模式。	是。
`list_id`	字符串	必须设置为 `endpoint_blocklists`。	是
`item_id`	字符串	异常项目的唯一标识符。	否，未提供时自动创建。
`meta`	对象	异常项目元数据的占位符。	否
`name`	字符串	黑名单条目的名称。	是
`namespace_type`	字符串	对于端点工件，必须设置为 `agnostic`。	是
`os_types`	os_type[]	使用此字段指定操作系统。只输入一个值。	是
`tags`	字符串[]	包含单词和短语的字符串数组，用于帮助对异常项目进行分类。标签也可用于将黑名单条目定义为全局适用于所有策略，或分配给一个或多个策略（每个策略）。有关更多详情，请参见范围分配。	否
`type`	字符串	必须设置为 `simple`。	是

示例请求

编辑

POST api/exception_lists/items

{
    "comments": [],
    "description": "some description about this entry",
    "entries": [
        {
            "field": "file.path",
            "value": [
                "c:/path/to/file.exe",
                "c:/path/to/file2.exe"
            ],
            "type": "match_any",
            "operator": "included"
        }
    ],
    "list_id": "endpoint_blocklists",
    "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": "file.path",
            "value": [
                "c:/path/to/file.exe",
                "c:/path/to/file2.exe"
            ],
            "type": "match_any",
            "operator": "included"
        }
    ],
    "id": "17ba1bf0-997c-11ec-b212-9f4ed8b5942f",
    "item_id": "29f480e6-6d34-4bc7-9038-f809f11cb679",
    "list_id": "endpoint_blocklists",
    "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_blocklists。
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`	字符串[]	包含单词和短语的字符串数组，用于帮助对异常项目进行分类。标签也可用于将黑名单条目定义为全局适用于所有策略，或分配给一个或多个策略（每个策略）。有关更多详情，请参见范围分配。	否
`type`	字符串	必须为 `simple`。	是
`_version`	字符串	版本 ID，通常在检索项目时由 API 返回。使用它可以确保针对最新版本进行更新。	否

示例请求

编辑

更新 entries

PUT api/exception_lists/items
{
    "_version": "WzEzNjIsMV0=",
    "name": "ABC blocklist",
    "description": "These applications must be blocked",
    "entries": [
        {
            "field": "file.path",
            "value": [
                "c:/path/to/file.exe",
                "c:/path/to/file2.exe"
                "c:/path/to/file3.exe"
            ],
            "type": "match_any",
            "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": "These applications must be blocked",
    "entries": [
        {
            "field": "file.path",
            "value": [
                "c:/path/to/file.exe",
                "c:/path/to/file2.exe"
                "c:/path/to/file3.exe"
            ],
            "type": "match_any",
            "operator": "included"
        }
    ],
    "id": "17ba1bf0-997c-11ec-b212-9f4ed8b5942f",
    "item_id": "29f480e6-6d34-4bc7-9038-f809f11cb679",
    "list_id": "endpoint_blocklists",
    "name": "ABC blocklist",
    "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

URL 查询参数

编辑

URL 查询必须包含以下内容之一：

id - 条目的 id，或
item_id - 条目的 item_id

除了以上内容外，还需要 namespace_type URL 查询参数，其值为 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": "These applications must be blocked",
  "entries": [
     {
            "field": "file.path",
            "value": [
                "c:/path/to/file.exe",
                "c:/path/to/file2.exe"
                "c:/path/to/file3.exe"
            ],
            "type": "match_any",
            "operator": "included"
      }
  ],
  "id": "17ba1bf0-997c-11ec-b212-9f4ed8b5942f",
  "item_id": "29f480e6-6d34-4bc7-9038-f809f11cb679",
  "list_id": "endpoint_blocklists",
  "name": "ABC blocklist",
  "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 查询参数

编辑

URL 查询必须包含以下内容之一：

id - 条目的 id，或
item_id - 条目的 item_id

除了以上内容外，还需要 namespace_type URL 查询参数，其值为 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": "These applications must be blocked",
  "entries": [
    {
            "field": "file.path",
            "value": [
                "c:/path/to/file.exe",
                "c:/path/to/file2.exe"
                "c:/path/to/file3.exe"
            ],
            "type": "match_any",
            "operator": "included"
      }
  ],
  "id": "17ba1bf0-997c-11ec-b212-9f4ed8b5942f",
  "item_id": "29f480e6-6d34-4bc7-9038-f809f11cb679",
  "list_id": "endpoint_blocklists",
  "name": "ABC blocklist",
  "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_blocklists`。	是
`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_blocklists&namespace_type=agnostic

响应代码

编辑

200: 表示调用成功。

响应有效负载

编辑

{
  "data": [
    {
      "_version": "WzEzNjcsMV0=",
      "comments": [],
      "created_at": "2022-03-01T16:24:39.471Z",
      "created_by": "elastic",
      "description": "These applications must be blocked",
      "entries": [
        {
            "field": "file.path",
            "value": [
                "c:/path/to/file.exe",
                "c:/path/to/file2.exe"
                "c:/path/to/file3.exe"
            ],
            "type": "match_any",
            "operator": "included"
        }
      ],
      "id": "17ba1bf0-997c-11ec-b212-9f4ed8b5942f",
      "item_id": "29f480e6-6d34-4bc7-9038-f809f11cb679",
      "list_id": "endpoint_blocklists",
      "name": "ABC blocklist",
      "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"
}

与更新 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>：黑名单条目分配给策略。可以使用多个 per policy 标签将黑名单条目与多个策略关联。

`entry` 对象模式

编辑

在端点黑名单条目上至少可以定义 3 个条件。不允许重复。黑名单条目支持以下条目：

文件哈希值

编辑

所有操作系统类型都支持文件哈希值。文件哈希条目具有以下结构：

field：支持 file.hash.md5、file.hash.sha1 或 file.hash.sha256 值。
value：与 field 关联的哈希值数组。
type：必须为 match_any。
operator：必须为 included。

{
    "field": "file.hash.md5",
    "value": [
        "741462ab431a22233C787BAAB9B653C7"
    ],
    "type": "match_any",
    "operator": "included"
}

进程文件路径

编辑

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

field：必须为 file.path。
value：要匹配的文件路径数组。
type：必须为 match_any。
operator：必须为 included。

{
  "field": "file.path",
  "value": "c:/path/to/file.exe",
  "type": "match_any",
  "operator": "included"
}

进程文件签名

编辑

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

field：必须设置为 file.Ext.code_signature。
type：必须设置为 nested。
entries：包含 1 个 entry 条目的数组。
entries[0]：定义要匹配的签名的条目
- field：必须设置为 subject_name。
- value：要匹配多个签名，请指定签名名称数组。要匹配单个签名，请将签名名称指定为字符串。
- type：要匹配多个签名，设置为 match_any。要匹配单个签名，设置为 match。
- operator：必须设置为 included。

{
    "field": "file.Ext.code_signature",
    "entries": [
        {
            "field": "subject_name",
            "value": [
                "test1",
                "test2"
            ],
            "type": "match_any",
            "operator": "included"
        }
    ],
    "type": "nested"
}

Windows 黑名单条目示例。

编辑

每个黑名单项只允许一个 file.path 或 file.Ext.code_signature 条目。同时支持 file.hash.* 条目，并最多接受三个值。 file.hash.* 允许的哈希类型为 md5、sha1 或 sha256。

[
 {
      "field": "file.hash.md5",
      "value": [
          "741462ab431a22233C787BAAB9B653C7"
      ],
      "type": "match_any",
      "operator": "included"
  },
  {
      "field": "file.hash.sha1",
      "value": [
          "aedb279e378BED6C2DB3C9DC9e12ba635e0b391c"
      ],
      "type": "match_any",
      "operator": "included"
  },
  {
      "field": "file.hash.sha256",
      "value": [
          "a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3"
      ],
      "type": "match_any",
      "operator": "included"
  }
]

[
 {
    "field": "file.Ext.code_signature",
    "entries": [
        {
            "field": "subject_name",
            "value": [
                "test1",
                "test2"
            ],
            "type": "match_any",
            "operator": "included"
        }
    ],
    "type": "nested"
 }
]

[
  {
    "field": "file.path",
    "value": "c:/path/to/file.exe",
    "type": "match_any",
    "operator": "included"
  }
]

« 主机隔离例外获取操作详情 »

黑名单

黑名单

创建黑名单条目容器

请求体

示例请求

响应代码

响应有效负载

创建黑名单条目

请求体

示例请求

响应代码

响应有效负载

更新黑名单条目

请求体

示例请求

响应代码

响应有效负载

删除黑名单条目

URL 查询参数

示例请求

响应代码

响应有效负载

检索单个黑名单条目

URL 查询参数

示例请求

响应代码

响应有效负载

查找黑名单条目

URL 查询参数

示例请求

响应代码

响应有效负载

值类型

comment 对象模式

os_types 值

范围分配

entry 对象模式

文件哈希值

进程文件路径

进程文件签名

Windows 黑名单条目示例。

`comment` 对象模式

`os_types` 值

`entry` 对象模式