Metadata-Version: 2.4
Name: spl-tls-analyze
Version: 0.3.2b0
Summary: Fast, zero-dependency TLS risk analysis with OCSP revocation detection and structured decisions
Keywords: tls,ssl,security,certificate,ocsp,risk-analysis,cli,devops,devsecops,network-security
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Topic :: Security
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
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 20 risk categories with 5 severity levels. 3 operating profiles. JSON + Markdown structured output.

Beta software. Use for TLS risk assessment and CI guardrails; not a complete security audit.

## Install

```bash
pip install spl-tls-analyze
```

Or install from source:

```bash
cd spl_v7_project_with_frontier/spl_v7_project
python scripts/spl_tls_analyze.py example.com
```

Docker image available: see `docs/DOCKER_USAGE.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
- **20 risk categories** — VALID_TLS, EXPIRED_CERT, REVOKED_CERT, SELF_SIGNED_CERT, WRONG_HOST_CERT, UNTRUSTED_CHAIN, INCOMPLETE_CHAIN, WEAK_SIGNATURE_ALGORITHM, WEAK_CIPHER_SUITE, STATIC_RSA_KEY_EXCHANGE, TLS_COMPRESSION_ENABLED, WILDCARD_CERTIFICATE, MISSING_OCSP_STAPLE, 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
- Beta software — see `docs/KNOWN_LIMITATIONS.md`
- SPL evidence pipeline (`--spl` flag) requires optional `[spl-core]` extras

## Quickstart

```bash
# Install
pip install spl-tls-analyze

# Analyze a single domain
spl-tls-analyze example.com

# Batch analysis with strict profile, JSON output
spl-tls-analyze domains.txt --profile strict --json-out report.json

# Markdown report with conservative profile
spl-tls-analyze domains.txt --profile conservative --markdown-out report.md

# Quiet mode — batch summary only
spl-tls-analyze domains.txt --quiet
```

Python 3.10+.

## 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.3.2b0 .

# 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.3.0b0.md Release notes
  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.3.0b0.md` — Release notes
- `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

## Commercial Audits

Need a TLS audit report for your domains or clients? Open an issue or contact binsalemadam.lang@gmail.com.

## License

See `LICENSE` or project documentation.
