PacketPirate

一款无头、可脚本化、基于命令行的 MITM 代理，专为 Windows 系统上的网络流量拦截、分析与修改而设计。它的工作方式类似于业界标准的图形界面代理，但针对自动化环境、无头运行以及与开发工作流的集成进行了优化。

注意：这是一个使用 Node.js 实现的独立、零依赖工具。

概述

• PacketPirate 是一款系统级网络拦截工具。通过利用 Windows HTTP 代理设置，它可以捕获你机器上任何应用程序的流量——包括 Web 浏览器（Chrome、Edge）、CLI 工具（curl、git）以及桌面应用（Spotify、VS Code、Discord）。

• 全局系统拦截：捕获来自任何遵循系统代理的进程的 HTTP/HTTPS 流量。

• 进程感知：精确定位是哪个应用在产生流量。

• 动态规则引擎：可通过 JSON 配置，对匹配的流量执行特定操作（例如，令牌提取、请求日志记录）。

• 完整流量日志：能够导出完整的请求与响应体（HTML、JSON、二进制）以供分析。

• 无头架构：完全通过 CLI 运行，适用于后台服务和自动化测试流水线。

• 自定义证书管理：包含用于生成并信任自签名根 CA 以进行 HTTPS 解密的实用程序。

安装

先决条件

• Node.js（v14 或更高版本）
• Windows 10/11（系统代理自动化功能必需）
• PowerShell（用于证书管理脚本）

设置

克隆仓库并初始化环境：

# 1. Generate local SSL certificates
npm run setup

# 2. Trust the generated Root CA
npm run trust
# Note: Requires administrative approval to add the certificate to the Trusted Root Store.

用法

启动代理服务器：

npm start

这将启动标准 CLI 界面。

CLI 操作

交互式菜单提供以下控制选项：

1. 扫描进程：列出具有已建立网络连接的活跃进程。支持将流量过滤到特定 PID（例如，仅监控 code.exe）。
2. 切换过滤器：启用/禁用特定的监控子系统：
   • API URL 扫描：记录请求的 API 端点。
   • Header 转储：将完整请求头输出到控制台。
   • Token 搜索：基于启发式规则检测 Authorization 头中的 Bearer 令牌。
   • 完整流量转储：将所有流量（请求头 + 完整请求体）捕获到结构化的 jsonl 日志文件中。
3. 启动代理：将服务器绑定到第一个可用端口（默认 8080），并配置 Windows 系统代理。
4. 生成规则：帮助快速创建新的拦截模式。

配置

拦截逻辑在 config/rules.json 中定义。该文件允许对流量处理进行持久化配置。

Schema（结构说明）：

{
  "rules": [
    {
      "name": "Description of rule",
      "host": "hostname.match",
      "urlPattern": "regex_pattern",
      "action": "log | save_token",
      "outputFile": "path/to/output.txt",
      "tokenFilter": "regex_filter"
    }
  ]
}

示例：

{
    "rules": [
        {
            "name": "Test API",
            "host": "jsonplaceholder.typicode.com",
            "action": "save_token",
            "outputFile": "test_tokens.txt"
        }
    ]
}

技术细节

架构

该工具采用双服务器架构：

1. 代理服务器：处理初始的 CONNECT 隧道请求，并执行主机过滤。
2. MITM 服务器：使用动态生成的 CA 解密 HTTPS 流量，根据规则引擎检查负载，并将请求转发到上游。

网络处理

• 端口管理：自动检测 EADDRINUSE 错误并递增端口号，直到找到空闲端口。
• 系统代理：通过 PowerShell 直接操作注册表，以在系统范围内强制应用代理设置。
• 清理：实现了 SIGINT/SIGTERM 处理程序，确保退出时还原代理设置，避免网络连接问题。

证书生命周期与安全性

该工具依赖双证书模型进行 HTTPS 拦截：

1. 根 CA 生成：npm run setup 创建自签名根 CA（PacketPirateRoot）。
   • 逻辑：使用 PowerShell 的 New-SelfSignedCertificate 生成有效期为 5 年的密钥对。
   • 导出：密钥将以密码 "headless" 导出到 src/certs/server.pfx（PKCS#12 格式）。
2. 信任建立：npm run trust 将此根 CA 注入 Windows 的 CurrentUser\Root 存储中。
   • 安全范围：通过针对 CurrentUser 而非 LocalMachine，我们将信任范围限制在当前用户配置文件内，从而降低系统级风险。
   • 浏览器接受度：Chrome、Edge 和 IE 会继承此信任存储。Firefox 需要单独开启 security.enterprise_roots.enabled 选项才会遵循 Windows 信任存储。
3. 移除：npm run untrust 提供干净的清理拆除。
   • 识别：脚本通过其唯一的 FriendlyName（"PacketPirateRoot"）定位证书，确保不会触碰其他用户证书。
   • 验证：移除后会执行检查，确认注册表中不再存在该证书的指纹（thumbprint）。

🎓 教学：我们是如何构建它的

本项目是使用 Node.js 进行系统编程的一个实际示例。它超越了典型的 Web 服务器，在更底层与操作系统和网络协议栈进行交互。

架构

participant App as Application (VS Code)
participant OS as Windows OS
participant Proxy as Proxy Server
participant MITM as MITM Server
participant Web as Internet

Note over App,Proxy: 1. Plain HTTP Tunneling
App->>Proxy: CONNECT google.com:443
Proxy-->>App: 200 Connection Established

Note over Proxy,MITM: 2. The "Hand-Off" Trick
Proxy->>MITM: Pipe socket data (raw encrypted bytes)

Note over App,MITM: 3. TLS Handshake and Decryption
MITM-->>App: ServerHello (signed by local root CA)
App->>MITM: Encrypted request (GET /)

Note over MITM: 4. Interception Logic
MITM->>MITM: Decrypt → Inspect headers → Log

Note over MITM,Web: 5. Upstream Forwarding
MITM->>Web: New HTTPS request (GET /)
Web-->>MITM: Response
MITM-->>App: Response

核心概念

1. "双服务器"模式

Node.js 自带的标准 http 模块很难在同一服务器实例上同时处理 CONNECT 方法（用于 HTTPS 隧道）和普通 HTTPS 流量。

• 服务器 A（Net/HTTP）：监听 8080 端口。它处理初始的 CONNECT 请求，并充当一个哑 TCP 管道。
• 服务器 B（HTTPS）：仅存在于内存中（或运行在随机端口上）。它持有私钥。
• 技巧所在：当服务器 A 收到连接时，它会将 socket "移交"给服务器 B。服务器 B 会认为自己刚刚收到一个新连接，并开始 SSL 握手。这让我们可以无缝地解密流量。

2. 进程归属（netstat 技巧）

我们如何知道哪个应用在发送流量？TCP 数据包本身并没有携带"进程 ID"标签。

• 临时端口：每个出站连接都使用一个随机的高位端口号（例如 54321）。
• 关联：我们调用 netstat -ano 来查找端口 54321 对应的 PID。
• 优化：对每个数据包都执行此操作会很慢，因此我们会缓存结果，或仅在必要时进行检查。

3. 流分叉（Stream Forking）

我们使用 Node.js Streams 来高效处理数据。我们不会等待完整的 10MB 响应下载完成后再显示它，而是对流进行"分叉"：

• 管道 1：流向客户端（保证应用继续正常工作）。
• 管道 2：流向日志记录器（以便保存到磁盘）。 这是通过 PassThrough 流实现的，能够以极低的额外延迟进行实时监控。

许可证

GNU GPL v3.0