[!] This project is provided as-is, without warranties or guarantees of any kind, and has not been validated in a production environment unless explicitly stated otherwise. You are solely responsible for evaluating, testing, securing, and operating it safely in your environment and for verifying compliance with any legal, regulatory, or contractual requirements. By using this project, you accept all risk, and the authors and contributors assume no liability for any loss, damage, outage, misuse, or other consequences arising from its use. [!]

ReadyCheck

ReadyCheck (readycheck) is a CLI for repeatable, audit-friendly connectivity validation. It compares observed network behavior to declared intent (allow or deny) and produces artifacts suitable for operations handoff, change evidence, and baseline comparison.

Current release: 0.0.1

Overview

• YAML-driven source, destination, and check matrix.
• Checks: tcp, tls, http, ssh, dns.
• Normalized failure statuses for stable triage.
• Outputs: results.json, results.csv, report.html, summary.txt.
• Baseline comparison outputs: diff.json, diff.html.
• Optional CI/automation gate thresholds for policy mismatches and technical failures.

What It Does Not Do

• No remote multi-probe orchestration in 0.0.1.
• No generic UDP scanning beyond DNS-specific checks.
• No credentialed checks, login flows, or remote command execution.
• No certificate-policy validation beyond basic TLS handshake success.
• No guarantee that one probe host represents every real source path.

Core Terms

• success: technical check result (true or false).
• expected: policy intent (allow or deny).
• policy_pass: whether observed behavior matched intent.

success and policy outcome are intentionally separate:

• If expected=allow, success is typically desired.
• If expected=deny, failure is typically desired.

Requirements

• Python 3.11+
• Network authorization for every declared target
• A probe host whose routing and DNS path represent the source context you want to validate

Assumptions

• Each run is executed from one local probe host.
• The operator controls the YAML matrix and declares only approved targets.
• Timeout and retry values are tuned for the lab or network segment being tested.

Setup

1. Create and activate a virtual environment.

python3 -m venv .venv
source .venv/bin/activate

2. Install ReadyCheck in editable mode with dev tooling.

python -m pip install -U pip
python -m pip install -e ".[dev]"

3. Copy the example matrix.

cp matrix.example.yaml matrix.yaml

4. Edit matrix.yaml with authorized hosts, ports, and expectations.

Usage

Run a standard validation:

python -m readycheck.cli run --spec matrix.yaml --output out

Fail the command if any policy assertion mismatches:

python -m readycheck.cli run \
  --spec matrix.yaml \
  --output out \
  --fail-on-policy-failures 0

Fail the command if more than one technical check fails:

python -m readycheck.cli run \
  --spec matrix.yaml \
  --output out \
  --fail-on-check-failures 1

Create a baseline:

python -m readycheck.cli run --spec matrix.yaml --output out_baseline

Compare a later run to that baseline:

python -m readycheck.cli run \
  --spec matrix.yaml \
  --output out_current \
  --baseline out_baseline/results.json

Diff two existing result sets directly:

python -m readycheck.cli diff \
  --baseline out_baseline/results.json \
  --current out_current/results.json \
  --output out_diff

Expected Output

Artifacts are written to the selected output directory:

• results.json: machine-readable source of truth
• results.csv: spreadsheet-friendly export
• report.html: human-readable run report
• summary.txt: quick counters for tickets and CI comments
• diff.json: machine-readable change set when --baseline is used
• diff.html: human-readable baseline comparison when --baseline is used

Matrix Rules

• sources must be a non-empty list.
• destinations must be a non-empty list with name and host.
• matrix must be a non-empty list.
• Each matrix row must reference known source and destination.
• Each matrix row must include at least one check.
• Supported checks: tcp, tls, http, ssh, dns.

Failure Status Normalization

Raw errors are mapped into:

• timeout
• refused
• unreachable
• tls_error
• protocol_error
• dns_error
• unknown

This keeps reports and diffs stable across runtime environments.

Validation Commands

Run the standard local gate:

./scripts/check.sh

./scripts/check.sh delegates to the repo-level check.sh, which runs formatting, linting, tests, configured security checks, and dependency audit where tooling is available.

Troubleshooting

• error: spec file does not exist: confirm --spec points to the YAML file you intended to run.
• unknown source or unknown destination: the matrix section does not match the names declared under sources or destinations.
• Mostly timeout: check routing, ACL state, resolver path, and timeout value.
• protocol_error: the target is reachable but did not behave like the expected protocol.
• readycheck gating failure: the run completed, but the configured failure threshold was exceeded.

Known Limitations

• Live network validation against authorized hosts is still an operator-run step, not a fully automated integration test in this repo.
• The local gate can only prove code quality and local lab behavior, not real-world ACL correctness.
• HTML and JSON artifacts are deterministic, but network outcomes are still probe- and environment-dependent.

Recovery, Rollback, And Compatibility Notes

• ReadyCheck does not change remote systems; rollback is deleting or replacing generated output directories such as out/, out_baseline/, and out_diff/.
• Keep prior results.json artifacts when you need a stable baseline for comparison.
• Treat matrix schema changes as compatibility changes and validate them with ./scripts/check.sh before using them in CI or change evidence workflows.

Documentation

• Operator guide: docs/OPERATORS_GUIDE.md
• WSL2 runbook: docs/WSL2_RUNBOOK.md
• Project spec: SPEC.md
• Current state snapshot: STATE.md
• Full disclaimer: DISCLAIMER.md

Repository Layout

• src/readycheck/cli.py: command orchestration (run, diff)
• src/readycheck/spec.py: matrix parsing, validation, and execution planning
• src/readycheck/checks/: protocol check implementations
• src/readycheck/classify.py: failure classification
• src/readycheck/report/: JSON, CSV, HTML, and summary writers
• src/readycheck/diff.py: baseline comparison and severity scoring
• tests/: unit and light integration coverage

Safety

Use ReadyCheck only against systems and networks where you have explicit authorization. It is built for declared, targeted validation workflows and evidence collection, not exploration or broad scanning.