81 lines
3.5 KiB
Markdown
81 lines
3.5 KiB
Markdown
# 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.
|