security: pre-commit hook rejecting unencrypted private keys

[rdhyee]

Part of the remediation for EbookFoundation/security-private#10 — the April 8 wildcard TLS private key exposure.

Why

A Claude Code session on April 8 committed an unencrypted wildcard *.unglue.it + unglue.it private key to this public repo. The key was exposed for ~13 days before detection. See security-private#10 for the full incident report, forensics, and post-mortem.

The compromised cert has been revoked (LE accepted keyCompromise) and the plaintext key removed from the working tree. This PR adds layered prevention so the same class of leak is caught locally and in CI going forward.

What changed

Local layer — pre-commit hooks

• .pre-commit-config.yaml — pre-commit framework config with three hooks:

  • no-plaintext-private-keys — custom hook rejecting PEM private keys unless file is $ANSIBLE_VAULT-prefixed
  • pre-commit-hooks/detect-private-key — built-in redundant check
  • gitleaks/gitleaks — broader scanning (AWS keys, GitHub tokens, Stripe keys, generic API keys, private keys in any PEM format, etc.)

• .githooks/check-no-plaintext-keys.sh — the custom hook logic. Scans each staged file for PEM private key headers (RSA, EC, DSA, OPENSSH, ENCRYPTED). Rejects if found and file is not ansible-vault encrypted.

• .gitleaks.toml — repo-specific gitleaks config. Extends the default ruleset with an allowlist for three files containing Ansible template placeholder defaults (012345678901234... and abcdef... patterns meant to be overridden by vault.yml at deploy time). Without this allowlist, gitleaks produces known false positives.

CI layer — GitHub Actions

• .github/workflows/gitleaks.yml — runs gitleaks on every PR and every push to master. Downloads the gitleaks binary directly (MIT-licensed) rather than using the official gitleaks-action@v2 (which now requires a paid license for GitHub organizations). Catches secrets that slip past the pre-commit hook when a contributor hasn't installed it or uses --no-verify.

Why the belt-and-suspenders approach

GitHub's built-in Secret Scanning + Push Protection was enabled on this repo today as part of the incident response. Empirical testing on 2026-04-21 revealed it does NOT reliably block generic PEM private keys (our specific threat model). The free tier validates vendor tokens (real AWS keys, real GitHub PATs) with the issuer; generic PEM detection requires paid GitHub Advanced Security. See the correction comment on security-private#10.

gitleaks uses pure pattern matching (no issuer validation) so it catches generic keys reliably. This PR closes that coverage gap.

Verified

Test	Expected	Actual
Custom hook: plaintext PEM key file	REJECT	✅ REJECT
Custom hook: $ANSIBLE_VAULT file	ALLOW	✅ ALLOW
Custom hook: all 10 existing vault-encrypted keys	all PASS	✅ all PASS
gitleaks on current tree	0 leaks (allowlist filters placeholders)	✅ 0 leaks
gitleaks on full git history	1 leak (the d474401 April 8 commit itself, now revoked)	✅ 1 leak (expected historical)
gitleaks on fresh synthetic RSA key	DETECT	✅ DETECT
CI workflow on this branch	success	✅ success

Layered controls stack after this PR merges

Layer	Where	Bypassable?	Catches generic PEM?	Catches vendor tokens?
Pre-commit hook (custom)	Local	--no-verify	✅	❌ (by design)
Pre-commit hook (gitleaks)	Local	--no-verify	✅	✅
GitHub Push Protection	Server	Org bypass only	❌ (needs paid GHAS)	✅
GitHub Actions gitleaks	Server	No	✅	✅

No single layer is sufficient. Together: defense in depth.

Contributor setup

After this PR merges, collaborators should install the pre-commit hook once:

pip install pre-commit
pre-commit install

Then git commit runs all three hooks automatically. Bypass with --no-verify for exceptional cases (discouraged — CI will still catch you).

Test plan

• Custom hook rejects fake plaintext keys; allows vault-encrypted files
• gitleaks scans run cleanly on current tree (allowlist working)
• gitleaks catches synthetic new keys
• CI workflow runs successfully on branch push
• After merge, mark "Secret scan (gitleaks)" as a required status check in branch protection

Not in this PR

Tracked in security-private#10:

• Fix roles/regluit_prod/tasks/certs.yml:138 to use decrypted-at-runtime path
• Remove force: yes from acme_certificate task
• ADR documenting per-host certs as default pattern
• Collaborator list pruning (33 push-access accounts)
• Branch protection rules on master

[rdhyee]

Review findings:

1. .gitleaks.toml:20 allowlists the entire roles/regluit_common/defaults/main.yml, common.py.j2, and host.py.j2 files, not just the known placeholder literals. That creates a real blind spot: any future hardcoded API key, password, or private key added anywhere in those files will be ignored by both local pre-commit gitleaks and the CI workflow. For a PR whose goal is leak prevention, this materially weakens coverage in exactly the config/template surfaces where secrets are likely to appear. The allowlist should be narrowed to the specific placeholder values or rules causing the false positives rather than path-wide suppression.

2. .github/workflows/gitleaks.yml:31 downloads and executes the gitleaks binary straight from a release URL without verifying a checksum or signature. That turns the new secret-scanning control into an unverified supply-chain dependency in CI: if the asset or download path is ever tampered with, the workflow will happily install and run attacker-controlled code. Since this is a security remediation PR, the install step should pin and verify the published checksum before execution, or use a vetted package source.

[rdhyee]

Re-reviewed the current head (0e6c0b5). I did not find any additional issues in this revision.

The earlier concerns appear resolved:

• .gitleaks.toml now narrows suppression to specific placeholder stopwords instead of allowlisting whole files, so future real secrets in those templates/defaults should still be caught.
• .github/workflows/gitleaks.yml now verifies the pinned SHA-256 of the downloaded gitleaks release tarball before extraction/execution.

Residual gap: this was a static re-review from the patch; I did not run the hooks or the GitHub Actions workflow from this environment.

Signed: Codex