Cert Expiry Checker

Overview

Cert Expiry Checker checks how many days remain until the SSL/TLS certificates of a list of websites expire. Hosts are listed in a YAML configuration file.

It runs in two modes: CLI mode prints a table for a quick check, and exporter mode exposes the same numbers as Prometheus metrics so certificate expiry can be graphed and alerted on alongside the rest of your monitoring.

Key Features

• CLI mode — Prints a table of hosts, ports, expiration dates and days remaining, followed by any connection errors.
• Prometheus exporter mode — Exposes a certificate_expiration_days gauge per host and port on the port set in the configuration.
• YAML host list — Hosts are configured as host:port entries in a single YAML file.
• Logging — Coloured, simplified console logs and detailed file logs with timestamps, module names and levels.

Installation

Install into a virtual environment from source:

Requirements

• Python 3.8 or newer

git clone https://github.com/qf3l3k/cert_expiry_checker
cd cert_expiry_checker
python -m venv ./venv
source venv/bin/activate
python -m pip install -r requirements.txt
pip install -e .

Configuration

List the hosts to check and, for exporter mode, the port to listen on:

exporter:
  port: 8000
urls:
  - url: github.com:443
  - url: chaintools.tech:443
  - url: explorer.chaintools.tech:443
  - url: testnet.explorer.chaintools.tech:443

Usage

python -m cert_exp_check --mode cli --config config.yaml --log-level verbose

python -m cert_exp_check --mode exporter --config config.yaml --log-level info

# Metrics are served on the configured port, e.g.
# http://localhost:8000

Output Examples

+-----+--------------------------+------+--------------------------+------------+
| No. |         Hostname         | Port |     Expiration date      | Expires in |
+-----+--------------------------+------+--------------------------+------------+
|  1. | github.com               | 443  | Mar 15 23:59:59 2023 GMT |   164 days |
|  2. | nonexistingserver        | 443  |    Unable to connect.    |      NA    |
|  3. | chaintools.tech          | 443  | Dec 4 09:51:51 2022 GMT  |   62 days  |
+-----+--------------------------+------+--------------------------+------------+
===
Errors during check
-
nonexistingserver: Connection error

# HELP certificate_expiration_days Days until SSL certificate expires
# TYPE certificate_expiration_days gauge
certificate_expiration_days{hostname="github.com",port="443"} 164
certificate_expiration_days{hostname="chaintools.tech",port="443"} 62
certificate_expiration_days{hostname="explorer.chaintools.tech",port="443"} 99

Related Resources

• Prometheus documentation — Scraping and alerting on the exporter metrics
• Let's Encrypt — Free, automated certificate authority
• SSL Labs server test — In-depth TLS configuration testing