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

--json and --junit can be combined.

Exit codes

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

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.