« 管道处理器 注册域名处理器 »
Elastic 文档 ›Elasticsearch 指南 [8.17] ›摄取管道 ›摄取处理器参考

密文处理器

编辑

密文处理器

编辑

密文处理器使用 Grok 规则引擎来模糊输入文档中与给定 Grok 模式匹配的文本。该处理器可以通过配置来检测已知模式（如电子邮件或 IP 地址）以模糊个人身份信息 (PII)。与 Grok 模式匹配的文本会被替换为可配置的字符串，例如匹配电子邮件地址时使用 <EMAIL>，或者如果首选，则简单地将所有匹配项替换为文本 <REDACTED>。

Elasticsearch 打包了许多有用的预定义模式，可以通过密文处理器方便地引用。如果其中一个不适合您的需要，请使用自定义模式定义创建新模式。密文处理器会替换每次出现的匹配项。如果有多个匹配项，所有匹配项都将替换为模式名称。

密文处理器与Elastic Common Schema (ECS)模式兼容。不支持旧版 Grok 模式。

在管道中使用密文处理器

编辑

表 35. 密文选项

名称 必需 默认值 描述

field

是

-

要密文的字段

patterns

是

-

一个 Grok 表达式列表，用于匹配和密文具有命名捕获的内容

pattern_definitions

否

-

一个模式名称和模式元组的映射，定义处理器要使用的自定义模式。与现有名称匹配的模式将覆盖预先存在的定义

prefix

否

<

使用此标记开始密文部分

suffix

否

>

使用此标记结束密文部分

ignore_missing

否

true

如果 true 并且 field 不存在或为 null，则处理器将静默退出，而不修改文档

description

否

-

处理器的描述。用于描述处理器的目的或其配置。

if

否

-

有条件地执行处理器。请参阅有条件地运行处理器。

ignore_failure

否

false

忽略处理器的失败。请参阅处理管道失败。

on_failure

否

-

处理处理器的失败。请参阅处理管道失败。

tag

否

-

处理器的标识符。对于调试和指标很有用。

skip_if_unlicensed

否

false

如果 true 并且当前许可证不支持运行密文处理器，则处理器将静默退出，而不修改文档

trace_redact

否

false

如果 true，则如果文档已被密文，摄取元数据 _ingest._redact._is_redacted 将设置为 true

在此示例中，预定义的 IP Grok 模式用于匹配和密文 message 文本字段中的 IP 地址。使用模拟 API 测试管道。

resp = client.ingest.simulate(
    pipeline={
        "description": "Hide my IP",
        "processors": [
            {
                "redact": {
                    "field": "message",
                    "patterns": [
                        "%{IP:client}"
                    ]
                }
            }
        ]
    },
    docs=[
        {
            "_source": {
                "message": "55.3.244.1 GET /index.html 15824 0.043"
            }
        }
    ],
)
print(resp)
response = client.ingest.simulate(
  body: {
    pipeline: {
      description: 'Hide my IP',
      processors: [
        {
          redact: {
            field: 'message',
            patterns: [
              '%{IP:client}'
            ]
          }
        }
      ]
    },
    docs: [
      {
        _source: {
          message: '55.3.244.1 GET /index.html 15824 0.043'
        }
      }
    ]
  }
)
puts response
const response = await client.ingest.simulate({
  pipeline: {
    description: "Hide my IP",
    processors: [
      {
        redact: {
          field: "message",
          patterns: ["%{IP:client}"],
        },
      },
    ],
  },
  docs: [
    {
      _source: {
        message: "55.3.244.1 GET /index.html 15824 0.043",
      },
    },
  ],
});
console.log(response);
POST _ingest/pipeline/_simulate
{
  "pipeline": {
    "description" : "Hide my IP",
    "processors": [
      {
        "redact": {
          "field": "message",
          "patterns": ["%{IP:client}"]
        }
      }
    ]
  },
  "docs":[
    {
      "_source": {
        "message": "55.3.244.1 GET /index.html 15824 0.043"
      }
    }
  ]
}

响应中的文档仍然包含 message 字段，但现在 IP 地址 55.3.244.1 已被文本 <client> 替换。

{
  "docs": [
    {
      "doc": {
        "_index": "_index",
        "_id": "_id",
        "_version": "-3",
        "_source": {
          "message": "<client> GET /index.html 15824 0.043"
        },
        "_ingest": {
          "timestamp": "2023-02-01T16:08:39.419056008Z"
        }
      }
    }
  ]
}

IP 地址被替换为单词 client，因为这是 Grok 模式 %{IP:client} 中指定的。使用 prefix 和 suffix 选项可以配置包围模式名称的 < 和 > 标记。

下一个示例定义了多个模式，这些模式都将替换为单词 REDACTED，并且前缀和后缀标记设置为 *

resp = client.ingest.simulate(
    pipeline={
        "description": "Hide my IP",
        "processors": [
            {
                "redact": {
                    "field": "message",
                    "patterns": [
                        "%{IP:REDACTED}",
                        "%{EMAILADDRESS:REDACTED}"
                    ],
                    "prefix": "*",
                    "suffix": "*"
                }
            }
        ]
    },
    docs=[
        {
            "_source": {
                "message": "55.3.244.1 GET /index.html 15824 0.043 [email protected]"
            }
        }
    ],
)
print(resp)
response = client.ingest.simulate(
  body: {
    pipeline: {
      description: 'Hide my IP',
      processors: [
        {
          redact: {
            field: 'message',
            patterns: [
              '%{IP:REDACTED}',
              '%{EMAILADDRESS:REDACTED}'
            ],
            prefix: '*',
            suffix: '*'
          }
        }
      ]
    },
    docs: [
      {
        _source: {
          message: '55.3.244.1 GET /index.html 15824 0.043 [email protected]'
        }
      }
    ]
  }
)
puts response
const response = await client.ingest.simulate({
  pipeline: {
    description: "Hide my IP",
    processors: [
      {
        redact: {
          field: "message",
          patterns: ["%{IP:REDACTED}", "%{EMAILADDRESS:REDACTED}"],
          prefix: "*",
          suffix: "*",
        },
      },
    ],
  },
  docs: [
    {
      _source: {
        message: "55.3.244.1 GET /index.html 15824 0.043 [email protected]",
      },
    },
  ],
});
console.log(response);
POST _ingest/pipeline/_simulate
{
  "pipeline": {
    "description": "Hide my IP",
    "processors": [
      {
        "redact": {
          "field": "message",
          "patterns": [
            "%{IP:REDACTED}",
            "%{EMAILADDRESS:REDACTED}"
          ],
          "prefix": "*",
          "suffix": "*"
        }
      }
    ]
  },
  "docs": [
    {
      "_source": {
        "message": "55.3.244.1 GET /index.html 15824 0.043 [email protected]"
      }
    }
  ]
}

在响应中，IP 55.3.244.1 和电子邮件地址 [email protected] 都已被 *REDACTED* 替换。

{
  "docs": [
    {
      "doc": {
        "_index": "_index",
        "_id": "_id",
        "_version": "-3",
        "_source": {
          "message": "*REDACTED* GET /index.html 15824 0.043 *REDACTED*"
        },
        "_ingest": {
          "timestamp": "2023-02-01T16:53:14.560005377Z"
        }
      }
    }
  ]
}

自定义模式

编辑

如果现有的 Grok 模式之一不符合您的要求，可以使用 pattern_definitions 选项添加自定义模式。新的模式定义由模式名称和模式本身组成。该模式可以是正则表达式或引用现有 Grok 模式。

此示例定义了自定义模式 GITHUB_NAME 以匹配 GitHub 用户名。模式定义使用现有的 USERNAME Grok 模式，该模式以文字 @ 为前缀。

Grok 调试器是构建自定义模式的非常有用的工具。

resp = client.ingest.simulate(
    pipeline={
        "processors": [
            {
                "redact": {
                    "field": "message",
                    "patterns": [
                        "%{GITHUB_NAME:GITHUB_NAME}"
                    ],
                    "pattern_definitions": {
                        "GITHUB_NAME": "@%{USERNAME}"
                    }
                }
            }
        ]
    },
    docs=[
        {
            "_source": {
                "message": "@elastic-data-management the PR is ready for review"
            }
        }
    ],
)
print(resp)
response = client.ingest.simulate(
  body: {
    pipeline: {
      processors: [
        {
          redact: {
            field: 'message',
            patterns: [
              '%{GITHUB_NAME:GITHUB_NAME}'
            ],
            pattern_definitions: {
              "GITHUB_NAME": '@%<USERNAME>s'
            }
          }
        }
      ]
    },
    docs: [
      {
        _source: {
          message: '@elastic-data-management the PR is ready for review'
        }
      }
    ]
  }
)
puts response
const response = await client.ingest.simulate({
  pipeline: {
    processors: [
      {
        redact: {
          field: "message",
          patterns: ["%{GITHUB_NAME:GITHUB_NAME}"],
          pattern_definitions: {
            GITHUB_NAME: "@%{USERNAME}",
          },
        },
      },
    ],
  },
  docs: [
    {
      _source: {
        message: "@elastic-data-management the PR is ready for review",
      },
    },
  ],
});
console.log(response);
POST _ingest/pipeline/_simulate
{
  "pipeline": {
    "processors": [
      {
        "redact": {
          "field": "message",
          "patterns": [
            "%{GITHUB_NAME:GITHUB_NAME}"
          ],
          "pattern_definitions": {
            "GITHUB_NAME": "@%{USERNAME}"
          }
        }
      }
    ]
  },
  "docs": [
    {
      "_source": {
        "message": "@elastic-data-management the PR is ready for review"
      }
    }
  ]
}

响应中已密文用户名。

{
  "docs": [
    {
      "doc": {
        "_index": "_index",
        "_id": "_id",
        "_version": "-3",
        "_source": {
          "message": "<GITHUB_NAME> the PR is ready for review"
        },
        "_ingest": {
          "timestamp": "2023-02-01T16:53:14.560005377Z"
        }
      }
    }
  ]
}

Grok 监控

编辑

监控会中断执行时间过长的表达式。中断时，密文处理器会失败并出现错误。控制 Grok 监控超时的相同设置也适用于密文处理器。

许可

编辑

redact 处理器是一项商业功能，需要适当的许可。有关详细信息，请参阅 https://elastic.ac.cn/subscriptions。

可以在密文处理器上设置 skip_if_unlicensed 选项，以控制集群许可证不足以运行此类处理器时的行为。skip_if_unlicensed 默认为 false，如果集群的许可证不足，密文处理器将引发异常。但是，如果将 skip_if_unlicensed 选项设置为 true，则在许可证不足的情况下，密文处理器将不会引发异常（它将不执行任何操作）。

« 管道处理器 注册域名处理器 »