Back to Details

code-hardcode-audit

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Code Hardcode Audit

代码硬编码审计

When to Use This Skill

何时使用该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"
  • "secret scanning", "leaked secrets", "API keys"
  • "passwords in code", "credential leaks"
当用户提及以下内容时使用本Skill：
  • “硬编码值”、“硬编码”、“魔术数字”
  • “常量检测”、“查找常量”
  • “重复常量”、“违反DRY原则”
  • “代码审计”、“硬编码审计”
  • “PLR2004”、“semgrep”、“jscpd”、“gitleaks”
  • “秘密扫描”、“密钥泄露”、“API密钥”
  • “代码中的密码”、“凭证泄露”

Quick Start

快速开始

bash
undefined
bash
undefined

Full audit (all tools, both outputs)

完整审计（所有工具，两种输出格式）

uv run --script scripts/audit_hardcodes.py -- src/
uv run --script scripts/audit_hardcodes.py -- src/

Python magic numbers only (fastest)

仅检测Python魔术数字（最快）

uv run --script scripts/run_ruff_plr.py -- src/
uv run --script scripts/run_ruff_plr.py -- src/

Pattern-based detection (URLs, ports, paths)

基于模式的检测（URL、端口、路径）

uv run --script scripts/run_semgrep.py -- src/
uv run --script scripts/run_semgrep.py -- src/

Copy-paste detection

重复代码检测

uv run --script scripts/run_jscpd.py -- src/
uv run --script scripts/run_jscpd.py -- src/

Secret scanning (API keys, tokens, passwords)

秘密扫描（API密钥、令牌、密码）

uv run --script scripts/run_gitleaks.py -- src/
undefined
uv run --script scripts/run_gitleaks.py -- src/
undefined

Tool Overview

工具概述

ToolDetection FocusLanguage SupportSpeed
Ruff PLR2004Magic value comparisonsPythonFast
SemgrepURLs, ports, paths, credentialsMulti-languageMedium
jscpdDuplicate code blocksMulti-languageSlow
gitleaksSecrets, API keys, passwordsAny (file-based)Fast
工具检测重点语言支持速度
Ruff PLR2004魔术数值比较Python快速
SemgrepURL、端口、路径、凭证多语言中等
jscpd重复代码块多语言缓慢
gitleaks秘密信息、API密钥、密码任意（基于文件）快速

Output Formats

输出格式

JSON (--output json)

JSON格式（--output json）

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

类编译器文本格式（--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)
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

CLI选项

--output {json,text,both}  Output format (default: both)
--tools {all,ruff,semgrep,jscpd,gitleaks}  Tools to run (default: all)
--severity {all,high,medium,low}  Filter by severity (default: all)
--exclude PATTERN  Glob pattern to exclude (repeatable)
--parallel  Run tools in parallel (default: true)
--output {json,text,both}  输出格式（默认：both）
--tools {all,ruff,semgrep,jscpd,gitleaks}  要运行的工具（默认：all）
--severity {all,high,medium,low}  按严重程度过滤（默认：all）
--exclude PATTERN  要排除的Glob模式（可重复）
--parallel  并行运行工具（默认：true）

References

参考资料

  • Tool Comparison - Detailed tool capabilities
  • Output Schema - JSON schema specification
  • Troubleshooting - Common issues and fixes
  • 工具对比 - 详细的工具能力说明
  • 输出Schema - JSON Schema规范
  • 故障排查 - 常见问题与解决方法

Related

相关内容

  • ADR-0046: Semantic Constants Abstraction
  • ADR-0047: Code Hardcode Audit Skill
  • code-clone-assistant
    - PMD CPD-based clone detection (DRY focus)
  • ADR-0046：语义常量抽象
  • ADR-0047：代码硬编码审计Skill
  • code-clone-assistant
    - 基于PMD CPD的重复代码检测（聚焦DRY原则）

Troubleshooting

故障排查

IssueCauseSolution
Ruff PLR2004 not foundRuff not installed or old
uv tool install ruff
or upgrade
Semgrep timeoutLarge codebase scanUse 
--exclude
to limit scope
jscpd memory errorToo many filesIncrease Node heap: 
NODE_OPTIONS=--max-old-space-size=4096
gitleaks false positivesTest data flaggedAdd patterns to 
.gitleaks.toml
allowlist
No findings in outputWrong directory specifiedVerify path exists and contains source files
JSON parse errorTool output malformedRun tool individually with 
--output text
Missing tool in PATHTool not installed globallyInstall via mise, homebrew, or npm
Severity filter emptyNo findings at that levelUse 
--severity all
to see all findings
问题原因解决方案
Ruff PLR2004未找到Ruff未安装或版本过旧
uv tool install ruff
或升级版本
Semgrep超时代码库过大使用
--exclude
限制扫描范围
jscpd内存错误文件数量过多增加Node堆内存：
NODE_OPTIONS=--max-old-space-size=4096
gitleaks误报测试数据被标记将规则添加到
.gitleaks.toml
白名单中
输出无检测结果指定目录错误验证路径存在且包含源代码文件
JSON解析错误工具输出格式异常单独运行工具并使用
--output text
查看输出
工具未在PATH中找到工具未全局安装通过mise、homebrew或npm安装
严重程度过滤无结果该级别无匹配检测结果使用
--severity all
查看所有检测结果