70 lines
3.7 KiB
Markdown
70 lines
3.7 KiB
Markdown
> Per AI Blitz Plan §claude. Layer: 1. Repo: devops-infra-helm-charts.
|
|
|
|
# 08 — Pre-commit and hooks
|
|
|
|
What runs when you `git commit` here, what blocks, what doesn't, and why nothing should be bypassed.
|
|
|
|
## Hook installation
|
|
|
|
One-time, per clone:
|
|
|
|
```
|
|
pre-commit install \
|
|
--hook-type pre-commit \
|
|
--hook-type pre-push \
|
|
--hook-type post-commit
|
|
```
|
|
|
|
If the hooks aren't installed, the local commit will skip them — but PR review is the catch-net, and a missed scan in a feature branch can still catch the secret before merge.
|
|
|
|
## Active hooks
|
|
|
|
### TruffleHog (pre-commit, blocking)
|
|
|
|
Scans the staged content for high-entropy strings and known secret patterns (AWS keys, GCP service-account JSON, GitHub tokens, generic JWTs, etc.).
|
|
|
|
- **Blocks the commit** on any positive match.
|
|
- **NEVER bypass** with `git commit --no-verify` or `git commit -n`. This is on the don't-touch list — see [`../docs/global/SANCTITY_RULES.md`](../docs/global/SANCTITY_RULES.md).
|
|
- If the hook fires on a **real secret**: stop, rotate the credential immediately (any value that touched a Git working tree is half-burned), then move to External Secrets Operator. See [`./06-secrets-and-identity.md`](./06-secrets-and-identity.md).
|
|
- If the hook fires on a **false positive**: fix the regex in `pre-commit-scripts/` rather than skip-listing the file. The fix is reusable across the org.
|
|
|
|
### CAC and Yaak (pre-commit / pre-push, gated)
|
|
|
|
These hooks exist in the platform's standard `.pre-commit-config.yaml`, but they are gated on file paths this repo doesn't carry (CAC config files, Yaak collections). They no-op here. The same scripts run for real in service repos.
|
|
|
|
If a future change ever introduces matching paths, the hooks will start firing — read their messages and fix forward. Do not disable.
|
|
|
|
## Background hooks
|
|
|
|
### Cursor AI commit metric collector (post-commit, non-blocking)
|
|
|
|
Posts a metric ping to `observe.meeshogcp.in` describing the commit (author, files touched, AI tool used). Runs in the background, does not block, and silently drops on failure.
|
|
|
|
- This is **the only sanctioned outbound call to a `*.meeshogcp.in` host** the agent should ever observe in this repo. Agents must still refuse to *initiate* any such call themselves. See [`../docs/global/SANCTITY_RULES.md`](../docs/global/SANCTITY_RULES.md).
|
|
- If the post-commit script is failing, that's a platform issue — escalate per [`../docs/global/escalation-matrix.md`](../docs/global/escalation-matrix.md). Do not remove the script.
|
|
|
|
## Why never `--no-verify`
|
|
|
|
A bypassed pre-commit hook is invisible to the PR reviewer. Real secrets ship through merged PRs are very expensive to recover from:
|
|
|
|
- The credential itself must be rotated everywhere it's used.
|
|
- The Git history must be force-rewritten (and even then, the Git push may be cached on a mirror).
|
|
- Any system that ingested the secret value (CI logs, Slack quotes, downstream forks) is now compromised.
|
|
|
|
The 5 seconds saved bypassing the hook is a 5-day-or-more incident later.
|
|
|
|
## When the hook is wrong
|
|
|
|
Two kinds of false-positive:
|
|
|
|
1. **Pattern over-matches** — TruffleHog regex matches a non-secret high-entropy string (a hash, a UUID, a build label). Fix: tighten the regex in `pre-commit-scripts/`.
|
|
2. **Genuine fixture / test data** — a fake-looking string in a chart's example values or test fixture. Fix: same — tighten the pattern, or move the fixture to a path TruffleHog already excludes (chart `templates/` test fixtures usually qualify).
|
|
|
|
Either way, the fix is in the hook, not in the bypass.
|
|
|
|
## See also
|
|
|
|
- [`./06-secrets-and-identity.md`](./06-secrets-and-identity.md)
|
|
- [`../docs/global/SANCTITY_RULES.md`](../docs/global/SANCTITY_RULES.md)
|
|
- [`../docs/global/agent-operations-guide.md`](../docs/global/agent-operations-guide.md)
|