Skip to content

Security Rulebook

Last updated: 2026-02-22

This rulebook defines mandatory security workflow for this repository.

1. Core Principles

  1. Stop the line on security risks.
  2. Secrets never belong in tracked files.
  3. Tracked app manifests must reference secrets by name, not value.
  4. Run security checks before pushing.
  5. Treat any leak as a formal incident.

2. Non-Negotiable Rules

  1. Never commit:
  2. tokens, API keys, kubeconfigs, or private keys
  3. machine-specific credentials and runtime secrets
  4. local files like .k3s-node-token, kubeconfig-raw.yml, terraform/terraform.tfvars
  5. Keep tracked app manifests secret-free (no plaintext stringData values).
  6. Use placeholders in docs and examples:
  7. CHANGE_ME_*
  8. ${ENV_VAR}
  9. Required local checks before push:
  10. pre-commit run --all-files
  11. bash -n scripts/*.sh
  12. python3 scripts/security_scrub.py --no-history

3. Standard Workflow

Before coding

  • Pull latest main.
  • Confirm no secret-bearing local files are staged.
  • Use placeholders for new secret fields in manifests/docs.

During coding

  • Keep credentials in local password manager or local-only files.
  • Do not place real values in stringData in tracked manifests.

Before commit

git status
pre-commit run --all-files
bash -n scripts/*.sh
python3 scripts/security_scrub.py --no-history

Before push

pre-commit run --all-files
bash -n scripts/*.sh
python3 scripts/security_scrub.py

After push

  • Confirm CI .github/workflows/ci.yml passed.
  • If any leak is found, start incident handling immediately.

4. Security Incident Playbook

Trigger conditions

  • Secret/token/key appears in tracked content.
  • security_scrub.py reports high-severity findings.
  • Sensitive local file is committed by mistake.

Immediate response

  1. Freeze pushes and merges on affected branch.
  2. Revoke or rotate exposed credentials immediately.
  3. Remove leaked content from current branch.
  4. Re-run local checks.

If history is affected

  1. Create safety tag:
git tag pre-history-scrub-$(date +%Y%m%d-%H%M%S)
  1. Rewrite with git-filter-repo using:
  2. --replace-text for leaked literals
  3. --invert-paths for files that should never be tracked
  4. Verify removal:
git log --all -S"<leaked-value>" --oneline
git rev-list --all -- <sensitive/path>
  1. Force-push rewritten refs:
git push --force origin main
  1. Notify collaborators to re-clone or hard reset.

Collaborator recovery

git fetch origin
git checkout main
git reset --hard origin/main

5. Documentation Rules

  1. Keep SECURITY.md and this rulebook aligned.
  2. Never include realistic secrets in docs or examples.
  3. Replace exposed values with REDACTED_* markers.
  4. Update docs in the same PR as security-sensitive changes.

6. Reference Commands

# Quick local gate
pre-commit run --all-files
bash -n scripts/*.sh
python3 scripts/security_scrub.py --no-history

# Full scrub including git history
python3 scripts/security_scrub.py