› › ›

Процессор Redact

Процессор Redact использует движок правил Grok для замены текста в входном документе, соответствующего заданным шаблонам Grok. Процессор можно использовать для маскирования персональных идентификационных данных (PII), настроив его на обнаружение известных шаблонов, таких как адреса электронной почты или IP-адреса. Текст, соответствующий шаблону Grok, заменяется на настраиваемую строку, например, <EMAIL> при совпадении с адресом электронной почты или просто заменяет все совпадения на текст <REDACTED>, если это предпочтительнее.

Elasticsearch поставляется с рядом полезных предопределенных шаблонов, которые удобно использовать в процессоре Redact. Если ни один из них не подходит для ваших нужд, создайте новый шаблон с пользовательским определением. Процессор Redact заменяет все вхождения совпадения. Если есть несколько совпадений, все они будут заменены именем шаблона.

Процессор Redact совместим с Elastic Common Schema (ECS) шаблонами. Устаревшие шаблоны Grok не поддерживаются.

Использование процессора Redact в конвейере

Таблица 35. Параметры 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, то процессор тихо завершается, не изменяя документ
`trace_redact`	нет	`false`	Если `true`, то метаданные ingest `_ingest._redact._is_redacted` устанавливаются в `true`, если документ был заменён

В этом примере используется предопределенный IP шаблон Grok для поиска и замены IP-адресов в поле текста message. Конвейер тестируется с помощью API Simulate.

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 test@elastic.co"
            }
        }
    ],
)
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 test@elastic.co'
        }
      }
    ]
  }
)
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 test@elastic.co",
      },
    },
  ],
});
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 test@elastic.co"
      }
    }
  ]
}

В ответе оба IP-адреса 55.3.244.1 и адрес электронной почты test@elastic.co заменены на *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 Debugger является очень полезным инструментом для создания пользовательских шаблонов.

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 watchdog

Watchdog прерывает выражения, которые выполняются слишком долго. При прерывании процессор Redact завершается с ошибкой. Те же настройки, которые управляют таймаутом Grok Watchdog, также применяются к процессору Redact.

Лицензирование

Процессор redact является коммерческой функцией, требующей соответствующей лицензии. Дополнительную информацию см. на странице https://www.elastic.co/subscriptions.

Параметр skip_if_unlicensed может быть задан для процессора Redact, чтобы управлять поведением при отсутствии достаточной лицензии кластера для выполнения такого процессора. skip_if_unlicensed по умолчанию false, и процессор Redact выбросит исключение, если лицензия кластера недостаточна. Однако, если вы зададите параметр skip_if_unlicensed на true, процессор Redact не выбросит исключение (он ничего не сделает) в случае недостаточной лицензии.

© 2023-2025 Elasticsearch
As of September 2024, Elasticsearch is available under a choice of three licenses: the Server Side Public License (SSPL), the Elastic License, or the AGPLv3 (OSI approved).
Elasticsearch and the Elasticsearch logo are trademarks of Elasticsearch B.V., registered in the U.S. and in other countries.
https://www.elastic.co/guide/en/elasticsearch/reference/8.17/redact-processor.html