# piihound

**Repository Path**: tomlen/piihound

## Basic Information

- **Project Name**: piihound
- **Description**: PII scanner for codebases: idcard MOD11-2 / Luhn bankcard / mask / baseline incremental gate. Single-file, zero-dependency.
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-28
- **Last Updated**: 2026-10-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🐕 piihound

> **代码库里的个人信息（PII）安检犬。** 扫描、掩码、增量门禁——单文件，零依赖，3 秒出结果。

简体中文 | [English](README_EN.md)

```bash
curl -fsSL https://gcore.jsdelivr.net/gh/tomlen045/piihound@main/piihound.py -o piihound.py
python3 piihound.py selftest   # 18/18 PASS 再用
```

**一个 Python 文件（约 700 行），无 pip install，macOS / Linux 通用。**

## 为什么

每个开发团队都见过这一幕：测试库里导出了一份真实用户数据，`users_dump.csv` 拷进仓库调样式，调完顺手就提交了。密钥进仓有 secretweeper 堵着，**人的信息进仓没有人在看**——而《个人信息保护法》第 4 条把姓名、身份证号、手机号、行踪信息全都列为个人信息，监管通报里「测试环境未脱敏」出现的次数一点不比「密钥硬编码」少。

piihound 补上这道缺：

| 命令 | 干什么 |
|---|---|
| `scan` | 扫描（默认 staged，CI 建议 --full），新增身份证/银行卡命中退出码 1 |
| `mask` | 格式保留掩码：`138****5678`，文件照常能跑 |
| `selftest` | 18 项自测，合成数据，不碰真实 PII |

## 和 secretweeper 的分工

| | secretweeper | piihound |
|---|---|---|
| 管什么 | 机器凭据（AK/SK、token、私钥） | 人的信息（身份证、手机号、银行卡、邮箱、IP） |
| 泄的是什么 | 机器的身份 | 用户的身份 |
| 一起用 | 出仓前双安检：先扫机器的，再扫人的 | |

## 为什么误报低：官方校验位说了算

网上九成「身份证正则」是 17 位数字加个 X，连生日合法都不验，随手一个订单号就命中。piihound 只认**官方校验算法**：

- 身份证：**GB 11643-1999 MOD 11-2** 校验码（加权因子 × 模 11 查表）
- 银行卡：**ISO/IEC 7812-1 Luhn** 算法
- 手机号：第二位限 3-9、前后非数字边界
- 内网 IP 默认豁免（RFC1918/CGNAT 是基础设施，不是用户数据；`--with-private-ip` 可开）

校验不过的一律不算数。宁漏报给的测试号，不误报伤开发。

## 增量门禁：存量问题不清零也能先止血

存量代码里躺着几百条历史 PII，一夜清完不现实——但不能一直拦着所有人合代码。baseline 模式只拦**新增**：

```bash
# 第一次：把存量命中固化成基线（一次性）
python3 piihound.py scan --full --baseline .piihound_baseline.json --update-baseline

# 之后每次提交（pre-commit / CI 都行）：只拦新增，存量放行
python3 piihound.py scan --staged --baseline .piihound_baseline.json
```

基线文件里只有「类别+路径+掩码」的 SHA-256 单向指纹，**不含任何明文 PII**，可以放心进仓。

## 真机实测

```
$ python3 piihound.py selftest
  PASS  身份证校验位：合成真号过 / 改一位不过
  PASS  银行卡 Luhn：过验卡号 HIGH / 错一位不命中
  ...（省略 14 行）
18/18 PASS
```

100 文件偏态仓库实测：94 个干净文件（塞满时间戳、订单号、内网 IP 等近失噪声）+ 6 个埋雷文件，13 处 PII 全捕获、干净文件零误伤。

## 注意

- HIGH = 过官方校验位，可直接拦；MED = 形态匹配（手机号/邮箱/IP），建议人工过目
- 掩码预览永远只有 `110101********0038` 这种形态——报告本身不会变成新的泄漏源
- 15 位老身份证无校验位，按「日期合法+形态」判 HIGH，已是最大诚实