python-gitleaks-staged-vs-fulltree-gap

Answer

Root cause: gitleaks protect --staged only diffs the staging area. A gitignored, repo-local .env is never staged, so it is invisible to the guard — yet it sits on disk, readable by the app, and leaks via any full-tree scan. Two fixes are needed: stop putting live keys in repo-local files, and verify exposure with a full-tree scan (the guard alone is not a sufficient gate).

1. Never keep live keys in a repo-local .env — delete it, keep only a placeholder template:

# .env.example  (placeholder only — never a real key)
OPENAI_API_KEY=sk-replace-me-with-a-real-key-at-runtime

2. Inject secrets via the environment, not files:

# scripts/run.sh — refuses to start without an injected secret
#!/usr/bin/env bash
set -euo pipefail
if [[ -z "${OPENAI_API_KEY:-}" ]]; then
  echo "FATAL: OPENAI_API_KEY is not set. Inject via export / CI secret / secret manager." >&2
  exit 1
fi
exec python3 app.py

# app.py — reads ONLY from os.environ, fails closed
import os
PLACEHOLDERS = {"", "sk-replace-me-with-a-real-key-at-runtime"}

def main():
    key = os.environ.get("OPENAI_API_KEY", "")
    if key in PLACEHOLDERS or key.startswith("sk-replace"):
        raise SystemExit("FATAL: OPENAI_API_KEY missing or placeholder — inject a real secret via the environment")
    print(f"OK: key loaded (masked={key[:8]}...)")

3. Verify exposure with a full-tree scan — this is the gap-closer; run it in CI and pre-push, alongside the staged guard:

# scripts/full-scan.sh — scans EVERY file on disk, including gitignored .env
#!/usr/bin/env bash
set -euo pipefail
gitleaks detect --source . --no-git \
  --report-format json --report-path gitleaks-report.json -v

# .github/workflows/secrets.yml (conceptual)
on: [push, pull_request]
jobs:
  secrets:
    steps:
      - uses: actions/checkout@v4
      - run: gitleaks protect --staged --source .   # fast, staged diff
      - run: gitleaks detect --source . --no-git -v # full tree, catches .env

Local dev/CI injection: export OPENAI_API_KEY=$(op read "op://MyVault/OpenAI/credential") or a provider secret store — the key never touches the repo.