certminder 0.2.0__tar.gz

certminder-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michele Angrisano
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

certminder-0.2.0/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: certminder
+Version: 0.2.0
+Summary: Continuous TLS certificate monitoring and alerting, powered by certinspect.
+Author-email: Michele Angrisano <michele.angrisano@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/mangrisano/certminder
+Project-URL: Repository, https://github.com/mangrisano/certminder
+Project-URL: Issues, https://github.com/mangrisano/certminder/issues
+Keywords: tls,ssl,x509,certificate,monitoring,alerting,pki
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: certinspect>=1.0.0
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Dynamic: license-file
+
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/mangrisano/certminder/main/docs/logo.svg" alt="certminder" width="440">
+
+[![CI](https://github.com/mangrisano/certminder/actions/workflows/ci.yml/badge.svg)](https://github.com/mangrisano/certminder/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/certminder.svg)](https://pypi.org/project/certminder/)
+[![Python](https://img.shields.io/pypi/pyversions/certminder.svg)](https://pypi.org/project/certminder/)
+[![License: MIT](https://img.shields.io/pypi/l/certminder.svg)](LICENSE)
+
+**Scheduled checks · Expiry & revocation alerts · Fingerprint change detection · Deduplicated notifications · Console / email / Slack / webhook · Prometheus metrics**
+
+[PyPI](https://pypi.org/project/certminder/) · [Quick start](#quick-start) · [Configure](#configure) · [Alerts](#what-it-alerts-on) · [Prometheus](#prometheus-metrics) · [Deployment](#deployment) · [Issues](https://github.com/mangrisano/certminder/issues)
+
+</div>
+
+**Continuous TLS certificate monitoring and alerting** — the watch loop on top
+of [certinspect](https://github.com/mangrisano/certinspect).
+
+`certinspect` tells you what a certificate looks like _right now_.
+`certminder` runs it on a schedule, remembers what it saw last time, and
+**alerts you when a certificate is about to expire, gets revoked, changes
+fingerprint, or becomes unreachable**.
+
+## Why a separate tool
+
+certminder never re-implements TLS or X.509 logic — that all lives in
+certinspect. certminder adds only what a monitor needs:
+
+- a **schedule** (run once for cron, or loop as a daemon),
+- **state memory** to detect _changes_ between runs,
+- **deduplicated alerts** (notify once per condition, recover once),
+- pluggable **notifiers** (console, email, Slack, generic webhook),
+- optional **Prometheus** metrics for the node_exporter textfile collector.
+
+## Install
+
+```bash
+pip install certminder       # pulls in certinspect automatically
+# or from source:
+pip install -e '.[dev]'
+```
+
+## Quick start
+
+```bash
+# inspect a single host ad hoc
+certminder check example.com
+
+# copy and edit the sample config, then:
+certminder once -c certminder.yml     # one cycle — ideal for cron
+certminder run  -c certminder.yml     # run continuously as a daemon
+```
+
+## Configure
+
+Everything is driven by a YAML file (see
+[`certminder.example.yml`](certminder.example.yml)):
+
+```yaml
+interval: 6h
+state_file: ~/.certminder/state.json
+defaults:
+  verify: true
+  days: 30
+  critical_days: 15
+notifiers:
+  - type: console
+  - type: slack
+    webhook_url: "https://hooks.slack.com/services/XXX/YYY/ZZZ"
+  - type: email
+    host: smtp.example.com
+    port: 587
+    username: alerts@example.com
+    password: CHANGE_ME
+    from_addr: alerts@example.com
+    to: [ops@example.com]
+targets:
+  - host: example.com
+  - host: api.example.com
+    port: 8443
+  - host: mail.example.com
+    starttls: smtp
+```
+
+## What it alerts on
+
+| Event                  | Severity | Trigger                                    |
+| ---------------------- | -------- | ------------------------------------------ |
+| `EXPIRING`             | warning  | within `--days` of expiry                  |
+| `CRITICAL` / `EXPIRED` | critical | within `critical_days`, or already expired |
+| `REVOKED`              | critical | OCSP/CRL says revoked (needs `verify`)     |
+| `CHAIN_UNTRUSTED`      | critical | chain fails to validate                    |
+| `HOSTNAME_MISMATCH`    | critical | cert does not match the hostname           |
+| `FINGERPRINT_CHANGED`  | warning  | fingerprint differs from last cycle        |
+| `UNREACHABLE`          | critical | host/handshake failed                      |
+| `RECOVERED`            | info     | a prior problem cleared                    |
+
+Each condition alerts **once**; certminder remembers it and stays quiet until it
+changes, then sends a single recovery notice.
+
+## Exit codes (`once`)
+
+- `0` — no events this cycle
+- `1` — at least one event was emitted
+- `2` — configuration error
+
+Add `--json` to `once` to print a machine-readable summary of the cycle (one
+entry per target plus the events) to stdout, handy for piping:
+
+```bash
+certminder once -c certminder.yml --json | jq '.targets[] | {target, status, days_to_expire}'
+```
+
+## Prometheus metrics
+
+Set `prometheus_file` in the config to a path inside the node_exporter
+[textfile collector](https://github.com/prometheus/node_exporter#textfile-collector)
+directory. certminder rewrites it atomically at the end of every cycle:
+
+```
+certminder_certificate_expiry_days{target="example.com:443",host="example.com",port="443",status="VALID"} 42
+certminder_certificate_valid{...} 1
+certminder_target_up{...} 1
+certminder_last_run_timestamp_seconds 1700000000
+```
+
+## Deployment
+
+Ready-to-use units live in [`deploy/`](deploy/) plus a [`Dockerfile`](Dockerfile):
+
+- **systemd timer** — [`certminder.service`](deploy/systemd/certminder.service) +
+  [`certminder.timer`](deploy/systemd/certminder.timer) run one cycle on a
+  schedule (cron-style, recommended).
+- **systemd daemon** — [`certminder-daemon.service`](deploy/systemd/certminder-daemon.service)
+  runs the `run` loop under supervision.
+- **cron** — [`certminder.cron`](deploy/cron/certminder.cron) for hosts without
+  systemd timers.
+- **Docker** — multi-stage build; mount your `certminder.yml` at
+  `/etc/certminder/certminder.yml` and a volume at `/var/lib/certminder`.
+
+## Development
+
+```bash
+ruff check . && ruff format --check .
+pytest -q
+```
+
+Tests mock the certinspect subprocess, so the suite never touches the network.
+
+## License
+
+MIT © Michele Angrisano

certminder-0.2.0/README.md

@@ -0,0 +1,152 @@
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/mangrisano/certminder/main/docs/logo.svg" alt="certminder" width="440">
+
+[![CI](https://github.com/mangrisano/certminder/actions/workflows/ci.yml/badge.svg)](https://github.com/mangrisano/certminder/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/certminder.svg)](https://pypi.org/project/certminder/)
+[![Python](https://img.shields.io/pypi/pyversions/certminder.svg)](https://pypi.org/project/certminder/)
+[![License: MIT](https://img.shields.io/pypi/l/certminder.svg)](LICENSE)
+
+**Scheduled checks · Expiry & revocation alerts · Fingerprint change detection · Deduplicated notifications · Console / email / Slack / webhook · Prometheus metrics**
+
+[PyPI](https://pypi.org/project/certminder/) · [Quick start](#quick-start) · [Configure](#configure) · [Alerts](#what-it-alerts-on) · [Prometheus](#prometheus-metrics) · [Deployment](#deployment) · [Issues](https://github.com/mangrisano/certminder/issues)
+
+</div>
+
+**Continuous TLS certificate monitoring and alerting** — the watch loop on top
+of [certinspect](https://github.com/mangrisano/certinspect).
+
+`certinspect` tells you what a certificate looks like _right now_.
+`certminder` runs it on a schedule, remembers what it saw last time, and
+**alerts you when a certificate is about to expire, gets revoked, changes
+fingerprint, or becomes unreachable**.
+
+## Why a separate tool
+
+certminder never re-implements TLS or X.509 logic — that all lives in
+certinspect. certminder adds only what a monitor needs:
+
+- a **schedule** (run once for cron, or loop as a daemon),
+- **state memory** to detect _changes_ between runs,
+- **deduplicated alerts** (notify once per condition, recover once),
+- pluggable **notifiers** (console, email, Slack, generic webhook),
+- optional **Prometheus** metrics for the node_exporter textfile collector.
+
+## Install
+
+```bash
+pip install certminder       # pulls in certinspect automatically
+# or from source:
+pip install -e '.[dev]'
+```
+
+## Quick start
+
+```bash
+# inspect a single host ad hoc
+certminder check example.com
+
+# copy and edit the sample config, then:
+certminder once -c certminder.yml     # one cycle — ideal for cron
+certminder run  -c certminder.yml     # run continuously as a daemon
+```
+
+## Configure
+
+Everything is driven by a YAML file (see
+[`certminder.example.yml`](certminder.example.yml)):
+
+```yaml
+interval: 6h
+state_file: ~/.certminder/state.json
+defaults:
+  verify: true
+  days: 30
+  critical_days: 15
+notifiers:
+  - type: console
+  - type: slack
+    webhook_url: "https://hooks.slack.com/services/XXX/YYY/ZZZ"
+  - type: email
+    host: smtp.example.com
+    port: 587
+    username: alerts@example.com
+    password: CHANGE_ME
+    from_addr: alerts@example.com
+    to: [ops@example.com]
+targets:
+  - host: example.com
+  - host: api.example.com
+    port: 8443
+  - host: mail.example.com
+    starttls: smtp
+```
+
+## What it alerts on
+
+| Event                  | Severity | Trigger                                    |
+| ---------------------- | -------- | ------------------------------------------ |
+| `EXPIRING`             | warning  | within `--days` of expiry                  |
+| `CRITICAL` / `EXPIRED` | critical | within `critical_days`, or already expired |
+| `REVOKED`              | critical | OCSP/CRL says revoked (needs `verify`)     |
+| `CHAIN_UNTRUSTED`      | critical | chain fails to validate                    |
+| `HOSTNAME_MISMATCH`    | critical | cert does not match the hostname           |
+| `FINGERPRINT_CHANGED`  | warning  | fingerprint differs from last cycle        |
+| `UNREACHABLE`          | critical | host/handshake failed                      |
+| `RECOVERED`            | info     | a prior problem cleared                    |
+
+Each condition alerts **once**; certminder remembers it and stays quiet until it
+changes, then sends a single recovery notice.
+
+## Exit codes (`once`)
+
+- `0` — no events this cycle
+- `1` — at least one event was emitted
+- `2` — configuration error
+
+Add `--json` to `once` to print a machine-readable summary of the cycle (one
+entry per target plus the events) to stdout, handy for piping:
+
+```bash
+certminder once -c certminder.yml --json | jq '.targets[] | {target, status, days_to_expire}'
+```
+
+## Prometheus metrics
+
+Set `prometheus_file` in the config to a path inside the node_exporter
+[textfile collector](https://github.com/prometheus/node_exporter#textfile-collector)
+directory. certminder rewrites it atomically at the end of every cycle:
+
+```
+certminder_certificate_expiry_days{target="example.com:443",host="example.com",port="443",status="VALID"} 42
+certminder_certificate_valid{...} 1
+certminder_target_up{...} 1
+certminder_last_run_timestamp_seconds 1700000000
+```
+
+## Deployment
+
+Ready-to-use units live in [`deploy/`](deploy/) plus a [`Dockerfile`](Dockerfile):
+
+- **systemd timer** — [`certminder.service`](deploy/systemd/certminder.service) +
+  [`certminder.timer`](deploy/systemd/certminder.timer) run one cycle on a
+  schedule (cron-style, recommended).
+- **systemd daemon** — [`certminder-daemon.service`](deploy/systemd/certminder-daemon.service)
+  runs the `run` loop under supervision.
+- **cron** — [`certminder.cron`](deploy/cron/certminder.cron) for hosts without
+  systemd timers.
+- **Docker** — multi-stage build; mount your `certminder.yml` at
+  `/etc/certminder/certminder.yml` and a volume at `/var/lib/certminder`.
+
+## Development
+
+```bash
+ruff check . && ruff format --check .
+pytest -q
+```
+
+Tests mock the certinspect subprocess, so the suite never touches the network.
+
+## License
+
+MIT © Michele Angrisano

certminder-0.2.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools>=77.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "certminder"
+version = "0.2.0"
+description = "Continuous TLS certificate monitoring and alerting, powered by certinspect."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Michele Angrisano", email = "michele.angrisano@gmail.com" }]
+keywords = ["tls", "ssl", "x509", "certificate", "monitoring", "alerting", "pki"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: System Administrators",
+    "Programming Language :: Python :: 3",
+    "Topic :: System :: Monitoring",
+    "Topic :: Security",
+]
+dependencies = [
+    "certinspect>=1.0.0",
+    "PyYAML>=6.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "ruff>=0.5"]
+
+[project.urls]
+Homepage = "https://github.com/mangrisano/certminder"
+Repository = "https://github.com/mangrisano/certminder"
+Issues = "https://github.com/mangrisano/certminder/issues"
+
+[project.scripts]
+certminder = "certminder.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 88
+src = ["src", "tests"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

certminder-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

certminder-0.2.0/src/certminder/__init__.py

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

certminder-0.2.0/src/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-0.2.0/src/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
+        ),
+    )