certminder 2.2.0__tar.gz → 2.3.0__tar.gz

{certminder-2.2.0/src/certminder.egg-info → certminder-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: certminder
-Version: 2.2.0
+Version: 2.3.0
 Summary: Continuous TLS certificate monitoring and alerting, powered by certinspect.
 Author-email: Michele Angrisano <michele.angrisano@gmail.com>
 License-Expression: MIT
@@ -20,8 +20,9 @@ Classifier: Topic :: Security
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: certinspect>=2.1.1
+Requires-Dist: certinspect>=2.2.0
 Requires-Dist: PyYAML>=6.0.3
+Requires-Dist: python-dotenv>=1.0.0
 Provides-Extra: dev
 Requires-Dist: pytest>=9.1.1; extra == "dev"
 Requires-Dist: ruff>=0.16.5; extra == "dev"
@@ -149,6 +150,55 @@ sorted: `expiry` (default — the soonest-expiring certificates first, already
 expired ones at the very top), `severity` (worst first), or `none` (in the order
 problems were detected).
 
+### Using environment variables in the file
+
+Any string value anywhere in the file — a notifier secret, a target `host`,
+`state_file`, `cafile`, `secrets_file` itself, etc. — can reference an
+environment variable with Docker Compose-style `${VAR}` or `$VAR` syntax.
+`$$` is a literal dollar sign. There is no default-value fallback: a variable
+that isn't set is a hard error, so a missing value fails loudly instead of
+being sent empty or interpolated as a literal `${VAR}` string.
+
+The value is resolved `env > file`: the real environment first, then a `.env`
+file next to the config (parsed with
+[`python-dotenv`](https://pypi.org/project/python-dotenv/), so comments,
+quoting and `export` prefixes all work as expected). Point at a different
+file with a top-level `secrets_file:` (a relative path resolves against the
+config's directory, and is itself resolved against the real environment
+only, since the `.env` file it names doesn't exist yet to resolve it
+against). Because the real environment wins, an `export`-ed shell variable
+overrides the file for a single run.
+
+```yaml
+# certminder.yml
+secrets_file: secrets.env # optional; a .env next to the config is auto-loaded
+targets:
+  - host: ${TARGET_HOST}
+notifiers:
+  - type: slack
+    webhook_url: ${SLACK_WEBHOOK_URL}
+  - type: webhook
+    url: https://example.com/hook
+    headers:
+      Authorization: "Bearer ${WEBHOOK_TOKEN}"
+  - type: email
+    host: smtp.example.com
+    from_addr: alerts@example.com
+    to: [ops@example.com]
+    password: ${SMTP_PASSWORD}
+```
+
+```dotenv
+# .env — keep it out of version control
+TARGET_HOST=internal.example.com
+SLACK_WEBHOOK_URL=https://hooks.slack.com/services/T00/B00/xxxx
+WEBHOOK_TOKEN=abc123
+SMTP_PASSWORD=SuperSecret
+```
+
+Copy [`.env.example`](.env.example) to `.env` and fill in real values as a
+starting point.
+
 ### Grouping targets (shared settings)
 
 Put targets that share settings — say a whole installation behind its own

{certminder-2.2.0 → certminder-2.3.0}/README.md

@@ -120,6 +120,55 @@ sorted: `expiry` (default — the soonest-expiring certificates first, already
 expired ones at the very top), `severity` (worst first), or `none` (in the order
 problems were detected).
 
+### Using environment variables in the file
+
+Any string value anywhere in the file — a notifier secret, a target `host`,
+`state_file`, `cafile`, `secrets_file` itself, etc. — can reference an
+environment variable with Docker Compose-style `${VAR}` or `$VAR` syntax.
+`$$` is a literal dollar sign. There is no default-value fallback: a variable
+that isn't set is a hard error, so a missing value fails loudly instead of
+being sent empty or interpolated as a literal `${VAR}` string.
+
+The value is resolved `env > file`: the real environment first, then a `.env`
+file next to the config (parsed with
+[`python-dotenv`](https://pypi.org/project/python-dotenv/), so comments,
+quoting and `export` prefixes all work as expected). Point at a different
+file with a top-level `secrets_file:` (a relative path resolves against the
+config's directory, and is itself resolved against the real environment
+only, since the `.env` file it names doesn't exist yet to resolve it
+against). Because the real environment wins, an `export`-ed shell variable
+overrides the file for a single run.
+
+```yaml
+# certminder.yml
+secrets_file: secrets.env # optional; a .env next to the config is auto-loaded
+targets:
+  - host: ${TARGET_HOST}
+notifiers:
+  - type: slack
+    webhook_url: ${SLACK_WEBHOOK_URL}
+  - type: webhook
+    url: https://example.com/hook
+    headers:
+      Authorization: "Bearer ${WEBHOOK_TOKEN}"
+  - type: email
+    host: smtp.example.com
+    from_addr: alerts@example.com
+    to: [ops@example.com]
+    password: ${SMTP_PASSWORD}
+```
+
+```dotenv
+# .env — keep it out of version control
+TARGET_HOST=internal.example.com
+SLACK_WEBHOOK_URL=https://hooks.slack.com/services/T00/B00/xxxx
+WEBHOOK_TOKEN=abc123
+SMTP_PASSWORD=SuperSecret
+```
+
+Copy [`.env.example`](.env.example) to `.env` and fill in real values as a
+starting point.
+
 ### Grouping targets (shared settings)
 
 Put targets that share settings — say a whole installation behind its own

{certminder-2.2.0 → certminder-2.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "certminder"
-version = "2.2.0"
+version = "2.3.0"
 description = "Continuous TLS certificate monitoring and alerting, powered by certinspect."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -24,8 +24,9 @@ classifiers = [
     "Topic :: Security",
 ]
 dependencies = [
-    "certinspect>=2.1.1",
+    "certinspect>=2.2.0",
     "PyYAML>=6.0.3",
+    "python-dotenv>=1.0.0",
 ]
 
 [project.optional-dependencies]

{certminder-2.2.0 → certminder-2.3.0}/src/certminder/config.py

@@ -2,12 +2,14 @@
 
 from __future__ import annotations
 
+import os
 import re
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any
 
 import yaml
+from dotenv import dotenv_values
 
 from certminder.models import EventKind, Target
 
@@ -122,6 +124,75 @@ def _build_target(raw: dict[str, Any], defaults: dict[str, Any]) -> Target:
     return Target(**merged)
 
 
+def _load_environment(config_path: Path, secrets_file: str | None) -> dict[str, str]:
+    """Merge a secrets ``.env`` file with the real environment (env wins).
+
+    Parsing is delegated to ``python-dotenv``'s ``dotenv_values``, which reads
+    (without touching the real environment) rather than mutates ``os.environ``,
+    so this stays a pure merge: a variable already set in the real environment
+    overrides the file, so an ``export`` wins for a single run. Without
+    ``secrets_file`` a ``.env`` next to the config is read if present; an
+    explicit ``secrets_file`` (a relative path resolves against the config's
+    directory) must exist.
+    """
+    if secrets_file:
+        env_path = Path(secrets_file).expanduser()
+        if not env_path.is_absolute():
+            env_path = config_path.parent / env_path
+        if not env_path.is_file():
+            raise ConfigError(f"secrets_file not found: {env_path}")
+    else:
+        env_path = config_path.parent / ".env"
+    file_vars = dotenv_values(env_path) if env_path.is_file() else {}
+    for key, value in file_vars.items():
+        if value is None:
+            raise ConfigError(f"{env_path}: {key!r} has no value (expected KEY=VALUE)")
+    return {**file_vars, **os.environ}
+
+
+_VAR_RE = re.compile(
+    r"\$\$|\$\{(?P<braced>[A-Za-z_][A-Za-z0-9_]*)\}|\$(?P<bare>[A-Za-z_][A-Za-z0-9_]*)"
+)
+
+
+def _interpolate(value: str, env: dict[str, str]) -> str:
+    """Substitute Docker Compose-style ``${VAR}``/``$VAR`` in a string.
+
+    ``$$`` is a literal dollar sign. Every referenced variable must be set (in
+    the merged environment: the real environment, then a ``.env`` file) — there
+    is no default-value fallback, so a missing secret fails loudly.
+    """
+
+    def repl(match: re.Match[str]) -> str:
+        if match.group(0) == "$$":
+            return "$"
+        name = match.group("braced") or match.group("bare")
+        if name not in env:
+            raise ConfigError(
+                f"environment variable {name!r} (referenced in {value!r}) is not set"
+            )
+        return env[name]
+
+    return _VAR_RE.sub(repl, value)
+
+
+def _interpolate_value(value: Any, env: dict[str, str]) -> Any:
+    """Recursively substitute ``${VAR}``/``$VAR`` in every string, anywhere.
+
+    Applies to the whole parsed YAML, not just notifier secrets: a target
+    ``host``, a ``cafile`` path, ``state_file``, an ``expect`` entry, etc. can
+    all reference ``${VAR}``. Non-string values (int, bool, None, ...) pass
+    through unchanged.
+    """
+    if isinstance(value, str):
+        return _interpolate(value, env)
+    if isinstance(value, dict):
+        return {k: _interpolate_value(v, env) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_interpolate_value(item, env) for item in value]
+    return value
+
+
 def load_config(path: str | Path) -> Config:
     """Read, parse and validate the configuration at ``path``."""
     path = Path(path).expanduser()
@@ -136,6 +207,17 @@ def load_config(path: str | Path) -> Config:
     if not isinstance(data, dict):
         raise ConfigError("top-level configuration must be a mapping")
 
+    # secrets_file itself is resolved against the real environment only: the
+    # .env file it points at doesn't exist yet to resolve it against.
+    raw_secrets_file = data.get("secrets_file")
+    secrets_file = (
+        _interpolate(raw_secrets_file, os.environ)
+        if isinstance(raw_secrets_file, str)
+        else raw_secrets_file
+    )
+    env = _load_environment(path, secrets_file)
+    data = _interpolate_value(data, env)
+
     raw_targets = data.get("targets") or []
     defaults = data.get("defaults") or {}
     targets = [_build_target(t, defaults) for t in raw_targets]

{certminder-2.2.0 → certminder-2.3.0/src/certminder.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: certminder
-Version: 2.2.0
+Version: 2.3.0
 Summary: Continuous TLS certificate monitoring and alerting, powered by certinspect.
 Author-email: Michele Angrisano <michele.angrisano@gmail.com>
 License-Expression: MIT
@@ -20,8 +20,9 @@ Classifier: Topic :: Security
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: certinspect>=2.1.1
+Requires-Dist: certinspect>=2.2.0
 Requires-Dist: PyYAML>=6.0.3
+Requires-Dist: python-dotenv>=1.0.0
 Provides-Extra: dev
 Requires-Dist: pytest>=9.1.1; extra == "dev"
 Requires-Dist: ruff>=0.16.5; extra == "dev"
@@ -149,6 +150,55 @@ sorted: `expiry` (default — the soonest-expiring certificates first, already
 expired ones at the very top), `severity` (worst first), or `none` (in the order
 problems were detected).
 
+### Using environment variables in the file
+
+Any string value anywhere in the file — a notifier secret, a target `host`,
+`state_file`, `cafile`, `secrets_file` itself, etc. — can reference an
+environment variable with Docker Compose-style `${VAR}` or `$VAR` syntax.
+`$$` is a literal dollar sign. There is no default-value fallback: a variable
+that isn't set is a hard error, so a missing value fails loudly instead of
+being sent empty or interpolated as a literal `${VAR}` string.
+
+The value is resolved `env > file`: the real environment first, then a `.env`
+file next to the config (parsed with
+[`python-dotenv`](https://pypi.org/project/python-dotenv/), so comments,
+quoting and `export` prefixes all work as expected). Point at a different
+file with a top-level `secrets_file:` (a relative path resolves against the
+config's directory, and is itself resolved against the real environment
+only, since the `.env` file it names doesn't exist yet to resolve it
+against). Because the real environment wins, an `export`-ed shell variable
+overrides the file for a single run.
+
+```yaml
+# certminder.yml
+secrets_file: secrets.env # optional; a .env next to the config is auto-loaded
+targets:
+  - host: ${TARGET_HOST}
+notifiers:
+  - type: slack
+    webhook_url: ${SLACK_WEBHOOK_URL}
+  - type: webhook
+    url: https://example.com/hook
+    headers:
+      Authorization: "Bearer ${WEBHOOK_TOKEN}"
+  - type: email
+    host: smtp.example.com
+    from_addr: alerts@example.com
+    to: [ops@example.com]
+    password: ${SMTP_PASSWORD}
+```
+
+```dotenv
+# .env — keep it out of version control
+TARGET_HOST=internal.example.com
+SLACK_WEBHOOK_URL=https://hooks.slack.com/services/T00/B00/xxxx
+WEBHOOK_TOKEN=abc123
+SMTP_PASSWORD=SuperSecret
+```
+
+Copy [`.env.example`](.env.example) to `.env` and fill in real values as a
+starting point.
+
 ### Grouping targets (shared settings)
 
 Put targets that share settings — say a whole installation behind its own

{certminder-2.2.0 → certminder-2.3.0}/src/certminder.egg-info/requires.txt

@@ -1,5 +1,6 @@
-certinspect>=2.1.1
+certinspect>=2.2.0
 PyYAML>=6.0.3
+python-dotenv>=1.0.0
 
 [dev]
 pytest>=9.1.1

{certminder-2.2.0 → certminder-2.3.0}/tests/test_config.py

@@ -336,3 +336,286 @@ def test_network_robustness_keys_accepted(tmp_path):
     assert t.retries == 2
     assert t.connect_timeout == 3
     assert t.read_timeout == 8
+
+
+def test_braced_var_reads_from_environment(tmp_path, monkeypatch):
+    monkeypatch.setenv("SMTP_PASS", "s3cret")
+    cfg = load_config(
+        _write(
+            tmp_path,
+            """
+            notifiers:
+              - type: email
+                password: ${SMTP_PASS}
+            targets:
+              - host: example.com
+            """,
+        )
+    )
+    assert cfg.notifiers[0].options["password"] == "s3cret"
+
+
+def test_bare_var_reads_from_environment(tmp_path, monkeypatch):
+    monkeypatch.setenv("SMTP_PASS", "s3cret")
+    cfg = load_config(
+        _write(
+            tmp_path,
+            """
+            notifiers:
+              - type: email
+                password: $SMTP_PASS
+            targets:
+              - host: example.com
+            """,
+        )
+    )
+    assert cfg.notifiers[0].options["password"] == "s3cret"
+
+
+def test_missing_variable_is_error(tmp_path, monkeypatch):
+    monkeypatch.delenv("NO_SUCH_SECRET", raising=False)
+    path = _write(
+        tmp_path,
+        """
+        notifiers:
+          - type: slack
+            webhook_url: ${NO_SUCH_SECRET}
+        targets:
+          - host: example.com
+        """,
+    )
+    with pytest.raises(ConfigError):
+        load_config(path)
+
+
+def test_var_resolves_inside_nested_headers(tmp_path, monkeypatch):
+    monkeypatch.setenv("WEBHOOK_TOKEN", "abc123")
+    cfg = load_config(
+        _write(
+            tmp_path,
+            """
+            notifiers:
+              - type: webhook
+                url: https://example.com/hook
+                headers:
+                  Authorization: "Bearer ${WEBHOOK_TOKEN}"
+            targets:
+              - host: example.com
+            """,
+        )
+    )
+    headers = cfg.notifiers[0].options["headers"]
+    assert headers["Authorization"] == "Bearer abc123"
+
+
+def test_var_resolves_inside_list_items(tmp_path, monkeypatch):
+    monkeypatch.setenv("OPS_EMAIL", "ops@example.com")
+    cfg = load_config(
+        _write(
+            tmp_path,
+            """
+            notifiers:
+              - type: email
+                host: smtp.example.com
+                from_addr: alerts@example.com
+                to: ["${OPS_EMAIL}"]
+            targets:
+              - host: example.com
+            """,
+        )
+    )
+    assert cfg.notifiers[0].options["to"] == ["ops@example.com"]
+
+
+def test_double_dollar_is_literal_dollar(tmp_path, monkeypatch):
+    cfg = load_config(
+        _write(
+            tmp_path,
+            """
+            notifiers:
+              - type: email
+                password: "pa$$word"
+            targets:
+              - host: example.com
+            """,
+        )
+    )
+    assert cfg.notifiers[0].options["password"] == "pa$word"
+
+
+def test_var_resolves_in_target_fields(tmp_path, monkeypatch):
+    monkeypatch.setenv("TARGET_HOST", "internal.example.com")
+    cfg = load_config(
+        _write(
+            tmp_path,
+            """
+            targets:
+              - host: ${TARGET_HOST}
+                label: prod-${TARGET_HOST}
+            """,
+        )
+    )
+    assert cfg.targets[0].host == "internal.example.com"
+    assert cfg.targets[0].label == "prod-internal.example.com"
+
+
+def test_var_resolves_in_top_level_settings(tmp_path, monkeypatch):
+    monkeypatch.setenv("STATE_DIR", str(tmp_path / "state"))
+    cfg = load_config(
+        _write(
+            tmp_path,
+            """
+            state_file: ${STATE_DIR}/state.json
+            targets:
+              - host: example.com
+            """,
+        )
+    )
+    assert cfg.state_file == (tmp_path / "state" / "state.json")
+
+
+def test_secrets_file_path_resolves_against_real_environment(tmp_path, monkeypatch):
+    monkeypatch.setenv("SECRETS_NAME", "secrets.env")
+    monkeypatch.delenv("SMTP_PASSWORD", raising=False)
+    (tmp_path / "secrets.env").write_text("SMTP_PASSWORD=explicit-secret\n")
+    cfg = load_config(
+        _write(
+            tmp_path,
+            """
+            secrets_file: ${SECRETS_NAME}
+            notifiers:
+              - type: email
+                password: ${SMTP_PASSWORD}
+            targets:
+              - host: example.com
+            """,
+        )
+    )
+    assert cfg.notifiers[0].options["password"] == "explicit-secret"
+
+
+def test_env_file_next_to_config_supplies_variable(tmp_path, monkeypatch):
+    monkeypatch.delenv("SLACK_WEBHOOK_URL", raising=False)
+    (tmp_path / ".env").write_text(
+        "SLACK_WEBHOOK_URL=https://hooks.example/from-file\n"
+    )
+    cfg = load_config(
+        _write(
+            tmp_path,
+            """
+            notifiers:
+              - type: slack
+                webhook_url: ${SLACK_WEBHOOK_URL}
+            targets:
+              - host: example.com
+            """,
+        )
+    )
+    assert cfg.notifiers[0].options["webhook_url"] == "https://hooks.example/from-file"
+
+
+def test_real_environment_overrides_env_file(tmp_path, monkeypatch):
+    (tmp_path / ".env").write_text(
+        "SLACK_WEBHOOK_URL=https://hooks.example/from-file\n"
+    )
+    monkeypatch.setenv("SLACK_WEBHOOK_URL", "https://hooks.example/from-environment")
+    cfg = load_config(
+        _write(
+            tmp_path,
+            """
+            notifiers:
+              - type: slack
+                webhook_url: ${SLACK_WEBHOOK_URL}
+            targets:
+              - host: example.com
+            """,
+        )
+    )
+    assert (
+        cfg.notifiers[0].options["webhook_url"]
+        == "https://hooks.example/from-environment"
+    )
+
+
+def test_env_file_preserves_case_and_strips_quotes(tmp_path, monkeypatch):
+    monkeypatch.delenv("SMTP_PASSWORD", raising=False)
+    (tmp_path / ".env").write_text('SMTP_PASSWORD="pa%word"\n')
+    cfg = load_config(
+        _write(
+            tmp_path,
+            """
+            notifiers:
+              - type: email
+                password: ${SMTP_PASSWORD}
+            targets:
+              - host: example.com
+            """,
+        )
+    )
+    assert cfg.notifiers[0].options["password"] == "pa%word"
+
+
+def test_env_file_skips_blank_lines_and_comments(tmp_path, monkeypatch):
+    monkeypatch.delenv("SMTP_PASSWORD", raising=False)
+    (tmp_path / ".env").write_text("# a comment\n\nSMTP_PASSWORD=s3cret\n")
+    cfg = load_config(
+        _write(
+            tmp_path,
+            """
+            notifiers:
+              - type: email
+                password: ${SMTP_PASSWORD}
+            targets:
+              - host: example.com
+            """,
+        )
+    )
+    assert cfg.notifiers[0].options["password"] == "s3cret"
+
+
+def test_explicit_secrets_file_relative_to_config(tmp_path, monkeypatch):
+    monkeypatch.delenv("SMTP_PASSWORD", raising=False)
+    (tmp_path / "secrets.env").write_text("SMTP_PASSWORD=explicit-secret\n")
+    cfg = load_config(
+        _write(
+            tmp_path,
+            """
+            secrets_file: secrets.env
+            notifiers:
+              - type: email
+                password: ${SMTP_PASSWORD}
+            targets:
+              - host: example.com
+            """,
+        )
+    )
+    assert cfg.notifiers[0].options["password"] == "explicit-secret"
+
+
+def test_missing_explicit_secrets_file_is_error(tmp_path):
+    path = _write(
+        tmp_path,
+        """
+        secrets_file: nope.env
+        targets:
+          - host: example.com
+        """,
+    )
+    with pytest.raises(ConfigError):
+        load_config(path)
+
+
+def test_env_file_without_equals_is_error(tmp_path):
+    (tmp_path / ".env").write_text("oops-no-equals\n")
+    path = _write(
+        tmp_path,
+        """
+        notifiers:
+          - type: email
+            password: ${SMTP_PASSWORD}
+        targets:
+          - host: example.com
+        """,
+    )
+    with pytest.raises(ConfigError):
+        load_config(path)