code-hardcode-audit

代码硬编码审计

自我演进技能：此技能会在使用过程中不断改进。如果说明有误、参数发生偏移，或需要采用变通方法，请立即修复此文件，不要拖延。仅针对真实且可复现的问题进行更新。

何时使用此技能

当用户提到以下内容时，请使用此技能：

• “硬编码值”“硬编码”
• “常量检测”“查找常量”
• “重复常量”“违反 DRY 原则”
• “代码审计”“硬编码审计”
• “PLR2004”“semgrep”“jscpd”“gitleaks”“ast-grep”“SSoT 违规”
• “密钥扫描”“密钥泄露”“API 密钥”“bandit”“trufflehog”“whispers”
• “代码中的密码”“凭据泄露”“熵检测”
• “配置文件中的密钥”“硬编码凭据”

快速开始

# 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/

工具概览

工具	检测重点	语言支持	速度
Preflight	工具可用性 + 配置验证	不适用	即时
Bandit	Python 中的硬编码密码、令牌（B105-7）	Python	快
TruffleHog	基于熵的密钥检测 + API 验证	任意（基于文件）	中
Whispers	配置文件中的密钥（YAML、JSON、Docker、.env）	配置文件	中
ast-grep	参数、sleep、URL、路径中的硬编码字面量	多语言	快
Ruff PLR2004	魔法值比较	Python	快
Semgrep	URL、端口、路径、凭据、重试配置	多语言	中
Env-coverage	BaseSettings 交叉引用、覆盖缺口	Python	快
jscpd	重复代码块	多语言	慢
gitleaks	基于正则表达式的密钥、API 密钥、密码	任意（基于文件）	快

输出格式

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"]
    }
  ]
}

类编译器文本（--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 选项

--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

参考资料

• 工具对比 - 详细的工具功能
• 输出架构 - JSON 架构规范
• 故障排除 - 常见问题与修复方法

相关内容

• ADR-0046：语义常量抽象
• ADR-0047：代码硬编码审计技能
• code-clone-assistant - 基于 PMD CPD 的克隆检测（侧重 DRY）

---

故障排除

问题	原因	解决方案
Ruff PLR2004 无输出	全局禁用了 PLR2004	运行预检：uv run --python 3.14 --script scripts/preflight.py -- .
找不到 Ruff PLR2004	未安装 Ruff 或版本过旧	uv tool install ruff 或升级
找不到 ast-grep	未安装二进制文件	cargo install ast-grep 或 brew install ast-grep
Semgrep 超时	代码库扫描规模较大	使用 --exclude 限定范围
jscpd 内存错误	文件过多	增加 Node 堆内存：NODE_OPTIONS=--max-old-space-size=4096
gitleaks 误报	测试数据被标记	将模式添加到 .gitleaks.toml 允许列表
Env-coverage 漏检	未使用 BaseSettings	仅检测 pydantic BaseSettings；会跳过其他配置模式
输出中没有发现项	指定了错误的目录	确认路径存在且包含源文件
JSON 解析错误	工具输出格式错误	单独运行工具并使用 --output text
PATH 中缺少工具	未全局安装工具	先运行预检，再安装缺少的工具
Bandit 误报	初始化代码中有 password = ''	按置信度筛选 B105：--confidence HIGH
TruffleHog 超时	正在扫描 .venv/node_modules	所有工具都会遵循 .gitignore；确保大型目录已加入 gitignore
TruffleHog 正则表达式错误	.gitignore 中有 Glob 模式	复杂的 Glob（**/*.rs.bk）会自动跳过；仅使用简单名称
Whispers 扫描缓慢	目录较大	通过 .gitignore 排除；会根据它自动生成 whispers 配置
Whispers 未发现任何内容	范围内没有配置文件	Whispers 目标格式为 YAML/JSON/Docker/INI；请在项目根目录而非 src/ 中运行
严重性筛选结果为空	该级别没有发现项	使用 --severity all 查看所有发现项

执行后回顾

此技能完成后，请在结束前检查：

1. 命令是否成功？ — 如果没有，请修正导致失败的指令或错误表。
2. 参数或输出是否发生变化？ — 如果底层工具的接口已变更，请更新用法示例和参数表，使其与之匹配。
3. 是否需要变通方案？ — 如果你不得不临时变通（使用不同的标志、增加额外步骤），请更新此 SKILL.md，避免下次调用时需要重复采用相同的变通方案。

只有在问题真实且可复现时才进行更新，不要基于猜测更新。