hardbyte/netchecks

**Netchecks** 是一套用于测试网络状况并断言其是否符合预期的工具。 主要包含两个组件： - **Netchecks Operator** - Kubernetes Operator，用于运行网络检查并将结果作为 `PolicyReport` 资源报告。更多详情请参见 [operator README](https://github.com/hardbyte/netchecks/blob/main/operator/README.md)，完整文档可在 [https://docs.netchecks.io](https://docs.netchecks.io) 找到。 - **Netcheck CLI 和 Python 库** - 用于运行网络检查并断言其是否符合预期的命令行工具。请继续阅读以获取快速入门指南。 # Netcheck 命令行工具 `netcheck` 是一个可配置的命令行应用程序，用于测试网络状况是否符合预期。它可用于验证 DNS 和 HTTP 连接，并可配置为断言结果是否符合预期，例如： ``` netcheck http --url=https://github.com/status --validation-rule "data.body.contains('GitHub lives!') && data['status-code'] in [200, 201]" ``` ## 安装 从 PyPi 安装 Python 包： ``` pip install netcheck ``` 也可以通过 Docker 运行 CLI： ``` docker run -it ghcr.io/hardbyte/netchecks:main ``` ### 单独断言 默认情况下，`netcheck` 将 JSON 结果输出到标准输出，包括响应详情： ``` $ netcheck dns ``` ``` { "spec": { "type": "dns", "nameserver": null, "host": "github.com", "timeout": 30.0 }, "data": { "canonical_name": "github.com.", "expiration": 1675825244.2986872, "response": "id 6176\nopcode QUERY\nrcode NOERROR\nflags QR RD RA\nedns 0\npayload 65494\n;QUESTION\ngithub.com. IN A\n;ANSWER\ngithub.com. 60 IN A 20.248.137.48\n;AUTHORITY\n;ADDITIONAL", "A": [ "20.248.137.48" ], "startTimestamp": "2023-02-08T02:59:44.248174", "endTimestamp": "2023-02-08T02:59:44.298773" }, "status": "pass" } ``` 传递 `-v` 标志以查看日志消息。 每个检查都可以配置，例如，您可以为 `dns` 检查指定 `server` 和 `host`， 并告知 `netcheck` 特定配置是预期通过还是失败： ``` netcheck dns --server 1.1.1.1 --host hardbyte.nz --should-pass ``` ``` { "spec": { "type": "dns", "nameserver": "1.1.1.1", "host": "hardbyte.nz", "timeout": 30.0, "pattern": "\ndata['response-code'] == 'NOERROR' &&\nsize(data['A']) >= 1 && \n(timestamp(data['endTimestamp']) - timestamp(data['startTimestamp']) < duration('10s'))\n" }, "data": { "canonical_name": "hardbyte.nz.", "expiration": 1683241225.5542665, "response": "id 53196\nopcode QUERY\nrcode NOERROR\nflags QR RD RA\n;QUESTION\nhardbyte.nz. IN A\n;ANSWER\nhardbyte.nz. 3600 IN A 209.58.165.79\n;AUTHORITY\n;ADDITIONAL", "A": [ "209.58.165.79" ], "response-code": "NOERROR", "startTimestamp": "2023-05-04T22:00:24.491750", "endTimestamp": "2023-05-04T22:00:25.554344" }, "status": "pass" } ``` Netcheck 可以处理预期失败检查： ``` $ netcheck dns --server=1.1.1.1 --host=made.updomain --should-fail ``` 请注意，如果检查按预期失败，结果状态将显示 **pass**，如果检查意外通过，则显示 **fail**！ netcheck 对每种检查类型都有内置的默认验证。例如，`dns` 检查将在 DNS 响应代码为 `NOERROR`、至少有一个 `A` 记录且解析器在 10 秒内响应时通过。也可以进行自定义验证，请参阅下面的 [自定义验证](#custom-validation) 部分。 ## 自定义验证 可以通过在命令行上提供 `validation-rule` 选项，或者在通过 JSON 配置时的测试规范规则中提供 `validation` 键，来向检查添加自定义验证。 例如，覆盖 `dns` 检查的默认验证，以检查 A 记录是否解析为特定 IP： ``` netcheck dns --host github.com --validation-rule "data['A'].contains('20.248.137.48')" ``` 验证规则是一个 CEL 表达式，使用检查返回的 `data` 和作用域内的 `spec` 对象进行求值。有关 CEL 的介绍，请参阅 https://github.com/google/cel-spec/blob/master/doc/intro.md ## HTTP 检查 也支持 `http` 检查： 断言 GitHub 的状态页包含文本 "GitHub lives!" 且响应代码为 200： ``` netcheck http --url=https://github.com/status --validation-rule "data.body.contains('GitHub lives!') && data['status-code'] in [200, 201]" ``` 随请求提供 Header： ``` netcheck http --url https://pie.dev/headers --header "X-Header:special" ``` 验证响应正文是否为有效 JSON，并包含一个含有 `X-Header` 键且值为 `special` 的 `headers` 对象： ``` netcheck http --url https://pie.dev/headers \ --header "X-Header:special" \ --validation-rule "parse_json(data.body).headers['X-Header'] == 'special'" ``` 确保 POST 请求失败： ``` $ netcheck http --method=post --url=https://s3.ap-southeast-2.amazonaws.com --should-fail ``` ## 通过文件配置 运行 `netcheck` 的主要方式是传入断言列表。 可以提供一个包含要检查断言列表的 JSON 文件： ``` { "assertions": [ { "name": "deny-cloudflare-dns", "rules": [ {"type": "dns", "server": "1.1.1.1", "host": "github.com"} ] } ] } ``` 然后调用 `run` 命令： ``` $ netcheck run --config tests/testdata/dns-config.json ``` 输出应该是包含每个断言结果的有效 JSON。 配置文件中可以指定具有多个规则的多重断言， 每个规则可以提供配置，例如 Header 和自定义验证： ``` { "assertions": [ {"name": "get-with-header", "rules": [ {"type": "http", "url": "https://pie.dev/headers", "headers": {"X-Test-Header": "value"}}, {"type": "http", "url": "https://pie.dev/headers", "headers": {"X-Header": "secret"}, "validation": "parse_json(data.body).headers['X-Header'] == 'secret'" } ]} ] } ``` ## 外部数据 最后，可以引用外部上下文来注入数据。以下示例是一个有效的配置文件，虽然有点刻意： ``` { "assertions": [ { "name": "example-assertion", "rules": [ { "type": "http", "url": "{{customdata.url}}", "headers": {"{{customdata.header}}": "{{ b64decode(token) }}"}, "validation": "parse_json(data.body).headers['X-Header'] == 'secret'" } ] } ], "contexts": [ {"name": "customdata", "type": "inline", "data": {"url": "https://pie.dev/headers", "header": "X-Header"}}, {"name": "token", "type": "inline", "data": "c2VjcmV0=="}, {"name": "selfref", "type": "file", "path": "example-config.json"} ] } ``` 在上面的示例中，`customdata` 和 `token` 上下文被注入到规则中。 `customdata.url` 用作请求的 URL，`customdata.header` 用作 Header 的名称。 `token` 经过 base64 解码并用作 Header 的值。 `selfref` 上下文未使用，但展示了如何加载外部 JSON 文件，Kubernetes operator 广泛使用此方法来注入数据。 ## 开发 更新 `pyproject.toml` 中的版本，推送到 `main` 分支并在 GitHub 上创建 Release。PyPI 发布将由 GitHub Actions 执行。 使用 `uv` 安装开发依赖： ``` uv sync ``` ### 测试 使用 Pytest 进行测试。 ``` uv run pytest ```

标签：Docker, Helm, Python, 二进制发布, 子域名突变, 安全防御评估, 开源工具, 开源软件, 情报分析, 提示注入, 插件系统, 数据泄露防护, 断言测试, 无后门, 系统运维, 网络安全, 网络探测, 网络策略, 网络诊断, 网络连通性, 网络验证, 请求拦截, 连接测试, 逆向工具, 隐私保护, 集群管理