lameiro0x/osint-veil
GitHub: lameiro0x/osint-veil
一个本地隐私代理网关，在 OSINT/安全审计工具与 Claude API 之间对敏感数据和标识符进行自动匿名化处理，确保只有脱敏文本被发送到云端。
Stars: 0 | Forks: 0
# osint-veil
这是一个本地的隐私网关，部署在你的 OSINT/CTI 工具与 Claude 的 API 之间。它接收 prompt 或工具的输出结果，**检测敏感信息，对标识符进行匿名化/化名替换，移除机密数据**，将映射关系在本地（加密）保存，并且**仅向 Claude 发送安全版本的数据**。
**从这里开始：** [`docs/VISION.md`](docs/VISION.md)（它是什么以及为什么有用，包含示例） · [`docs/DESIGN.md`](docs/DESIGN.md)（架构与不变式）。
## 1. 它是什么
专为配合 Claude 进行 pentesting / OSINT 而设计（例如，从 OpenOSINT 或其他支持 OpenAI 兼容 endpoint 的工具中使用）。目标是实现**最大程度的隐私保护**：确保不向 API 或任何其他地方泄露有关客户端、主机或 pentester 的任何信息。
关于模型训练：**Anthropic 的 API 不会使用通过 API 发送的数据进行训练**（标准保留策略；可通过向 Anthropic 申请实现零保留）。尽管如此，这个 proxy 更进一步，只发送已经过匿名化处理的文本，且不包含任何用户元数据。
## 2. 架构
```
herramienta OSINT / script
│ (formato OpenAI chat completions)
▼
┌───────────────────────────────────────────┐
│ Privacy Proxy (FastAPI, 127.0.0.1:8000) │
│ │
│ 1. auth local (Bearer) │
│ 2. sanitizer: │
│ - elimina secretos → SECRET_REMOVED │
│ - tokeniza ids → EMAIL_001 ... │
│ 3. storage cifrado por case_id (Fernet) │
│ 4. convierte OpenAI → Anthropic Messages │
└───────────────┬────────────────────────────┘
│ solo texto anonimizado
▼
api.anthropic.com (Claude)
```
模块 (`proxy/`):
| 文件 | 职责 |
| ------------------ | ------------------------------------------------------ |
| `config.py` | 从 `.env` 读取 settings 及各案例的 config (YAML/JSON)。 |
| `sanitizer.py` | 移除机密数据 + 确定性 token 化。 |
| `storage.py` | 按 `case_id` 存储的 mappings 和 audit log，支持可选加密。|
| `claude_client.py` | OpenAI → Anthropic Messages API，无元数据。 |
| `app.py` | FastAPI Endpoints。 |
| `keygen.py` | `python -m proxy.keygen` 生成加密密钥。 |
## 3. 安装
```
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```
## 4. 配置 `.env`
```
cp .env.example .env
# 生成加密密钥并将其粘贴到 PROXY_ENCRYPTION_KEY
python -m proxy.keygen
```
| 变量 | 用途 |
| --------------------- | ------------------------------------------------------------ |
| `ANTHROPIC_API_KEY` | 你的 Anthropic 密钥（仅在调用 Claude 时使用）。 |
| `ANTHROPIC_BASE_URL` | `https://api.anthropic.com`。 |
| `ANTHROPIC_MODEL` | 默认模型（`claude-sonnet-4-6`；你也可以使用 opus）。 |
| `PROXY_LOCAL_API_KEY` | Proxy 在 `Authorization: Bearer ...` 中要求的密钥。 |
| `PROXY_CASE_ID` | 如果请求未发送 `case_id`，则使用的默认案例。 |
| `PROXY_STORAGE_PATH` | mappings/logs 文件夹（已加入 gitignore）。 |
| `PROXY_ENCRYPTION_KEY`| 用于加密本地存储的 Fernet 密钥。 |
| `PROXY_MODE` | `strict`（默认）、`balanced` 或 `reporting`。 |
| `PROXY_CASES_PATH` | 包含各案例 YAML/JSON 的文件夹。 |
### 各案例配置
创建 `cases/.yaml`（参见 `cases/cliente_a_2026.yaml`）：
```
case_id: cliente_a_2026
provider: claude
model: claude-sonnet-4-6
mode: strict
rehydrate_output: false
sensitive_domains:
- cliente.com
- cliente.local
sensitive_keywords:
- vpn
- intranet
- payroll
```
## 5. 如何启动
```
./run.sh
# 或：
uvicorn proxy.app:app --host 127.0.0.1 --port 8000
```
## 6. 测试 `/health`
```
curl http://127.0.0.1:8000/health
# {"status":"ok"}
```
## 7. 测试 `/privacy/sanitize`
```
curl -X POST http://127.0.0.1:8000/privacy/sanitize \
-H "Authorization: Bearer change-me" \
-H "Content-Type: application/json" \
-d '{
"case_id": "cliente_a_2026",
"text": "El email juan.perez@cliente.com aparece en vpn.cliente.com con token ghp_xxxxxxxxx"
}'
```
响应：
```
{
"sanitized_text": "El email EMAIL_001 aparece en SUBDOMAIN_001 con token SECRET_REMOVED",
"findings": [
{"type": "GITHUB_TOKEN", "replacement": "SECRET_REMOVED"},
{"type": "EMAIL", "token": "EMAIL_001"},
{"type": "SUBDOMAIN", "token": "SUBDOMAIN_001"}
]
}
```
## 8. 作为 OpenAI 兼容 endpoint 使用
将你的工具指向 `http://127.0.0.1:8000/v1`，并使用 `PROXY_LOCAL_API_KEY` 作为 API key。
```
export OPENAI_BASE_URL=http://127.0.0.1:8000/v1
export OPENAI_API_KEY=change-me
```
直接调用：
```
curl -X POST http://127.0.0.1:8000/v1/chat/completions \
-H "Authorization: Bearer change-me" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-sonnet-4-6",
"case_id": "cliente_a_2026",
"messages": [
{"role": "system", "content": "Eres un analista de seguridad"},
{"role": "user", "content": "Analiza estos hallazgos: admin@cliente.com en 10.0.0.5"}
],
"max_tokens": 2000
}'
```
Proxy 会对消息进行 sanitize，仅使用 tokens 调用 Claude，并返回 OpenAI 格式（`choices[].message.content`）的响应。
### `dry-run` 模式（不调用 Claude）
添加 `"dry_run": true` 可查看哪些内容会被过滤，而无需消耗 API 调用：
```
curl -X POST http://127.0.0.1:8000/v1/chat/completions \
-H "Authorization: Bearer change-me" -H "Content-Type: application/json" \
-d '{"case_id":"cliente_a_2026","dry_run":true,
"messages":[{"role":"user","content":"admin@cliente.com en 10.0.0.5"}]}'
```
### 其他 endpoints
| Endpoint | 用途 |
| ------------------------------------- | ---------------------------------------------------- |
| `POST /privacy/sanitize` | 对文本进行匿名化处理，并返回 findings 和标注。 |
| `POST /privacy/rehydrate` | 将 tokens 还原为原值（仅在允许的情况下）。 |
| `GET /privacy/mappings/{case_id}` | 案例的 Mappings（仅在本地）。 |
| `GET /privacy/audit-log/{case_id}` | 记录哪些类型被过滤及其次数。 |
| `GET /privacy/review-queue/{case_id}` | 高相关性的发现（非阻塞式审查）。 |
| `POST /osint/run` | 启动安全且自主的 OSINT（client-side 循环）。 |
| `GET /osint/report/{case_id}` | Markdown 报告（`?rehydrate=true` 仅限本地）。 |
## CLI（推荐的审计用法）
```
# 对目标进行安全且自主的 OSint；将重构报告写入 LOCAL
python -m proxy.cli audit --case cliente_a_2026 --target cliente.com
# 重新生成案例报告（使用 --anon 以保留 tokens）
python -m proxy.cli report --case cliente_a_2026
# 查看审查队列（高相关性发现）
python -m proxy.cli review --case cliente_a_2026
```
集成的 OSINT 工具都是被动的，且不需要外部二进制文件（`dns_resolve`, `http_headers`）。你可以通过在 `proxy/gateway.py` 中注册一个 `ToolSpec` 来添加你自己的工具（amass, nmap 等）。
## Egress control（在生产环境中是强制性的）
软件层（`proxy/egress.py`）会阻止工具直接访问 Anthropic，但**真正的保障是在网络层**：运行 `deploy/egress_lockdown.sh` 以确保只有 proxy 进程能够与 API 通信。如果没有这一步，外部二进制文件可能会打开自己的 socket。
模式 (`PROXY_EGRESS`)：
| 模式 | 自主 OSINT 的行为 |
| --------- | ---------------------------------------------------------------- |
| `off` | 不检查任何内容。 |
| `warn` | 在日志中警告 egress 未被强制执行（默认）。 |
| `enforce` | **拒绝启动**，除非确认网络锁定已生效（`PROXY_EGRESS_LOCKED=1`，由部署脚本 / Docker 设置）。 |
生产环境建议：`PROXY_EGRESS=enforce` + `deploy/egress_lockdown.sh`。
## 9. 模式
| 模式 | 行为 |
| ----------- | ---------------------------------------------------------------------- |
| `strict` | 对**所有**标识符进行 Token 化（包括域名和公网 IP）。默认选项。非常适合真实审计场景。 |
| `balanced` | 移除机密数据，并对 emails/内部 IP 进行 token 化，但允许**未**标记为敏感的域名和公网 IP 通过。 |
| `reporting` | 类似于 `balanced`，并在设置了 `rehydrate_output: true` 时允许对输出进行 rehydrate。 |
## 10. 检测内容
**机密数据（将被移除，绝不存储）：** `sk-`, `ghp_`, `github_pat_`,
`gho_/ghs_/ghu_`, `AKIA…`, JWT (`eyJ…`), `Authorization: Bearer …`,
`Cookie:` / `Set-Cookie:`, `client_secret=`, `password=`, `passwd=`,
`access_token=`, `refresh_token=`, PEM 私钥 (`BEGIN … PRIVATE KEY`)。
**标识符（将被 Token 化，并附带相关性提示）：** email → `EMAIL_001`，
域名 → `DOMAIN_001`，子域名 → `SUBDOMAIN_001`，内部 IP →
`INTERNAL_IP_001`，公网 IP → `PUBLIC_IP_001`，存储库 → `REPO_001`，私有
URL → `URL_001`，GUID → `APP_ID_001`/`TENANT_ID_001`（取决于上下文），服务账户 →
`SERVICE_ACCOUNT_001`，人员 → `PERSON_001`，内部路径 →
`PATH_001`，案例关键词 → `KEYWORD_001`。
## 11. 测试
```
pytest -q
```
覆盖范围包括：emails、敏感域名和内部 IP 的 token 化；移除 GitHub tokens、JWTs 和 Bearer；确认机密数据**不会**存储在 mappings 中；确认同一个 email 在同一个案例中保持相同的 token；确认不同案例具有独立的 mappings；确认 `/privacy/sanitize` 工作正常；静态加密。
## 12. 限制
- **人员姓名**：检测能力有限。会对其在案例 config 的 `sensitive_names` 中列出的姓名进行 token 化，如果你安装了 spaCy 及其模型（`pip install spacy && python -m spacy download es_core_news_sm`），也可以通过自动 NER 识别（**可选**依赖，如果存在则自动激活）。未安装 spaCy 时，仅识别已知姓名。不过，**服务账户**确实会被检测到（`svc_*`, `DOMINIO\\usuario`, `*$` 等） → `SERVICE_ACCOUNT_001`。
- **Tenant ID vs App ID**：两者均为 GUIDs。系统通过**上下文**进行区分（例如附近有 `app`/`client_id` 等词汇 → `APP_ID`，否则为 `TENANT_ID`）。这是一种启发式方法，并非万无一失。
- **`DOMAIN` vs `SUBDOMAIN`** 的区分取决于标签数量（≥3 = subdomain），而不是基于复合 TLDs（如 `co.uk`），因此某些类似 `ejemplo.co.uk` 可能会被标记为 subdomain。
- Sanitization 是基于 **regex** 的，而非语义识别：未涵盖格式的敏感数据可能会漏网。在审计前，请务必在 `dry-run` 模式下进行检查。
- OpenAI→Anthropic 转换支持包含文本内容的 `system`/`user`/`assistant`。暂不支持 tool-calls 和图像（**TODO**）。
## 13. 残余风险
- **Regex 的假阴性**：格式异常的标识符可能会被发送给 Claude。请使用 `dry-run` 并扩充 `sensitive_keywords`/`sensitive_domains`。
- **Mappings = 敏感数据**：`proxy_data/` 包含真实数值（如果配置了 `PROXY_ENCRYPTION_KEY` 则为加密形式）。请妥善保护它，切勿上传至 git（已在 `.gitignore` 中排除）。如果没有加密密钥，数据将以明文形式保存。
- **Rehydrate**：将 tokens 还原为真实数值。仅在设置了 `rehydrate_output: true` 或 `force=true` 时允许，且绝不应用于发送给 Claude 的内容 —— 仅用于本地的最终报告响应。
- **Proxy 本地密钥**：任何拥有 `PROXY_LOCAL_API_KEY` 的人都可以使用该 proxy 并读取 mappings。请修改默认值，不要共享。
- **信任但要验证**：该 proxy 极大地减少了泄露面，但检查发送内容的最终责任仍在于 pentester。
标签：AI安全网关, AV绕过, ESC4, FastAPI, OSINT, 数据脱敏, 本地代理, 网络安全, 逆向工具, 隐私保护