An expired TLS certificate is one of the most embarrassing — and preventable — outages in software engineering. It doesn't announce itself in advance. It just silently breaks your HTTPS handshake at 2 AM, taking down your API, your dashboard, or your customer portal with it. pkiwatch-py is the Python library and CLI I built to make sure that never happens on your watch.

What pkiwatch-py Does

pkiwatch-py gives engineers a fast, scriptable way to inspect TLS certificates across enterprise endpoints — tracking expiry dates, issuer chains, and compliance posture without requiring a full-blown monitoring platform. It's designed to fit naturally into CI/CD pipelines, cron jobs, Cloud Scheduler triggers, and operational runbooks.

At its core it does three things well:

• Certificate expiry monitoring with configurable warning thresholds
• Certificate inventory across large batches of endpoints
• Basic compliance reporting in structured JSON for downstream consumption

Getting Started

Installation is a single pip command:

pip install pkiwatch-py

Quick Scan via CLI

The fastest way to check a certificate:

pkiwatch scan google.com

For structured output you can pipe into other tools or ingest into BigQuery:

pkiwatch scan google.com --output json

Batch Scanning an Endpoint Inventory
In enterprise environments, you're rarely monitoring just one domain. pkiwatch-py handles bulk scanning natively:

printf "google.com\nexample.com:443\n" > targets.txt
pkiwatch batch targets.txt --output-file cert-report.json

The --output-file flag writes a complete JSON report you can archive, diff across runs, or load directly into a BigQuery table for trend analysis. This is particularly useful for compliance teams who need a timestamped record of certificate health across all production endpoints.

Python API

For programmatic use inside pipelines, monitoring agents, or agentic AI workflows, the Python API gives you full access to certificate metadata:

from pkiwatch import scan_tls_certificate

report = scan_tls_certificate("google.com", warning_days=45)
print(report.days_remaining)   # e.g., 62
print(report.issuer)           # e.g., "GTS CA 1C3"

The warning_days parameter sets your alert threshold — anything under 45 days remaining will be flagged in the report object, letting you build conditional logic for alerting, ticket creation, or automated renewal triggers.

The report object is designed to be serializable, so you can log it directly to Datastore for operational state tracking, or stream it to BigQuery as a structured analytics event.

cEnterprise Integration Patterns

Cloud Scheduler + Cloud Run — Schedule a daily pkiwatch batch run via Cloud Scheduler against a Cloud Run service. Write the JSON output to BigQuery for historical tracking and alert on certificates crossing your warning threshold.

• CI/CD Pipeline Gate — Add a pkiwatch scan step to your deployment pipeline as a pre-flight check. Fail the deployment if any certificate in scope has fewer than 30 days remaining — catching renewals before they become incidents.
• Compliance Reporting — Export batch scan results as JSON and load them into BigQuery. Build a Looker or Data Studio dashboard showing certificate health across your entire domain inventory, filterable by issuer, expiry window, and environment.
• Agentic AI Integration — Feed scan_tls_certificate output into an AgentDecisionInput (as used in GCP AgentFlow) to let your AI orchestration layer automatically route certificates approaching expiry into a renewal workflow.
• SIEM and Security Tooling — The structured JSON output integrates cleanly with log aggregation and SIEM platforms. You get issuer, expiry, subject, and SAN data in a consistent schema that security teams can query without writing custom parsers.

Compliance Use Cases

pkiwatch-py is built with enterprise compliance workflows in mind:

• GDPR — Document that all data-in-transit endpoints maintain valid, unexpired TLS certificates as part of your security controls evidence
• FISMA / FedRAMP — Generate timestamped certificate inventory reports for continuous monitoring documentation requirements
• SOC 2 / ISO 27001 — Demonstrate automated certificate lifecycle monitoring as a compensating control against certificate mismanagement risk
• Internal PKI Audits — Track issuer chains across your endpoint inventory to detect certificates issued by unexpected or legacy CAs

The JSON report format is audit-friendly by design — each record carries the endpoint, scan timestamp, issuer, subject, expiry date, days remaining, and warning flag.

Development Workflow
Setting up a local development environment:

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Running tests and linting:

pytest
ruff check src tests

pkiwatch-py uses Ruff for linting, which is fast, zero-config, and enforces consistent code style across the codebase. All tests are pytest-based and designed to run without network access for CI reliability — certificate scan tests use fixtures rather than live connections.

Building and Publishing to PyPI

python -m build
python -m twine check dist/*
python -m twine upload dist/*

Use token as the username and your PyPI API token as the password. The twine check step validates your distribution metadata before upload, catching packaging issues before they reach users.

Design Philosophy

pkiwatch-py follows the Unix principle: do one thing well and compose cleanly with everything else. It doesn't try to be a full certificate lifecycle management platform — it's a sharp, scriptable tool for the monitoring and reporting layer.

The MIT license means you can integrate it freely into commercial products, internal tooling, academic research, or open-source projects without restriction. It's built to be the certificate monitoring primitive that larger systems — whether a GCP event-driven pipeline, a compliance automation platform, or an agentic AI workflow — can depend on.

Author:

Raghava Chellu | FBCS | Innovation Technologist, Data Infrastructure
MIT License — freely usable for academic, personal, and commercial projects.