opskit 0.1.0__py3-none-any.whl

opskit/tls/cli.py

@@ -0,0 +1,267 @@
+"""Thin Typer sub-app for TLS verification: parse args, delegate to the API, render.
+
+Holds no business logic — it maps options onto :mod:`opskit.tls.api` and turns typed
+results/exceptions into human or JSON output and structured exit codes. Supports bulk
+targets via a positional argument and/or ``--input-file`` (one ``host[:port]`` per line).
+
+.. note::
+   This module intentionally does **not** use ``from __future__ import annotations``. Typer
+   reads the ``Annotated[...]`` metadata off the concrete annotation objects; deferring them
+   to strings (PEP 563) makes Typer silently drop the metadata on Python 3.9. Keep
+   annotations eager here and use ``Optional[...]``.
+"""
+
+import json
+from pathlib import Path
+from typing import Annotated, Any, Optional
+
+import typer
+from rich.markup import escape
+
+from opskit.core.cliutils import (
+    ActionResult,
+    aggregate_exit,
+    collect_outcomes,
+    collect_targets,
+    emit_envelopes,
+    run_or_watch,
+)
+from opskit.core.errors import OpskitError, UsageError
+from opskit.core.exit_codes import ExitCode, exit_code_for
+from opskit.core.output import make_console
+from opskit.core.result import build_envelope
+from opskit.tls import api
+from opskit.tls.models import TlsCheckResult, TlsOutcome, parse_target
+from opskit.tls.output import render_check
+
+app = typer.Typer(
+    name="tls",
+    help="TLS verification (certificates, chains, protocol).",
+    no_args_is_help=True,
+)
+
+_CHECK_EPILOG = """\
+[bold]Examples[/bold]
+
+  opskit tls check example.com
+  opskit tls check example.com:8443
+  opskit tls check 192.0.2.10 -p 8443 --sni internal.example.com
+  opskit tls check ldap.corp.example:636 --ca-file corp-root.pem
+  opskit tls check example.com --warn-days 14
+  opskit tls check -i endpoints.txt --jsonl
+  opskit tls check example.com --watch 30s
+"""
+
+_OUTCOME_EXIT = {
+    TlsOutcome.OK: ExitCode.OK,
+    TlsOutcome.EXPIRING_SOON: ExitCode.CERT_EXPIRING,
+    TlsOutcome.CERT_INVALID: ExitCode.CERT_INVALID,
+}
+
+
+def _result_exit(result: TlsCheckResult) -> ExitCode:
+    return _OUTCOME_EXIT.get(result.outcome, ExitCode.ERROR)
+
+
+def _envelope(
+    target: str,
+    result: Optional[TlsCheckResult],
+    error: Optional[OpskitError],
+    *,
+    controls: "dict[str, Any]",
+) -> "dict[str, Any]":
+    """Build the JSON envelope for one target (success or failure — never dropped)."""
+    if result is not None:
+        query = dict(result.target.to_dict(), **controls)
+        return build_envelope(
+            command="tls.check",
+            query=query,
+            result=result.to_dict(),
+            error=None,
+            elapsed_ms=result.elapsed_ms,
+        )
+    # Failure path: enrich the query with the parsed host/port/SNI when the target parses,
+    # so a failed target's envelope still identifies the endpoint (not just the raw string).
+    try:
+        error_query: dict[str, Any] = parse_target(target).to_dict()
+    except UsageError:
+        error_query = {"target": target}
+    return build_envelope(
+        command="tls.check",
+        query=dict(error_query, **controls),
+        result=None,
+        error=error,
+        elapsed_ms=0.0,
+    )
+
+
+def _signature(
+    outcomes: "list[tuple[str, Optional[TlsCheckResult], Optional[OpskitError]]]",
+) -> str:
+    """Change-detection key: outcome class + leaf fingerprint + expiry + protocol (R8)."""
+    parts: list[object] = []
+    for target, result, error in outcomes:
+        if result is not None:
+            leaf = result.leaf
+            parts.append(
+                [
+                    target,
+                    result.outcome.value,
+                    leaf.fingerprint_sha256 if leaf else None,
+                    leaf.not_after if leaf else None,
+                    result.tls_version,
+                ]
+            )
+        else:
+            parts.append([target, error.code if error else "error"])
+    return json.dumps(parts, sort_keys=True)
+
+
+@app.command(epilog=_CHECK_EPILOG)
+def check(
+    target: Annotated[
+        Optional[str],
+        typer.Argument(
+            help=r"host, host:port, IP, or \[ipv6]:port (or use --input-file)."
+        ),
+    ] = None,
+    port: Annotated[
+        Optional[int],
+        typer.Option(
+            "--port",
+            "-p",
+            help="Port to check (default 443; must agree with host:port shorthand).",
+            rich_help_panel="Query controls",
+        ),
+    ] = None,
+    sni: Annotated[
+        Optional[str],
+        typer.Option(
+            "--sni",
+            help="Server name to send (default: the hostname; omitted for IP targets).",
+            rich_help_panel="Query controls",
+        ),
+    ] = None,
+    ca_file: Annotated[
+        Optional[Path],
+        typer.Option(
+            "--ca-file",
+            help="PEM bundle replacing the platform trust store (private PKI).",
+            rich_help_panel="Query controls",
+        ),
+    ] = None,
+    warn_days: Annotated[
+        int,
+        typer.Option(
+            "--warn-days",
+            help="Warn when the certificate expires within N days (0 disables).",
+            rich_help_panel="Query controls",
+        ),
+    ] = 30,
+    timeout: Annotated[
+        float,
+        typer.Option(
+            "--timeout",
+            help="Per-attempt timeout, seconds.",
+            rich_help_panel="Query controls",
+        ),
+    ] = 5.0,
+    retries: Annotated[
+        int,
+        typer.Option(
+            "--retries", help="Retries on timeout.", rich_help_panel="Query controls"
+        ),
+    ] = 2,
+    input_file: Annotated[
+        Optional[Path],
+        typer.Option(
+            "--input-file",
+            "-i",
+            help="File of targets, one host[:port] per line (# comments allowed).",
+            rich_help_panel="Query",
+        ),
+    ] = None,
+    watch: Annotated[
+        Optional[str],
+        typer.Option(
+            "--watch",
+            help="Re-run every interval (e.g. 30s, 2m) until Ctrl-C.",
+            rich_help_panel="Modes",
+        ),
+    ] = None,
+    as_json: Annotated[
+        bool,
+        typer.Option(
+            "--json", help="Emit the versioned JSON envelope.", rich_help_panel="Output"
+        ),
+    ] = False,
+    jsonl: Annotated[
+        bool,
+        typer.Option(
+            "--jsonl",
+            help="Emit one JSON envelope per line (NDJSON).",
+            rich_help_panel="Output",
+        ),
+    ] = False,
+    no_color: Annotated[
+        bool,
+        typer.Option(
+            "--no-color", help="Disable colored output.", rich_help_panel="Output"
+        ),
+    ] = False,
+) -> None:
+    """Verify the TLS health of one or more endpoints (default port 443)."""
+    try:
+        targets = collect_targets(target, input_file)
+    except UsageError as error:
+        typer.echo(f"error: {error.message}", err=True)
+        raise typer.Exit(int(ExitCode.USAGE)) from error
+
+    controls: dict[str, Any] = {
+        "timeout": timeout,
+        "retries": retries,
+        "warn_days": warn_days,
+    }
+    if ca_file is not None:
+        controls["ca_file"] = str(ca_file)
+
+    def run_one(raw: str) -> TlsCheckResult:
+        return api.check(
+            raw,
+            port=port,
+            server_name=sni,
+            ca_file=ca_file,
+            warn_days=warn_days,
+            timeout=timeout,
+            retries=retries,
+        )
+
+    def action() -> ActionResult:
+        outcomes = collect_outcomes(targets, run_one)
+        if as_json or jsonl:
+            emit_envelopes(
+                [_envelope(t, r, e, controls=controls) for t, r, e in outcomes],
+                jsonl=jsonl,
+            )
+        else:
+            console = make_console(no_color=no_color)
+            batch = len(targets) > 1
+            for raw, result, error in outcomes:
+                if batch:
+                    console.print(f"[bold];; {escape(raw)}[/bold]")
+                if result is not None:
+                    render_check(result, console=console)
+                elif error is not None:
+                    message = f"error: {raw}: {error.message}"
+                    if error.hint:
+                        message += f"\nhint: {error.hint}"
+                    typer.echo(message, err=True)
+        codes: list[ExitCode] = []
+        for _, result, error in outcomes:
+            if result is not None:
+                codes.append(_result_exit(result))
+            elif error is not None:
+                codes.append(exit_code_for(error))
+        return aggregate_exit(codes), _signature(outcomes)
+
+    run_or_watch(action, watch_spec=watch, no_color=no_color)

opskit/tls/errors.py

@@ -0,0 +1,65 @@
+"""TLS-specific exception hierarchy (subclasses of :class:`opskit.core.errors.OpskitError`).
+
+Connection-layer failures come from :mod:`opskit.net.errors`; these cover the handshake and
+certificate-validation layers. Each type owns its exit code (constitution Art. VII).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from opskit.core.errors import OpskitError
+from opskit.core.exit_codes import ExitCode
+
+if TYPE_CHECKING:
+    from opskit.tls.models import ValidationFinding
+
+
+class TlsError(OpskitError):
+    """Base class for TLS handshake/validation failures."""
+
+    code = "tls_error"
+    exit_code = ExitCode.HANDSHAKE_FAILED
+
+
+class HandshakeError(TlsError):
+    """The TLS handshake failed (the service may not speak TLS on this port)."""
+
+    code = "handshake_failed"
+    exit_code = ExitCode.HANDSHAKE_FAILED
+
+
+class CertificateInvalid(TlsError):
+    """The certificate failed validation (expired, name mismatch, untrusted, ...)."""
+
+    code = "cert_invalid"
+    exit_code = ExitCode.CERT_INVALID
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        hint: str | None = None,
+        findings: tuple[ValidationFinding, ...] = (),
+    ) -> None:
+        """Initialize with the failing findings attached for programmatic access."""
+        super().__init__(message, hint=hint)
+        self.findings = findings
+
+
+class CertificateExpiring(TlsError):
+    """The certificate is valid but expires within the warning threshold."""
+
+    code = "cert_expiring"
+    exit_code = ExitCode.CERT_EXPIRING
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        hint: str | None = None,
+        days_remaining: int = 0,
+    ) -> None:
+        """Initialize with the days remaining until expiry."""
+        super().__init__(message, hint=hint)
+        self.days_remaining = days_remaining

opskit/tls/handshake.py

@@ -0,0 +1,243 @@
+"""pyOpenSSL handshake with a recording verify callback.
+
+The callback never aborts the handshake — it records every OpenSSL verify error so one
+connection yields both the full presented chain *and* the precise validation findings
+(FR-006). The trust store is sourced from the stdlib's platform defaults, or replaced by a
+user CA bundle (research R2).
+
+Security review (constitution Art. III)
+---------------------------------------
+Static scanners (CodeQL ``py/insecure-protocol``, SonarCloud S4423/S4830/S5527) flag the
+client below as an "insecure TLS client". That is **by design and reviewed as safe**, because
+opskit is a read-only TLS *inspector*, not a data-transferring client:
+
+* It MUST complete the handshake to a server presenting an **invalid** certificate in order to
+  report on it (FR-006) — so the verify callback *records* OpenSSL errors and returns success
+  instead of aborting. The recorded errors drive the verdict/exit code; nothing is trusted.
+* Hostname/SAN validation is done in-tree (RFC 6125, :mod:`opskit.tls.inspect`) so the report
+  can say "requested X, certificate covers Y" — OpenSSL's built-in check only gives a boolean.
+* The connection is anonymous and **no application data is ever sent**, so negotiating with an
+  untrusted peer carries no interception/exfiltration risk.
+* The protocol floor is still TLS 1.2 (``set_min_proto_version`` + explicit ``OP_NO_*``).
+
+Every scanner suppression in this module points back to this note.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import select
+import socket
+import ssl as stdlib_ssl
+import time
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import cast
+
+from cryptography import x509
+from OpenSSL import SSL
+from OpenSSL.crypto import X509
+
+from opskit.net.errors import ConnectTimeout
+from opskit.tls.errors import HandshakeError
+
+_NON_TLS_MARKERS = (
+    "wrong version number",
+    "unknown protocol",
+    "packet length too long",
+    "record layer failure",
+    "unexpected message",
+)
+
+
+@dataclass(frozen=True)
+class HandshakeOutcome:
+    """Everything one completed handshake yields."""
+
+    chain: tuple[x509.Certificate, ...]  # as presented, leaf first
+    tls_version: str | None
+    cipher: str | None
+    verify_errors: tuple[tuple[int, int], ...]  # (errno, depth) pairs
+
+
+def _load_platform_store(context: SSL.Context) -> None:
+    """Fill the pyOpenSSL store with the platform's default CAs.
+
+    Two complementary sources (research R2): OpenSSL's own default paths (Linux/macOS
+    cafile/capath — covers distros where the stdlib loads a lazy capath that
+    ``get_ca_certs`` cannot enumerate) plus the stdlib's enumeration (which pulls from
+    the Windows system certificate stores).
+    """
+    with contextlib.suppress(SSL.Error):
+        context.set_default_verify_paths()
+    stdlib_context = stdlib_ssl.SSLContext(stdlib_ssl.PROTOCOL_TLS_CLIENT)
+    stdlib_context.load_default_certs(stdlib_ssl.Purpose.SERVER_AUTH)
+    store = context.get_cert_store()
+    if store is None:  # pragma: no cover - pyOpenSSL always returns a store
+        return
+    for der in stdlib_context.get_ca_certs(binary_form=True):
+        try:
+            store.add_cert(X509.from_cryptography(x509.load_der_x509_certificate(der)))
+        except (ValueError, TypeError, SSL.Error):
+            continue  # skip a malformed platform entry, keep loading the rest
+
+
+def build_context(ca_file: str | Path | None = None) -> SSL.Context:
+    """Return a TLS client context whose trust store is the platform's (or ``ca_file``).
+
+    The client requires **TLS 1.2 or newer**: opskit is secure-by-default, so it will not
+    negotiate down to SSLv3/TLS 1.0/1.1. A server offering only a legacy protocol therefore
+    fails the handshake (with a hint) rather than being connected to.
+    """
+    # See the module "Security review" note: this inspector requires TLS 1.2+ (min-proto plus
+    # explicit OP_NO_* for scanners) but intentionally does not delegate the pass/fail decision
+    # to OpenSSL — validation is recorded and evaluated by opskit (FR-006).
+    context = SSL.Context(
+        SSL.TLS_CLIENT_METHOD
+    )  # NOSONAR - S4423; TLS>=1.2 enforced below
+    context.set_min_proto_version(SSL.TLS1_2_VERSION)
+    context.set_options(
+        SSL.OP_NO_SSLv2 | SSL.OP_NO_SSLv3 | SSL.OP_NO_TLSv1 | SSL.OP_NO_TLSv1_1
+    )
+    if ca_file is not None:
+        context.load_verify_locations(str(ca_file))
+    else:
+        _load_platform_store(context)
+    return context
+
+
+def perform_handshake(
+    sock: socket.socket,
+    *,
+    server_name: str | None,
+    timeout: float,
+    ca_file: str | Path | None = None,
+) -> HandshakeOutcome:
+    """Run the TLS handshake over an already-connected socket; never sends app data.
+
+    Args:
+        sock: Connected TCP socket (consumed; caller still closes it).
+        server_name: SNI to send, or ``None`` to omit (IP targets).
+        timeout: Handshake timeout in seconds.
+        ca_file: Optional PEM bundle replacing the platform trust store.
+
+    Raises:
+        ConnectTimeout: If the peer stops responding mid-handshake.
+        HandshakeError: If the handshake fails (e.g. the service does not speak TLS).
+    """
+    verify_errors: list[tuple[int, int]] = []
+
+    def _record(
+        _conn: SSL.Connection,
+        _cert: object,
+        errno: int,
+        depth: int,
+        ok: int,
+    ) -> bool:
+        # Reviewed-safe (see module note): record the error and continue so an INVALID
+        # certificate can still be inspected (FR-006); opskit — not OpenSSL — decides.
+        if not ok:
+            verify_errors.append((errno, depth))
+        return True  # NOSONAR - S4830; inspector records verify errors, never trusts blindly
+
+    context = build_context(ca_file)
+    # Verification is intentionally recorded (not delegated) and hostname matching is done
+    # in-tree (RFC 6125); see the module "Security review" note.
+    context.set_verify(SSL.VERIFY_PEER, _record)  # NOSONAR - S4830/S5527, reviewed safe
+    # CodeQL py/insecure-protocol reports this as allowing SSLv3/TLS1.0/1.1: a false positive,
+    # since the context enforces TLS 1.2+ (set_min_proto_version + OP_NO_*) which CodeQL does
+    # not model for pyOpenSSL. Reviewed safe — dismissed on the default branch with this reason.
+    connection = SSL.Connection(context, sock)
+    if server_name:
+        try:
+            encoded = server_name.encode("idna")
+        except UnicodeError:
+            encoded = server_name.encode("ascii", errors="ignore")
+        connection.set_tlsext_host_name(encoded)
+    sock.settimeout(timeout)
+    connection.set_connect_state()
+    try:
+        _handshake_with_timeout(connection, sock, timeout)
+    except socket.timeout as exc:
+        raise ConnectTimeout(
+            f"TLS handshake timed out after {timeout}s",
+            hint="the service may be hanging mid-handshake; try a longer --timeout",
+        ) from exc
+    except SSL.SysCallError as exc:
+        raise HandshakeError(
+            f"connection closed during TLS handshake: {exc}",
+            hint="the service may not speak TLS on this port",
+        ) from exc
+    except SSL.Error as exc:
+        raise HandshakeError(
+            f"TLS handshake failed: {_ssl_error_text(exc)}",
+            hint=(
+                "the service may not speak TLS on this port, or may only offer TLS "
+                "below 1.2 which opskit refuses (STARTTLS upgrades are not supported)"
+            ),
+        ) from exc
+
+    chain = tuple(connection.get_peer_cert_chain(as_cryptography=True) or [])
+    tls_version: str | None = connection.get_protocol_version_name()
+    cipher: str | None = connection.get_cipher_name()
+    # Best-effort close; the data is already extracted.
+    with contextlib.suppress(SSL.Error, OSError):
+        connection.shutdown()
+    return HandshakeOutcome(
+        chain=chain,
+        tls_version=tls_version,
+        cipher=cipher,
+        verify_errors=tuple(verify_errors),
+    )
+
+
+def _handshake_with_timeout(
+    connection: SSL.Connection, sock: socket.socket, timeout: float
+) -> None:
+    """Drive ``do_handshake`` to completion under a wall-clock deadline.
+
+    A Python socket with a timeout is internally non-blocking, so pyOpenSSL surfaces
+    ``WantRead/WantWrite`` — wait with ``select`` and retry until done or out of time.
+    """
+    deadline = time.monotonic() + timeout
+    while True:
+        try:
+            connection.do_handshake()
+            return
+        except (SSL.WantReadError, SSL.WantWriteError) as exc:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise socket.timeout("handshake deadline exceeded") from exc
+            wants_read = isinstance(exc, SSL.WantReadError)
+            readable, writable, _ = select.select(
+                [sock] if wants_read else [],
+                [] if wants_read else [sock],
+                [],
+                remaining,
+            )
+            if not readable and not writable:
+                raise socket.timeout("handshake deadline exceeded") from exc
+
+
+def _ssl_error_text(exc: SSL.Error) -> str:
+    """Flatten pyOpenSSL's ``[(lib, func, reason), ...]`` error args into one line."""
+    parts: list[str] = []
+    for entry in cast("tuple[object, ...]", exc.args):
+        if isinstance(entry, (list, tuple)):
+            for item in cast("Sequence[object]", entry):
+                if isinstance(item, (list, tuple)):
+                    joined = ":".join(
+                        str(piece) for piece in cast("Sequence[object]", item) if piece
+                    )
+                    if joined:
+                        parts.append(joined)
+                elif str(item):
+                    parts.append(str(item))
+        elif str(entry):
+            parts.append(str(entry))
+    text = "; ".join(parts) or exc.__class__.__name__
+    lowered = text.lower()
+    if any(marker in lowered for marker in _NON_TLS_MARKERS):
+        text += " (the response does not look like TLS)"
+    return text