Redact processor

Redactプロセッサは、Grokルールエンジンを使用して、指定されたGrokパターンに一致する入力ドキュメント内のテキストを隠します。このプロセッサは、メールアドレスやIPアドレスなどの既知のパターンを検出するように設定することで、個人識別情報（PII）を隠すために使用できます。Grokパターンに一致するテキストは、メールアドレスが一致した場合は<EMAIL>のような設定可能な文字列に置き換えられるか、好ましい場合はすべての一致を<REDACTED>というテキストに単純に置き換えます。

Elasticsearchには、Redactプロセッサが便利に参照できるいくつかの有用な事前定義されたパターンがパッケージされています。それらのいずれかがニーズに合わない場合は、カスタムパターン定義を使用して新しいパターンを作成します。Redactプロセッサは、一致のすべての発生を置き換えます。複数の一致がある場合、すべてがパターン名で置き換えられます。

Redactプロセッサは、Elastic Common Schema (ECS)パターンと互換性があります。レガシーGrokパターンはサポートされていません。

Using the Redact processor in a pipeline


表34. Redactオプション

名前 必須 デフォルト 説明
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および現在のライセンスがRedactプロセッサの実行をサポートしていない場合、プロセッサはドキュメントを変更せずに静かに終了します。

この例では、事前定義されたIP Grokパターンを使用して、messageテキストフィールドからIPアドレスを一致させて隠します。パイプラインは、シミュレートAPIを使用してテストされます。

Python

  1. resp = client.ingest.simulate(
  2.    pipeline={
  3.    "description": "Hide my IP",
  4.    "processors": [
  5.    {
  6.    "redact": {
  7.    "field": "message",
  8.    "patterns": [
  9.    "%{IP:client}"
  10.    ]
  11.    }
  12.    }
  13.    ]
  14.    },
  15.    docs=[
  16.    {
  17.    "_source": {
  18.    "message": "55.3.244.1 GET /index.html 15824 0.043"
  19.    }
  20.    }
  21.    ],
  22. )
  23. print(resp)

Ruby

  1. response = client.ingest.simulate(
  2.   body: {
  3.    pipeline: {
  4.    description: 'Hide my IP',
  5.    processors: [
  6.    {
  7.    redact: {
  8.    field: 'message',
  9.    patterns: [
  10.    '%{IP:client}'
  11.    ]
  12.    }
  13.    }
  14.    ]
  15.    },
  16.    docs: [
  17.    {
  18.    _source: {
  19.    message: '55.3.244.1 GET /index.html 15824 0.043'
  20.    }
  21.    }
  22.    ]
  23.   }
  24. )
  25. puts response

Js

  1. const response = await client.ingest.simulate({
  2.   pipeline: {
  3.    description: "Hide my IP",
  4.    processors: [
  5.    {
  6.    redact: {
  7.    field: "message",
  8.    patterns: ["%{IP:client}"],
  9.    },
  10.    },
  11.    ],
  12.   },
  13.   docs: [
  14.    {
  15.    _source: {
  16.    message: "55.3.244.1 GET /index.html 15824 0.043",
  17.    },
  18.    },
  19.   ],
  20. });
  21. console.log(response);

Console

  1. POST _ingest/pipeline/_simulate
  2. {
  3.   "pipeline": {
  4.    "description" : "Hide my IP",
  5.    "processors": [
  6.    {
  7.    "redact": {
  8.    "field": "message",
  9.    "patterns": ["%{IP:client}"]
  10.    }
  11.    }
  12.    ]
  13.   },
  14.   "docs":[
  15.    {
  16.    "_source": {
  17.    "message": "55.3.244.1 GET /index.html 15824 0.043"
  18.    }
  19.    }
  20.   ]
  21. }

レスポンス内のドキュメントにはmessageフィールドがまだ含まれていますが、今度はIPアドレス55.3.244.1が<client>というテキストに置き換えられています。

Console-Result

  1. {
  2.   "docs": [
  3.    {
  4.    "doc": {
  5.    "_index": "_index",
  6.    "_id": "_id",
  7.    "_version": "-3",
  8.    "_source": {
  9.    "message": "<client> GET /index.html 15824 0.043"
  10.    },
  11.    "_ingest": {
  12.    "timestamp": "2023-02-01T16:08:39.419056008Z"
  13.    }
  14.    }
  15.    }
  16.   ]
  17. }

IPアドレスは、Grokパターン%{IP:client}で指定されているため、clientという単語に置き換えられます。パターン名を囲む<および>トークンは、prefixおよびsuffixオプションを使用して設定可能です。

次の例では、両方の複数のパターンがREDACTEDという単語に置き換えられ、接頭辞および接尾辞トークンが*に設定されています。

Python

  1. resp = client.ingest.simulate(
  2.    pipeline={
  3.    "description": "Hide my IP",
  4.    "processors": [
  5.    {
  6.    "redact": {
  7.    "field": "message",
  8.    "patterns": [
  9.    "%{IP:REDACTED}",
  10.    "%{EMAILADDRESS:REDACTED}"
  11.    ],
  12.    "prefix": "*",
  13.    "suffix": "*"
  14.    }
  15.    }
  16.    ]
  17.    },
  18.    docs=[
  19.    {
  20.    "_source": {
  21.    "message": "55.3.244.1 GET /index.html 15824 0.043 [email protected]"
  22.    }
  23.    }
  24.    ],
  25. )
  26. print(resp)

Ruby

  1. response = client.ingest.simulate(
  2.   body: {
  3.    pipeline: {
  4.    description: 'Hide my IP',
  5.    processors: [
  6.    {
  7.    redact: {
  8.    field: 'message',
  9.    patterns: [
  10.    '%{IP:REDACTED}',
  11.    '%{EMAILADDRESS:REDACTED}'
  12.    ],
  13.    prefix: '*',
  14.    suffix: '*'
  15.    }
  16.    }
  17.    ]
  18.    },
  19.    docs: [
  20.    {
  21.    _source: {
  22.    message: '55.3.244.1 GET /index.html 15824 0.043 [email protected]'
  23.    }
  24.    }
  25.    ]
  26.   }
  27. )
  28. puts response

Js

  1. const response = await client.ingest.simulate({
  2.   pipeline: {
  3.    description: "Hide my IP",
  4.    processors: [
  5.    {
  6.    redact: {
  7.    field: "message",
  8.    patterns: ["%{IP:REDACTED}", "%{EMAILADDRESS:REDACTED}"],
  9.    prefix: "*",
  10.    suffix: "*",
  11.    },
  12.    },
  13.    ],
  14.   },
  15.   docs: [
  16.    {
  17.    _source: {
  18.    message: "55.3.244.1 GET /index.html 15824 0.043 [email protected]",
  19.    },
  20.    },
  21.   ],
  22. });
  23. console.log(response);

Console

  1. POST _ingest/pipeline/_simulate
  2. {
  3.   "pipeline": {
  4.    "description": "Hide my IP",
  5.    "processors": [
  6.    {
  7.    "redact": {
  8.    "field": "message",
  9.    "patterns": [
  10.    "%{IP:REDACTED}",
  11.    "%{EMAILADDRESS:REDACTED}"
  12.    ],
  13.    "prefix": "*",
  14.    "suffix": "*"
  15.    }
  16.    }
  17.    ]
  18.   },
  19.   "docs": [
  20.    {
  21.    "_source": {
  22.    "message": "55.3.244.1 GET /index.html 15824 0.043 [email protected]"
  23.    }
  24.    }
  25.   ]
  26. }

レスポンス内では、IP 55.3.244.1およびメールアドレス[email protected]が*REDACTED*に置き換えられています。

Console-Result

  1. {
  2.   "docs": [
  3.    {
  4.    "doc": {
  5.    "_index": "_index",
  6.    "_id": "_id",
  7.    "_version": "-3",
  8.    "_source": {
  9.    "message": "*REDACTED* GET /index.html 15824 0.043 *REDACTED*"
  10.    },
  11.    "_ingest": {
  12.    "timestamp": "2023-02-01T16:53:14.560005377Z"
  13.    }
  14.    }
  15.    }
  16.   ]
  17. }

Custom patterns

既存のGrok パターンのいずれかが要件に合わない場合、pattern_definitionsオプションを使用してカスタムパターンを追加できます。新しいパターン定義は、パターン名とパターン自体で構成されます。パターンは正規表現であるか、既存のGrokパターンを参照することができます。

この例では、GitHubユーザー名に一致するカスタムパターンGITHUB_NAMEを定義します。パターン定義は、リテラル@で接頭辞された既存のUSERNAME Grok パターンを使用します。

Grokデバッガーは、カスタムパターンを構築するための非常に便利なツールです。

Python

  1. resp = client.ingest.simulate(
  2.    pipeline={
  3.    "processors": [
  4.    {
  5.    "redact": {
  6.    "field": "message",
  7.    "patterns": [
  8.    "%{GITHUB_NAME:GITHUB_NAME}"
  9.    ],
  10.    "pattern_definitions": {
  11.    "GITHUB_NAME": "@%{USERNAME}"
  12.    }
  13.    }
  14.    }
  15.    ]
  16.    },
  17.    docs=[
  18.    {
  19.    "_source": {
  20.    "message": "@elastic-data-management the PR is ready for review"
  21.    }
  22.    }
  23.    ],
  24. )
  25. print(resp)

Ruby

  1. response = client.ingest.simulate(
  2.   body: {
  3.    pipeline: {
  4.    processors: [
  5.    {
  6.    redact: {
  7.    field: 'message',
  8.    patterns: [
  9.    '%{GITHUB_NAME:GITHUB_NAME}'
  10.    ],
  11.    pattern_definitions: {
  12.    "GITHUB_NAME": '@%<USERNAME>s'
  13.    }
  14.    }
  15.    }
  16.    ]
  17.    },
  18.    docs: [
  19.    {
  20.    _source: {
  21.    message: '@elastic-data-management the PR is ready for review'
  22.    }
  23.    }
  24.    ]
  25.   }
  26. )
  27. puts response

Js

  1. const response = await client.ingest.simulate({
  2.   pipeline: {
  3.    processors: [
  4.    {
  5.    redact: {
  6.    field: "message",
  7.    patterns: ["%{GITHUB_NAME:GITHUB_NAME}"],
  8.    pattern_definitions: {
  9.    GITHUB_NAME: "@%{USERNAME}",
  10.    },
  11.    },
  12.    },
  13.    ],
  14.   },
  15.   docs: [
  16.    {
  17.    _source: {
  18.    message: "@elastic-data-management the PR is ready for review",
  19.    },
  20.    },
  21.   ],
  22. });
  23. console.log(response);

Console

  1. POST _ingest/pipeline/_simulate
  2. {
  3.   "pipeline": {
  4.    "processors": [
  5.    {
  6.    "redact": {
  7.    "field": "message",
  8.    "patterns": [
  9.    "%{GITHUB_NAME:GITHUB_NAME}"
  10.    ],
  11.    "pattern_definitions": {
  12.    "GITHUB_NAME": "@%{USERNAME}"
  13.    }
  14.    }
  15.    }
  16.    ]
  17.   },
  18.   "docs": [
  19.    {
  20.    "_source": {
  21.    "message": "@elastic-data-management the PR is ready for review"
  22.    }
  23.    }
  24.   ]
  25. }

レスポンス内でユーザー名が隠されています。

Console-Result

  1. {
  2.   "docs": [
  3.    {
  4.    "doc": {
  5.    "_index": "_index",
  6.    "_id": "_id",
  7.    "_version": "-3",
  8.    "_source": {
  9.    "message": "<GITHUB_NAME> the PR is ready for review"
  10.    },
  11.    "_ingest": {
  12.    "timestamp": "2023-02-01T16:53:14.560005377Z"
  13.    }
  14.    }
  15.    }
  16.   ]
  17. }

Grok watchdog

ウォッチドッグは、実行に時間がかかりすぎる式を中断します。中断されると、Redactプロセッサはエラーで失敗します。Grokウォッチドッグのタイムアウトを制御するのと同じ設定がRedactプロセッサにも適用されます。

Licensing

redactプロセッサは、適切なライセンスを必要とする商業機能です。詳細については、https://www.elastic.co/subscriptionsを参照してください。

skip_if_unlicensedオプションは、クラスターのライセンスがそのようなプロセッサを実行するのに十分でない場合の動作を制御するために、Redactプロセッサに設定できます。skip_if_unlicensedはfalseにデフォルト設定されており、クラスターのライセンスが不十分な場合、Redactプロセッサは例外をスローします。ただし、skip_if_unlicensedオプションをtrueに設定すると、Redactプロセッサは例外をスローせず（何もしない）、ライセンスが不十分な場合でも動作します。