tlsvalidator

TLS connection posture validator for the NC3 Testing Platform. Assesses a server's TLS configuration — protocol versions, cipher suites, certificate, and known vulnerabilities — using SSLyze as an in-process scan engine, then grades it A+ to F with the same penalty model as headersvalidator.

Discovery, not exploitation. Every check detects and reports; none exploits.

Install

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

Usage

tlsvalidator check example.com                 # scan port 443
tlsvalidator check example.com:8443            # scan an explicit port
tlsvalidator check example.com --port 8443     # equivalent
tlsvalidator check example.com --json          # machine-readable output
tlsvalidator check example.com -o report.html  # save .txt / .svg / .html
tlsvalidator check example.com --strict        # exit 1 on WARN as well as FAIL

tlsvalidator info rules                         # every rule + severity
tlsvalidator info grades                        # the penalty/grade model
tlsvalidator --version                          # -V

Exit codes

Code	Meaning
0	All evaluated checks pass
1	One or more checks fail (or warn with --strict), or bad input
2	Network / connection error

What it checks

Category	Checks
Protocol versions	SSL 2.0 / 3.0 (CRITICAL), TLS 1.0 / 1.1 (HIGH), TLS 1.2 / 1.3 support
Cipher suites	Insecure (NULL/EXPORT/RC4/anon/MD5), weak (3DES/DES/…), forward secrecy
Certificate	Chain trust + hostname, expiry, key strength, SHA-1 signature, OCSP stapling
Vulnerabilities	Heartbleed, ROBOT, CCS injection, secure renegotiation, CRIME, downgrade (SCSV)
Post-quantum	ML-KEM hybrid key-exchange readiness (via quantumvalidator), informational — like SSL Labs

See docs/SECURITY_VERDICT.md for the full rule reference, severity rationale, and grading model.

Architecture

tlsvalidator/
  cli.py           Typer entry point (check + info commands)
  assessor.py      Public API: assess(target, *, port, timeout, progress_cb) -> TLSReport
  sslyze_utils.py  SSLyze boundary — run_scan() -> RawScanResult
  pqc_utils.py     quantumvalidator boundary — probe_pqc() -> PqcInfo
  checker.py       Pure rule evaluation over RawScanResult
  constants.py     Rule catalogue, thresholds, cipher classification
  verdict.py       Penalty-point grading (A+ … F)
  models.py        Dataclasses (raw scan + result types)
  reporter.py      Rich terminal / .txt / .svg / .html rendering (nested panels)

Network I/O is isolated in two boundaries — sslyze_utils.run_scan (SSLyze) and pqc_utils.probe_pqc (quantumvalidator). Tests mock both, so the suite runs offline. The post-quantum probe is best-effort: if it cannot run (e.g. openssl < 3.5), the PQC check is reported as informational and never fails the scan.

Development

pytest --tb=short -q          # full suite (159 tests, 100% coverage enforced)
ruff check tlsvalidator/      # lint

The post-quantum check depends on the sibling quantumvalidator package (declared in pyproject.toml) and its openssl ≥ 3.5 runtime requirement for live ML-KEM probing. For local development against the monorepo checkout: pip install -e ../quantumvalidator.

License

GPL-3.0