Write a rule that matches your token's fixed prefix, its exact length and character set, and optionally a checksum. Test it against known good tokens, near misses and ordinary code, then run it over your history to count false positives. A distinctive prefix does most of the work.
Why built in rules are not enough
Scanners ship with rules for popular services. Your internal tokens, session secrets and partner keys are not in them. Entropy checks may catch some, but they are noisy. A custom rule gives precise alerts for the formats only you use.
If you control token design, make it easy to detect. Our post on designing an API key that can be found when it leaks covers the design side. The rest of this post assumes tokens already exist.
Anatomy of a good rule
| Part | Purpose | Example idea |
|---|---|---|
| Prefix | Makes the match distinctive | A short fixed string such as acme_live_ |
| Character set and length | Cuts random matches | Exactly 32 letters and digits after the prefix |
| Boundaries | Avoids matching inside longer strings | Require a non word character before and after |
| Context keywords | Optional extra signal | The word token or key nearby |
| Checksum | Confirms the format is real | Last characters derived from the rest |
A rule in a typical scanner configuration is a regular expression, like this illustrative one:
\bacme_live_[A-Za-z0-9]{32}\b
This is an example for a made up prefix, not a real format. Use your own.
Steps
- Collect samples. Gather a handful of real tokens from a test environment, in a safe place.
- Write the pattern. Start strict: prefix, exact length, boundaries.
- Add near misses. Create strings that are too short, too long or have a wrong prefix. The rule must not match them.
- Run on a clean sample of code. Pick a few repositories that should have no tokens. Zero matches expected.
- Run on history. Scan the full history and review every hit. See how to scan full git history.
- Add allowlist entries only with a reason. For example, documented example tokens.
- Version the rule in a repository and review changes like code.
- Assign an owner who answers for the rule's accuracy.
Verification makes rules better
Some platforms let a pattern call a verification endpoint to confirm a match is live. GitHub's secret scanning documentation describes validity checks that confirm whether a detected secret is still active. If you can expose a safe check for your own tokens, alerts become much easier to prioritise.
Quick check
Should the rule match old token formats too?
Yes, if old tokens still work or exist in history. Write one rule per format and label them clearly.
How do I avoid matching the example token in my docs?
Use one documented example value and allowlist that exact string with a comment, rather than a broad path exclusion.
Safeguard can scan repositories and enforce policies on pull requests; try a free scan to see current findings.
Sources
Last reviewed: 19 October 2026.
