« 事件过滤器 黑名单 »
Elastic 文档 ›Elastic 安全解决方案 [8.16] ›Elastic 安全 API ›端点管理 API

主机隔离异常

编辑

主机隔离异常

编辑

新的 API 参考

有关最新的 API 详情，请参阅 端点管理 API。

通过 API 创建、检索、更新和删除端点主机隔离异常。主机隔离异常通过异常 API 使用静态容器 ID（list_id）为 endpoint_host_isolation_exceptions 进行管理，必须先创建此 ID 才能添加主机隔离异常。访问这些 API 需要用户具有管理端点的权限。

创建主机隔离异常容器

编辑

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

请求正文

编辑

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

  • list_id 值必须为 endpoint_host_isolation_exceptions。
  • namespace_type 值必须为 agnostic。
  • type 值必须为 endpoint_host_isolation_exceptions。
名称 类型 描述 必填

description

字符串

描述主机隔离异常容器。

是

list_id

字符串

必须设置为 endpoint_host_isolation_exceptions。

是

meta

对象

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

否

name

字符串

主机隔离异常容器的名称。

是

namespace_type

字符串

必须设置为 agnostic。

是

tags

字符串[]

包含单词和短语的字符串数组，用于帮助对主机隔离异常容器进行分类。

否

type

字符串

必须设置为 endpoint_host_isolation_exceptions。

是

示例请求

编辑
POST api/exception_lists
{
  "description": "Elastic Defend Host Isolation Exceptions List",
  "name": "Elastic Defend Host Isolation Exceptions List",
  "list_id": "endpoint_host_isolation_exceptions",
  "type": "endpoint_host_isolation_exceptions",
  "namespace_type": "agnostic"
}

响应代码

编辑
200
表示成功调用。

响应有效负载

编辑
{
	"_version": "WzIxMTgsMV0=",
	"created_at": "2022-03-03T13:55:32.176Z",
	"created_by": "elastic",
	"description": "Elastic Defend Host Isolation Exceptions List",
	"id": "978cbd00-9af9-11ec-94b1-fd7e90cc2a08",
	"immutable": false,
	"list_id": "endpoint_host_isolation_exceptions",
	"name": "Elastic Defend Host Isolation Exceptions List",
	"namespace_type": "agnostic",
	"os_types": [],
	"tags": [],
	"tie_breaker_id": "9894ae5c-2ce0-47dc-8c52-784ca2219fc3",
	"type": "endpoint_host_isolation_exceptions",
	"updated_at": "2022-03-03T13:55:32.178Z",
	"updated_by": "elastic",
	"version": 1
}

创建主机隔离异常

编辑

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

请求正文

编辑

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

  • list_id 值必须为 endpoint_host_isolation_exceptions。
  • namespace_type 值必须为 agnostic。
  • type 值必须为 simple。
  • os_types 必须是一个包含所有os_types 值 的数组
名称 类型 描述 必填

comments

comment[]

comment 对象的数组。

否，默认为空数组。

description

字符串

描述主机隔离异常项。

是

entries

entry[]

包含主机隔离异常查询条件的数组。有关详细信息，请参阅entry 对象模式。

是。

list_id

字符串

必须设置为 endpoint_host_isolation_exceptions。

是

item_id

字符串

异常项的唯一标识符。

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

meta

对象

异常项元数据的占位符。

否

name

字符串

主机隔离异常名称。

是

namespace_type

字符串

对于端点工件，必须设置为 agnostic。

是

os_types

os_type[]

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

是

tags

字符串[]

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

否

type

字符串

必须设置为 simple。

是
示例请求
编辑
POST api/exception_lists/items
{
  "description": "some description about this entry",
  "entries": [
      {
          "field": "destination.ip",
          "value": "10.10.0.1",
          "type": "match",
          "operator": "included"
      }
  ],
  "list_id": "endpoint_host_isolation_exceptions",
  "name": "Some name for this item",
  "namespace_type": "agnostic",
  "os_types": [
    "linux",
    "macos",
    "windows"
  ],
  "tags": [
      "policy:all"
  ],
  "type": "simple"
}

响应代码

编辑
200
表示成功调用。

响应有效负载

编辑
{
	"_version": "WzIxNDcsMV0=",
	"created_at": "2022-03-03T14:04:00.496Z",
	"created_by": "elastic",
	"description": "some description about this entry",
	"entries": [
		{
			"field": "destination.ip",
			"value": "10.10.0.1",
			"type": "match",
			"operator": "included"
		}
	],
	"id": "c6883700-9afa-11ec-94b1-fd7e90cc2a08",
	"item_id": "1342081d-66ad-4b03-b554-131195ce404b",
	"list_id": "endpoint_host_isolation_exceptions",
	"name": "Host Isolation Exception - Created with API",
	"namespace_type": "agnostic",
	"os_types": [
		"linux",
		"macos",
		"windows"
	],
	"tags": [
		"policy:all"
	],
	"tie_breaker_id": "b65843e1-07b8-46d2-9e2b-5f0586dc364a",
	"type": "simple",
	"updated_at": "2022-03-03T14:04:00.498Z",
	"updated_by": "elastic"
}

更新主机隔离异常

编辑

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

请求正文

编辑

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

  • list_id 值必须为 endpoint_host_isolation_exceptions。
  • namespace_type 值必须为 agnostic。
  • type 值必须为 simple。
  • os_types 必须是一个包含所有os_types 值 的数组
名称 类型 描述 必填

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
{
	"description": "via API",
	"entries": [
		{
			"field": "destination.ip",
			"type": "match",
			"value": "10.10.0.15",
			"operator": "included"
		}
	],
	"id": "c6883700-9afa-11ec-94b1-fd7e90cc2a08",
	"item_id": "1342081d-66ad-4b03-b554-131195ce404b",
	"name": "Host Isolation Exception - Created with API",
	"namespace_type": "agnostic",
	"os_types": [
		"linux",
		"macos",
		"windows"
	],
	"type": "simple"
}

响应代码

编辑
200
表示成功调用。

响应有效负载

编辑
{
	"_version": "WzIyMDIsMV0=",
	"created_at": "2022-03-03T14:04:00.496Z",
	"created_by": "elastic",
	"description": "via API",
	"entries": [
		{
			"field": "destination.ip",
			"type": "match",
			"value": "10.10.0.15",
			"operator": "included"
		}
	],
	"id": "c6883700-9afa-11ec-94b1-fd7e90cc2a08",
	"item_id": "1342081d-66ad-4b03-b554-131195ce404b",
	"list_id": "endpoint_host_isolation_exceptions",
	"name": "HIE via API",
	"namespace_type": "agnostic",
	"os_types": [
		"linux",
		"macos",
		"windows"
	],
	"tags": [],
	"tie_breaker_id": "b65843e1-07b8-46d2-9e2b-5f0586dc364a",
	"type": "simple",
	"updated_at": "2022-03-03T14:22:08.345Z",
	"updated_by": "elastic"
}

删除主机隔离异常

编辑

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

URL 查询参数

编辑

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

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

除了以上内容外，还需要 namespace_type URL 查询参数，其值为 agnostic。

示例请求
编辑

删除 item_id 为 1342081d-66ad-4b03-b554-131195ce404b 的主机隔离异常。

DELETE api/exception_lists/items?item_id=1342081d-66ad-4b03-b554-131195ce404b&namespace_type=agnostic

响应代码

编辑
200
表示成功调用。

响应有效负载

编辑

已删除的项目

{
	"_version": "WzIyNDksMV0=",
	"comments": [],
	"created_at": "2022-03-04T12:42:41.797Z",
	"created_by": "elastic",
	"description": "some description about this entry",
	"entries": [
		{
			"field": "destination.ip",
			"value": "10.10.0.1",
			"type": "match",
			"operator": "included"
		}
	],
	"id": "c6883700-9afa-11ec-94b1-fd7e90cc2a08",
	"item_id": "1342081d-66ad-4b03-b554-131195ce404b",
	"list_id": "endpoint_host_isolation_exceptions",
	"name": "Host Isolation Exception via API",
	"namespace_type": "agnostic",
	"os_types": [
		"linux",
		"macos",
		"windows"
	],
	"tags": [
		"policy:all"
	],
	"tie_breaker_id": "c0401075-7bd5-47e2-bd6c-4f7e088aa348",
	"type": "simple",
	"updated_at": "2022-03-04T12:42:41.802Z",
	"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=1342081d-66ad-4b03-b554-131195ce404b&namespace_type=agnostic

响应代码

编辑
200
表示成功调用。

响应有效负载

编辑
{
  "_version": "WzEzNjcsMV0=",
  "created_at": "2022-03-01T16:24:39.471Z",
  "created_by": "elastic",
  "description": "Host Isolation Exception item via API",
  "entries": [
    {
      "field": "destination.ip",
      "type": "match",
      "value": "10.10.0.15",
      "operator": "included"
    }
  ],
  "id": "c6883700-9afa-11ec-94b1-fd7e90cc2a08",
	"item_id": "1342081d-66ad-4b03-b554-131195ce404b",
  "list_id": "endpoint_host_isolation_exceptions",
  "name": "Host Isolation Exception via API",
  "namespace_type": "agnostic",
  "os_types": [
		"linux",
		"macos",
		"windows"
	],
  "tags": [
    "policy:all"
  ],
  "tie_breaker_id": "97fe9d23-c8b8-4dc1-97e1-16444c8d863a",
  "type": "simple",
  "updated_at": "2022-03-01T17:21:07.273Z",
  "updated_by": "elastic"
}

查找主机隔离异常

编辑

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

URL 查询参数

编辑
名称 类型 描述 必填

list_id

字符串

必须设置为 endpoint_host_isolation_exceptions。

是

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_host_isolation_exceptions&namespace_type=agnostic

响应代码

编辑
200
表示成功调用。

响应有效负载

编辑
{
  "data": [
    {
      "_version": "WzEzNjcsMV0=",
      "created_at": "2022-03-01T16:24:39.471Z",
      "created_by": "elastic",
      "description": "Host Isolation Exception item via API",
      "entries": [
        {
          "field": "destination.ip",
          "type": "match",
          "value": "10.10.0.15",
          "operator": "included"
        }
      ],
      "id": "4e0e4e10-9af8-11ec-94b1-fd7e90cc2a08",
      "item_id": "6555a6ed-b31c-4c74-b1a1-f2c5d9fb7d4a",
      "list_id": "endpoint_host_isolation_exceptions",
      "name": "Host Isolation Exception via API",
      "namespace_type": "agnostic",
      "os_types": [
        "linux",
        "macos",
        "windows"
      ],
      "tags": [
        "policy:all"
      ],
      "tie_breaker_id": "97fe9d23-c8b8-4dc1-97e1-16444c8d863a",
      "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 对象模式

编辑

主机隔离异常最多允许定义 1 个条件。主机隔离异常支持以下条目：

目标 IP
编辑

所有操作系统类型 都支持目标 IP。目标 IP 条目具有以下结构：

{
  "field": "destination.ip",
  "value": "192.168.1.1",
  "type": "match",
  "operator": "included"
}
  • field：destination.ip。
  • value：有效的 IPv4 地址，以及与 field 关联的可选 CIDR。
  • type：必须为 match。
  • operator：必须为 included。
« 事件过滤器 黑名单 »