ctardy/mirageia
GitHub: ctardy/mirageia
LLM API 智能假名代理，在请求发送前自动检测并替换 PII，响应时还原原始数据，确保敏感信息不泄露给外部 AI 服务。
Stars: 0 | Forks: 0
# MirageIA
**LLM API 智能化假名代理。**
API 永远不会看到你的真实数据 —— 它看到的只是幻象。
```
Your app --> MirageIA (local proxy :3100) --> LLM API (Anthropic / OpenAI)
│ │
├─ Detects PII (regex + ONNX) │
├─ Pseudonymizes before sending │
└─ Restores in the response <────────┘
```
## 问题背景
当你通过 API 使用 Claude、ChatGPT 或任何其他 LLM 时，你的数据会以明文形式传输到外部服务器：姓名、电子邮件、IP 地址、API 密钥、电话号码……这些敏感数据在你不知情的情况下被暴露。
## 解决方案
MirageIA 位于你的应用程序和 LLM API 之间。它会自动检测敏感数据，将其替换为一致的虚假值，并在响应中还原原始数据。
| 原始数据 | API 接收到的数据 | 你取回的数据 |
|---|---|---|
| `jean.dupont@acme.fr` | `alice@example.com` | `jean.dupont@acme.fr` (已还原) |
| `192.168.1.22` | `10.0.84.12` | `192.168.1.22` (已还原) |
| `06 12 34 56 78` | `06 47 91 28 53` | `06 12 34 56 78` (已还原) |
| `sk-abc123def456...` | `sk-xR9mK2pL7wQ4...` | `sk-abc123def456...` (已还原) |
LLM 处理的是虚假但一致的数据 —— 它的响应同样有效，而你的数据从未离开过你的机器。
## 快速开始
### 安装
从 [GitHub Releases](https://github.com/ctardy/mirageia/releases/latest) 下载适用于你操作系统的二进制文件：
```
# Linux / macOS
curl -sSfL https://github.com/ctardy/mirageia/releases/latest/download/mirageia-linux-x86_64.tar.gz \
| tar xz -C ~/.local/bin/
# 或从源码构建 (需要 Rust 1.75+)
git clone https://github.com/ctardy/mirageia.git && cd mirageia && cargo build --release
```
在 Windows 上，从 [Releases](https://github.com/ctardy/mirageia/releases/latest) 页面下载 `mirageia-windows-x86_64.zip`。
### 设置
```
# 向导将引导您：port, LLM providers, whitelist, shell
mirageia setup
```
### 使用
```
# 启动 proxy
mirageia
# 通过 proxy 使用 Claude Code (仅限此会话)
mirageia wrap -- claude
# 实时监控请求 (在另一个终端中)
mirageia console
# Web dashboard
# 在浏览器中打开 http://localhost:3100/dashboard
```
**单次会话激活** —— `mirageia wrap` 会在启用代理的情况下启动你的命令，而不会修改你的 shell。当命令退出时，代理将不再被使用：
```
mirageia wrap -- claude # Claude Code protected
mirageia wrap -- python app.py # Python script protected
claude # Claude Code direct (no proxy)
```
### 临时禁用
```
# 选项 1：Passthrough mode (proxy 在不进行匿名化的情况下中继)
mirageia proxy --passthrough
# 选项 2：停止 proxy — 不影响正常启动的应用
# 只有通过 `mirageia wrap` 启动的应用才会经过 proxy
```
### 验证
```
# Health check
curl http://localhost:3100/health
# -> {"status":"ok","passthrough":false,"pii_mappings":0}
# 测试请求 (需要 Anthropic API key)
curl -X POST http://localhost:3100/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "content-type: application/json" \
-d '{
"model": "claude-sonnet-4-20250514",
"max_tokens": 100,
"messages": [{"role": "user", "content": "My email is jean@acme.fr and my IP is 192.168.1.50"}]
}'
```
在 MirageIA 日志中，你会看到检测到并已假名化的 PII。发送给 Anthropic 的请求将既不包含原始电子邮件，也不包含 IP。
## 配置
MirageIA 无需配置即可工作（零配置）。如需自定义，请创建 `~/.mirageia/config.toml`：
```
[proxy]
listen_addr = "127.0.0.1:3100" # Listening address
log_level = "info" # debug, info, warn, error
add_header = false # Add X-MirageIA: active header to requests
fail_open = true # Forward request if pseudonymization fails
passthrough = false # Passthrough mode: relay without pseudonymizing
[detection]
confidence_threshold = 0.75 # Confidence threshold (0.0-1.0)
whitelist = [ # Terms to never pseudonymize
"localhost",
"127.0.0.1",
"Thomas Edison",
]
```
环境变量优先于配置文件：
| 变量 | 描述 |
|---|---|
| `MIRAGEIA_LISTEN_ADDR` | 监听地址（例如 `0.0.0.0:3100`） |
| `MIRAGEIA_ANTHROPIC_URL` | Anthropic 基础 URL |
| `MIRAGEIA_OPENAI_URL` | OpenAI 基础 URL |
| `MIRAGEIA_LOG_LEVEL` | 日志级别 |
| `MIRAGEIA_PASSTHROUGH` | 启用透传模式（任意值 = 启用） |
## 检测的 PII 类型
正则检测器 (v1) 覆盖固定格式的 PII：
| 类型 | 示例 | 生成的假名 |
|---|---|---|
| Email | `jean@acme.fr` | `alice@example.com` |
| IPv4 | `192.168.1.50` | `10.0.84.12` |
| IPv6 | `2001:db8::1` | `fd00::a1b2:c3d4` |
| 电话 | `06 12 34 56 78` | `06 47 91 28 53` (保留格式) |
| 信用卡 | `4111 1111 1111 1111` | `4892 7631 0458 2173` (Luhn 有效) |
| IBAN | `FR7612345678901234567890` | `FR8398765432109876543210` |
| API 密钥 / token | `sk-abc123def456...` | `sk-xR9mK2pL7wQ4...` (保留前缀) |
| 社会保障号 | `1 85 07 75 123 456 78` | `2 91 03 69 847 215 34` |
上下文 ONNX 检测器（v2，开发中）将增加对人名、邮政地址的检测，并能理解上下文（历史课中的 "Thomas Edison" = 不屏蔽）。
## 架构
```
src/
├── main.rs CLI (proxy / setup / detect / wrap / console)
├── lib.rs Public modules
├── config/
│ └── settings.rs AppConfig, TOML + env loading
├── proxy/
│ ├── server.rs axum handler, full pipeline, dashboard
│ ├── router.rs Anthropic / OpenAI routing by path
│ ├── client.rs Upstream HTTP client (reqwest)
│ ├── extractor.rs JSON extraction/rebuild per provider
│ └── error.rs Proxy error types
├── detection/
│ ├── regex_detector.rs PII detector via regex (v1)
│ ├── types.rs PiiType, PiiEntity, label_to_pii_type
│ ├── model.rs ONNX model (feature-gated, v2)
│ ├── tokenizer.rs HuggingFace tokenizer, segmentation
│ ├── postprocess.rs Softmax, BIO decode, entity merging
│ └── error.rs Detection errors
├── pseudonymization/
│ ├── generator.rs Pseudonym generator by type
│ ├── replacer.rs Text replacement (offsets)
│ ├── depseudonymizer.rs De-pseudonymization (AhoCorasick)
│ └── dictionaries.rs Embedded first/last names
├── mapping/
│ ├── table.rs Bidirectional table (SHA-256 + AES-256-GCM)
│ ├── crypto.rs Encryption/decryption, zeroization
│ └── error.rs Mapping errors
└── streaming/
├── sse_parser.rs Parse/rebuild SSE Anthropic/OpenAI
└── buffer.rs Buffer for pseudonyms split between tokens
```
### 处理流水线
```
INCOMING REQUEST
│
▼
[JSON Extraction] <- extractor.rs (Anthropic/OpenAI text fields)
│
▼
[PII Detection] <- regex_detector.rs (emails, IPs, phones, CC, IBAN, keys)
│ + whitelist filtering
▼
[Pseudonymization] <- replacer.rs (descending positions)
│ + generator.rs (consistent pseudonyms by type)
│ + mapping/table.rs (AES-256-GCM in memory)
▼
[Reconstruction] <- extractor.rs (rebuild JSON)
│
▼
[Forward] <- client.rs -> upstream API
│
▼
UPSTREAM RESPONSE
│
▼
[De-pseudonymize] <- depseudonymizer.rs (AhoCorasick, longest-first)
│ or buffer.rs (streaming SSE, split between tokens)
▼
CLIENT RESPONSE (original data restored)
```
## 测试
```
# 所有测试 (145)
cargo test
# 仅 Unit tests
cargo test --lib
# E2E tests (proxy + mock upstream)
cargo test --test e2e_proxy
# 特定模块测试
cargo test -- detection::regex_detector
cargo test -- mapping::crypto
cargo test -- pseudonymization
```
### 测试覆盖率
| 模块 | 测试数 | 覆盖范围 |
|---|---:|---|
| config | 6 | 默认配置, TOML 解析, 部分, 空, 透传 |
| proxy/router | 7 | Anthropic/OpenAI 路由, URL |
| proxy/extractor | 9 | JSON 提取/重建, 内容字符串/数组, 系统 |
| detection/types | 7 | 标签, 阈值, 别名, 显示 |
| detection/postprocess | 11 | Softmax, 提取, 合并, 多 token, 阈值 |
| detection/tokenizer | 5 | 分段, 重叠, 推进 |
| detection/regex_detector | 16 | Email, IP, 电话, 信用卡, IBAN, API 密钥, 白名单 |
| detection/model | 2 | 模型目录, 缺失文件 |
| detection/mod | 4 | 标签映射加载 |
| mapping/crypto | 6 | AES-256-GCM 往返, nonce, unicode |
| mapping/table | 8 | 双向, 并发, 唯一 ID |
| pseudonymization/generator | 13 | 所有 PII 类型, Luhn, 格式 |
| pseudonymization/replacer | 5 | 位置, 会话一致性 |
| pseudonymization/depseudonymizer | 6 | 往返, 最长优先 |
| streaming/sse_parser | 7 | Anthropic, OpenAI, DONE, 重建 |
| streaming/buffer | 7 | 拆分假名, 刷新 |
| **e2e** | **12** | **完整流水线, 透传, SSE 事件, 仪表盘** |
| **总计** | **145** | |
## 项目状态
| 组件 | 状态 | 备注 |
|---|---|---|
| 透明 HTTP 代理 | 完成 | axum, Anthropic/OpenAI 路由 |
| 正则 PII 检测 | 完成 | 8 种 PII 类型 |
| 可逆假名化 | 完成 | AES-256-GCM 映射 |
| 响应去假名化 | 完成 | 非流式 + SSE 缓冲 |
| TOML 配置 + 白名单 | 完成 | ~/.mirageia/config.toml |
| 故障开放 | 完成 | 错误时透传 |
| 透传模式 | 完成 | `--passthrough` / 配置 / 环境变量 |
| 单次会话激活 | 完成 | `mirageia wrap -- claude` |
| 监控控制台 | 完成 | `mirageia console` (实时 SSE) |
| Web 仪表盘 | 完成 | `/dashboard` 嵌入二进制文件 |
| Docker + 部署 | 完成 | Dockerfile, 运维指南, Apache 反向代理 |
| E2E 测试 | 完成 | 145 项测试 |
| 上下文 ONNX 检测 | 结构化 | 代码就绪, ONNX Runtime 受 MSVC 工具链阻塞 |
| Tauri 仪表盘 | 计划中 | 第 4 阶段 |
## 文档
| | FR | EN |
|---|---|---|
| **安装** | [`docs/fr/installation.md`](docs/fr/installation.md) | [`docs/en/installation.md`](docs/en/installation.md) |
| **运维部署** | [`docs/fr/deploiement-ops.md`](docs/fr/deploiement-ops.md) | [`docs/en/deployment-ops.md`](docs/en/deployment-ops.md) |
| **分发** | [`docs/fr/distribution.md`](docs/fr/distribution.md) | [`docs/en/distribution.md`](docs/en/distribution.md) |
| **贡献** | [`docs/fr/contribution.md`](docs/fr/contribution.md) | [`docs/en/contributing.md`](docs/en/contributing.md) |
| 架构 | [`docs/fr/architecture/`](docs/fr/architecture/) | [`docs/en/architecture/`](docs/en/architecture/) |
| 安全 | [`docs/fr/securite/`](docs/fr/securite/) | [`docs/en/security/`](docs/en/security/) |
| 技术 | [`docs/fr/technique/`](docs/fr/technique/) | [`docs/en/technical/`](docs/en/technical/) |
| 研究 | [`docs/recherche/`](docs/recherche/) | |
| 工单 | [`docs/tickets/`](docs/tickets/) | |
## 许可证
MIT
标签：Anthropic, API 密钥保护, API 网关, ChatGPT 安全, CIS基准, Claude 安全, DLP, JSONLines, LLM 安全, ONNX, OpenAI, PII 检测, Rust, WSL, 中间件, 人工智能安全, 人工智能安全, 代理服务, 伪匿名化, 内存规避, 可视化界面, 合规性, 合规性, 敏感数据检测, 数据脱敏, 数据遮蔽, 数据防泄露, 本地代理, 网络安全, 网络安全, 网络流量审计, 通知系统, 防御绕过, 隐私保护, 隐私保护, 零信任