spl-tls-analyze 0.3.1b0

Fast, zero-dependency TLS risk analysis with OCSP revocation detection and structured decisions

SPL TLS Risk Analyzer

Fast, zero-dependency TLS risk analysis with OCSP revocation detection and structured decisions.

Probes domains for TLS certificate validity, checks OCSP revocation, detects deprecated protocols (TLS 1.0/1.1), and produces ALLOW/REVIEW/DENY decisions across 15 risk categories with 5 severity levels. 3 operating profiles. JSON + Markdown structured output. No pip install required.

Not production ready. See docs/KNOWN_LIMITATIONS.md.

Local Beta Freeze — v0.2.0b0. See docs/RELEASE_NOTES_0.2.0b0.md and docs/LOCAL_BETA_FREEZE_MANIFEST.md.

What It Does

• TLS probing — certificate validity, expiry, chain trust, protocol version via Python ssl
• OCSP revocation checking — AIA responder URL extraction + OCSP staple verification
• Deprecated TLS detection — secondary probe forces TLS 1.0 negotiation to detect legacy support
• 15 risk categories — VALID_TLS, EXPIRED_CERT, REVOKED_CERT, SELF_SIGNED_CERT, WRONG_HOST_CERT, UNTRUSTED_CHAIN, INCOMPLETE_CHAIN, WEAK_SIGNATURE_ALGORITHM, DNS_FAILURE, CONNECTION_ERROR, TIMEOUT, TLS_HANDSHAKE_FAILURE, OCSP_UNREACHABLE, UNKNOWN_SSL_ERROR, DEPRECATED_TLS_VERSION
• 5 severity levels — NONE -> LOW -> MEDIUM -> HIGH -> CRITICAL
• 3 operating profiles — conservative, balanced (default), strict
• 3 output formats — structured console text, JSON (with schema), Markdown
• Zero external dependencies — stdlib only (Python 3.10+)
• Batch analysis — domain list files with progress reporting

Limitations

• No multi-IP or IPv6 probing
• Not production-ready — see docs/KNOWN_LIMITATIONS.md
• SPL evidence pipeline (--spl flag) requires optional [spl-core] extras

Quickstart

# From the project root:
cd spl_v7_project_with_frontier/spl_v7_project

# Analyze a single domain
python scripts/spl_tls_analyze.py example.com

# Batch analysis with strict profile, JSON output
python scripts/spl_tls_analyze.py domains.txt --profile strict --json-out report.json

# Markdown report with conservative profile
python scripts/spl_tls_analyze.py domains.txt --profile conservative --markdown-out report.md

# Quiet mode — batch summary only
python scripts/spl_tls_analyze.py domains.txt --quiet

No pip install required. Python 3.10+.

Docker image available: see docs/DOCKER_USAGE.md.

Profiles

Profile	ALLOW Threshold	HIGH Security	Deprecated TLS	Fallback ALLOW	Use Case
balanced (default)	0.5	REVIEW	REVIEW	Clean VALID_TLS only	General-purpose
conservative	0.7	REVIEW	REVIEW	Never	High-sensitivity
strict	0.7	DENY	DENY	Never	Security-critical

See docs/OPERATING_PROFILES.md for full details.

Run Tests

# Official release verification (13 checks)
python scripts/verify_release.py

# Or run individual components:

# All tests (530 tests)
python -m unittest discover -s tests -v

# With pytest
python -m pytest tests/ -q

# Compile check
python -m compileall -q spl_v7 experiments scripts tests tls_policy_adapter decision_orchestrator

# Golden acceptance tests
python -m pytest tests/test_cli_golden_acceptance.py -v

# Docker build (optional)
docker build -t spl-tls-analyze:0.2.0b0 .

# Docker smoke tests
python -m pytest tests/test_docker_docs.py -v

# VPS dry-run script (Linux/macOS)
./scripts/run_vps_dry_run.sh

Project Structure

spl_v7/                  SPL Core (untouched since Phase 1)
tls_policy_adapter/      Risk category mapping (Phase 6)
decision_orchestrator/   Decision rules + profiles (Phase 7/8)
scripts/
  spl_tls_analyze.py      CLI entry point (Phase 9)
  verify_release.py        Release verification (13 checks)
  run_docker_dogfood.ps1   Docker dogfood helper
  run_vps_dry_run.sh        VPS dry-run script (Linux)
  run_vps_dry_run.ps1       VPS dry-run script (PowerShell)
  run_dogfood_cli.py        Dogfood runner
  generate_golden_fixtures.ps1  Golden snapshot generator
  ...
tests/
  test_cli_golden_acceptance.py  Golden acceptance tests (Phase 10)
  test_spl_tls_analyze.py        CLI unit tests (Phase 9)
  test_decision_orchestrator.py  Orchestrator tests (Phase 7/7.5/8)
  test_tls_policy_adapter.py     Adapter tests (Phase 6/6.5)
  test_docker_docs.py            Docker smoke tests (Phase 15)
  ...
datasets/
  cli_golden_samples.json  Golden sample definitions (Phase 10)
  vps_dry_run_domains.txt   VPS dry-run dataset (15 domains)
docs/
  CLI_USAGE.md             Full CLI reference
  CLI_OUTPUT_SCHEMA.md     JSON schema
  CLI_GOLDEN_TESTING.md    Golden testing methodology
  CLI_EXAMPLES.md          Example runs
  KNOWN_LIMITATIONS.md     Known limitations
  OPERATING_PROFILES.md    Profile definitions
  RELEASE_NOTES_0.2.0b0.md Release notes
  LOCAL_BETA_FREEZE_MANIFEST.md  Freeze manifest
  RELEASE_CHECKLIST.md     Pre-release checklist
  TEST_SUITE_STATUS.md     Test suite breakdown
  DOGFOOD_FINDINGS.md      Dogfood analysis
  CLI_CONFIDENCE_FALLBACK_POLICY.md  Fallback policy
  DOCKER_USAGE.md          Docker build and usage
  VPS_DRY_RUN.md            VPS dry-run guide
  VPS_DRY_RUN_REPORT_TEMPLATE.md  VPS dry-run report template

Exit Codes

Code	Meaning
0	All domains ALLOW
1	One or more REVIEW (no DENY)
2	One or more DENY
3	All domains errored
4	Invalid arguments

Dogfood Results

See docs/DOGFOOD_FINDINGS.md for results of running the CLI against 31 real public domains. Key findings:

• 31/31 domains probed, 0 errors, 0 timeouts
• After Phase 13 fallback: 19 ALLOW, 11 REVIEW, 1 DENY
• Before Phase 13: 0 ALLOW, 30 REVIEW, 1 DENY (fallback was missing)
• wrong.host.badssl.com correctly DENY'd
• revoked.badssl.com correctly detected as REVOKED_CERT — OCSP checking now implemented
• deprecated TLS detected (e.g. TLSv1.1) — secondary probe forces lower version negotiation
• Exit code 2 (DENY) clearly signals action needed
• Fallback ALLOW is adapter-policy based, not SPL confidence — see docs/CLI_CONFIDENCE_FALLBACK_POLICY.md

The CLI is now practical for routine scanning (exit code 0 fires for clean domains).

Key Documents

• docs/CLI_USAGE.md — Full CLI reference
• docs/CLI_OUTPUT_SCHEMA.md — JSON output schema
• docs/CLI_EXAMPLES.md — Example runs with output
• docs/CLI_CONFIDENCE_FALLBACK_POLICY.md — Fallback policy design
• docs/CLI_GOLDEN_TESTING.md — Golden acceptance testing
• docs/KNOWN_LIMITATIONS.md — All known limitations
• docs/OPERATING_PROFILES.md — Profile definitions
• docs/RELEASE_CHECKLIST.md — Pre-release checklist
• docs/TEST_SUITE_STATUS.md — Test suite breakdown
• docs/RELEASE_NOTES_0.2.0b0.md — Release notes
• docs/LOCAL_BETA_FREEZE_MANIFEST.md — Freeze manifest with stable contracts
• docs/DOCKER_USAGE.md — Docker build and usage
• docs/VPS_DRY_RUN.md — VPS dry run guide
• docs/VPS_DRY_RUN_REPORT_TEMPLATE.md — VPS dry run report template
• docs/DECISION_ORCHESTRATION_POLICY.md — Orchestrator design
• docs/DECISION_SEMANTICS_AUDIT.md — Decision semantics
• docs/TLS_RISK_POLICY_ADAPTER.md — Adapter design

License

See LICENSE or project documentation.