opskit 0.1.0__py3-none-any.whl

opskit/tls/inspect.py

@@ -0,0 +1,273 @@
+"""Certificate parsing, RFC 6125 name matching, and validation-finding assembly.
+
+Pure functions over :mod:`cryptography` certificate objects — no sockets, no printing —
+so every rule here is unit-testable against generated certificates.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+from collections.abc import Sequence
+from datetime import datetime, timezone
+
+from cryptography import x509
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.asymmetric import dsa, ec, ed448, ed25519, rsa
+
+from opskit.tls.models import CertificateInfo, FindingCode, TlsTarget, ValidationFinding
+
+# OpenSSL X509 verify-callback error codes we classify (see `man verify(1)`).
+X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT = 2
+X509_V_ERR_CERT_NOT_YET_VALID = 9
+X509_V_ERR_CERT_HAS_EXPIRED = 10
+X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT = 18
+X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN = 19
+X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY = 20
+X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE = 21
+
+_LEGACY_PROTOCOLS = {"SSLv3", "TLSv1", "TLSv1.1"}
+
+
+def parse_certificate(cert: x509.Certificate) -> CertificateInfo:
+    """Extract the reportable attributes (FR-011) from one certificate."""
+    dns_sans: list[str] = []
+    ip_sans: list[str] = []
+    try:
+        san_ext = cert.extensions.get_extension_for_class(x509.SubjectAlternativeName)
+        dns_sans = list(san_ext.value.get_values_for_type(x509.DNSName))
+        ip_sans = [str(ip) for ip in san_ext.value.get_values_for_type(x509.IPAddress)]
+    except x509.ExtensionNotFound:
+        pass
+
+    not_before = cert.not_valid_before_utc
+    not_after = cert.not_valid_after_utc
+    now = datetime.now(timezone.utc)
+    days = (not_after - now).days
+
+    key = cert.public_key()
+    if isinstance(key, rsa.RSAPublicKey):
+        key_type, key_bits = "RSA", key.key_size
+    elif isinstance(key, ec.EllipticCurvePublicKey):
+        key_type, key_bits = "EC", key.curve.key_size
+    elif isinstance(key, ed25519.Ed25519PublicKey):
+        key_type, key_bits = "Ed25519", 256
+    elif isinstance(key, ed448.Ed448PublicKey):
+        key_type, key_bits = "Ed448", 456
+    elif isinstance(key, dsa.DSAPublicKey):
+        key_type, key_bits = "DSA", key.key_size
+    else:  # pragma: no cover - exotic key types
+        key_type, key_bits = type(key).__name__, 0
+
+    oid = cert.signature_algorithm_oid
+    signature_algorithm = getattr(oid, "_name", None) or oid.dotted_string
+
+    return CertificateInfo(
+        subject=cert.subject.rfc4514_string(),
+        issuer=cert.issuer.rfc4514_string(),
+        sans=tuple(
+            [f"dns:{name}" for name in dns_sans] + [f"ip:{addr}" for addr in ip_sans]
+        ),
+        not_before=not_before.isoformat(),
+        not_after=not_after.isoformat(),
+        days_until_expiry=days,
+        serial=format(cert.serial_number, "x").upper(),
+        signature_algorithm=signature_algorithm,
+        key_type=key_type,
+        key_bits=key_bits,
+        fingerprint_sha256=cert.fingerprint(hashes.SHA256()).hex(),
+        is_self_signed=cert.subject == cert.issuer,
+    )
+
+
+def effective_name(target: TlsTarget) -> str:
+    """The identity validation checks: the SNI override when given, else the host."""
+    return target.server_name or target.host
+
+
+def match_hostname(target: TlsTarget, cert: x509.Certificate) -> bool:
+    """RFC 6125 name matching: exact DNS-SAN, single left-most wildcard label, IP SANs.
+
+    Validation targets :func:`effective_name` — an explicit ``--sni`` names the vhost
+    identity being verified. No CN fallback: a certificate without a matching SAN does
+    not cover the target.
+    """
+    try:
+        san_ext = cert.extensions.get_extension_for_class(x509.SubjectAlternativeName)
+    except x509.ExtensionNotFound:
+        return False
+    name = effective_name(target)
+    try:
+        wanted = ipaddress.ip_address(name)
+    except ValueError:
+        pass
+    else:
+        return any(
+            ip == wanted for ip in san_ext.value.get_values_for_type(x509.IPAddress)
+        )
+    host = name.lower()
+    return any(
+        _dns_name_matches(pattern.lower(), host)
+        for pattern in san_ext.value.get_values_for_type(x509.DNSName)
+    )
+
+
+def _dns_name_matches(pattern: str, host: str) -> bool:
+    pattern = pattern.rstrip(".")
+    host = host.rstrip(".")
+    if pattern == host:
+        return True
+    if not pattern.startswith("*."):
+        return False
+    pattern_labels = pattern.split(".")
+    host_labels = host.split(".")
+    # The wildcard covers exactly one left-most label; never the bare domain.
+    if len(pattern_labels) != len(host_labels):
+        return False
+    return pattern_labels[1:] == host_labels[1:]
+
+
+def _cert_sans_summary(leaf: CertificateInfo) -> str:
+    return ", ".join(leaf.sans) if leaf.sans else "(none)"
+
+
+def _classify_verify_error(
+    errno: int, depth: int, leaf: CertificateInfo, chain_length: int
+) -> tuple[FindingCode, str, str | None]:
+    """Map one OpenSSL verify error (errno, depth) to a finding triple."""
+    where = "certificate" if depth == 0 else f"chain certificate (depth {depth})"
+    ca_hint = "pass the issuing root via --ca-file if this is a private PKI"
+    finding: tuple[FindingCode, str, str | None]
+    if errno == X509_V_ERR_CERT_HAS_EXPIRED:
+        message = (
+            f"{where} expired on {leaf.not_after}"
+            if depth == 0
+            else f"{where} has expired"
+        )
+        finding = (FindingCode.EXPIRED, message, "renew the certificate")
+    elif errno == X509_V_ERR_CERT_NOT_YET_VALID:
+        message = (
+            f"{where} is not valid before {leaf.not_before}"
+            if depth == 0
+            else f"{where} is not yet valid"
+        )
+        finding = (
+            FindingCode.NOT_YET_VALID,
+            message,
+            "check the server clock and the certificate's validity window",
+        )
+    elif errno == X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT:
+        finding = (
+            FindingCode.SELF_SIGNED,
+            "certificate is self-signed",
+            "add it to a private CA bundle and pass --ca-file to trust it",
+        )
+    elif errno == X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN:
+        finding = (
+            FindingCode.UNTRUSTED_CHAIN,
+            "chain ends in a root that is not in the trust store",
+            ca_hint,
+        )
+    elif errno in (
+        X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT,
+        X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY,
+        X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE,
+    ):
+        if chain_length <= 1 and not leaf.is_self_signed:
+            finding = (
+                FindingCode.INCOMPLETE_CHAIN,
+                "server did not present the intermediate certificate(s)",
+                "configure the server to serve the full chain",
+            )
+        else:
+            finding = (
+                FindingCode.UNTRUSTED_CHAIN,
+                "certificate does not chain to a trusted authority",
+                ca_hint,
+            )
+    else:
+        finding = (
+            FindingCode.UNTRUSTED_CHAIN,
+            f"chain validation failed (OpenSSL verify error {errno} at depth {depth})",
+            None,
+        )
+    return finding
+
+
+def build_findings(
+    target: TlsTarget,
+    leaf: CertificateInfo,
+    *,
+    name_matched: bool,
+    verify_errors: Sequence[tuple[int, int]],
+    chain_length: int,
+    tls_version: str | None,
+    warn_days: int,
+) -> tuple[ValidationFinding, ...]:
+    """Turn the verify-callback errors + parsed leaf + match result into findings.
+
+    Args:
+        target: What was checked (drives the name-mismatch message).
+        leaf: Parsed leaf certificate.
+        name_matched: Result of :func:`match_hostname`.
+        verify_errors: (errno, depth) pairs recorded during the handshake.
+        chain_length: Number of certificates the server presented.
+        tls_version: Negotiated protocol name.
+        warn_days: Expiring-soon threshold (0 disables).
+    """
+    findings: list[ValidationFinding] = []
+    seen: set[FindingCode] = set()
+
+    def add(code: FindingCode, message: str, hint: str | None = None) -> None:
+        if code not in seen:
+            seen.add(code)
+            findings.append(ValidationFinding(code=code, message=message, hint=hint))
+
+    for errno, depth in verify_errors:
+        add(*_classify_verify_error(errno, depth, leaf, chain_length))
+
+    if not name_matched:
+        if not leaf.sans:
+            add(
+                FindingCode.NO_SANS,
+                "certificate has no subject alternative names "
+                "(legacy CN-only certificates fail modern validation)",
+                hint="reissue the certificate with SANs",
+            )
+        name = effective_name(target)
+        mode = "IP address" if target.is_ip and name == target.host else "name"
+        add(
+            FindingCode.NAME_MISMATCH,
+            f"requested {mode} {name!r} is not covered; "
+            f"certificate covers: {_cert_sans_summary(leaf)}",
+            hint="check you are hitting the intended vhost (see --sni)",
+        )
+
+    if tls_version in _LEGACY_PROTOCOLS:
+        add(
+            FindingCode.LEGACY_PROTOCOL,
+            f"negotiated {tls_version} is below TLS 1.2",
+            hint="enable TLS 1.2+ on the server",
+        )
+
+    invalid = {
+        FindingCode.EXPIRED,
+        FindingCode.NOT_YET_VALID,
+        FindingCode.NAME_MISMATCH,
+        FindingCode.SELF_SIGNED,
+        FindingCode.UNTRUSTED_CHAIN,
+        FindingCode.INCOMPLETE_CHAIN,
+        FindingCode.NO_SANS,
+    }
+    if (
+        warn_days > 0
+        and 0 <= leaf.days_until_expiry <= warn_days
+        and not (seen & invalid)
+    ):
+        add(
+            FindingCode.EXPIRING_SOON,
+            f"certificate expires in {leaf.days_until_expiry} day(s) "
+            f"(threshold {warn_days})",
+            hint="schedule renewal",
+        )
+
+    return tuple(findings)

opskit/tls/models.py

@@ -0,0 +1,240 @@
+"""Typed data model for TLS verification diagnostics.
+
+Frozen stdlib dataclasses (no Pydantic) with ``to_dict()`` for the JSON envelope.
+See specs/002-tls-verification/data-model.md.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+from opskit.core.errors import UsageError
+
+DEFAULT_PORT = 443
+_MAX_PORT = 65535
+
+
+class TlsOutcome(str, Enum):
+    """Overall verdict class — the first failing layer wins (spec US3)."""
+
+    OK = "ok"
+    EXPIRING_SOON = "expiring_soon"
+    RESOLVE_FAILED = "resolve_failed"
+    CONNECT_REFUSED = "connect_refused"
+    CONNECT_TIMEOUT = "connect_timeout"
+    HANDSHAKE_FAILED = "handshake_failed"
+    CERT_INVALID = "cert_invalid"
+    USAGE_ERROR = "usage_error"
+
+
+class FindingCode(str, Enum):
+    """One distinct validation condition (FR-007/009/010)."""
+
+    EXPIRED = "expired"
+    NOT_YET_VALID = "not_yet_valid"
+    NAME_MISMATCH = "name_mismatch"
+    SELF_SIGNED = "self_signed"
+    UNTRUSTED_CHAIN = "untrusted_chain"
+    INCOMPLETE_CHAIN = "incomplete_chain"
+    NO_SANS = "no_sans"
+    EXPIRING_SOON = "expiring_soon"
+    LEGACY_PROTOCOL = "legacy_protocol"
+
+
+@dataclass(frozen=True)
+class TlsTarget:
+    """What the user asked to check (host, port, effective SNI)."""
+
+    host: str
+    port: int
+    server_name: str | None  # SNI actually sent; None for IP targets
+    is_ip: bool
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a JSON-serializable mapping of this target."""
+        return {
+            "host": self.host,
+            "port": self.port,
+            "server_name": self.server_name,
+            "is_ip": self.is_ip,
+        }
+
+
+def parse_target(
+    raw: str,
+    *,
+    port: int | None = None,
+    server_name: str | None = None,
+) -> TlsTarget:
+    """Parse ``host``, ``host:port``, IP literals, or ``[v6]:port`` into a TlsTarget.
+
+    Args:
+        raw: The user-supplied target string.
+        port: Explicit ``--port`` value; must agree with any shorthand port.
+        server_name: Explicit SNI override (``--sni``).
+
+    Raises:
+        UsageError: For empty targets, invalid ports, or a shorthand/option conflict.
+    """
+    text = raw.strip()
+    if not text:
+        raise UsageError("a target host is required")
+
+    host, shorthand_port = _split_host_port(text, raw)
+    host = host.strip().rstrip(".")  # normalize trailing-dot hostnames
+    if not host:
+        raise UsageError(f"invalid target (empty host): {raw}")
+
+    if port is not None and shorthand_port is not None and port != shorthand_port:
+        raise UsageError(
+            f"conflicting ports: --port {port} vs target '{raw}'",
+            hint="give the port once (either --port or host:port)",
+        )
+    effective_port = shorthand_port if shorthand_port is not None else port
+    if effective_port is None:
+        effective_port = DEFAULT_PORT
+    elif not 1 <= effective_port <= _MAX_PORT:
+        raise UsageError(f"port must be between 1 and {_MAX_PORT}: {effective_port}")
+    is_ip = _is_ip_literal(host)
+
+    if server_name:
+        effective_sni: str | None = server_name
+    elif is_ip:
+        effective_sni = None  # SNI does not apply to IP targets
+    else:
+        effective_sni = host
+    return TlsTarget(
+        host=host, port=effective_port, server_name=effective_sni, is_ip=is_ip
+    )
+
+
+def _split_host_port(text: str, raw: str) -> tuple[str, int | None]:
+    """Split a target into (host, shorthand-port); handles `[v6]:port` and bare IPv6."""
+    if text.startswith("["):  # [v6]:port or [v6]
+        closing = text.find("]")
+        if closing < 0:
+            raise UsageError(f"invalid target (unclosed '['): {raw}")
+        rest = text[closing + 1 :]
+        if rest.startswith(":"):
+            return text[1:closing], _parse_port(rest[1:], raw)
+        if rest:
+            raise UsageError(f"invalid target: {raw}")
+        return text[1:closing], None
+    if text.count(":") == 1:  # host:port (a single colon cannot be bare IPv6)
+        host, _, port_text = text.partition(":")
+        return host, _parse_port(port_text, raw)
+    if text.count(":") > 1 and not _is_ip_literal(text):
+        # Multiple colons are only valid as a bare IPv6 literal; anything else is ambiguous.
+        raise UsageError(
+            f"invalid target: {raw}",
+            hint="use [ipv6]:port to add a port to an IPv6 address",
+        )
+    return text, None  # bare hostname, IPv4, or bare IPv6 literal
+
+
+def _is_ip_literal(host: str) -> bool:
+    try:
+        ipaddress.ip_address(host)
+    except ValueError:
+        return False
+    return True
+
+
+def _parse_port(text: str, raw: str) -> int:
+    try:
+        value = int(text)
+    except ValueError as exc:
+        raise UsageError(f"invalid port in target: {raw}") from exc
+    if not 1 <= value <= _MAX_PORT:
+        raise UsageError(f"port must be between 1 and {_MAX_PORT}: {raw}")
+    return value
+
+
+@dataclass(frozen=True)
+class CertificateInfo:
+    """Descriptive attributes of one certificate plus derived facts."""
+
+    subject: str
+    issuer: str
+    sans: tuple[str, ...]  # "dns:<name>" / "ip:<addr>"
+    not_before: str  # ISO 8601 UTC
+    not_after: str  # ISO 8601 UTC
+    days_until_expiry: int  # negative when expired
+    serial: str  # hex
+    signature_algorithm: str
+    key_type: str
+    key_bits: int
+    fingerprint_sha256: str
+    is_self_signed: bool
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a JSON-serializable mapping of this certificate."""
+        return {
+            "subject": self.subject,
+            "issuer": self.issuer,
+            "sans": list(self.sans),
+            "not_before": self.not_before,
+            "not_after": self.not_after,
+            "days_until_expiry": self.days_until_expiry,
+            "serial": self.serial,
+            "signature_algorithm": self.signature_algorithm,
+            "key_type": self.key_type,
+            "key_bits": self.key_bits,
+            "fingerprint_sha256": self.fingerprint_sha256,
+            "is_self_signed": self.is_self_signed,
+        }
+
+
+@dataclass(frozen=True)
+class ValidationFinding:
+    """One failed or warned validation condition, with explanation and hint."""
+
+    code: FindingCode
+    message: str
+    hint: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a JSON-serializable mapping of this finding."""
+        return {"code": self.code.value, "message": self.message, "hint": self.hint}
+
+
+@dataclass(frozen=True)
+class TlsCheckResult:
+    """The layered outcome of one TLS check (see data-model.md)."""
+
+    target: TlsTarget
+    outcome: TlsOutcome
+    connection: Any | None = (
+        None  # opskit.net.TcpConnection (kept loose to avoid cycle)
+    )
+    tls_version: str | None = None
+    cipher: str | None = None
+    leaf: CertificateInfo | None = None
+    chain: tuple[CertificateInfo, ...] = ()
+    findings: tuple[ValidationFinding, ...] = field(default=())
+    elapsed_ms: float = 0.0
+
+    @property
+    def ok(self) -> bool:
+        """True when the check passed cleanly."""
+        return self.outcome is TlsOutcome.OK
+
+    def __bool__(self) -> bool:
+        """Truthiness mirrors :attr:`ok`."""
+        return self.ok
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a JSON-serializable mapping matching the CLI envelope's result."""
+        return {
+            "outcome": self.outcome.value,
+            "connection": self.connection.to_dict() if self.connection else None,
+            "tls_version": self.tls_version,
+            "cipher": self.cipher,
+            "leaf": self.leaf.to_dict() if self.leaf else None,
+            "chain": [cert.to_dict() for cert in self.chain],
+            "findings": [finding.to_dict() for finding in self.findings],
+            "elapsed_ms": round(self.elapsed_ms, 3),
+        }

opskit/tls/output.py

@@ -0,0 +1,85 @@
+"""Rendering of TLS check results to human-readable (rich) tables.
+
+Category-owned so :mod:`opskit.core` stays free of TLS models. Certificate- and
+server-derived strings are escaped as rich markup before printing.
+"""
+
+from __future__ import annotations
+
+from rich.console import Console
+from rich.markup import escape
+from rich.table import Table
+
+from opskit.tls.models import TlsCheckResult, TlsOutcome
+
+_VERDICT_STYLE = {
+    TlsOutcome.OK: "[green]OK[/green]",
+    TlsOutcome.EXPIRING_SOON: "[yellow]EXPIRING SOON[/yellow]",
+    TlsOutcome.CERT_INVALID: "[red]CERTIFICATE INVALID[/red]",
+}
+
+
+def render_check(result: TlsCheckResult, *, console: Console) -> None:
+    """Print the full layered report: verdict, leaf, chain, protocol, findings."""
+    verdict = _VERDICT_STYLE.get(result.outcome, result.outcome.value)
+    target = result.target
+    console.print(
+        f"{verdict}  {escape(target.host)}:{target.port}"
+        + (
+            f"  (sni: {escape(target.server_name)})"
+            if target.server_name and target.server_name != target.host
+            else ""
+        )
+    )
+    if result.connection is not None:
+        console.print(
+            f"[dim]connected to {escape(result.connection.address)} "
+            f"({result.connection.family}) in {result.connection.connect_ms:.0f} ms[/dim]"
+        )
+    if target.is_ip:
+        console.print("[dim]IP target: no SNI sent; matched against IP SANs[/dim]")
+
+    leaf = result.leaf
+    if leaf is not None:
+        table = Table(show_header=False, box=None, pad_edge=False)
+        table.add_column("field", style="bold", no_wrap=True)
+        table.add_column("value")
+        table.add_row("subject", escape(leaf.subject))
+        table.add_row("issuer", escape(leaf.issuer))
+        table.add_row("SANs", escape(", ".join(leaf.sans) or "(none)"))
+        table.add_row(
+            "validity",
+            escape(f"{leaf.not_before} -> {leaf.not_after}")
+            + f"  ({leaf.days_until_expiry} days remaining)",
+        )
+        table.add_row("serial", escape(leaf.serial))
+        table.add_row("signature", escape(leaf.signature_algorithm))
+        table.add_row("public key", f"{escape(leaf.key_type)} {leaf.key_bits} bits")
+        table.add_row("sha256", escape(leaf.fingerprint_sha256))
+        console.print(table)
+
+    if len(result.chain) > 1:
+        chain_table = Table(show_header=True, header_style="bold", title="Chain")
+        chain_table.add_column("#", justify="right")
+        chain_table.add_column("SUBJECT")
+        chain_table.add_column("ISSUER")
+        chain_table.add_column("EXPIRES")
+        for index, cert in enumerate(result.chain):
+            chain_table.add_row(
+                str(index),
+                escape(cert.subject),
+                escape(cert.issuer),
+                escape(cert.not_after),
+            )
+        console.print(chain_table)
+
+    if result.tls_version or result.cipher:
+        console.print(
+            f"protocol: [bold]{escape(result.tls_version or '?')}[/bold]"
+            f"  cipher: {escape(result.cipher or '?')}"
+        )
+
+    for finding in result.findings:
+        console.print(f"[red]![/red] {finding.code.value}: {escape(finding.message)}")
+        if finding.hint:
+            console.print(f"  [dim]hint: {escape(finding.hint)}[/dim]")