A doctor or bug report command should remove tokens, passwords, usernames, hostnames and absolute home paths by default, write the report to a local file, and let the user read it before sharing. Users paste these reports into public issue trackers, so assume they will be public.
Why these commands are risky
Support teams love diagnostics. A command that gathers version numbers, config values and recent logs saves hours. The same command can collect a token from a config file, a private repository name from a path, or an internal hostname from a proxy setting. Then a user pastes it into a public issue.
What to include and what to drop
| Include | Drop or mask |
|---|---|
| Tool version, OS, architecture | Tokens, passwords, API keys |
| Names of enabled features | Usernames and email addresses |
| Config keys that are set (not values) | Hostnames and internal URLs |
| Error codes and last error message | Absolute paths that contain a username |
| Length and type of credentials found | The credentials themselves |
Showing that a credential is present, and where it came from, helps support. Showing its value never does.
Design steps
- Collect from an allowlist. List what you gather. Do not dump the whole config or environment and filter after.
- Mask paths. Replace the home directory with a placeholder such as a tilde, and strip drive and user segments.
- Redact values by key name and by pattern. Keys such as token, secret, password and key are hidden. Add patterns for values that look like credentials.
- Write to a file, not the screen. Tell the user where it is and invite them to open it.
- Show a summary of what was removed. For example, "3 values hidden". It builds trust and helps catch gaps.
- Never upload on its own. If your tool can send reports, require an explicit confirm after the user has seen the content.
- Handle logs separately. Recent log lines are the most likely place for leaks. Redact them with the same function your logger uses.
Test with planted values
Put fake secrets in the config, in the environment and in a log line. Run the command and search the output. If any fake value appears, fix the allowlist, not just the pattern.
What to say in the issue template
Ask users to read the file before attaching it. Tell them that if they find a secret in it, they should rotate the secret and tell you. Your tool should never have put it there, so treat it as a bug in the command.
Cross-link this with your logging rules. The post on stopping secrets in CI logs covers the output side.
Quick check
Is it enough to hide keys named token?
No. Values can sit under unexpected names or inside URLs. Use an allowlist for what you collect and patterns for what you print.
Should the command upload the report automatically?
No. Write it to a file, let the user review it, and share only on their action.
Safeguard's free scan at gold.safeguard.sh/scan can show which libraries your CLI uses to handle such data.
Last reviewed: 19 October 2026.
