PKI Compliance Gate (CertGuard Engine)

PKI Compliance Gate (CertGuard Engine) is a Policy-as-Code engine for X.509 certificates, CA/Browser Forum Baseline Requirements, and API TLS posture checks.

One YAML policy profile is the source of truth for evaluation, CI gating, and generated CP/CPS Section 7 documentation.

Quick Start

Option 1: GitHub Action in CI/CD

Use the immutable v0.1.3 release tag (there is no moving v1 tag yet). The GitHub Marketplace listing tracks this Action.

steps:
  - uses: actions/checkout@v4
  - name: Run PKI Compliance Gate
    uses: thulisa-n/pki-compliance-gate@v0.1.3
    with:
      cert: 'tests/certificates/valid_cert.pem'

Option 2: Install from PyPI

python3 -m pip install "pki-compliance-gate==0.1.3"
pki-gate --cert path/to/server.crt

Option 3: Run from a clone

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

# Evaluate a certificate
pki-gate --cert tests/certificates/valid_cert.pem

# Export CP/CPS Section 7 documentation from the policy YAML
pki-gate --mode export-cps-doc --policy policies/cabf_policy.yaml --summary-output CPS_SECTION_7.md

What this repo actually enforces

• Baseline policy (policies/cabf_policy.yaml): max validity 200 days, RSA >= 2048, no SHA-1/MD5, SAN required, blocked internal suffixes (.local, .internal, .intranet).
• Optional crypto-transition overlay (crypto_transition.*, disabled by default): target max validity 47 days and RSA >= 3072 when you opt in.
• API TLS posture (--mode apisec --endpoint example.com): live TLS version, weak-cipher, expiry, and certificate checks.
• Keyless provenance in this repository's CI: on push to main, reports/release_provenance.json is signed with cosign. GitHub native attestations are published only on public repositories.
• Exit codes from evaluation:
  • 0: no failing checks (and lint not failed)
  • 1: only low-severity check failures
  • 2: medium/high failures, lint failure, or CLI usage/input errors
  • 3: at least one critical check failure

How it flows

flowchart LR
    A[PEM Certificate / Domain] --> B[X509 and TLS Parser]
    B --> C[Policy Validator Engine]
    C --> D[Compliance Report]
    C --> E[CP/CPS Docs Exporter]
    C --> F[Audit Evidence]
    D --> G[CI Exit Code 0..3]

Execution modes

Repository structure

src/certguard/          Core agents, CLI, bundled policy, and engine
src/certguard/policy_exporter.py  CP/CPS exporter
src/main.py             Backward-compatible repository entrypoint
policies/               Policy YAML profiles and Rego rules
tests/                  Automated test suite
action.yml              Composite GitHub Action
.github/workflows/      CI workflows

Distribution status

The GitHub Action, wheel, and sdist are published from the v0.1.3 tag. Install the CLI with pip install pki-compliance-gate==0.1.3. Later GitHub releases reuse .github/workflows/publish.yml with PyPI trusted publishing (OIDC, no API token in the repository).

License

Licensed under the MIT License.