› › ›

创建例外项

编辑

创建例外项

编辑

创建例外项并将其与指定的例外容器关联。

有关从列表（例如 IP 地址或主机名列表）创建例外项的信息，请参阅列表 API。

在创建例外项之前，您必须创建例外容器。

端点规则例外项不能使用列表（entries数组中的list），并且以下字段不能在例外查询中使用（作为entries对象中的field值）：

file.Ext.quarantine_path
file.Ext.quarantine_result
process.entity_id
process.parent.entity_id
process.ancestry

请求 URL

编辑

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

请求正文

编辑

包含以下字段的 JSON 对象

名称	类型	描述	必填
`comments`	comments[]	`comment` 字段的数组 `comment` (string): 关于例外项的注释。	否，默认为空数组。
`description`	字符串	描述例外项。	是
`entries`	entries[]	包含例外查询的数组。布尔值`AND`逻辑用于评估数组元素之间的关系。如果要使用`OR`逻辑，请创建单独的例外项。	是
`expire_time`	字符串	例外项的到期日期，采用 ISO 格式。此字段仅适用于常规例外项，不适用于端点例外。	否
`list_id`	字符串	关联的例外容器的 ID。	是
`item_id`	字符串	例外项的唯一标识符。	否，未提供时会自动创建。
`meta`	对象	关于例外项的元数据的占位符。	否
`name`	字符串	例外项的名称。	是
`namespace_type`	字符串	确定例外项是在所有 Kibana 空间中可用，还是仅在创建它的空间中可用，其中 `single`：仅在创建它的 Kibana 空间中可用。 `agnostic`：在所有 Kibana 空间中可用。必须与其关联的例外容器的值相同。	否，默认为`single`。
`tags`	String[]	包含用于帮助对例外项进行分类的单词和短语的字符串数组。	否
`type`	字符串	例外查询类型，必须为`simple`。	是
`_tags`	String[]	仅对于端点规则，定义实施例外的操作系统。有效值为 `os:windows`：Windows 操作系统 `os:linux`：Linux 操作系统 `os:macos`：Mac 操作系统该数组还必须包含一个`endpoint`元素（要在 Linux 主机上实施例外，请使用：`["endpoint", "os:linux"]`）。	对于端点例外，为是。对于检测例外，为否。

`entries` 架构

编辑

名称	类型	描述	必填
`field`	字符串	用于定义例外的源事件字段。不能为空字符串。	是
`list`	list	包含列表容器的`id`和`type`的对象。仅对检测例外项有效。	否，除非使用列表来定义检测例外。
`operator`	字符串	用于确定何时使用例外的运算符。可以是 `included`：`field` 具有指定的值或多个值。 `excluded`：`field` 没有指定的值或多个值。	是
`type`	字符串	查询的`type` `match`：必须与定义的值完全匹配。 `match_any`：匹配任何定义的值。 `exists`：该字段存在。 `list`：该字段与列表容器中的值匹配。 `wildcard`：使用通配符匹配`value`，例如`C:\path\\app.exe`。使用`?`匹配一个字符，使用``匹配零个或多个字符。`field`数据类型必须是keyword、text或wildcard。 `nested`：`entries`对象的数组。排除某些端点字段需要嵌套条件（请参阅以下示例）。具有嵌套条件的例外列出了所有需要`nested`类型的端点字段。	是
`value`	字符串 String[]	字段值或多个值字符串：当`type`为`match`或`wildcard`时。 String[]: 当`type`为`match_any`时。	是，当`type`为`exists`或`list`时除外。

当您使用列表容器（"type": "list"）时，您不能在entries数组中使用其他类型（match、match_any、exists或nested）。

对于端点例外，您不能基于排除的值创建例外项（"operator": "excluded"）。

示例请求

编辑

示例 1

将maintenance-job进程添加到trusted-linux-processes例外容器

POST api/exception_lists/items
{
  "description": "Excludes the weekly maintenance job",
  "entries": [
    {
      "field": "process.name",
      "operator": "included",
      "type": "match",
      "value": "maintenance-job"
    }
  ],
  "list_id": "trusted-linux-processes",
  "name": "Linux maintenance job",
  "namespace_type": "single",
  "tags": [
    "in-house processes",
    "linux"
  ],
  "type": "simple"
}

示例 2

将允许运行maintenance进程的主机添加到allowed-processes例外容器

POST api/exception_lists/items
{
  "comments": [
    {"comment": "Allows maintenance process to run on the specified machines"}
  ],
  "description": "Process allowlist",
  "entries": [
    {
      "field": "process.name",
      "operator": "included",
      "type": "match",
      "value": "maintenance"
    },
    { 
      "field": "host.name",
      "operator": "included",
      "type": "match_any",
      "value": [
        "liv-win-anf",
        "livw-win-mel",
        "linux-anfield"
      ]
    }
  ],
  "list_id": "allowed-processes",
  "item_id": "allow-process-on-machines",
  "name": "Host-process exclusions",
  "namespace_type": "single",
  "tags": [
    "hosts",
    "processes"
  ],
  "type": "simple"
}

使用AND运算符评估多个数组元素。

示例 3

为 Windows 操作系统上具有指定 SHA-1 哈希值的文件创建端点例外项

POST api/exception_lists/items
{
  "_tags": [
    "endpoint", 
    "os:windows" 
  ],
  "comments": [
  ]
  "description": "File exception for Windows",
  "entries": [
    {
      "field": "file.hash.sha1",
      "operator": "included",
      "type": "match",
      "value": "27fb21cf5db95ffca43b234affa99becc4023b9d"
    }
  ],
  "item_id": "trusted-windows-file",
  "list_id": "endpoint-exception-container",
  "name": "Trusted Windows file",
  "namespace_type": "agnostic", 
  "tags": [
  ]
  "type": "simple"
}

	指示此项用于端点规则。
	相关操作系统。
	可从所有 Kibana 空间访问的项。

示例 4

将external-ip-excludes列表容器作为例外项与trusted-IPs例外容器关联

POST api/exception_lists/items
{
  "description": "Uses the external-ip-container list to exclude trusted external IPs.",
  "entries": [
    {
      "field": "destination.ip",
      "list": {
        "id": "external-ip-excludes", 
        "type": "ip"
      },
      "operator": "included",
      "type": "list"
    }
  ],
  "list_id": "trusted-IPs", 
  "item_id": "external-IPs",
  "name": "Trusted external IPs",
  "namespace_type": "single",
  "tags": [
    "network",
    "trusted IPs"
  ],
  "type": "simple"
}

	保存 IP 地址列表项的列表容器。
	例外容器的 ID。

示例 5

为嵌套的端点字段添加例外

POST api/exception_lists/items
{
  "description": "Excludes all processes signed by Trusted Signer, Inc.",
  "entries": [
    {
      "field": "process.Ext.code_signature",
      "type": "nested",
      "entries": [
        {
          "field": "trusted",
          "type": "match",
          "operator": "included",
          "value": "true"
        },
        {
          "field": "subject_name",
          "type": "match",
          "operator": "included",
          "value": "Trusted Signer, Inc."
        }
      ]
    }
  ],
  "list_id": "trusted-self-signed-processes",
  "name": "In-house processes",
  "namespace_type": "single",
  "tags": [
    "in-house processes",
    "linux"
  ],
  "type": "simple"
}

响应代码

编辑

200: 表示调用成功。

响应有效负载

编辑

{
  "_tags": [],
  "comments": [
    {
      "comment": "Allows maintenance process to run on the specified machines",
      "created_at": "2020-07-14T08:36:33.172Z",
      "created_by": "elastic",
      "id": "f6c61b4d-31dd-4a5d-8c73-f64787d03b4d"
    }
  ],
  "created_at": "2020-07-14T08:36:33.172Z",
  "created_by": "elastic",
  "description": "Process allowlist",
  "entries": [
    {
      "field": "process.name",
      "operator": "included",
      "type": "match",
      "value": "maintenance"
    },
    {
      "field": "host.name",
      "operator": "included",
      "type": "match_any",
      "value": [
        "liv-win-anf",
        "livw-win-mel",
        "linux-anfield"
      ]
    }
  ],
  "id": "1f4d38b0-c5ad-11ea-a3d8-a5b753aeeb9e",
  "item_id": "allow-process-on-machines",
  "list_id": "allowed-processes",
  "name": "Host-process exclusions",
  "namespace_type": "single",
  "tags": [
    "hosts",
    "processes"
  ],
  "tie_breaker_id": "bb04f1c7-2537-47c1-aaca-40a7c8f771d3",
  "type": "simple",
  "updated_at": "2020-07-14T08:36:33.339Z",
  "updated_by": "elastic"
}

« 创建例外容器创建共享例外列表 »

创建例外项

创建例外项

请求 URL

请求正文

entries 架构

示例请求

响应代码

响应有效负载

`entries` 架构