Claude Code Skills 开发实战：从零造一个硬编码密钥扫描 Skill

flowchart TD
    A[会话启动] --> B[预载全部 Skill 的<br/>name + description 进系统提示]
    B --> C{用户请求是否<br/>命中某个 description?}
    C -->|是| D[加载该 Skill 的 SKILL.md 全文]
    C -->|否| E[全文从不加载 零成本]
    D --> F{SKILL.md 是否引用<br/>更细的文件/脚本?}
    F -->|是| G[按需读取 reference.md<br/>或执行 scripts/xxx.py]
    F -->|否| H[直接按指令执行]
    G --> I[脚本只返回输出<br/>源码不进上下文]
    H --> I
    I --> J[产出结果]

mkdir -p ~/.claude/skills/scan-secrets

---
name: scan-secrets
description: Scans source files for hardcoded secrets and credentials (AWS keys, GitHub/Slack/Stripe tokens, private keys, JWTs) and ranks findings by severity. Use when the user asks to check for leaked secrets, review security before a commit, audit credentials in the codebase, or asks "is there a key/token/password hardcoded here?".
when_to_use: Commit-time security checks, PR reviews, onboarding a new repo, investigating "did I leak my token". Triggers on phrases like 密钥泄露、凭据扫描、检查 token、提交前安全检查、硬编码密钥.
argument-hint: [path]
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/scan_secrets.py *) Bash(git diff --name-only *) Bash(git status --short *) Read
paths: "**/*.py, **/*.js, **/*.ts, **/*.go, **/*.java, **/*.{yml,yaml,json,env,conf,ini,toml}, **/.*rc, Dockerfile*, .env*"
---

## 当前改动（commit 前检查模式）
如果当前目录是 git 仓库，先用以下未提交文件清单聚焦扫描：
!`git diff --name-only HEAD 2>/dev/null; git status --short 2>/dev/null`

## 扫描任务
对 `$ARGUMENTS`（未传参则用 `.`）指定的路径运行嗅探脚本，输出按严重度分级的发现：

```bash
python3 ${CLAUDE_SKILL_DIR}/scripts/scan_secrets.py "$ARGUMENTS"
```

## 输出规范
1. 先按 CRITICAL / HIGH / MEDIUM / LOW 汇总数：例如「CRITICAL 2，HIGH 1」。
2. 逐条列出：`文件:行号 [规则] 命中片段（脱敏，只显示首尾4位）`。
3. CRITICAL（私钥、生产 Stripe/AWS 等）必须给出「立刻做什么」的一句行动建议。
4. 若脚本报告 0 命中，明确说「未发现已知模式的硬编码密钥」，并提示三条易漏点（.env 漏提交、构建产物里的 source map、CI 日志里的 token）。
5. 绝不把完整密钥明文回显到对话；脱敏后展示。

## 规则细节
完整规则库与误报排除策略见 [rules.md](rules.md)，按需阅读，不必每次加载。

#!/usr/bin/env python3
# Hardcoded secret scanner. Deterministic regex rules + severity ranking.
import os, re, sys, json, math

RULES = [
    # (name, regex, severity)
    ("AWS Access Key ID",  r"AKIA[0-9A-Z]{16}", "CRITICAL"),
    ("AWS Secret Key",     r"(?i)aws.{0,20}?(?:secret|priv).{0,20}?[\"\']([0-9a-zA-Z/+]{40})[\"\']", "CRITICAL"),
    ("GitHub Token",       r"gh[pousr]_[0-9A-Za-z]{36}|github_pat_[0-9A-Za-z_]{82}", "CRITICAL"),
    ("Google API Key",     r"AIza[0-9A-Za-z\-_]{35}", "HIGH"),
    ("Slack Token",        r"xox[baprs]-[0-9A-Za-z-]{10,}", "HIGH"),
    ("Stripe Live Key",    r"sk_live_[0-9a-zA-Z]{24}|rk_live_[0-9a-zA-Z]{24}", "CRITICAL"),
    ("GitLab PAT",         r"glpat-[0-9a-zA-Z\-_]{20}", "HIGH"),
    ("Private Key Block",  r"-----BEGIN (?:RSA|EC|OPENSSH|PGP|DSA) PRIVATE KEY-----", "CRITICAL"),
    ("JWT",                r"eyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}", "MEDIUM"),
    ("Generic Assignment", r"(?i)(?:password|passwd|pwd|secret|token|api_key)\s*[:=]\s*[\"\']([^\"\'\s]{12,})[\"\']", "MEDIUM"),
]
SKIP_DIRS = {".git", "node_modules", "vendor", "dist", "build", ".venv", "__pycache__"}
SKIP_EXT = {".png", ".jpg", ".jpeg", ".gif", ".lock", ".min.js", ".map"}

def entropy(s):
    if not s: return 0.0
    return -sum((s.count(c)/len(s))*math.log2(s.count(c)/len(s)) for c in set(s))

def scan(path):
    hits = []
    for root, dirs, files in os.walk(path or "."):
        dirs[:] = [d for d in dirs if d not in SKIP_DIRS]
        for fn in files:
            ext = os.path.splitext(fn)[1]
            if ext in SKIP_EXT: continue
            fp = os.path.join(root, fn)
            try:
                with open(fp, "r", encoding="utf-8", errors="ignore") as f:
                    for i, line in enumerate(f, 1):
                        for name, pat, sev in RULES:
                            m = re.search(pat, line)
                            if m:
                                secret = m.group(1) if m.lastindex else m.group(0)
                                # Generic 规则额外要求高熵，过滤 password="changeme" 之类
                                if name == "Generic Assignment" and entropy(secret) < 3.0:
                                    continue
                                masked = secret[:4] + "…" + secret[-4:] if len(secret) > 8 else "***"
                                hits.append({"file": fp, "line": i, "rule": name, "severity": sev, "match": masked})
            except (OSError, UnicodeDecodeError):
                continue
    return hits

if __name__ == "__main__":
    target = sys.argv[1] if len(sys.argv) > 1 else "."
    hits = scan(target)
    order = {"CRITICAL": 0, "HIGH": 1, "MEDIUM": 2, "LOW": 3}
    hits.sort(key=lambda h: (order[h["severity"]], h["file"], h["line"]))
    print(json.dumps(hits, ensure_ascii=False, indent=2))
    sys.exit(1 if hits else 0)

# 嗅探规则与误报排除

## 严重度定义
- CRITICAL：可直接利用的生产凭据（私钥、AWS、Stripe live、GitHub PAT）
- HIGH：云厂商可变现 key（Google、Slack、GitLab）
- MEDIUM：疑似密钥需人工确认（JWT、通用赋值）

## 常见误报排除
- 测试夹具里的假密钥：路径含 `/test/` 或 `/fixtures/` 且值形如 `test_` / `example_`
- 文档示例：文件名含 `.md` 且整行以 `>` 或 `//` 开头
- 占位符：`YOUR_API_KEY` / `<token>` / `xxx`

## 易漏盲区（扫描后必提醒）
1. 已提交进 git 历史的密钥——需用 `git log -p | scan` 二次扫描
2. 构建产物 source map 里泄露的源码
3. CI/CD 日志、Docker image 层、error 上报平台里打印的 token

/skill-creator
> 帮我为 scan-secrets 设计 eval 样例集，正例（应触发）如「这个 PR 安全吗」「会不会有 key 泄露」，
  负例（不该触发）如「帮我写个正则」「这段逻辑有 bug 吗」，然后跑一轮评测。

~/.claude/skills/scan-secrets/
├── SKILL.md              # frontmatter + 主体指令（动态注入 git diff + 调脚本）
├── rules.md              # 规则库与误报排除（按需读）
└── scripts/
    └── scan_secrets.py   # 确定性扫描脚本（只看输出）

import os
AWS_KEY = "AKIAIOSFODNN7EXAMPLE"
gh_token = "ghp_0123456789abcdef0123456789abcdef01234567"
stripe = "sk_live_51HqyWYY2tX9b7e4c5d6f7g8h9i0j"
password = "correct horse battery staple"   # 低熵，应被过滤
db_url = "postgres://u:p@localhost/db"      # 无命中

python3 ~/.claude/skills/scan-secrets/scripts/scan_secrets.py leak_demo.py

[
  { "file": "leak_demo.py", "line": 2, "rule": "AWS Access Key ID", "severity": "CRITICAL", "match": "AKIA…7EXAMPLE" },
  { "file": "leak_demo.py", "line": 3, "rule": "GitHub Token",       "severity": "CRITICAL", "match": "ghp_…4567" },
  { "file": "leak_demo.py", "line": 4, "rule": "Stripe Live Key",    "severity": "CRITICAL", "match": "sk_l…0j" }
]

flowchart LR
    U[/scan-secrets src/] --> S[加载 SKILL.md]
    S --> D[注入 git diff 文件清单]
    D --> P[执行 scan_secrets.py]
    P --> J[输出 JSON 命中]
    J --> M[Claude 解读: 分级+脱敏+建议]
    M --> R[用户收到安全报告]