spl-tls-analyze 0.3.0b0__tar.gz

spl_tls_analyze-0.3.0b0/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: spl-tls-analyze
+Version: 0.3.0b0
+Summary: Fast, zero-dependency TLS risk analysis with OCSP revocation detection and structured decisions
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: kafka
+Requires-Dist: confluent-kafka>=2.5; extra == "kafka"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Provides-Extra: ca-store
+Requires-Dist: certifi>=2024.0.0; extra == "ca-store"
+Provides-Extra: spl-core
+Requires-Dist: numpy>=1.26; extra == "spl-core"
+Requires-Dist: plotly>=5.20; extra == "spl-core"
+Requires-Dist: networkx>=3.2; extra == "spl-core"
+Requires-Dist: fastapi>=0.111; extra == "spl-core"
+Requires-Dist: uvicorn>=0.30; extra == "spl-core"
+
+# 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
+
+```bash
+# 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
+
+```bash
+# 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.

spl_tls_analyze-0.3.0b0/README.md

@@ -0,0 +1,184 @@
+# 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
+
+```bash
+# 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
+
+```bash
+# 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.

spl_tls_analyze-0.3.0b0/decision_orchestrator/__init__.py

@@ -0,0 +1,41 @@
+"""Decision Orchestration Policy — sidecar that combines adapter + SPL outputs.
+
+Consumes TLS Risk Policy Adapter output and SPL decision output to produce
+a transparent final decision (ALLOW / REVIEW / DENY) without modifying SPL Core.
+
+Exports:
+    FinalDecision, FinalRisk, DecisionSource: Literal types.
+    OrchestratorInput: TypedDict for all input fields.
+    OrchestratorOutput: TypedDict for the final output.
+    decide: The core orchestration function.
+    generate_report: Produce a structured benchmark report.
+    SEVERITY_RANK: Dict for comparing severity levels.
+"""
+
+from decision_orchestrator.schema import (
+    FinalDecision,
+    FinalRisk,
+    DecisionSource,
+    OrchestratorInput,
+    OrchestratorOutput,
+    SEVERITY_ORDER,
+    SEVERITY_RANK,
+    OperatingProfile,
+)
+from decision_orchestrator.policy import decide, orchestrate
+from decision_orchestrator.reporter import generate_report, save_results, BenchmarkRunResult
+
+__all__ = [
+    "FinalDecision",
+    "FinalRisk",
+    "DecisionSource",
+    "OrchestratorInput",
+    "OrchestratorOutput",
+    "SEVERITY_ORDER",
+    "SEVERITY_RANK",
+    "OperatingProfile",
+    "decide",
+    "orchestrate",
+    "generate_report",
+    "BenchmarkRunResult",
+]