umbermark-cli 1.0.0rc1__py3-none-any.whl

umbermark/core/external/checks/tls_hygiene.py

@@ -0,0 +1,107 @@
+"""External check: TLS protocol and certificate hygiene.
+
+Everything here is visible from the handshake alone — no authentication. We flag
+deprecated protocol versions still on offer (SSLv2/3, TLS 1.0/1.1), an expired
+or self-signed leaf certificate (hard fail), and a certificate within two weeks
+of expiry (advisory — fix it before it lapses).
+
+A legacy version the scanner's own TLS stack could not offer (UMBR-34) is
+"unknown", not "not offered": such a result is never a PASS. Hard failures
+still FAIL and near-expiry still WARNs; otherwise the check SKIPs.
+A certificate that could not be read or parsed (UMBR-35) is a WARN: its expiry
+and issuer are unverified, so it is never a PASS.
+A chain that does not verify against a public trust store (UMBR-40) is a FAIL:
+self-signed and private-CA certificates alike (issuer != subject does not make a
+certificate trusted). If the verifying handshake could not run, trust is unknown
+and the result is a WARN, never a PASS.
+"""
+from __future__ import annotations
+
+from umbermark.core.check import Finding, Severity, Verdict
+from umbermark.core.external.check import ExternalCheck
+from umbermark.core.external.probe import ExternalProbe
+
+# TLS/SSL versions that should no longer be offered.
+_LEGACY_PROTOCOLS = {"SSLv2", "SSLv3", "TLSv1", "TLSv1.0", "TLSv1.1"}
+_EXPIRY_WARN_DAYS = 14
+
+
+class TlsHygieneCheck(ExternalCheck):
+    id = "external_tls_hygiene"
+    title = "TLS uses modern protocols and a valid certificate"
+    category = "external_network"
+    severity = Severity.HIGH
+    weight = 10
+    remediation = (
+        "Disable SSLv2/SSLv3/TLS 1.0/1.1 and offer only TLS 1.2+ (prefer 1.3). "
+        "Serve a current certificate from a trusted CA (not self-signed) and "
+        "renew well before expiry — automate it with ACME/Let's Encrypt."
+    )
+
+    def run(self, probe: ExternalProbe) -> Finding:
+        info = probe.tls_info(443)
+        if info is None:
+            return self._finding(
+                Verdict.SKIP,
+                skip_reason="no TLS service answered on port 443",
+            )
+
+        hard: list[str] = []  # FAIL-level problems
+        legacy = sorted(p for p in info.protocols if p in _LEGACY_PROTOCOLS)
+        if legacy:
+            hard.append(f"deprecated protocols offered: {', '.join(legacy)}")
+        if info.cert_readable:
+            if info.days_until_expiry < 0:
+                hard.append(f"certificate expired {abs(info.days_until_expiry)} days ago")
+            if info.self_signed:
+                hard.append("certificate is self-signed (not from a trusted CA)")
+        # Trust is judged even when the leaf could not be parsed: the verifying
+        # handshake reads the chain independently of our DER parser.
+        if info.chain_trusted is False:
+            reason = info.trust_error or "verification failed"
+            redundant = info.cert_readable and (
+                info.self_signed
+                or (info.days_until_expiry < 0 and "expired" in reason.lower())
+            )
+            if not redundant:
+                if "local issuer" in reason.lower():
+                    # Also what a server that omits its intermediate certificate produces:
+                    # browsers may fill the gap, but curl, Python and many apps fail.
+                    hard.append(
+                        "certificate chain is incomplete or not trusted by a public CA "
+                        f"({reason}; if the certificate is CA-issued, serve the full chain)"
+                    )
+                else:
+                    hard.append(f"certificate chain is not trusted by a public CA ({reason})")
+
+        unprobed = sorted(p for p in info.unprobed if p in _LEGACY_PROTOCOLS)
+        unknown: list[str] = []
+        if not info.cert_readable:
+            unknown.append("certificate could not be read or parsed (expiry and issuer unverified)")
+        if info.chain_trusted is None:
+            unknown.append("certificate chain trust could not be verified")
+        if unprobed:
+            unknown.append(
+                f"could not probe {', '.join(unprobed)} (scanner TLS library cannot offer it)"
+            )
+
+        if hard:
+            return self._finding(Verdict.FAIL, evidence="; ".join(hard + unknown))
+
+        warn: list[str] = []
+        if info.cert_readable and 0 <= info.days_until_expiry < _EXPIRY_WARN_DAYS:
+            warn.append(f"certificate expires in {info.days_until_expiry} days")
+        if warn or not info.cert_readable or info.chain_trusted is None:
+            return self._finding(Verdict.WARN, evidence="; ".join(warn + unknown))
+
+        if unprobed:
+            return self._finding(
+                Verdict.SKIP,
+                skip_reason=f"{unknown[0]}; legacy-protocol support unverified "
+                            "(certificate valid and not near expiry)",
+            )
+
+        return self._finding(
+            Verdict.PASS,
+            evidence="modern TLS only, certificate valid and not near expiry",
+        )

umbermark/core/external/engine.py

@@ -0,0 +1,89 @@
+"""External scan orchestrator — runs external checks against a network probe.
+
+Mirrors `core.engine.run_scan` but for the outside-in probe: no platform
+detection, no distro gating. Reuses `ScanReport` + `scoring.score` so the report
+and rendering are identical to the on-box tiers.
+"""
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Iterable
+
+from umbermark.core.check import Finding, Verdict
+from umbermark.core.engine import ScanReport
+from umbermark.core.external.check import ExternalCheck
+from umbermark.core.external.probe import ExternalProbe
+from umbermark.core.scoring import score
+
+
+UNVERIFIED_SKIP_REASON = "target ownership not verified"
+IP_CHANGED_SKIP_REASON = "target IP changed since verification; re-verify ownership"
+# Check-specific unverified reasons (set as ExternalCheck.unverified_skip_reason).
+ALT_SSH_UNVERIFIED_SKIP_REASON = "alternate SSH ports not probed (unverified)"
+GATE_SKIP_REASONS = (
+    UNVERIFIED_SKIP_REASON,
+    IP_CHANGED_SKIP_REASON,
+    ALT_SSH_UNVERIFIED_SKIP_REASON,
+)
+
+
+def run_external_scan(
+    target: str,
+    probe: ExternalProbe,
+    checks: Iterable[ExternalCheck],
+    *,
+    verified: bool = False,
+    unverified_reason: str = UNVERIFIED_SKIP_REASON,
+    active_probe: ExternalProbe | None = None,
+) -> ScanReport:
+    """Run ``checks`` against ``probe``.
+
+    ``verified`` defaults to False (fail closed): ACTIVE checks (port probing)
+    are never invoked unless the caller has established target ownership. They
+    are reported as SKIP so coverage honestly reflects what was not tested.
+    """
+    started = datetime.now(timezone.utc).isoformat()
+    findings: list[Finding] = []
+    for c in checks:
+        if c.active and not verified:
+            # A caller-supplied reason (e.g. IP changed) is more specific than
+            # the check's own wording, so it wins over the per-check default.
+            reason = unverified_reason
+            if reason == UNVERIFIED_SKIP_REASON and c.unverified_skip_reason:
+                reason = c.unverified_skip_reason
+            findings.append(
+                Finding(
+                    check_id=c.id,
+                    title=c.title,
+                    category=c.category,
+                    severity=c.severity,
+                    weight=c.weight,
+                    verdict=Verdict.SKIP,
+                    skip_reason=reason,
+                )
+            )
+            continue
+        try:
+            findings.append(
+                c.run(active_probe if c.active and active_probe is not None else probe)
+            )
+        except Exception as exc:
+            findings.append(
+                Finding(
+                    check_id=c.id,
+                    title=c.title,
+                    category=c.category,
+                    severity=c.severity,
+                    weight=c.weight,
+                    verdict=Verdict.SKIP,
+                    skip_reason=f"check raised: {exc!r}",
+                )
+            )
+    finished = datetime.now(timezone.utc).isoformat()
+    return ScanReport(
+        target=target,
+        started_at=started,
+        finished_at=finished,
+        findings=findings,
+        result=score(findings),
+    )