certminder 0.2.0__py3-none-any.whl

certminder/__init__.py

@@ -0,0 +1,3 @@
+"""certminder: continuous TLS certificate monitoring built on top of certinspect."""
+
+__version__ = "0.2.0"

certminder/cli.py

@@ -0,0 +1,100 @@
+"""Command-line entry point for certminder.
+
+Subcommands:
+    once    run a single inspection cycle and exit (ideal for cron)
+    run     run continuously, sleeping ``interval`` between cycles (daemon)
+    check   inspect a single host ad hoc, ignoring the config's targets
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from certminder import __version__
+from certminder.config import Config, ConfigError, load_config
+from certminder.engine import check_target
+from certminder.models import Target
+from certminder.scheduler import run_loop, run_once
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="certminder",
+        description="Continuously monitor TLS certificates and alert on changes.",
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"%(prog)s {__version__}"
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_once = sub.add_parser("once", help="run a single inspection cycle and exit")
+    p_once.add_argument("-c", "--config", required=True, help="path to certminder.yml")
+    p_once.add_argument(
+        "--json",
+        action="store_true",
+        help="print a JSON summary of the cycle to stdout",
+    )
+
+    p_run = sub.add_parser("run", help="run continuously as a daemon")
+    p_run.add_argument("-c", "--config", required=True, help="path to certminder.yml")
+
+    p_check = sub.add_parser("check", help="inspect one host ad hoc")
+    p_check.add_argument("host")
+    p_check.add_argument("--port", type=int, default=443)
+    p_check.add_argument("--no-verify", action="store_true")
+    p_check.add_argument("--starttls")
+    p_check.add_argument("--bin", default="certinspect", help="certinspect path")
+
+    return parser
+
+
+def _cmd_check(args: argparse.Namespace) -> int:
+    target = Target(
+        host=args.host,
+        port=args.port,
+        verify=not args.no_verify,
+        starttls=args.starttls,
+    )
+    result = check_target(target, args.bin)
+    icon = "ok" if result.status == "VALID" else result.status
+    detail = (
+        f"{result.days_to_expire} day(s) left"
+        if result.days_to_expire is not None
+        else (result.error or "")
+    )
+    print(f"{target.name}: {icon} ({detail})")
+    return 0 if result.status == "VALID" else 1
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+
+    if args.command == "check":
+        return _cmd_check(args)
+
+    try:
+        config: Config = load_config(args.config)
+    except ConfigError as exc:
+        print(f"certminder: {exc}", file=sys.stderr)
+        return 2
+
+    if args.command == "once":
+        report = run_once(config)
+        if args.json:
+            print(json.dumps(report.to_dict(), indent=2))
+        return 1 if report.events else 0
+
+    if args.command == "run":
+        try:
+            run_loop(config)
+        except KeyboardInterrupt:  # pragma: no cover
+            print("certminder: stopped", file=sys.stderr)
+        return 0
+
+    return 2  # pragma: no cover
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

certminder/config.py

@@ -0,0 +1,120 @@
+"""Load and validate the YAML configuration into typed objects."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from certminder.models import Target
+
+_DURATION_RE = re.compile(r"^\s*(\d+)\s*([smhd])\s*$", re.IGNORECASE)
+_UNIT_SECONDS = {"s": 1, "m": 60, "h": 3600, "d": 86400}
+
+
+class ConfigError(ValueError):
+    """Raised when the configuration file is missing or malformed."""
+
+
+def parse_duration(value: str | int) -> int:
+    """Convert a duration like '6h', '30m', '1d' (or an int) into seconds."""
+    if isinstance(value, int):
+        return value
+    match = _DURATION_RE.match(str(value))
+    if not match:
+        raise ConfigError(
+            f"invalid duration {value!r}; use a number with s/m/h/d (e.g. 6h)"
+        )
+    amount, unit = match.groups()
+    return int(amount) * _UNIT_SECONDS[unit.lower()]
+
+
+@dataclass
+class NotifierConfig:
+    """Raw notifier settings; interpreted by the notifiers package."""
+
+    type: str
+    options: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class Config:
+    """The fully parsed certminder configuration."""
+
+    targets: list[Target]
+    notifiers: list[NotifierConfig]
+    certinspect_bin: str = "certinspect"
+    interval: int = 21600  # 6h
+    state_file: Path = Path("~/.certminder/state.json")
+    concurrency: int = 8
+    prometheus_file: Path | None = None
+
+
+def _build_target(raw: dict[str, Any], defaults: dict[str, Any]) -> Target:
+    if "host" not in raw:
+        raise ConfigError(f"target is missing required 'host': {raw!r}")
+    merged = {**defaults, **raw}
+    allowed = {
+        "host",
+        "port",
+        "verify",
+        "days",
+        "critical_days",
+        "timeout",
+        "starttls",
+        "cafile",
+        "capath",
+        "label",
+    }
+    unknown = set(merged) - allowed
+    if unknown:
+        raise ConfigError(f"unknown target keys {sorted(unknown)} in {raw!r}")
+    return Target(**merged)
+
+
+def load_config(path: str | Path) -> Config:
+    """Read, parse and validate the configuration at ``path``."""
+    path = Path(path).expanduser()
+    if not path.is_file():
+        raise ConfigError(f"config file not found: {path}")
+
+    try:
+        data = yaml.safe_load(path.read_text()) or {}
+    except yaml.YAMLError as exc:  # pragma: no cover - passthrough
+        raise ConfigError(f"could not parse YAML: {exc}") from exc
+
+    if not isinstance(data, dict):
+        raise ConfigError("top-level configuration must be a mapping")
+
+    raw_targets = data.get("targets") or []
+    if not raw_targets:
+        raise ConfigError("at least one target is required")
+
+    defaults = data.get("defaults") or {}
+    targets = [_build_target(t, defaults) for t in raw_targets]
+
+    notifiers = []
+    for entry in data.get("notifiers") or [{"type": "console"}]:
+        if "type" not in entry:
+            raise ConfigError(f"notifier is missing 'type': {entry!r}")
+        options = {k: v for k, v in entry.items() if k != "type"}
+        notifiers.append(NotifierConfig(type=entry["type"], options=options))
+
+    return Config(
+        targets=targets,
+        notifiers=notifiers,
+        certinspect_bin=data.get("certinspect_bin", "certinspect"),
+        interval=parse_duration(data.get("interval", "6h")),
+        state_file=Path(
+            data.get("state_file", "~/.certminder/state.json")
+        ).expanduser(),
+        concurrency=int(data.get("concurrency", 8)),
+        prometheus_file=(
+            Path(data["prometheus_file"]).expanduser()
+            if data.get("prometheus_file")
+            else None
+        ),
+    )

certminder/engine.py

@@ -0,0 +1,129 @@
+"""Run certinspect against a target and normalise its result.
+
+certminder never re-implements TLS or X.509 logic: it shells out to certinspect
+(one target per invocation, ``--json``) and trusts its exit code as the
+authoritative status. The exit-code contract is:
+
+    0 VALID            3 EXPIRING          4 CRITICAL / EXPIRED / INVALID DATES
+    5 HOSTNAME mismatch  6 chain untrusted or REVOKED   7 pin mismatch
+    1 runtime error (e.g. unreachable)   2 usage error
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from typing import Any
+
+from certminder.models import CheckResult, Target
+
+# Exit codes that still produce a usable JSON document (the certificate was
+# fetched and analysed; it simply has a problem).
+_ANALYSED_CODES = {0, 3, 4, 5, 6, 7}
+
+
+def build_command(bin_path: str, target: Target) -> list[str]:
+    """Assemble the certinspect command line for ``target``."""
+    cmd = [
+        bin_path,
+        target.host,
+        "--json",
+        "--port",
+        str(target.port),
+        "--timeout",
+        str(target.timeout),
+        "--days",
+        str(target.days),
+        "--critical-days",
+        str(target.critical_days),
+    ]
+    if target.verify:
+        cmd.append("--verify")
+    if target.starttls:
+        cmd += ["--starttls", target.starttls]
+    if target.cafile:
+        cmd += ["--cafile", target.cafile]
+    if target.capath:
+        cmd += ["--capath", target.capath]
+    return cmd
+
+
+def _status_from(exit_code: int, info: dict[str, Any]) -> str:
+    """Refine certinspect's exit code into a certminder status string."""
+    if exit_code == 0:
+        return "VALID"
+    if exit_code == 3:
+        return "EXPIRING"
+    if exit_code == 4:
+        days = info.get("days_to_expire")
+        if isinstance(days, int) and days < 0:
+            return "EXPIRED"
+        return "CRITICAL"
+    if exit_code == 5:
+        return "HOSTNAME_MISMATCH"
+    if exit_code == 6:
+        if info.get("revocation_status") == "REVOKED":
+            return "REVOKED"
+        return "CHAIN_UNTRUSTED"
+    if exit_code == 7:
+        return "PIN_MISMATCH"
+    return "UNREACHABLE"
+
+
+def check_target(target: Target, bin_path: str = "certinspect") -> CheckResult:
+    """Inspect a single target and return a normalised :class:`CheckResult`."""
+    cmd = build_command(bin_path, target)
+    try:
+        proc = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=target.timeout + 30,
+        )
+    except FileNotFoundError:
+        return CheckResult(
+            target=target,
+            reachable=False,
+            status="ERROR",
+            exit_code=127,
+            error=f"certinspect executable not found: {bin_path!r}",
+        )
+    except subprocess.TimeoutExpired:
+        return CheckResult(
+            target=target,
+            reachable=False,
+            status="UNREACHABLE",
+            exit_code=124,
+            error="certinspect timed out",
+        )
+
+    info: dict[str, Any] = {}
+    if proc.returncode in _ANALYSED_CODES:
+        try:
+            parsed = json.loads(proc.stdout or "[]")
+            if isinstance(parsed, list) and parsed:
+                info = parsed[0]
+        except json.JSONDecodeError:
+            info = {}
+
+    if proc.returncode not in _ANALYSED_CODES:
+        return CheckResult(
+            target=target,
+            reachable=False,
+            status="UNREACHABLE",
+            exit_code=proc.returncode,
+            error=(proc.stderr or proc.stdout or "").strip() or "inspection failed",
+        )
+
+    return CheckResult(
+        target=target,
+        reachable=True,
+        status=_status_from(proc.returncode, info),
+        exit_code=proc.returncode,
+        days_to_expire=info.get("days_to_expire"),
+        fingerprint=info.get("fingerprint_sha256"),
+        revocation=info.get("revocation_status"),
+        chain_trusted=info.get("chain_trusted"),
+        hostname_match=info.get("hostname_match"),
+        raw=info,
+    )

certminder/evaluator.py

@@ -0,0 +1,130 @@
+"""Turn a check result plus prior state into a list of alert events.
+
+The evaluator is pure: given the current :class:`CheckResult` and the previous
+:class:`TargetState`, it returns the events to emit *this cycle* and the new
+state to persist. Deduplication lives here: a problem already present in
+``active_alerts`` is not re-notified until it clears, at which point a single
+``RECOVERED`` event is emitted.
+"""
+
+from __future__ import annotations
+
+from certminder.models import CheckResult, Event, EventKind, Severity
+from certminder.state import TargetState
+
+# Map a status string to the event it raises and its severity.
+_STATUS_EVENTS: dict[str, tuple[EventKind, Severity]] = {
+    "EXPIRING": (EventKind.EXPIRING, Severity.WARNING),
+    "CRITICAL": (EventKind.CRITICAL, Severity.CRITICAL),
+    "EXPIRED": (EventKind.EXPIRED, Severity.CRITICAL),
+    "REVOKED": (EventKind.REVOKED, Severity.CRITICAL),
+    "CHAIN_UNTRUSTED": (EventKind.CHAIN_UNTRUSTED, Severity.CRITICAL),
+    "HOSTNAME_MISMATCH": (EventKind.HOSTNAME_MISMATCH, Severity.CRITICAL),
+}
+
+_PROBLEM_STATUSES = set(_STATUS_EVENTS) | {"UNREACHABLE", "ERROR"}
+
+
+def _message(result: CheckResult) -> str:
+    name = result.target.name
+    days = result.days_to_expire
+    if result.status in {"EXPIRING", "CRITICAL"}:
+        return f"{name}: certificate expires in {days} day(s)"
+    if result.status == "EXPIRED":
+        return f"{name}: certificate expired {abs(days) if days is not None else '?'} day(s) ago"
+    if result.status == "REVOKED":
+        return f"{name}: certificate is REVOKED"
+    if result.status == "CHAIN_UNTRUSTED":
+        return f"{name}: certificate chain is not trusted"
+    if result.status == "HOSTNAME_MISMATCH":
+        return f"{name}: certificate does not match the hostname"
+    return f"{name}: {result.status.lower()}"
+
+
+def evaluate(
+    result: CheckResult, previous: TargetState
+) -> tuple[list[Event], TargetState]:
+    """Compare ``result`` against ``previous`` and return (events, new_state)."""
+    events: list[Event] = []
+    name = result.target.name
+    active = set(previous.active_alerts)
+    new_active: set[str] = set()
+
+    # Unreachable / executable errors.
+    if not result.reachable:
+        kind = EventKind.UNREACHABLE
+        key = f"{name}|{kind.value}"
+        new_active.add(key)
+        if key not in active:
+            events.append(
+                Event(
+                    target_name=name,
+                    kind=kind,
+                    severity=Severity.CRITICAL,
+                    message=f"{name}: unreachable ({result.error or 'no detail'})",
+                    details={"error": result.error, "exit_code": result.exit_code},
+                )
+            )
+        # Keep the last known fingerprint; nothing new to compare.
+        return events, TargetState(
+            fingerprint=previous.fingerprint,
+            status=result.status,
+            active_alerts=sorted(new_active),
+        )
+
+    # Fingerprint change: report on every change (after the first sighting),
+    # regardless of validity — an unexpected rotation is itself the signal.
+    if (
+        previous.fingerprint
+        and result.fingerprint
+        and result.fingerprint != previous.fingerprint
+    ):
+        events.append(
+            Event(
+                target_name=name,
+                kind=EventKind.FINGERPRINT_CHANGED,
+                severity=Severity.WARNING,
+                message=f"{name}: certificate fingerprint changed",
+                details={
+                    "old": previous.fingerprint,
+                    "new": result.fingerprint,
+                },
+            )
+        )
+
+    # Validity-derived problems (deduplicated via active_alerts).
+    if result.status in _STATUS_EVENTS:
+        kind, severity = _STATUS_EVENTS[result.status]
+        key = f"{name}|{kind.value}"
+        new_active.add(key)
+        if key not in active:
+            events.append(
+                Event(
+                    target_name=name,
+                    kind=kind,
+                    severity=severity,
+                    message=_message(result),
+                    details={"days_to_expire": result.days_to_expire},
+                )
+            )
+
+    # Recovery: previously had an active problem, now VALID.
+    cleared = active - new_active
+    if result.status == "VALID" and any(
+        not k.endswith(f"|{EventKind.FINGERPRINT_CHANGED.value}") for k in cleared
+    ):
+        events.append(
+            Event(
+                target_name=name,
+                kind=EventKind.RECOVERED,
+                severity=Severity.INFO,
+                message=f"{name}: recovered, certificate is valid again",
+                details={"days_to_expire": result.days_to_expire},
+            )
+        )
+
+    return events, TargetState(
+        fingerprint=result.fingerprint or previous.fingerprint,
+        status=result.status,
+        active_alerts=sorted(new_active),
+    )

certminder/metrics.py

@@ -0,0 +1,87 @@
+"""Render check results as Prometheus textfile-collector metrics.
+
+The output is meant to be pointed at by the node_exporter ``textfile``
+collector (``--collector.textfile.directory``). One ``.prom`` file is rewritten
+atomically at the end of every cycle so a scrape never sees a half-written file.
+"""
+
+from __future__ import annotations
+
+import os
+import tempfile
+import time
+from pathlib import Path
+
+from certminder.models import CheckResult
+
+
+def _escape_label(value: str) -> str:
+    """Escape a Prometheus label value (backslash, quote, newline)."""
+    return value.replace("\\", "\\\\").replace('"', '\\"').replace("\n", "\\n")
+
+
+def _labels(result: CheckResult) -> str:
+    target = result.target
+    parts = {
+        "target": target.name,
+        "host": target.host,
+        "port": str(target.port),
+        "status": result.status,
+    }
+    inner = ",".join(f'{k}="{_escape_label(v)}"' for k, v in parts.items())
+    return "{" + inner + "}"
+
+
+def render(results: list[CheckResult], *, now: float | None = None) -> str:
+    """Build the Prometheus exposition text for ``results``."""
+    timestamp = time.time() if now is None else now
+    lines: list[str] = [
+        "# HELP certminder_certificate_expiry_days Days until the certificate expires.",
+        "# TYPE certminder_certificate_expiry_days gauge",
+    ]
+    for result in results:
+        if result.days_to_expire is not None:
+            lines.append(
+                f"certminder_certificate_expiry_days{_labels(result)} "
+                f"{result.days_to_expire}"
+            )
+
+    lines += [
+        "# HELP certminder_certificate_valid Whether the certificate is currently valid (1) or not (0).",
+        "# TYPE certminder_certificate_valid gauge",
+    ]
+    for result in results:
+        valid = 1 if result.status == "VALID" else 0
+        lines.append(f"certminder_certificate_valid{_labels(result)} {valid}")
+
+    lines += [
+        "# HELP certminder_target_up Whether the target was reachable this cycle (1) or not (0).",
+        "# TYPE certminder_target_up gauge",
+    ]
+    for result in results:
+        up = 1 if result.reachable else 0
+        lines.append(f"certminder_target_up{_labels(result)} {up}")
+
+    lines += [
+        "# HELP certminder_last_run_timestamp_seconds Unix time of the last completed cycle.",
+        "# TYPE certminder_last_run_timestamp_seconds gauge",
+        f"certminder_last_run_timestamp_seconds {timestamp:.0f}",
+    ]
+    return "\n".join(lines) + "\n"
+
+
+def write_prometheus(
+    results: list[CheckResult], path: str | Path, *, now: float | None = None
+) -> None:
+    """Atomically write the Prometheus metrics for ``results`` to ``path``."""
+    path = Path(path).expanduser()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    text = render(results, now=now)
+    fd, tmp = tempfile.mkstemp(dir=path.parent, suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w") as fh:
+            fh.write(text)
+        os.replace(tmp, path)
+    finally:
+        if os.path.exists(tmp):
+            os.unlink(tmp)

certminder/models.py

@@ -0,0 +1,91 @@
+"""Data structures shared across certminder.
+
+These dataclasses are deliberately small and serializable so they can be
+passed to notifiers and written to the state file without ceremony.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class Severity(str, Enum):
+    """Ordered alert severity, low to high."""
+
+    INFO = "info"
+    WARNING = "warning"
+    CRITICAL = "critical"
+
+
+class EventKind(str, Enum):
+    """The kinds of change certminder reports.
+
+    The first group derives from the certificate's own state; ``RECOVERED`` is
+    emitted once when a target returns to ``VALID`` after a prior problem.
+    """
+
+    EXPIRING = "expiring"
+    CRITICAL = "critical"
+    EXPIRED = "expired"
+    REVOKED = "revoked"
+    CHAIN_UNTRUSTED = "chain_untrusted"
+    HOSTNAME_MISMATCH = "hostname_mismatch"
+    FINGERPRINT_CHANGED = "fingerprint_changed"
+    UNREACHABLE = "unreachable"
+    RECOVERED = "recovered"
+
+
+@dataclass(frozen=True)
+class Target:
+    """A single certificate endpoint to watch."""
+
+    host: str
+    port: int = 443
+    verify: bool = True
+    days: int = 30
+    critical_days: int = 15
+    timeout: float = 5.0
+    starttls: str | None = None
+    cafile: str | None = None
+    capath: str | None = None
+    label: str | None = None
+
+    @property
+    def name(self) -> str:
+        """A stable, human-readable identifier used as the state key."""
+        base = f"{self.host}:{self.port}"
+        return f"{base} ({self.label})" if self.label else base
+
+
+@dataclass
+class CheckResult:
+    """The outcome of inspecting one target in a single cycle."""
+
+    target: Target
+    reachable: bool
+    status: str
+    exit_code: int
+    days_to_expire: int | None = None
+    fingerprint: str | None = None
+    revocation: str | None = None
+    chain_trusted: bool | None = None
+    hostname_match: bool | None = None
+    error: str | None = None
+    raw: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class Event:
+    """Something worth telling a human about."""
+
+    target_name: str
+    kind: EventKind
+    severity: Severity
+    message: str
+    details: dict[str, Any] = field(default_factory=dict)
+
+    def key(self) -> str:
+        """Identity used to deduplicate repeated alerts across cycles."""
+        return f"{self.target_name}|{self.kind.value}"

certminder/notifiers/__init__.py

@@ -0,0 +1,35 @@
+"""Notifier registry and base class.
+
+A notifier receives the events produced in a cycle and delivers them somewhere
+(stdout, Slack, a generic webhook). New sinks register themselves in
+:data:`REGISTRY` so the configuration's ``type`` field can resolve them.
+"""
+
+from __future__ import annotations
+
+from certminder.notifiers.base import Notifier
+from certminder.notifiers.console import ConsoleNotifier
+from certminder.notifiers.email import EmailNotifier
+from certminder.notifiers.slack import SlackNotifier
+from certminder.notifiers.webhook import WebhookNotifier
+
+REGISTRY: dict[str, type[Notifier]] = {
+    "console": ConsoleNotifier,
+    "email": EmailNotifier,
+    "slack": SlackNotifier,
+    "webhook": WebhookNotifier,
+}
+
+
+def build_notifier(kind: str, options: dict) -> Notifier:
+    """Instantiate a notifier of ``kind`` with its options."""
+    try:
+        cls = REGISTRY[kind]
+    except KeyError as exc:
+        raise ValueError(
+            f"unknown notifier type {kind!r}; choose from {sorted(REGISTRY)}"
+        ) from exc
+    return cls(**options)
+
+
+__all__ = ["Notifier", "REGISTRY", "build_notifier"]