docs(standards): propose push protection standard

Merged
DO
7mo ago
+1170-2

Summary

  • Add standards/push-protection.md proposing a defense-in-depth approach to prevent secrets, keys, and credentials from being accidentally pushed to any petry-projects repo — GitHub native secret scanning + push protection as primary enforcement, local gitleaks hooks, a complementary CI secret-scan job, and an incident response procedure
  • Cross-reference the new standard from AGENTS.md and add a Security & Analysis block to standards/github-settings.md documenting the required repo-level security_and_analysis settings

What's covered in the new standard

  • Scope — every repo regardless of visibility; source, configs, workflows, agent files, fixtures, notebooks
  • What counts as a secret — cloud creds, API tokens, DB strings, private keys, OAuth secrets, signing keys
  • Layer 1 — GitHub push protection (primary enforcement): required org + repo security_and_analysis settings, recommended custom secret-scanning patterns, admin-only bypass with audit
  • Layer 2 — Local pre-commit prevention: gitleaks via pre-commit, agent workstation rules
  • Layer 3 — CI secret scanning (secondary defense): required secret-scan job in ci.yml running gitleaks in full-history mode, coordination with AgentShield
  • Developer practices: handling real secrets, required .gitignore entries, fixture conventions, branch cleanup
  • Push protection block response — what to do when GitHub blocks your push (no bypass without justification)
  • Incident response — rotate first, history rewrite later; 7-step procedure with owners
  • Application to a repo and compliance audit checks the weekly audit should add

Test plan

  • markdownlint-cli2 passes on all changed .md files
  • shellcheck --severity=warning -x scripts/**/*.sh passes (CI globbing also fixed to recurse into scripts/lib/)
  • scripts/apply-repo-settings.sh enforces the new security_and_analysis flags via pp_apply_security_and_analysis from scripts/lib/push-protection.sh
  • scripts/compliance-audit.sh runs the 5 push-protection checks via pp_run_all_checks from the same shared lib
  • Review the illustrative custom secret-scanning regexes before enabling them org-wide
  • Follow-up: add the secret-scan job to the code-quality ruleset's required checks (still needs detect_required_checks() update in scripts/apply-rulesets.sh)
  • Smoke-test the apply script in DRY_RUN=true mode against a single repo before running --all

Summary by CodeRabbit

  • Documentation
    • Added an org-wide push-protection standard covering prohibited secret types, enforcement layers, developer rules, CI secret-scan requirements, incident response, onboarding checklist, and compliance audit matrix.
    • Updated repository security guidance to require secret scanning, push protection (including AI detection and custom/non-provider patterns), and Dependabot security updates.
    • Added a secrets-focused .gitignore to ignore common credential and token artifacts.
    • Updated organization standards index to reference the new push-protection standard.