certminder.example.yml

# How certinspect is invoked, and the meaning of its exit codes, is the
# contract certminder depends on. Keep this file as the single source of truth
# for operators: edit targets and notifiers here, not in code.

# Path or name of the certinspect executable (must be on PATH or absolute).
certinspect_bin: certinspect

# How often the watch loop runs. Accepts s/m/h/d suffixes (e.g. 30m, 6h, 1d).
interval: 6h

# Where the per-target state (last fingerprint, last status, sent alerts) is
# persisted between runs. '~' is expanded.
state_file: ~/.certminder/state.json

# How many targets to inspect in parallel each cycle.
concurrency: 8

# Optional: write Prometheus metrics for the node_exporter textfile collector.
# Point this at a file inside --collector.textfile.directory. Rewritten
# atomically at the end of every cycle. Omit to disable.
prometheus_file: /var/lib/node_exporter/textfile/certminder.prom

# On (re)start, report every currently-active problem once before switching to
# change-only alerts, so a restart surfaces the current picture instead of
# staying silent until the next change. Set to false to keep quiet until
# something changes.
startup_report: true

# Re-notify a still-active problem after this long since its last alert, so a
# persistent fault (e.g. an expired cert nobody fixed) doesn't stay silent
# forever. Omit to notify once per problem (default: off).
# renotify_after: 24h

# Print a one-line summary after each cycle (targets / ok / with problems) so a
# quiet daemon is visibly alive. Default: true.
heartbeat: true

# Flap dampening: a problem must be seen this many consecutive cycles before it
# alerts (and an unreachable host must stay down that long), so a one-cycle blip
# is ignored. Default: 1 (alert immediately).
# failure_threshold: 2

# Applied to every target unless the target overrides them.
defaults:
  port: 443
  verify: true        # chain + OCSP/CRL revocation; false runs certinspect --no-verify
  days: 30            # EXPIRING window (certinspect --days)
  critical_days: 15   # CRITICAL window (certinspect --critical-days)
  timeout: 5
  retries: 2          # retry transient connection failures (avoids false UNREACHABLE)
  # connect_timeout / read_timeout: split the single timeout if a server has a
  # slow handshake (both default to `timeout`). Needs certinspect >= 1.11.
  # Optional maximum-validity policy (certinspect exit code 9 ->
  # POLICY_VIOLATION). Use ONE of the two:
  #   cab_forum: true      # date-aware CA/Browser Forum cap (398->200->100->47)
  #   not_after_max: 47    # or pin an explicit limit in days
  # Other opt-in policy checks (also exit code 9 -> POLICY_VIOLATION):
  #   require_sct: true            # require embedded Certificate Transparency SCTs
  #   require_must_staple: true    # require the OCSP Must-Staple extension
  #   require_revocation_check: true # require OCSP/CRL to return GOOD
  #   min_tls_version: TLSv1.2     # fail below this negotiated TLS version
  # Or apply a whole bundle at once with a named profile (an intensity ladder,
  # not a compliance standard); explicit checks above still override it:
  #   profile: standard            # one of: lenient, standard, strict

# Alert sinks. Every notifier receives every event in a cycle.
#
# Keep secrets out of this file: any string value anywhere in this config can
# reference an environment variable with ${VAR} or $VAR (Docker Compose
# syntax; $$ is a literal $). The value is resolved env > file: the real
# environment first, then a .env file (KEY=VALUE lines) — a .env next to this
# config is read automatically, or set a top-level `secrets_file:` to point
# at another.
notifiers:
  - type: console
    # timestamp: true   # prefix each line with the local date and time
  - type: slack
    webhook_url: ${SLACK_WEBHOOK_URL}   # read from the environment or .env
    # min_severity: critical   # this sink only gets events at/above this level
    # kinds: [expired]         # this sink only gets these event types
    #   (expiring, critical, expired, not_yet_valid, revoked, chain_untrusted,
    #    hostname_mismatch, policy_violation, weak_crypto, chain_expiring,
    #    fingerprint_changed, unreachable, recovered)
  - type: webhook
    url: "https://example.com/certminder-hook"
    # optional extra headers, e.g. an auth token from the environment
    headers:
      Authorization: "Bearer ${WEBHOOK_TOKEN}"
  - type: email
    host: smtp.example.com
    port: 587            # 587 STARTTLS (use_tls) or 465 implicit TLS (use_ssl)
    use_tls: true
    username: alerts@example.com
    password: ${SMTP_PASSWORD}   # value comes from the environment or .env
    from_addr: alerts@example.com
    to:
      - ops@example.com
    # order: expiry      # body order: expiry (soonest-expiring first, default),
    #                    #   severity (worst first), or none (as detected)

# The certificates to watch.
targets:
  - host: example.com

  - host: api.example.com
    port: 8443
    label: "Public API"

  - host: mail.example.com
    starttls: smtp        # one of: smtp, imap, pop3, ftp
    days: 45

  - host: short-lived.example.com
    cab_forum: true       # fail if validity exceeds today's CA/B Forum maximum

  - host: internal.corp.example
    verify: true
    # certinspect supports --cafile/--capath for private PKIs; pass them here
    cafile: /etc/ssl/internal-ca.pem

  - host: hardened.example.com
    require_sct: true           # must carry Certificate Transparency SCTs
    require_must_staple: true   # must carry the OCSP Must-Staple extension
    require_revocation_check: true # OCSP/CRL must prove it is GOOD
    min_tls_version: TLSv1.2    # must negotiate at least TLS 1.2

  - host: strict.example.com
    profile: strict             # one-flag hardening bundle (lenient/standard/strict)

  - host: internal-lab.example.com
    verify: true
    # Known/accepted problems for this target: don't alert on them, but still
    # alert on anything else. Kinds: expiring, critical, expired, not_yet_valid,
    # revoked, chain_untrusted, hostname_mismatch, policy_violation, weak_crypto,
    # chain_expiring, unreachable.
    expect: [chain_untrusted]   # internal/private CA, expected

  # 'file:' watches a local certificate (PEM/DER) instead of a live host, e.g.
  # one rotated onto disk before deployment. port/starttls/min_tls_version/
  # require_revocation_check don't apply and are rejected here.
  - file: /etc/ssl/certs/vendored-leaf.pem
    label: "Vendored leaf"

# Groups apply shared settings to a set of targets, so a whole installation on
# its own internal CA is configured once instead of per host. Precedence:
# defaults < group < per-target. Top-level 'targets:' and 'groups:' can coexist.
groups:
  - name: "Site A (internal CA)"
    cafile: /etc/certminder/site-a-ca.pem
    targets:
      - host: iap.site-a.lan
      - host: trustapp.site-a.lan
      - host: webauth.site-a.lan
        cafile: /etc/certminder/other-ca.pem   # per-target override wins

# Expand a domain into every hostname Certificate Transparency logs have a
# certificate for (certinspect --discover-only), so a forgotten subdomain
# doesn't go unmonitored. Re-queried every cycle; any target setting applies
# to every host discovered under that domain. Can be used with or without a
# static 'targets:'/'groups:' list.
discover:
  - domain: example.com
    discover_timeout: 30   # seconds for the crt.sh query (default: 30)
    verify: true
  - domain: internal.example.lan
    cafile: /etc/certminder/internal-ca.pem