Architecting PyPI PGP Signature Verification in CI Pipelines

Problem & Takeaway

In continuous‑integration (CI) pipelines, installing third‑party Python packages from PyPI is routine, yet the integrity of those packages can’t be assumed. PyPI allows maintainers to attach PGP signatures (.asc files) to source distributions, but the platform does not enforce them. The core takeaway is: verify the signature before installing, and only trust packages signed by a key you explicitly import into the build environment.

Requirements

• Verify that a downloaded source distribution matches its .asc signature.
• Abort the pipeline if verification fails.
• Maintain a minimal set of trusted GPG keys, with clear rotation and revocation handling.
• Provide audit‑ready logs of verification status.
• Gracefully handle packages that are not signed.

Smallest Suitable Design

The architecture consists of three linear steps executed in the CI job:

1. Fetch the tarball and its accompanying .asc file from PyPI.
2. Verify the tarball against the .asc using a pre‑imported GPG key.
3. Only if the verification succeeds, run pip install against the tarball.

This design keeps the pipeline lightweight and avoids the need for additional tooling unless the project’s policy requires it.

Trust / Data Boundaries

The CI environment must contain only the GPG keys that the organization trusts. Importing a key is a one‑time operation that should be performed with the key’s fingerprint checked against a known value.

# Import a single maintainer key (run once, e.g., in a CI setup step)
# Replace {KEY_FINGERPRINT} with the 40‑character fingerprint.
cat <(curl -s https://keyserver.ubuntu.com/pks/lookup?op=get&search=0x{KEY_FINGERPRINT}) | gpg --import

# Verify import
gpg --fingerprint {KEY_FINGERPRINT}

Only the keys listed in trusted_keys.txt should be considered trustworthy. If a maintainer rotates keys, the CI must be updated to import the new key and optionally retire the old one.

Operational Checks

• Logging: Emit a structured log entry after verification, e.g., PGP verification succeeded for cryptography==3.4.8 (key 0xABCD1234).
• Failure Policy: The script should exit with a non‑zero status if the signature is missing or mismatched.
• Fallback Policy: If the policy allows, provide a flag (e.g., --allow-unverified) that permits installation without verification, but only after manual approval.
• Retry Logic: For network errors when fetching the .asc, retry up to three times with exponential back‑off.

Failure Modes & Mitigations

Failure Mode	Detection	Mitigation
Missing .asc file	HTTP 404 or empty file	Abort; optionally flag package as unverified if policy allows
Key mismatch or revocation	GPG exit code 255 or fingerprint mismatch	Abort; alert security team; rotate keys
Network partition during fetch	cURL or wget non‑zero exit	Retry; if still failing, abort
PyPI changes signing format	GPG verification fails with unknown format error	Update verification logic; notify maintainers

When the Design Should Change

• When the project needs to install many signed packages, consider a keyserver proxy to cache signatures and reduce external calls.
• If the organization adopts pip’s experimental PGP support, the verification step can be delegated to pip by passing --require-hashes and ensuring the package’s METADATA includes the signature.
• If key rotation becomes frequent, automate key import and revocation checks using a CI secret store.

Concrete Example: Bash Script for a CI Job

#!/usr/bin/env bash
set -euo pipefail

PACKAGE="cryptography==3.4.8"
TARBALL="${PACKAGE//==/}.tar.gz"
SIGNATURE="${TARBALL}.asc"
PYPI_URL="https://files.pythonhosted.org/packages/.../${TARBALL}"  # placeholder
SIGN_URL="https://files.pythonhosted.org/packages/.../${SIGNATURE}"  # placeholder

# 1. Fetch tarball and signature
curl -sSL -o "$TARBALL" "$PYPI_URL"
curl -sSL -o "$SIGNATURE" "$SIGN_URL"

# 2. Verify signature against the trusted key
if ! gpg --verify "$SIGNATURE" "$TARBALL" 2>&1 | tee "verify.log"; then
    echo "PGP verification failed for $PACKAGE" >&2
    exit 1
fi

# 3. Install only if verification succeeded
pip install "$TARBALL"

Replace the PYPI_URL and SIGN_URL placeholders with the actual URLs, which can be derived from the PyPI JSON API if desired. The script logs the verification output to verify.log for audit purposes.

Verification Checklist

1. Import the maintainer’s GPG key and confirm the fingerprint matches the expected value.
2. Run the script against a known signed package (e.g., cryptography==3.4.8) and verify that verify.log contains a successful verification message.
3. Alter the .asc file (e.g., change a byte) and rerun; the script should abort with an error.
4. Remove the .asc file and confirm the pipeline aborts, unless a fallback flag is supplied.

Limitations & Caveats

• Only source distributions (.tar.gz) can be signed; many packages ship wheels that are not signed by PyPI.
• Maintainers may choose not to sign packages; your CI must decide whether to treat such packages as untrusted or to allow them under a relaxed policy.
• Relying on a single GPG key introduces a single point of failure; consider key rotation and revocation checks.
• Network partitions can cause signature downloads to fail; local mirrors or retry logic mitigate this.
• PyPI’s signing format may evolve; keep the GPG tooling up to date and monitor PyPI announcements.

Conclusion

By integrating a lightweight PGP verification step into your CI pipeline, you establish a clear trust boundary: only packages signed by keys you import are installed. The minimal design keeps the pipeline fast, the operational checks provide auditability, and the failure modes are explicit, allowing rapid response to security incidents. Adapt the design to your organization’s scale and policy, but always ensure the key import process is auditable and the verification logic is maintainable.