Code Hardcode Audit
Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.
When to Use This Skill
Use this skill when the user mentions:
- "hardcoded values", "hardcodes", "magic numbers"
- "constant detection", "find constants"
- "duplicate constants", "DRY violations"
- "code audit", "hardcode audit"
- "PLR2004", "semgrep", "jscpd", "gitleaks", "ast-grep", "SSoT violations"
- "secret scanning", "leaked secrets", "API keys", "bandit", "trufflehog", "whispers"
- "passwords in code", "credential leaks", "entropy detection"
- "config file secrets", "hardcoded credentials"
Quick Start
# Preflight — verify all tools installed and configured
uv run --python 3.14 --script scripts/preflight.py -- .
# Full audit (all 9 tools, preflight + both outputs)
uv run --python 3.14 --script scripts/audit_hardcodes.py -- src/
# Individual tools (all respect .gitignore):
# Python credential detection (passwords, tokens, API keys in variable names)
uv run --python 3.14 --script scripts/run_bandit.py -- src/
# Entropy-based secret detection (catches secrets regex can't)
uv run --python 3.14 --script scripts/run_trufflehog.py -- src/
# Config file secrets (YAML, JSON, Dockerfile, .env, .properties)
uv run --python 3.14 --script scripts/run_whispers.py -- src/
# AST-based hardcode detection (numeric args, URLs, paths, sleep)
uv run --python 3.14 --script scripts/run_ast_grep.py -- src/
# Python magic numbers only (fastest)
uv run --python 3.14 --script scripts/run_ruff_plr.py -- src/
# Pattern-based detection (URLs, ports, paths, sleep, circuit breaker)
uv run --python 3.14 --script scripts/run_semgrep.py -- src/
# Env-var coverage audit (BaseSettings cross-reference)
uv run --python 3.14 --script scripts/audit_env_coverage.py -- src/
# Copy-paste detection
uv run --python 3.14 --script scripts/run_jscpd.py -- src/
# Regex-based secret scanning (API keys, tokens, passwords)
uv run --python 3.14 --script scripts/run_gitleaks.py -- src/
Tool Overview
| Tool |
Detection Focus |
Language Support |
Speed |
| Preflight |
Tool availability + config validation |
N/A |
Instant |
| Bandit |
Hardcoded passwords, tokens in Python (B105-7) |
Python |
Fast |
| TruffleHog |
Entropy-based secret + API verification |
Any (file-based) |
Medium |
| Whispers |
Config file secrets (YAML, JSON, Docker, .env) |
Config files |
Medium |
| ast-grep |
Hardcoded literals in args, sleep, URLs, paths |
Multi-language |
Fast |
| Ruff PLR2004 |
Magic value comparisons |
Python |
Fast |
| Semgrep |
URLs, ports, paths, credentials, retry config |
Multi-language |
Medium |
| Env-coverage |
BaseSettings cross-reference, coverage gaps |
Python |
Fast |
| jscpd |
Duplicate code blocks |
Multi-language |
Slow |
| gitleaks |
Regex-based secrets, API keys, passwords |
Any (file-based) |
Fast |
Output Formats
JSON (--output json)
{
"summary": {
"total_findings": 42,
"by_tool": { "ruff": 15, "semgrep": 20, "jscpd": 7 },
"by_severity": { "high": 5, "medium": 25, "low": 12 }
},
"findings": [
{
"id": "MAGIC-001",
"tool": "ruff",
"rule": "PLR2004",
"file": "src/config.py",
"line": 42,
"column": 8,
"message": "Magic value used in comparison: 8123",
"severity": "medium",
"suggested_fix": "Extract to named constant"
}
],
"refactoring_plan": [
{
"priority": 1,
"action": "Create constants/ports.py",
"finding_ids": ["MAGIC-001", "MAGIC-003"]
}
]
}
Compiler-like Text (--output text)
src/config.py:42:8: PLR2004 Magic value used in comparison: 8123 [ruff]
src/probe.py:15:1: hardcoded-url Hardcoded URL detected [semgrep]
src/client.py:20-35: Clone detected (16 lines, 95% similarity) [jscpd]
Summary: 42 findings (ruff: 15, semgrep: 20, jscpd: 7)
CLI Options
--output {json,text,both} Output format (default: both)
--tools {all,ast-grep,ruff,semgrep,jscpd,gitleaks,env-coverage,bandit,trufflehog,whispers} Tools to run
--severity {all,high,medium,low} Filter by severity (default: all)
--exclude PATTERN Glob pattern to exclude (repeatable)
--no-parallel Disable parallel execution
--skip-preflight Skip tool availability check
References
Related
- ADR-0046: Semantic Constants Abstraction
- ADR-0047: Code Hardcode Audit Skill
code-clone-assistant - PMD CPD-based clone detection (DRY focus)
Troubleshooting
| Issue |
Cause |
Solution |
| Ruff PLR2004 zero output |
PLR2004 globally suppressed |
Run preflight: uv run --python 3.14 --script scripts/preflight.py -- . |
| Ruff PLR2004 not found |
Ruff not installed or old |
uv tool install ruff or upgrade |
| ast-grep not found |
Binary not installed |
cargo install ast-grep or brew install ast-grep |
| Semgrep timeout |
Large codebase scan |
Use --exclude to limit scope |
| jscpd memory error |
Too many files |
Increase Node heap: NODE_OPTIONS=--max-old-space-size=4096 |
| gitleaks false positives |
Test data flagged |
Add patterns to .gitleaks.toml allowlist |
| Env-coverage misses |
Not using BaseSettings |
Only detects pydantic BaseSettings; other config patterns skipped |
| No findings in output |
Wrong directory specified |
Verify path exists and contains source files |
| JSON parse error |
Tool output malformed |
Run tool individually with --output text |
| Missing tool in PATH |
Tool not installed globally |
Run preflight first, then install missing tools |
| Bandit false positives |
password = '' in init |
Filter B105 by confidence: --confidence HIGH |
| TruffleHog timeout |
Scanning .venv/node_modules |
All tools respect .gitignore; ensure large dirs are gitignored |
| TruffleHog regex error |
Glob patterns in .gitignore |
Complex globs (**/*.rs.bk) are auto-skipped; only simple names used |
| Whispers slow scan |
Large directories |
Exclude via .gitignore; whispers config auto-generated from it |
| Whispers zero findings |
No config files in scope |
Whispers targets YAML/JSON/Docker/INI; use on project root, not src/ |
| Severity filter empty |
No findings at that level |
Use --severity all to see all findings |
Post-Execution Reflection
After this skill completes, check before closing:
- Did the command succeed? — If not, fix the instruction or error table that caused the failure.
- Did parameters or output change? — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
- Was a workaround needed? — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.
Only update if the issue is real and reproducible — not speculative.
1---
2name: code-hardcode-audit
3description: Detect hardcoded values, magic numbers, and leaked secrets. TRIGGERS - hardcode audit, magic numbers, PLR2004, secret scanning.
4allowed-tools: Bash, Read, Write, Glob, Grep
5metadata:
6 source: https://skillmd.com/skills/terrylica/code-hardcode-audit
7---
8
9# Code Hardcode Audit
10
11> **Self-Evolving Skill**: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.
12
13## When to Use This Skill
14
15Use this skill when the user mentions:
16
17- "hardcoded values", "hardcodes", "magic numbers"
18- "constant detection", "find constants"
19- "duplicate constants", "DRY violations"
20- "code audit", "hardcode audit"
21- "PLR2004", "semgrep", "jscpd", "gitleaks", "ast-grep", "SSoT violations"
22- "secret scanning", "leaked secrets", "API keys", "bandit", "trufflehog", "whispers"
23- "passwords in code", "credential leaks", "entropy detection"
24- "config file secrets", "hardcoded credentials"
25
26## Quick Start
27
28```bash
29# Preflight — verify all tools installed and configured
30uv run --python 3.14 --script scripts/preflight.py -- .
31
32# Full audit (all 9 tools, preflight + both outputs)
33uv run --python 3.14 --script scripts/audit_hardcodes.py -- src/
34
35# Individual tools (all respect .gitignore):
36
37# Python credential detection (passwords, tokens, API keys in variable names)
38uv run --python 3.14 --script scripts/run_bandit.py -- src/
39
40# Entropy-based secret detection (catches secrets regex can't)
41uv run --python 3.14 --script scripts/run_trufflehog.py -- src/
42
43# Config file secrets (YAML, JSON, Dockerfile, .env, .properties)
44uv run --python 3.14 --script scripts/run_whispers.py -- src/
45
46# AST-based hardcode detection (numeric args, URLs, paths, sleep)
47uv run --python 3.14 --script scripts/run_ast_grep.py -- src/
48
49# Python magic numbers only (fastest)
50uv run --python 3.14 --script scripts/run_ruff_plr.py -- src/
51
52# Pattern-based detection (URLs, ports, paths, sleep, circuit breaker)
53uv run --python 3.14 --script scripts/run_semgrep.py -- src/
54
55# Env-var coverage audit (BaseSettings cross-reference)
56uv run --python 3.14 --script scripts/audit_env_coverage.py -- src/
57
58# Copy-paste detection
59uv run --python 3.14 --script scripts/run_jscpd.py -- src/
60
61# Regex-based secret scanning (API keys, tokens, passwords)
62uv run --python 3.14 --script scripts/run_gitleaks.py -- src/
63```
64
65## Tool Overview
66
67| Tool | Detection Focus | Language Support | Speed |
68| ---------------- | ---------------------------------------------- | ---------------- | ------- |
69| **Preflight** | Tool availability + config validation | N/A | Instant |
70| **Bandit** | Hardcoded passwords, tokens in Python (B105-7) | Python | Fast |
71| **TruffleHog** | Entropy-based secret + API verification | Any (file-based) | Medium |
72| **Whispers** | Config file secrets (YAML, JSON, Docker, .env) | Config files | Medium |
73| **ast-grep** | Hardcoded literals in args, sleep, URLs, paths | Multi-language | Fast |
74| **Ruff PLR2004** | Magic value comparisons | Python | Fast |
75| **Semgrep** | URLs, ports, paths, credentials, retry config | Multi-language | Medium |
76| **Env-coverage** | BaseSettings cross-reference, coverage gaps | Python | Fast |
77| **jscpd** | Duplicate code blocks | Multi-language | Slow |
78| **gitleaks** | Regex-based secrets, API keys, passwords | Any (file-based) | Fast |
79
80## Output Formats
81
82### JSON (--output json)
83
84```json
85{
86 "summary": {
87 "total_findings": 42,
88 "by_tool": { "ruff": 15, "semgrep": 20, "jscpd": 7 },
89 "by_severity": { "high": 5, "medium": 25, "low": 12 }
90 },
91 "findings": [
92 {
93 "id": "MAGIC-001",
94 "tool": "ruff",
95 "rule": "PLR2004",
96 "file": "src/config.py",
97 "line": 42,
98 "column": 8,
99 "message": "Magic value used in comparison: 8123",
100 "severity": "medium",
101 "suggested_fix": "Extract to named constant"
102 }
103 ],
104 "refactoring_plan": [
105 {
106 "priority": 1,
107 "action": "Create constants/ports.py",
108 "finding_ids": ["MAGIC-001", "MAGIC-003"]
109 }
110 ]
111}
112```
113
114### Compiler-like Text (--output text)
115
116```
117src/config.py:42:8: PLR2004 Magic value used in comparison: 8123 [ruff]
118src/probe.py:15:1: hardcoded-url Hardcoded URL detected [semgrep]
119src/client.py:20-35: Clone detected (16 lines, 95% similarity) [jscpd]
120
121Summary: 42 findings (ruff: 15, semgrep: 20, jscpd: 7)
122```
123
124## CLI Options
125
126```
127--output {json,text,both} Output format (default: both)
128--tools {all,ast-grep,ruff,semgrep,jscpd,gitleaks,env-coverage,bandit,trufflehog,whispers} Tools to run
129--severity {all,high,medium,low} Filter by severity (default: all)
130--exclude PATTERN Glob pattern to exclude (repeatable)
131--no-parallel Disable parallel execution
132--skip-preflight Skip tool availability check
133```
134
135## References
136
137- [Tool Comparison](./references/tool-comparison.md) - Detailed tool capabilities
138- [Output Schema](./references/output-schema.md) - JSON schema specification
139- [Troubleshooting](./references/troubleshooting.md) - Common issues and fixes
140
141## Related
142
143- ADR-0046: Semantic Constants Abstraction
144- ADR-0047: Code Hardcode Audit Skill
145- `code-clone-assistant` - PMD CPD-based clone detection (DRY focus)
146
147---
148
149## Troubleshooting
150
151| Issue | Cause | Solution |
152| ------------------------ | --------------------------- | ------------------------------------------------------------------------ |
153| Ruff PLR2004 zero output | PLR2004 globally suppressed | Run preflight: `uv run --python 3.14 --script scripts/preflight.py -- .` |
154| Ruff PLR2004 not found | Ruff not installed or old | `uv tool install ruff` or upgrade |
155| ast-grep not found | Binary not installed | `cargo install ast-grep` or `brew install ast-grep` |
156| Semgrep timeout | Large codebase scan | Use `--exclude` to limit scope |
157| jscpd memory error | Too many files | Increase Node heap: `NODE_OPTIONS=--max-old-space-size=4096` |
158| gitleaks false positives | Test data flagged | Add patterns to `.gitleaks.toml` allowlist |
159| Env-coverage misses | Not using BaseSettings | Only detects pydantic BaseSettings; other config patterns skipped |
160| No findings in output | Wrong directory specified | Verify path exists and contains source files |
161| JSON parse error | Tool output malformed | Run tool individually with `--output text` |
162| Missing tool in PATH | Tool not installed globally | Run preflight first, then install missing tools |
163| Bandit false positives | `password = ''` in init | Filter B105 by confidence: `--confidence HIGH` |
164| TruffleHog timeout | Scanning .venv/node_modules | All tools respect `.gitignore`; ensure large dirs are gitignored |
165| TruffleHog regex error | Glob patterns in .gitignore | Complex globs (`**/*.rs.bk`) are auto-skipped; only simple names used |
166| Whispers slow scan | Large directories | Exclude via `.gitignore`; whispers config auto-generated from it |
167| Whispers zero findings | No config files in scope | Whispers targets YAML/JSON/Docker/INI; use on project root, not src/ |
168| Severity filter empty | No findings at that level | Use `--severity all` to see all findings |
169
170
171## Post-Execution Reflection
172
173After this skill completes, check before closing:
174
1751. **Did the command succeed?** — If not, fix the instruction or error table that caused the failure.
1762. **Did parameters or output change?** — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
1773. **Was a workaround needed?** — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.
178
179Only update if the issue is real and reproducible — not speculative.