# phantom-stream

**Repository Path**: eblog/phantom-stream

## Basic Information

- **Project Name**: phantom-stream
- **Description**: PhantomStream is a dynamic tracking and protection tool for PDF documents, validated through real-world red team-blue team exercises. This project has continuously iterated and optimized in authentic attack-defense environments, ultimately establishing a multi-anchor defense system with practical value.
- **Primary Language**: Go
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-10
- **Last Updated**: 2026-03-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PhantomStream - PDF 动态追踪与防护系统

## 项目简介

PhantomStream 是一个通过**红蓝对抗演练**实战验证的 PDF 文档动态追踪与防护工具。本项目在真实的攻防对抗环境中不断迭代优化，最终形成了一套具有实战价值的多锚点防御体系。

### 核心价值

- ✅ **实战验证**：经过真实红蓝对抗演练测试，抵御了多轮清洗攻击
- ✅ **多锚点防御**：采用 4 层独立锚点策略，任一锚点存活即可追踪
- ✅ **明文震慑**：Visual 水印直接展示追踪信息，产生心理威慑效果
- ✅ **极致轻量**：采用图像栅格化技术支持 Unicode 水印，无需内嵌大字体，二进制体积骤减
- ✅ **完整 Unicode 支持**：支持全球语言字符（中日韩等），自动适配最佳渲染策略

---

## 防护工具能力

### ✅ 支持的功能

1. **多锚点嵌入**（4 层独立防御）
   - **Attachment 锚点**：伪装为合法 PDF 附件
   - **SMask 锚点**：隐藏在图像软蒙版数据中
   - **Content 锚点**：嵌入页面内容流的不可见字符
   - **Visual 锚点**：可见水印，明文展示追踪信息

2. **加密与验证**
   - AES-256-GCM 加密保护追踪信息
   - 支持自定义加密密钥（32 字节）
   - 自动验证与解密提取

3. **跨平台支持**
   - macOS / Linux / Windows 完全兼容
   - 不依赖系统字体（字体已内嵌）
   - 单一二进制文件，开箱即用

4. **灵活的验证模式**
   - **Auto 模式**：首个成功锚点即停止（快速验证）
   - **All 模式**：逐一验证所有锚点（完整诊断）

### ⚠️ 限制与约束

1. **PDF 规范依赖**
   - 仅支持标准 PDF 格式文件
   - 需要 PDF 包含可嵌入内容（页面、图像等）

2. **清洗抵抗边界**
   - 可抵御常规清洗工具（PDFtk、Ghostscript 等）
   - 无法抵御彻底重建 PDF 结构的深度清洗

3. **Visual 水印特性**
   - 水印可见，用户可感知
   - 适用于震慑场景，不适合完全隐蔽追踪

---

## 能力评估

| 评估维度       | 等级  | 说明                                      |
| -------------- | ----- | ----------------------------------------- |
| **隐蔽性**     | ⭐⭐⭐⭐  | 3 个隐藏锚点 + 1 个可见锚点，综合隐蔽性强 |
| **抗清洗能力** | ⭐⭐⭐⭐  | 经实战验证，抵御常规清洗攻击              |
| **震慑效果**   | ⭐⭐⭐⭐⭐ | Visual 水印直接展示追踪信息，心理威慑显著 |
| **可移植性**   | ⭐⭐⭐⭐⭐ | 跨平台支持，无外部依赖                    |
| **易用性**     | ⭐⭐⭐⭐  | CLI 工具，简单易用                        |
| **完整性**     | ⭐⭐⭐⭐⭐ | 多锚点冗余，容错性强                      |

**综合评分：4.7/5.0**

---

## 文档导航

### 核心文档

- 📘 [**攻防演练联合报告**](docs/PHANTOM_STREAM_JOINT_REPORT.md) - 红蓝对抗全过程记录与技术分析
- 📗 [**Defender 技术文档**](defender/README.md) - 防护工具技术实现与架构说明
- 📙 [**用户使用手册**](defender/USER_MANUAL.md) - 工具安装、使用与常见问题

### 技术方案

详细的技术方案文档位于 [`defender/docs/`](defender/docs/) 目录：
- Phase 1-9 各阶段技术演进文档
- 多锚点防御策略设计
- 加密与验证流程说明

---

## 目录结构

```
phantom-stream/
├── README.md                          # 本文件 - 项目总览
├── docs/
│   └── PHANTOM_STREAM_JOINT_REPORT.md # 红蓝对抗联合报告
├── defender/                          # 🛡️ 防护工具（核心）
│   ├── README.md                      # Defender 技术文档
│   ├── USER_MANUAL.md                 # 用户手册
│   ├── bin/
│   │   └── phantom-guard              # 编译后的可执行文件
│   ├── injector/                      # 锚点注入与提取逻辑
│   │   ├── anchor_*.go                # 各锚点实现
│   │   ├── assets/                    # 嵌入资源（字体文件）
│   │   └── font_embed.go              # 字体嵌入逻辑
│   ├── docs/                          # 技术方案文档
│   └── Makefile                       # 构建脚本
└── attacker/                          # ⚔️ 攻击脚本（实验用途）
    ├── clean_*.sh                     # PDF 清洗脚本
    └── test_*.py                      # 测试脚本
```

---

## 关于 `attacker/` 目录

`attacker/` 目录包含一些**实验性的反抗脚本**，用于：
- 模拟红队清洗攻击
- 测试防护工具的鲁棒性
- 研究 PDF 处理工具的行为特征

**重要说明**：
- ⚠️ 这些脚本**不是工具的正式功能**，仅供研究与测试
- ⚠️ 使用这些脚本需要遵守相关法律法规
- ⚠️ 请勿将这些脚本用于非授权的攻击行为

---

## 快速开始

### 1. 编译工具

```bash
cd defender
make build
```

### 2. 嵌入追踪信息

```bash
./bin/phantom-guard sign \
  -f document.pdf \
  -m "UserID:12345" \
  -k "your-32-byte-encryption-key!!"
```

### 3. 验证追踪信息

```bash
./bin/phantom-guard verify \
  -f document_signed.pdf \
  -k "your-32-byte-encryption-key!!" \
  --mode=all
```

详细使用说明请参考 [用户手册](defender/USER_MANUAL.md)。

---

## 项目演进历程

本项目经历了 **9 个阶段**的红蓝对抗迭代：

1. **Phase 1-3**：基础附件锚点 → 被清洗 → 优化伪装
2. **Phase 4-6**：引入 SMask 锚点 → 多锚点防御初见成效
3. **Phase 7-8**：Content 锚点加入 → 三重保险体系
4. **Phase 9**：Visual 明文水印 → 震慑效果显著提升

完整对抗过程详见 [联合报告](docs/PHANTOM_STREAM_JOINT_REPORT.md)。

---

## 技术栈

- **语言**：Go 1.24+
- **PDF 处理**：pdfcpu v0.11.1
- **加密**：AES-256-GCM (crypto/aes)
- **图像处理**：golang.org/x/image (用于水印栅格化)
- **CLI 框架**：Cobra

---

## ⚠️ 重要免责声明

### 使用限制

本项目（PhantomStream）是一个**学术研究项目**，仅用于以下合法目的：

✅ **合法用途**：
- 安全研究与技术学习
- 网络安全教育与培训
- 在**明确授权**的红蓝对抗演练中使用
- 合法的文档版权保护与追溯
- 企业内部合规的文档管理

❌ **严格禁止**：
- 未经授权对他人文档进行追踪或监控
- 侵犯他人隐私或违反数据保护法规
- 用于非法目的或恶意活动
- 在未获得明确许可的情况下部署于生产环境
- 任何可能违反所在地区法律法规的行为

### 法律责任

1. **用户责任**：
   - 使用者必须遵守所在国家/地区的所有适用法律法规
   - 使用者对使用本工具的一切行为及后果承担全部法律责任
   - 使用者应自行评估使用本工具的合法性和合规性

2. **开发者免责**：
   - 本项目作者和贡献者不对任何直接或间接损失承担责任
   - 本项目作者和贡献者不对任何滥用或非法使用行为负责
   - 本项目按"现状"提供，不提供任何明示或暗示的担保

3. **数据隐私**：
   - 使用本工具处理包含个人信息的文档时，必须遵守 GDPR、CCPA 等数据保护法规
   - 在使用 Visual 水印功能时，需告知文档接收者相关追踪机制
   - 建议在使用前咨询法律顾问，确保合规使用

### 许可协议

本项目采用 [MIT License](LICENSE) 开源协议，但使用者仍需遵守上述免责声明。

**使用本软件即表示您已阅读、理解并同意上述所有条款。如不同意，请立即停止使用。**

📜 **详细免责声明**: 请阅读 [LEGAL_DISCLAIMER.md](LEGAL_DISCLAIMER.md) 了解完整的法律条款和合规指导。

---

## 联系方式

如有技术问题或建议，请通过以下方式联系：
- 提交 Issue 或 Pull Request
- 参考文档中的技术说明自行排查

---

**最后更新**：2025-12-13  
**项目状态**：✅ 稳定版本（已通过红蓝对抗验证）