bible/rules/patterns/secret-management/contract.md

Contract: Secret Management

Version: 1.1

Purpose

Общие правила, которые предотвращают утечку секретов в git, логи, конфиги, шаблоны и release-артефакты.

No Secrets In Git

Secrets must never be committed to the repository, even temporarily.

This includes:

• API keys
• access tokens
• passwords
• DSNs with credentials
• private keys
• session secrets
• OAuth client secrets
• .env files with real values
• production or staging config files with real credentials

Rules:

• Real secrets must never appear in tracked files, commit history, tags, release assets, examples, fixtures, tests, or docs.
• .gitignore is required for runtime config and local secret files, but .gitignore alone is not considered sufficient protection.
• Commit only templates and examples with obvious placeholders, for example CHANGEME, example, or empty strings.
• Never place secrets in screenshots, pasted logs, SQL dumps, backups, or exported archives that could later be committed.

Where Secrets Live

Rules:

• Store real secrets only in local runtime config, secret stores, environment injection, or deployment-specific configuration outside git.
• Keep committed config files secret-free: config.example.yaml, .env.example, and similar files must contain placeholders only.
• If a feature requires a new secret, document the config key name and format, not the real value.

Required Git Checks

Before every commit:

• Verify that files with real secrets are gitignored.
• Inspect staged changes for secrets, not just working tree files.
• Run an automated secret scan against staged content using project tooling or a repository-approved scanner.
• If the scan cannot be run, stop and do not commit until an equivalent staged-content check is performed.

Before every push:

• Scan the commits being pushed for secrets again.
• Refuse the push if any potential secret is detected until it is reviewed and removed.

High-risk patterns that must be checked explicitly:

• PEM blocks (BEGIN PRIVATE KEY, BEGIN OPENSSH PRIVATE KEY, BEGIN RSA PRIVATE KEY)
• tokens in URLs or DSNs
• password=, token=, secret=, apikey=, api_key=
• cloud credentials
• webhook secrets
• JWT signing keys

Scheduled Security Audit

Rules:

• Perform a security audit at least once per week.
• At least once per week, scan the git repository for leaked secrets, including current files, staged changes, commit history, and reachable tags.
• Treat weekly secret scanning as mandatory even if pre-commit and pre-push checks already exist.
• If the weekly audit finds a leaked secret, follow the Incident Response rules immediately.

Logging and Generated Artifacts

Rules:

• Do not print secrets into terminal output, structured logs, panic messages, or debug dumps.
• Do not embed secrets into generated backups, exports, support bundles, or crash reports unless the artifact is explicitly treated as secret operational data and guaranteed to stay outside git.
• If secrets must appear in an operational artifact, that artifact inherits the same "never in git" rule as backups.

Incident Response

If a secret is committed or pushed:

• Treat it as compromised immediately.
• Rotate or revoke the secret.
• Remove it from the current tree and from any generated artifacts.
• Remove it from all affected commits and from repository history, not just from the latest revision.
• Inform the user that history cleanup may be required.
• Do not claim safety merely because the repo is private.