ssl-cert-verifier

ssl-cert-verifier - Verify SSL certificates for expiration.

ssl-cert-verifier checks SSL certificates on one or more hosts and reports their expiration status. It can alert when certificates are nearing expiration or have already expired.

This utility is intended to be run nightly via cron, to monitor SSL certificates and alert before they expire.

The default expiration time interval is 28 days. This was based on the 30-day renewal interval for Let's Encrypt certificates.

Examples

Example use:

$ ssl-cert-verifier host1.example.com host2.example.com:8443 host3.example.com
host1.example.com is valid (expires in 315 days)
host2.example.com:8443 is valid (expires in 279 days)
Warning! host3.example.com will expire in 22 days

The --silent option only displays errors and warnings:

$ ssl-cert-verifier --silent host1.example.com host2.example.com:8443 host3.example.com
Warning! host3.example.com will expire in 22 days

JSON output, with long lines broken for readability:

$ ssl-cert-verifier --json host1.example.com host2.example.com:8443 host3.example.com
{"host": "host1.example.com", "port": 443,
    "cert": {"common_name": "host1.example.com", "expires_date": "2026-08-25T23:59:59+00:00", "expires_days": 315},
    "status": {"status": "OK", "message": "Certificate valid"}}
{"host": "host2.example.com", "port": 8443, "cert":
    {"common_name": "host2.example.com", "expires_date": "2026-07-20T16:59:00+00:00", "expires_days": 279},
    "status": {"status": "OK", "message": "Certificate valid"}}
{"host": "host3.example.com", "port": 443,
    "cert": {"common_name": "host3.example.com", "expires_date": "2025-11-05T23:59:59+00:00", "expires_days": 22},
    "status": {"status": "ALERT", "message": "Certificate is nearing expiration (22 days remaining)"}}

Usage

ssl-cert-verifier [OPTIONS] [HOST[:PORT] ...]

OPTIONS

• --file FILE or -f FILE -- File containing list of hosts (one per line, # for comments)
• --days DAYS or -d DAYS -- Number of days before expiration to warn about (default: 28)
• --silent or -s -- Only output information for certificates within the expiration time interval
• --json or -j -- Output in JSON format (default is text format)
• --insecure or -I -- Ignore certificate name mismatch errors
• --version or -v -- Display version number and exit
• HOST[:PORT] -- One or more hosts to check (port defaults to 443)

Hosts File Format

When using the --file option, create a text file with one host per line. Format of each line is:

HOST[:PORT]

Comments (lines starting with #) and blank lines are ignored.

Example hosts.txt:

# Production servers
example.com
api.example.com:8443

# Staging environment
staging.example.com

Requirements

• Python 3.x
• No external dependencies (uses only standard library)

Testing

The project includes a comprehensive test suite using pytest.

Running Tests

pip install pytest
pytest test_ssl_cert_verifier.py -v

Test Coverage

• Unit tests (29 tests) - Test individual functions and classes

  • Argument parsing
  • Host:port parsing
  • Text and JSON output formatting
  • File reading with comments and blank lines
  • Certificate info extraction
  • Status result handling

• System tests (2 tests) - Test against real SSL endpoints

  • Valid certificate verification
  • Threshold boundary conditions

System Test Configuration

System tests connect to real SSL endpoints and can be configured via environment variables:

• SSL_TEST_SITE - Hostname to test (default: badssl.com)
• SSL_TEST_PORT - Port to test (default: 443)
• SKIP_SYSTEM_TESTS=1 - Skip system tests entirely

Author

Courtney Rosenthal <cr@crosenthal.com>

License

This is free and unencumbered software released into the public domain.

See LICENSE for details.