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	ツールの利用可否と設定の検証	N/A	即時
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 を更新してください。

問題が実際に発生し、再現可能な場合にのみ更新してください。推測に基づいて更新しないでください。