« 事件过滤器 阻止列表 »
Elastic 文档 ›Elastic 安全解决方案 [8.17] ›Elastic 安全 API ›端点管理 API

主机隔离例外

编辑

主机隔离例外

编辑

新 API 参考

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

通过 API 创建、检索、更新和删除端点主机隔离例外。主机隔离例外通过例外 API 使用 endpoint_host_isolation_exceptions 的静态容器 ID (list_id) 进行管理，该 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>：主机隔离例外分配给策略。可以使用多个 按策略 标记将主机隔离例外关联到多个策略。

entry 对象模式

编辑

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

目标 IP
编辑

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

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