AI PII 扫描器

一款用于发现 PostgreSQL 数据库和 Jira 项目中个人身份信息（PII）的内部安全工具

概述

AI PII 扫描器是一款全面的、以安全为核心的工具，专为应用安全和隐私团队设计，用于发现和编目 PII。它支持两种扫描目标：

• PostgreSQL 数据库 — 跨应用模式进行列级 PII 发现
• Jira — 实时或定时扫描问题和评论，以发现意外的 PII 泄露

检测采用三层流水线：

• 基于正则的检测 — 针对电子邮件、电话、SSN、信用卡等的确定性模式
• NER/ML 检测 — 使用 Microsoft Presidio 或 spaCy 进行实体识别（姓名、地点、日期）
• 可选的 LLM 分类 — 使用自托管模型进行模糊自由文本分析

主要特性

• 多层 PII 检测 — 结合正则、ML 和可选 LLM，实现全面覆盖
• Jira 集成 — 通过轮询或实时 webhook 扫描新问题和评论
• 智能例外过滤器 — 抑制预期内容：@mentions 和公司电子邮件地址
• 带时间戳的报告 — Jira 扫描结果在每次运行时自动保存为带日期的 JSON 或 CSV 文件
• 安全优先设计 — 只读数据库访问，无外部 API 调用，最小化 PII 保留
• 智能采样 — 分析代表性数据样本，以最小化性能影响
• 全面的审计追踪 — 每次扫描都记录配置、时间戳和模型版本
• 隐私安全的日志记录 — 在所有日志和存储样本中自动脱敏 PII

安全与隐私

关键：本工具专为安全、受控环境中的内部使用而设计。

安全控制	实现方式
防止数据外泄	无第三方 API 调用；LLM 端点必须自托管
最小权限访问	只读数据库角色，对应用数据无写入权限
PII 最小化	发现结果仅存储元数据和高度脱敏的样本
审计追踪	所有扫描都记录谁/什么/何时/如何的详细信息
安全日志记录	结构化日志，自动脱敏 PII 字段
加密传输	所有数据库连接要求 SSL/TLS
Webhook 验证	对传入的 Jira 事件进行 HMAC-SHA256 签名验证

目录

• 安装 — 数据库模式扫描
• 安装 — Jira 扫描
• 配置
• 使用 — 数据库扫描
• 使用 — Jira 集成
• 架构
• 检测方法
• 数据库模式
• 示例
• 故障排除
• 高级主题
• 贡献

---

安装 — 数据库模式扫描

如果你想扫描 PostgreSQL 数据库中各列的 PII，请使用此方式。

步骤 1 — 基础安装

# Clone the repository
cd PIIHunter

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Download spaCy NER model (~800MB)
python -m spacy download en_core_web_lg

步骤 2 — 创建只读数据库角色

以 PostgreSQL 超级用户身份运行以下命令：

CREATE ROLE pii_scanner_readonly WITH LOGIN PASSWORD 'your_secure_password';
GRANT CONNECT ON DATABASE your_database TO pii_scanner_readonly;
GRANT USAGE ON SCHEMA public, app_data TO pii_scanner_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public, app_data TO pii_scanner_readonly;

步骤 3 — 配置环境

cp .env.example .env
# Fill in DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD

步骤 4 — 初始化元数据模式

创建用于存储扫描结果的 security_pii 模式。运行一次：

python -m pii_scanner.cli init-schema

步骤 5 — 运行你的第一次扫描

# Preview candidate columns (no data read)
python -m pii_scanner.cli discover

# Run PII detection
python -m pii_scanner.cli scan --sample-size 1000

# View results
python -m pii_scanner.cli report

随时验证连接性

python -m pii_scanner.cli test-connection

---

安装 — Jira 扫描

如果你想扫描 Jira 问题和评论中意外暴露的 PII，请使用此方式。

首先需要完成基础安装（上述步骤 1）。如果你只想进行 Jira 扫描，则不需要数据库设置（步骤 2–4）。

子章节 A — REST API（轮询）

按需轮询 Jira 以获取最近 N 小时内的活动。无需服务器。

步骤 1 — 基础安装（如果尚未完成）

cd PIIHunter
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python -m spacy download en_core_web_lg

步骤 2 — 生成 Jira API 令牌

1. 前往 https://id.atlassian.com → Security → API tokens
2. 点击 Create API token，为其命名，复制令牌

步骤 3 — 配置环境

cp .env.example .env

编辑 .env 并填写你的 Jira 详细信息：

JIRA_URL=https://yourcompany.atlassian.net
[email protected]
JIRA_API_TOKEN=your_api_token_here

# Optional — leave empty to scan all projects
# JIRA_PROJECT_KEYS=ENG,OPS,SUPPORT

# Emails from these domains will NOT be flagged as PII
COMPANY_EMAIL_DOMAINS=yourcompany.com

步骤 4 — 测试连接

验证您的凭据，列出可访问的项目，并获取近期问题的样本：

python -m pii_scanner.cli jira test

预期输出：

Testing connection to https://yourcompany.atlassian.net...

  Auth          ✓  logged in as Jane Smith ([email protected])
  Projects      ✓  3 accessible: ENG, OPS, SUPPORT
  Project ENG   ✓  accessible

  Recent issues (no time filter):
    ENG-101  Fix login timeout on mobile
    ENG-100  Update password policy

如果失败，请检查你的 API token，并确认 JIRA_EMAIL 与生成该 token 的账户一致。

第 5 步 — 运行扫描

# Scan last 24 hours
python -m pii_scanner.cli jira scan

# Custom lookback window
python -m pii_scanner.cli jira scan --hours 48

---

子章节 B — Webhook（实时）

启动一个 HTTP 服务器，接收 Jira 事件并在事件到达时立即扫描。需要可公开访问的端点。

步骤 1 — 基础安装 + REST API 设置（先完成子章节 A 的步骤 1–4）

步骤 2 — 安装 webhook 依赖

pip install fastapi uvicorn

步骤 3 — 将 webhook 配置添加到 .env

# Secret used to verify requests genuinely come from Jira
JIRA_WEBHOOK_SECRET=your_webhook_secret
JIRA_WEBHOOK_PORT=8080

步骤 4 — 启动 webhook 服务器

python -m pii_scanner.cli jira webhook

# Custom port
python -m pii_scanner.cli jira webhook --port 9090

步骤 5 — 在 Jira 中注册 webhook

1. 在 Jira 中转到 项目设置 → Webhooks → 创建 webhook
2. 将 URL 设置为 http://yourserver:8080/webhook
3. 在 事件 下选择：
   • Issue → created
   • Comment → created
4. 将密钥设置为与 .env 中的 JIRA_WEBHOOK_SECRET 匹配
5. 保存

现在，Jira 会针对每个新问题和评论向你的服务器发送 POST 请求。扫描器会立即处理每一个请求。

可用端点：

端点	用途
POST /webhook	接收 Jira 事件
GET /health	确认服务器正在运行

生产环境注意事项：不要将 uvicorn 直接暴露到互联网。请参阅高级主题下的生产环境 Webhook 设置部分。

---

配置

所有配置均通过 .env 中的环境变量进行管理。复制 .env.example 即可开始。

数据库连接

DB_HOST=localhost
DB_PORT=5432
DB_NAME=your_database
DB_USER=pii_scanner_readonly
DB_PASSWORD=your_secure_password
DB_SSLMODE=require

扫描选项

# Schemas to scan (comma-separated)
SCHEMAS_TO_SCAN=public,app_data,customer_data

# Schemas to exclude (comma-separated)
SCHEMAS_TO_EXCLUDE=pg_catalog,information_schema,pg_toast

# Rows to sample per column
SAMPLE_SIZE=1000

# Batch size for streaming
BATCH_SIZE=500

检测设置

# Minimum confidence threshold (0.0-1.0)
CONFIDENCE_THRESHOLD=0.5

# Enable/disable detection layers
ENABLE_REGEX_DETECTION=true
ENABLE_NER_DETECTION=true
ENABLE_LLM_DETECTION=false  # Only with self-hosted LLM

LLM 配置（可选）

仅与自托管端点一起使用。切勿将其指向公共 API。

LLM_ENDPOINT=http://your-internal-llm.company.local:8000/v1
LLM_API_KEY=your_private_key
LLM_MODEL=llama-2-7b

Jira 集成

# Jira connection
JIRA_URL=https://yourcompany.atlassian.net
[email protected]
JIRA_API_TOKEN=your_jira_api_token   # generate at id.atlassian.com

# Projects to watch — leave empty to scan ALL accessible projects
# JIRA_PROJECT_KEYS=ENG,OPS,SUPPORT

# Emails from these domains are NOT flagged as PII (your internal addresses)
COMPANY_EMAIL_DOMAINS=yourcompany.com,internal.yourcompany.com

# Webhook server settings (only needed for real-time mode)
# JIRA_WEBHOOK_SECRET=your_webhook_secret
JIRA_WEBHOOK_PORT=8080

日志记录

LOG_LEVEL=INFO   # DEBUG, INFO, WARNING, ERROR
LOG_FORMAT=json  # json or console

---

使用方法 — 数据库扫描

初始化 Schema

创建 security_pii 元数据 schema。首次设置时运行一次：

python -m pii_scanner.cli init-schema

发现列

预览按 PII 可能性排序的候选列——不读取任何数据：

# Discover all columns
python -m pii_scanner.cli discover

# Specific schemas only
python -m pii_scanner.cli discover --schemas public,customer_data

# Exclude schemas
python -m pii_scanner.cli discover --exclude test_data,staging

运行 PII 扫描

# Default scan (uses .env settings)
python -m pii_scanner.cli scan

# Custom sample size
python -m pii_scanner.cli scan --sample-size 5000

# High-confidence columns only (faster, skips ambiguous columns)
python -m pii_scanner.cli scan --high-confidence-only

# Specific schemas
python -m pii_scanner.cli scan --schemas public --sample-size 2000

生成报告

# Latest scan report
python -m pii_scanner.cli report

# Specific scan run
python -m pii_scanner.cli report --run-id 5

# Limit number of findings shown
python -m pii_scanner.cli report --limit 100

其他命令