Elasticsearch PII工具

你在Elasticsearch索引中找到了不属于那里的PII（个人可识别信息）吗？这是你的工具！

es-pii-tool可以帮助你从甚至可搜索快照挂载的索引中删除信息。它还可以处理深层嵌套的字段！

客户端配置

该工具通过es_client Python模块进行连接。

你可以使用命令行选项或YAML配置文件来配置客户端连接。如果需要使用配置文件，则配置文件结构需要在顶层包含elasticsearch，如下所示

---
elasticsearch:
  client:
    hosts: https://10.11.12.13:9200
    cloud_id:
    request_timeout: 60
    verify_certs:
    ca_certs:
    client_cert:
    client_key:
  other_settings:
    username:
    password:
    api_key:
      id:
      api_key:
      token:

logging:
  loglevel: INFO
  logfile: /path/to/file.log
  logformat: default
  blacklist: []

REDACTIONS_FILE 配置

  ---
  redactions:
    - job_name_20240930_redact_hot:
        pattern: hot-*
        query: {'match': {'message': 'message1'}}
        fields: ['message']
        message: REDACTED
        expected_docs: 1
        restore_settings: {'index.routing.allocation.include._tier_preference': 'data_warm,data_hot,data_content'}
    - job_name_20240930_redact_cold:
        pattern: restored-cold-*
        query: {'match': {'nested.key': 'nested19'}}
        fields: ['nested.key']
        message: REDACTED
        expected_docs: 1
        restore_settings: {'index.routing.allocation.include._tier_preference': 'data_warm,data_hot,data_content'}
        forcemerge:
          max_num_segments: 1
    - job_name_20240930_redact_frozen:
        pattern: partial-frozen-*
        query: {'range': {'number': {'gte': 8, 'lte': 11}}}
        fields: ['deep.l1.l2.l3']
        message: REDACTED
        expected_docs: 4
        forcemerge:
          only_expunge_deletes: True

作业名称

作业名称必须是唯一的。在跟踪索引中跟踪删除作业的进度，默认名称为redactions-tracker。如果作业进度因任何原因中断，则es-pii-tool将尝试从上次中断的地方继续。

pattern

“pattern”设置定义了将搜索哪些索引中的文档进行编辑。这可以是Elasticsearch支持的任何内容，包括通配符globbing和逗号分隔的值。

查询

用于隔离要编辑的文档的Elasticsearch查询。这应该以Elasticsearch Query DSL格式。

字段

要编辑的字段。如果字段不在文档的根级别，可以使用点表示法引用深层嵌套的对象。

这是一个数组值，因此可以指定多行。

注意：所有要编辑的文档都必须具有在fields数组中定义的所有字段，否则将产生错误条件。

消息

此值将替换在fields指定的每个字段中的内容。默认值为REDACTED。可以是任何字符串值。目前不支持部分或子字符串替换。

预期文档数

这必须与执行query产生的确切命中数相匹配。

注意：此值不能超过10,000。这是Elasticsearch强加的最大结果数量的默认限制。如果您的查询产生超过10,000个命中，并且所有这些都需要被编辑，建议您找到一些其他限制条件或过滤器来将总命中数降低到10,000以下。

恢复设置

从cold或frozen层级的索引中编辑数据之前，必须首先从快照存储库完全恢复它们。如果您想将这些要恢复的索引应用任何特定设置，请在此处设置。

restore_settings的主要用例是强制索引恢复到data_warm层或某些其他目标数据节点，但也可以用于应用任何其他所需的设置。

强制合并

这仅用于编辑cold或frozen层级的可搜索快照索引。最佳实践是在将索引快照并挂载到cold或frozen层之前，将索引强制合并到每个分片1个段。此工具默认在编辑数据后执行此强制合并。但您可以设置强制合并为only_expunge_deletes。

在Elasticsearch中，一旦索引了一个文档，该文档就是不可变的。为了编辑一个文档，Elasticsearch实际上删除了原始文档，并在其位置重新索引修改后的文档。

最大段数

此设置的默认值为1，表示每个分片1个段。这在磁盘I/O方面是一个相对“昂贵”的操作，如果您只从索引或分片中删除少量文档，那么执行完整强制合并可能没有太多意义。为了避免这种情况，请使用only_expunge_deletes设置。

仅清除删除

这是一个布尔设置，可以是true或false（或True或False）。

如果true，强制合并将仅删除标记为删除的位，即作为编辑过程的一部分删除的原始文档。

运行es_pii_tool

命令行执行

通过在命令行中执行pii-tool来运行此脚本。对于pii-tool有多个配置级别。顶级是为客户端连接到Elasticsearch配置。

后续命令包括show-all-options和file-based（意味着从YAML配置文件派生的编辑配置）。

客户端配置

pii-tool --help
Usage: pii-tool [OPTIONS] COMMAND [ARGS]...

  Elastic PII Tool

Options:
  --config PATH                   Path to configuration file.
  --hosts TEXT                    Elasticsearch URL to connect to.
  --cloud_id TEXT                 Elastic Cloud instance id
  --api_token TEXT                The base64 encoded API Key token
  --id TEXT                       API Key "id" value
  --api_key TEXT                  API Key "api_key" value
  --username TEXT                 Elasticsearch username
  --password TEXT                 Elasticsearch password
  --request_timeout FLOAT         Request timeout in seconds
  --verify_certs / --no-verify_certs
                                  Verify SSL/TLS certificate(s)
  --ca_certs TEXT                 Path to CA certificate file or directory
  --client_cert TEXT              Path to client certificate file
  --client_key TEXT               Path to client key file
  --loglevel [DEBUG|INFO|WARNING|ERROR|CRITICAL]
                                  Log level
  --logfile TEXT                  Log file
  --logformat [default|json|ecs]  Log output format
  -v, --version                   Show the version and exit.
  -h, --help                      Show this message and exit.

Commands:
  file-based        Redact from YAML config file
  show-all-options  Show all client configuration options

显示所有选项

由于仅客户端连接的配置选项列表相当长，默认的--help输出被截断了一些。您可以通过运行pii-tool show-all-options来显示所有配置选项，以及显示它们的环境变量名称。

Usage: pii-tool show-all-options [OPTIONS]

  ALL OPTIONS SHOWN

  The full list of options available for configuring a connection at the command-line.

Options:
  --config PATH                   Path to configuration file.  [env var: ESCLIENT_CONFIG]
  --hosts TEXT                    Elasticsearch URL to connect to.  [env var: ESCLIENT_HOSTS]
  --cloud_id TEXT                 Elastic Cloud instance id  [env var: ESCLIENT_CLOUD_ID]
  --api_token TEXT                The base64 encoded API Key token  [env var: ESCLIENT_API_TOKEN]
  --id TEXT                       API Key "id" value  [env var: ESCLIENT_ID]
  --api_key TEXT                  API Key "api_key" value  [env var: ESCLIENT_API_KEY]
  --username TEXT                 Elasticsearch username  [env var: ESCLIENT_USERNAME]
  --password TEXT                 Elasticsearch password  [env var: ESCLIENT_PASSWORD]
  --bearer_auth TEXT              Bearer authentication token  [env var: ESCLIENT_BEARER_AUTH]
  --opaque_id TEXT                X-Opaque-Id HTTP header value  [env var: ESCLIENT_OPAQUE_ID]
  --request_timeout FLOAT         Request timeout in seconds  [env var: ESCLIENT_REQUEST_TIMEOUT]
  --http_compress / --no-http_compress
                                  Enable HTTP compression  [env var: ESCLIENT_HTTP_COMPRESS]
  --verify_certs / --no-verify_certs
                                  Verify SSL/TLS certificate(s)  [env var: ESCLIENT_VERIFY_CERTS]
  --ca_certs TEXT                 Path to CA certificate file or directory  [env var: ESCLIENT_CA_CERTS]
  --client_cert TEXT              Path to client certificate file  [env var: ESCLIENT_CLIENT_CERT]
  --client_key TEXT               Path to client key file  [env var: ESCLIENT_CLIENT_KEY]
  --ssl_assert_hostname TEXT      Hostname or IP address to verify on the node's certificate.  [env var:
                                  ESCLIENT_SSL_ASSERT_HOSTNAME]
  --ssl_assert_fingerprint TEXT   SHA-256 fingerprint of the node's certificate. If this value is given then root-of-trust
                                  verification isn't done and only the node's certificate fingerprint is verified.  [env var:
                                  ESCLIENT_SSL_ASSERT_FINGERPRINT]
  --ssl_version TEXT              Minimum acceptable TLS/SSL version  [env var: ESCLIENT_SSL_VERSION]
  --master-only / --no-master-only
                                  Only run if the single host provided is the elected master  [env var: ESCLIENT_MASTER_ONLY]
  --skip_version_test / --no-skip_version_test
                                  Elasticsearch version compatibility check  [env var: ESCLIENT_SKIP_VERSION_TEST]
  --loglevel [DEBUG|INFO|WARNING|ERROR|CRITICAL]
                                  Log level  [env var: ESCLIENT_LOGLEVEL]
  --logfile TEXT                  Log file  [env var: ESCLIENT_LOGFILE]
  --logformat [default|json|ecs]  Log output format  [env var: ESCLIENT_LOGFORMAT]
  --blacklist TEXT                Named entities will not be logged  [env var: ESCLIENT_BLACKLIST]
  -h, --help                      Show this message and exit.

您会注意到，在这次查看中，每个选项都有一个env var: ESCLIENT_。

环境变量

如果已设置为环境变量，则不需要设置相关的命令行标志。

例如，如果我在/path/to/config.yaml有一个客户端配置YAML文件，并且设置了ESCLIENT_CONFIG环境变量，例如。

export ESCLIENT_CONFIG=/path/to/config.yaml

然后我可以执行pii-tool而无需在命令行中使用--config /path/to/config.yaml标志。

这对于基于Docker的执行非常有用！

在es_client文档中了解更多信息。

基于文件

file-based子命令是在设置客户端连接参数后使用的。

$ pii-tool file-based --help
Usage: run_script.py file-based [OPTIONS] REDACTIONS_FILE

  Redact from YAML config file

Options:
  --dry-run              Do not perform any changes.  [env var: PII_TOOL_DRY_RUN]
  --tracking-index TEXT  Name for the tracking index.  [env var: PII_TOOL_TRACKING_INDEX; default: redactions-tracker]
  -h, --help             Show this message and exit.

您会注意到这里也有环境变量！

Docker执行

Docker镜像需要将容器中的/.config映射到卷（目前是这样）。

配置文件应该放在这里，包括客户端YAML文件和用于file-based命令的编辑文件。

假设您在$(pwd)有一个名为REDACTIONS_FILE.yaml的文件

docker run \
  --rm \  # Remove the container after execution
  -it \   # Not strictly necessary, but helpful as it is an interactive terminal
  -v $(pwd)/:/.config \  # Map the present-working directory to /.config
  untergeek/es-pii-tool:${TAG} \
    --hosts https://127.0.0.1:9200 \ 
    --username USERNAME \
    --password HIDDEN \
    file-based /.config/REDACTIONS_FILE.yaml

所有命令行标志都可以使用。但还有更好的方法...

环境变量

如前所述，环境变量可以使Docker和Kubernetes中的事情变得非常简单。

docker run \
  --rm \  # Remove the container after execution
  -it \   # Not strictly necessary, but helpful as it is an interactive terminal
  -v $(pwd)/:/.config \  # Map the present-working directory to /.config
  -e ESCLIENT_HOSTS=${ESCLIENT_HOSTS} \ 
  -e ESCLIENT_USERNAME=${ESCLIENT_USERNAME} \ 
  -e ESCLIENT_PASSWORD=${ESCLIENT_PASSWORD} \ 
  untergeek/es-pii-tool:0.9.0 file-based /.config/REDACTIONS_FILE.yaml

测试

docker_test目录

希望您永远不需要修改这里的内容。为了运行本地测试，您真的应该在本地运行Docker，或者至少能够访问它。

如果不能，您应该计划导出以下环境变量

• TEST_ES_SERVER 应设置为您Elasticsearch集群的完整URL
• TEST_USER Elasticsearch测试用户名
• TEST_PASS TEST_USER的Elasticsearch密码
• CA_CRT 可选，如果您的集群由已知的签名者签名
• TEST_ES_REPO TEST_ES_SERVER上的存储库名称

每个都应该放在项目根目录的.env中，前面有export，例如。

export TEST_ES_SERVER=https://127.0.0.1:9200
...

为什么在.env中？因为pytest会在这里查找它。

您的测试集群还需要至少一个Trial X-Pack许可证，因为可搜索快照需要这个许可证。

现在，如果这听起来有点令人望而却步，它确实是。docker_test脚本为您自动化了这一切。

手动设置

docker_test/create.sh VERSION [SCENARIO]

VERSION需要是docker.elastic.co/elasticsearch/elasticsearch上认可的形象标记。

SCENARIO在技术上不是必需的，但对于本项目来说不是必需的。

为了测试从frozen层检索编辑，您至少需要有一个data_frozen节点。能够做到这一点的场景是frozen_node，例如。

$ docker_test/create.sh 8.15.1 frozen_node

Using scenario: frozen_node
Using Elasticsearch version 8.15.1

Creating 2 node(s)...

Starting node 1...
Container ID: ecf1e6d45bbc8d0617f75f47101372fd723a1424b27f7c250d1c7553f096960c
Getting Elasticsearch credentials from container es-pii-tool-test-0...
- 18s elapsed (typically 15s - 25s)...
Trial license started...
Snapshot repository initialized...

Node 1 started.
Node 2 started.

All nodes ready to test!

Environment variables are in .env

该脚本将创建第一个节点，并收集在创建过程中创建的凭据。然后它将启动X-Pack试用许可证并初始化快照存储库。然后在同一子网中，它将启动另一个节点，具有node_role: ["data_frozen"]。实际上，它创建的就是测试pii_tool所需的一切。

注意：两个节点启动和运行可能需要20到30秒。脚本在等待并尝试捕获凭据时运行一个漂亮的旋转器，以便您可以查看它是否在工作。之后应该会很快完成。

手动拆卸

$ docker_test/destroy.sh
Stopping all containers...
Removing all containers...
Deleting remaining files and directories
Cleanup complete.

这会清理所有容器、env var文件和用作共享文件系统快照存储库的“repo”目录。不需要额外的标志。

测试

由于docker_test对测试es-pii-tool如此重要，因此努力使Docker容器的设置和拆卸自动化。

$ pytest --docker_create true --docker_destroy true

如果省略了--docker_create true和/或--docker_destroy true，测试将假定您已经有了功能齐全的测试环境，并且环境变量已经在.env中配置。

输出如下所示

$ pytest --docker_create true --docker_destroy true
Running: "/Users/buh/WORK/es-pii-tool/docker_test/create.sh 8.15.1 frozen_node"

Using scenario: frozen_node
Using Elasticsearch version 8.15.1

Creating 2 node(s)...

Starting node 1...
Container ID: f4e006bc94cdc8fa0977d9ab5bae509250f6d5fd2e0b8de6a3bbc994c2ee684a
Getting Elasticsearch credentials from container es-pii-tool-test-0...
- 18s elapsed (typically 15s - 25s)...
Trial license started...
Snapshot repository initialized...

Node 1 started.
Node 2 started.

All nodes ready to test!

Environment variables are in .env[-shell]
===================================================== test session starts =====================================================
platform darwin -- Python 3.12.2, pytest-8.1.1, pluggy-1.5.0
rootdir: /Users/buh/WORK/es-pii-tool
configfile: pytest.ini
plugins: cov-5.0.0, anyio-4.3.0, returns-0.22.0
collected 70 items

tests/integration/test_cold.py .........................                                                                [ 35%]
tests/integration/test_frozen.py .........................                                                              [ 71%]
tests/integration/test_hot.py ....................                                                                      [100%]

 -- docker_test environment destroyed.


=============================================== 70 passed in 148.31s (0:02:28) ================================================

测试期间的错误

虽然不常见，但偶尔一个测试会挂起。虽然这可能是由于多种原因，但常见的原因是Docker无法正确访问资源，并且进程超时。

如果发生这种情况，很可能它看起来像其他测试失败了。这是因为主要的测试场景在3个索引的一系列中运行了4次通过。根据情况，其中2个索引可能是冻结的、冷的、数据流的一部分等。

如果测试超时，不要慌张。您需要手动使用docker_test/destroy.sh销毁Docker环境，因为测试环境默认不销毁测试环境，这样您就可以在必要时检查它。

完成此操作后，重新运行测试。如果它反复失败，那么可能还有其他问题。这也是为什么能够检查在Docker中未自动销毁的Elasticsearch环境是一个好事。