tlsninja 0.1.0

A CLI tool that diffs the TLS configuration between two hosts.

tlsninja

Diff the TLS configuration between two hosts.

sslyze and testssl.sh scan one host. tlsninja scans two and shows you what changed. Built for DevOps/SRE teams during migrations, blue/green deploys, and TLS regression testing in CI.

Why

When teams migrate services between providers (AWS ALB → Cloudflare, old nginx → new Caddy, prod → staging), TLS configuration silently regresses: HSTS weakens, cipher suites disappear, OCSP stapling turns off, certificate chains lose intermediates. Every existing tool scans one host at a time. tlsninja replaces the eyeball-two-terminal-windows workflow with one command.

Install

uv tool install tlsninja
# or
pipx install tlsninja

tlsninja requires Python 3.11+.

Quick usage

tlsninja diff cloudflare.com mozilla.org

A side-by-side terminal table prints, grouped by category, with rows colored:

• red for regressions (e.g. HSTS shortened, OCSP turned off)
• green for improvements (e.g. TLS 1.0 dropped, RSA → ECDSA)
• yellow for neutral changes (e.g. issuer rotated, SANs reordered)

Output flags

Flag	Effect
--json	Emit machine-readable JSON to stdout instead of the table. Schema is tlsninja.v1.
--junit PATH	Write a JUnit XML report to PATH. Each diff entry is a test; regressions are <failure> elements.
--baseline	Treat HOST_A as the source of truth. Any non-improvement difference fails (exit 1) — even neutral changes.

--json and --junit can be combined.

Exit codes

The exit-code contract is part of the public API:

Code	Meaning
0	No differences, or only improvements / neutrals (or, with --baseline, only improvements).
1	At least one regression detected (or, with --baseline, any non-improvement difference).
2	Scan failed (host unreachable, sslyze error).
3	Usage error (missing argument, bad path).

What the diff captures

• Protocols: TLS 1.0 / 1.1 / 1.2 / 1.3 support per host
• Ciphers: per protocol, added vs removed
• Certificate: subject CN, SANs, issuer, validity, key algorithm + size, signature algorithm, chain completeness and trust
• TLS features: OCSP stapling, session resumption (id and ticket), supported elliptic curves
• HTTP security headers: HSTS (max-age, includeSubDomains, preload), CSP presence, X-Frame-Options, X-Content-Type-Options, Referrer-Policy
• Compliance: which Mozilla SSL profile (modern, intermediate, old) each host meets

CI integration

- name: TLS regression check
  run: tlsninja diff prod.example.com staging.example.com --junit tls-diff.xml --baseline

- uses: actions/upload-artifact@v4
  if: always()
  with:
    name: tls-diff
    path: tls-diff.xml

The step fails the job if anything in staging.example.com is worse than (or merely different from) prod.example.com.

Development

git clone https://github.com/dumitory-dev/tlsninja
cd tlsninja
uv sync --all-groups

Run the full check matrix locally:

scripts/verify.bat            # Windows
ruff check . && ruff format --check . && mypy --strict tlsninja tests && pytest -m "not network and not perf"

The network-marked integration test (tests/test_scanner.py::test_scan_both_real_hosts_completes_under_10s) and the perf benchmark (tests/test_perf.py) are skipped by default. Run them on demand with pytest -m "network or perf".

License

Apache-2.0. See LICENSE.