Netchecks 是一套用于测试网络条件并断言它们符合预期的工具。

有两个主要组件

• Netchecks Operator - Kubernetes Operator，用于运行网络检查并将结果作为 PolicyReport 资源报告。有关详细信息，请参阅operator README，完整文档可在 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

CLI 还可以通过 Docker 运行

docker run -it ghcr.io/hardbyte/netchecks:main

单独的断言

默认情况下，netcheck 将 JSON 结果输出到 stdout，包括响应详情

$ 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秒内响应，则检查通过。还可以添加自定义验证，请参阅下文的 自定义验证 部分。

自定义验证

可以通过命令行上的 validation-rule 选项或配置 JSON 中的测试规范规则来添加自定义验证。

例如，要覆盖 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]"

随请求提供头信息

netcheck http --url https://pie.dev/headers --header "X-Header:special"

验证响应体是有效的 JSON，并且包含一个包含具有 special 值的 X-Header 键的 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

可以在配置文件中指定多个断言和多个规则，可以为每个规则提供配置，例如头信息和自定义验证

{
  "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 作为头信息的名称。将 token 进行 base64 解码并用作头信息的值。未使用 selfref 上下文，但它显示了如何加载外部 JSON 文件，该文件被 Kubernetes 操作符广泛用于注入数据。

开发

在 pyproject.toml 中更新版本，推送到 main 并在 GitHub 上创建一个版本。Pypi 发布将由 GitHub actions 执行。

使用 Poetry 安装开发依赖项

poetry install --with dev

手动发布

要手动发布，请使用 Poetry

poetry version patch
poetry build
poetry publish

测试

使用 Pytest 进行测试。

poetry run pytest