AI Assistant Secret Handling Rules

Purpose

Use these rules when an AI coding assistant can see, edit, summarize, test, or publish code that might contain secrets. Secrets include API keys, passwords, private keys, SSH keys, tokens, cookies, session identifiers, webhook secrets, database URLs, cloud credentials, signing keys, and sensitive internal identifiers.

The safest assistant behavior is boring and explicit: do not reveal the value, do not preserve it in generated output, do not move it into another public place, and do not treat cleanup as enough when a real credential was exposed.

Secret Classification

Classify a value as secret or potentially secret when it is:

• a credential value, private key, token, password, cookie, webhook secret, or connection string;
• a live-looking value in .env, config, CI, deployment, container, cloud, or package-publish settings;
• a generated fixture, screenshot, log, trace, notebook output, prompt, or documentation sample that resembles a credential;
• an internal hostname, account ID, customer identifier, database name, or incident detail that should not be public;
• a value the assistant cannot prove is synthetic.

When uncertain, handle the value as sensitive and ask for a safe placeholder.

Assistant Rules

• Never paste real secret values into prompts, model output, PR descriptions, issue comments, commit messages, generated docs, test fixtures, or examples.
• Replace discovered values with stable placeholders such as EXAMPLE_API_KEY, REDACTED_DATABASE_URL, or YOUR_SERVICE_TOKEN.
• Name the required variable or secret store key, but not the value.
• Preserve local-only files in .gitignore when the project expects secrets in untracked environment files.
• Prefer CI secret stores, deployment secret stores, or credential helpers over hardcoded config.
• Do not transform a secret into another leak, such as a base64 string, partial token, screenshot, log line, or generated summary.
• Stop and escalate when a real secret appears in history, public review text, CI logs, chat transcripts, or generated artifacts.

Commit And PR Rules

Before committing assistant-generated work:

1. Check staged files, untracked generated files, snapshots, notebooks, reports, logs, and docs for real-looking secrets.
2. Verify .gitignore covers local credential files, but do not rely on .gitignore after a secret has already been committed.
3. Review CI workflow changes for accidental secret printing, broad environment export, unsafe debugging, or untrusted pull request exposure.
4. Keep the PR body privacy-safe: describe the secret name or storage mechanism without revealing values, account IDs, or private incident context.
5. If a secret was exposed, request rotation and history cleanup from the owner before presenting the PR as safe.

Storage Rules

• Store local development values in local-only environment files or credential helpers according to the project policy.
• Store CI and deployment values in the platform's secret store, not in YAML, shell scripts, Dockerfiles, docs, or committed examples.
• Keep sample files synthetic and obvious: example.env, .env.example, and docs should contain placeholders, not copied local values.
• Scope secrets narrowly by environment, service, permission, and expiration where the platform supports it.
• Do not create new long-lived credentials to make an assistant task easier.

Rotation And Cleanup Rules

Editing the file is not enough when a real secret was exposed.

• Mark the credential as exposed.
• Notify the owner or security channel.
• Rotate, revoke, or expire the secret according to the project's policy.
• Remove or rewrite public history only through the maintainer-approved path.
• Check secondary copies: CI logs, issue comments, PR bodies, screenshots, traces, notebooks, generated docs, package artifacts, and assistant transcripts.
• Add or update a scanner or review checklist so the same leak is less likely to recur.

Secret Lifecycle (OWASP)

The OWASP Secrets Management Cheat Sheet defines a secret lifecycle (section 2.7). Map assistant behavior to each stage instead of treating "edit the file" as done.

Review Checklist

• {"task": "No real values", "description": "Diffs, prompts, docs, tests, fixtures, logs, screenshots, and generated artifacts contain placeholders instead of real secrets"}
• {"task": "Storage named", "description": "The entry or PR names the expected environment variable, CI secret, vault key, or credential helper without revealing the value"}
• {"task": "Local files ignored", "description": "Local credential files are untracked or ignored according to project policy"}
• {"task": "CI is safe", "description": "Workflow changes do not print secrets, export them broadly, or expose them to untrusted pull requests"}
• {"task": "Exposure escalated", "description": "Real or suspected exposed secrets trigger owner notification, rotation, and cleanup review"}
• {"task": "Public notes redacted", "description": "PR and issue text avoid raw tokens, private IDs, customer details, and incident context"}

Do Not Merge When

• a real-looking secret remains in the source diff, generated files, docs, examples, tests, screenshots, logs, or notebook output;
• a PR claims "secret removed" but does not mention rotation or owner review after exposure;
• a workflow prints environment variables, dumps contexts, or exposes secrets to untrusted code paths;
• a sample config uses a copied local value instead of a placeholder;
• the assistant included token fragments, hashes, screenshots, or summaries that still help identify the secret;
• cleanup requires private security handling but the public PR contains the sensitive evidence.

Troubleshooting

• A value might be fake: treat it as sensitive until the owner confirms it is synthetic or expired.
• The secret is already in history: stop normal review and follow the repository's history-cleanup and rotation process.
• The tests need credentials: use test doubles, local-only environment variables, or CI secret stores; do not commit the value.
• A scanner reports a false positive: document why it is synthetic, then keep the example clearly fake.
• The assistant needs context: provide the secret name, permission scope, and storage location, not the value.

Duplicate Check

Checked existing rules, guides, collections, hooks, agents, skills, commands, open PRs, and closed PR history for secret-handling rules, credential safety, secret scanning, environment variable review, pre-write secret checks, and AI assistant privacy guidance.

Adjacent content includes secret-scanning hooks, environment-variable validation, privacy metadata rules, and secure workflow guides. This entry is distinct because it gives portable do/don't behavior for AI coding assistants deciding how to handle secrets in prompts, diffs, generated artifacts, CI workflows, and public review notes.

References

• OWASP Secrets Management Cheat Sheet: https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html
• The Twelve-Factor App config guidance: https://12factor.net/config
• Git gitignore documentation: https://git-scm.com/docs/gitignore
• Git credential storage documentation: https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage
• GitHub Actions secrets documentation: https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets
• GitHub sensitive-data removal documentation: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/removing-sensitive-data-from-a-repository

• Source repositorygithub.com 2026-07-19T11:20:19-07:00
• Documentationcheatsheetseries.owasp.org
• Submitted by MkDev112026-06-04