pii-masker/                       # Skill 名就是目录名
├── SKILL.md                      # 唯一必需的入口文件
├── scripts/
│   └── mask.py                   # 挂载的可执行脚本
└── references/
    └── patterns.md               # 渐进式披露：详细正则表放这里

mkdir -p .claude/skills/pii-masker/scripts
mkdir -p .claude/skills/pii-masker/references
cd .claude/skills/pii-masker

---
name: pii-masker
description: Scans log files, config files, and pasted text for PII and secrets (Chinese phone numbers, emails, 18-digit ID cards, IPv4 addresses, bank card numbers, API keys/tokens) and masks them in place or to a new file. Use when the user wants to sanitize/脱敏 logs before sharing, remove sensitive data from configs before committing, or generate a PII report. Supports dry-run preview.
---

# PII Masker（敏感信息脱敏器）

## 何时使用
用户想"把日志发出去前先脱敏""配置文件提交前清掉密钥""给这份文件打码"时主动调用。

## 如何使用
1. 默认干跑（dry-run）：只报告发现哪些敏感数据、各多少条，不改动文件。
2. 确认后，运行真正的打码，原地替换或输出到新文件。

## 调用脚本
对单个或一批文件执行脱敏：
- 干跑预览：`python3 scripts/mask.py --path <file-or-dir> --dry-run`
- 原地打码：`python3 scripts/mask.py --path <file-or-dir> --inplace`
- 输出到新文件：`python3 scripts/mask.py --path <file> --out <newfile>`

## 打码规则（概要）
- 手机号 → `138****1234`；邮箱 → `j***@example.com`；身份证 → `110101************`；
- IPv4 → `10.*.*.*`；银行卡 → `****-****-****-1234`；API 密钥 → `sk-************`。
- 完整正则与定制方法见 `references/patterns.md`。

## 行为准则
- 永远先 `--dry-run` 给用户看报告，得到确认再写盘。
- 不要去碰 `.git/` 目录和二进制文件。
- 对每条规则单独计数，输出汇总表。

#!/usr/bin/env python3
"""PII Masker —— 日志/配置敏感信息脱敏，纯标准库实现。"""
import argparse
import os
import re
import sys

# 每条规则：(名字, 编译好的正则, 打码函数)
RULES = [
    ("中国手机号", re.compile(r"(?<!\d)1[3-9]\d{9}(?!\d)"),
     lambda m: m.group()[:3] + "****" + m.group()[-4:]),

    ("邮箱", re.compile(r"[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}"),
     lambda m: m.group()[0] + "***@" + m.group().split("@", 1)[1]),

    ("18位身份证号", re.compile(
        r"(?<!\d)[1-9]\d{5}(?:19|20)\d{2}"
        r"(?:0[1-9]|1[0-2])(?:0[1-9]|[12]\d|3[01])\d{3}[\dXx](?!\d)"),
     lambda m: m.group()[:6] + "************"),

    ("IPv4地址", re.compile(r"(?<!\d)(?:\d{1,3}\.){3}\d{1,3}(?!\d)"),
     lambda m: m.group().split(".", 1)[0] + ".*.*.*"),

    ("银行卡号", re.compile(r"(?<!\d)(?:\d[ -]?){15,18}(?!\d)"),
     lambda m: "****-****-****-" + re.sub(r"[^\d]", "", m.group())[-4:]),

    ("API密钥/Token", re.compile(
        r"(?i)(?:api[_-]?key|access[_-]?token|secret|password|bearer|sk-)"
        r"\s*[:=]\s*['\"]?([A-Za-z0-9_\-]{16,})['\"]?"),
     lambda m: m.group(1)[0] + "-" + "*" * (len(m.group(1)) - 4)
               + m.group(1)[-4:] if m.lastindex else "********"),
]


def mask_text(text):
    """对一段文本执行全部规则，返回 (脱敏后文本, {规则名: 命中数})。"""
    counts = {}
    out = text
    for name, pat, fn in RULES:
        def replace(m, fn=fn, name=name):
            counts[name] = counts.get(name, 0) + 1
            return fn(m)
        out = pat.sub(replace, out)
    return out, counts


def iter_files(path):
    if os.path.isfile(path):
        yield path
        return
    for root, dirs, files in os.walk(path):
        dirs[:] = [d for d in dirs if d != ".git"]
        for f in files:
            full = os.path.join(root, f)
            if os.path.getsize(full) > 5 * 1024 * 1024:  # 跳过 >5MB
                continue
            try:
                with open(full, "rb") as fh:
                    fh.read(2048).decode("utf-8")  # 二进制则跳过
                yield full
            except (UnicodeDecodeError, OSError):
                continue


def main():
    ap = argparse.ArgumentParser(description="PII 脱敏器")
    ap.add_argument("--path", required=True, help="文件或目录")
    g = ap.add_mutually_exclusive_group(required=True)
    g.add_argument("--dry-run", action="store_true", help="只报告，不改写")
    g.add_argument("--inplace", action="store_true", help="原地替换")
    g.add_argument("--out", help="输出到新文件（仅单文件）")
    args = ap.parse_args()

    if args.out and os.path.isdir(args.path):
        sys.exit("--out 仅支持单文件")

    total = {}
    for fp in iter_files(args.path):
        with open(fp, encoding="utf-8") as fh:
            text = fh.read()
        new_text, counts = mask_text(text)
        if not counts:
            continue
        for k, v in counts.items():
            total[k] = total.get(k, 0) + v
        if args.dry_run:
            print(f"[预览] {fp}: {counts}")
        elif args.inplace:
            with open(fp, "w", encoding="utf-8") as fh:
                fh.write(new_text)
            print(f"[已脱敏] {fp}: {counts}")
        elif args.out:
            with open(args.out, "w", encoding="utf-8") as fh:
                fh.write(new_text)
            print(f"[输出] {args.out}: {counts}")

    print("\n===== 汇总 =====")
    if not total:
        print("未发现敏感信息。")
    for k, v in sorted(total.items(), key=lambda x: -x[1]):
        print(f"{k:12s} {v}")
    return 0 if total else 1


if __name__ == "__main__":
    sys.exit(main())

cat > /tmp/app.log <<'EOF'
2026-07-04 user=张三 phone=13912345678 login from 10.20.30.40
2026-07-04 [email protected] id=110101199001011234
2026-07-04 api_key = sk-abcdef0123456789abcdef0123456789
EOF

python3 .claude/skills/pii-masker/scripts/mask.py --path /tmp/app.log --dry-run

[预览] /tmp/app.log: {'中国手机号': 1, 'IPv4地址': 1, '邮箱': 1, '18位身份证号': 1, 'API密钥/Token': 1}

===== 汇总 =====
API密钥/Token     1
IPv4地址          1
18位身份证号      1
中国手机号        1
邮箱              1

2026-07-04 user=张三 phone=139****5678 login from 10.*.*.*
2026-07-04 email=z***@corp.com id=110101************
2026-07-04 api_key = sk-************6789

# 脱敏规则正则与定制指南

| 类型 | 正则（简版） | 打码样式 |
|------|-------------|---------|
| 手机号 | `1[3-9]\d{9}` | 138****1234 |
| 邮箱 | `[A-Za-z0-9._%+-]+@...` | j***@domain.com |
| 身份证 | `[1-9]\d{5}(19\|20)\d{2}...` | 110101************ |
| IPv4 | `(?:\d{1,3}\.){3}\d{1,3}` | 10.*.*.* |
| 银行卡 | `(?:\d[ -]?){15,18}` | ****-****-****-1234 |
| API密钥 | `(api_key\|token\|secret)...` | sk-************ |

## 新增规则
在 scripts/mask.py 的 RULES 列表追加一个三元组 (名字, 编译正则, 打码函数) 即可。

## 行业差异
- 金融：银行卡按 PCI-DSS 保留前6后4。
- 医疗：身份证按 HIPAA 等价规则保留前6。
- 海外：手机号改用 E.164 格式 `+\d{6,15}`。

# 1) 拉一段线上日志
kubectl logs my-svc-pod > raw.log

# 2) 干跑看报告（让 Claude 自动调用 pii-masker）
#    在 Claude Code 里直接说："扫描 raw.log 看有哪些敏感信息"
#    → 模型运行 mask.py --path raw.log --dry-run

# 3) 确认后输出脱敏版
python3 .claude/skills/pii-masker/scripts/mask.py \
  --path raw.log --out raw.masked.log

# 4) 安全外发
cat raw.masked.log

flowchart TD
    A[用户对话: 帮我脱敏这份日志] --> B{模型扫描所有 Skill 的 description}
    B -->|关键词命中 脱敏/PII| C[加载 pii-masker 的 SKILL.md 正文]
    B -->|未命中| Z[走普通对话流程]
    C --> D[默认执行 mask.py --dry-run]
    D --> E[输出命中报告: 手机号×3 邮箱×2 ...]
    E --> F{用户确认写盘?}
    F -->|是| G[执行 --inplace 或 --out]
    F -->|需要改规则| H[加载 references/patterns.md]
    H --> I[按指南修改 mask.py 的 RULES]
    I --> D
    G --> J[完成: 文件已脱敏可安全外发]