# fiddler

**Repository Path**: peisonghai/fiddler

## Basic Information

- **Project Name**: fiddler
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-20
- **Last Updated**: 2026-02-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# GoFiddler - 网络抓包调试工具

GoFiddler 是一个使用 Go 语言开发的网络抓包调试工具，功能类似于 Fiddler，支持 HTTP/HTTPS/WebSocket 代理抓包和系统级 TCP/UDP 抓包。

## 文档

- [需求文档](docs/requirements.md) - 详细的功能需求和规格说明
- [设计文档](docs/design.md) - 系统架构和模块设计
- [使用指南](docs/user-guide.md) - 安装、配置和使用说明

## 功能特性

- **HTTP/HTTPS 代理**：作为代理服务器捕获 HTTP 和 HTTPS 流量
- **HTTPS 解密**：通过 MITM（中间人攻击）方式解密 HTTPS 流量
- **WebSocket 支持**：捕获和显示 WebSocket 消息
- **系统级抓包**：使用 libpcap 捕获原始 TCP/UDP 数据包
- **请求修改**：支持断点调试和请求/响应修改
- **规则引擎**：灵活的 URL 匹配和修改规则
- **Web UI**：现代化的 Web 界面，实时显示抓包数据
- **跨平台**：支持 Windows、macOS 和 Linux

## 安装

### 前置要求

- Go 1.21 或更高版本
- **Windows**: 安装 [Npcap](https://npcap.com/)（系统级抓包需要）
- **Linux**: 安装 libpcap-dev
- **macOS**: 系统自带 libpcap

### 编译

```bash
# 克隆项目
git clone https://github.com/user/fiddler.git
cd fiddler

# 安装 Go 依赖
go mod tidy

# 构建前端（可选，但推荐）
cd web
npm install
npm run build
cd ..

# 编译 Go 程序
go build -o gofiddler ./cmd/fiddler

# 运行
./gofiddler
```

### 开发模式

前端开发时可以使用 Vite 开发服务器：

```bash
# 终端 1：启动后端
go run ./cmd/fiddler

# 终端 2：启动前端开发服务器
cd web
npm run dev
```

前端开发服务器会自动代理 API 请求到后端。

## 使用方法

### 启动服务器

```bash
./gofiddler
./gofiddler.exe
```

启动后会显示：
- 代理地址：默认 `127.0.0.1:8888`
- Web UI 地址：默认 `http://127.0.0.1:8088`（以 `configs/config.yaml` 的 `server.port` 为准）

### 配置代理

#### 浏览器配置

1. 打开浏览器设置
2. 搜索"代理"
3. 设置 HTTP/HTTPS 代理为 `127.0.0.1:8888`

#### 系统代理（Windows）

1. 打开 设置 → 网络和 Internet → 代理
2. 手动设置代理
3. 地址：`127.0.0.1`，端口：`8888`

#### 命令行工具

```bash
# Linux/macOS
export http_proxy=http://127.0.0.1:8888
export https_proxy=http://127.0.0.1:8888

# Windows PowerShell
$env:http_proxy = "http://127.0.0.1:8888"
$env:https_proxy = "http://127.0.0.1:8888"
```

### 安装 CA 证书

要解密 HTTPS 流量，需要安装 GoFiddler 的 CA 证书：

1. 访问 `http://127.0.0.1:8088`
2. 点击"下载证书"按钮
3. 按照提示安装证书到系统信任库

说明：如果你修改了 `server.port`，请把上面的 `8088` 替换为你的实际端口。

#### Windows
```
双击证书 → 安装证书 → 本地计算机 → 受信任的根证书颁发机构
```

#### macOS
```
双击证书 → 添加到钥匙串 → 信任 → 始终信任
```

#### Linux
```bash
sudo cp GoFiddler_CA.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates
```

## 配置文件

配置文件位于 `configs/config.yaml`：

```yaml
# GoFiddler 配置文件

server:
  # Web UI 和 API 服务器端口
  port: 8088
  # 绑定地址
  host: "127.0.0.1"

proxy:
  # 代理服务器端口
  port: 8888
  # 绑定地址
  host: "127.0.0.1"
  # 是否启用 HTTPS MITM
  enable_mitm: true

capture:
  # 是否启用系统级抓包
  enabled: false
  # 网络接口名称（留空自动选择）
  interface: ""
  # 抓包过滤器 (BPF 语法)
  filter: ""

cert:
  # CA 证书目录
  dir: "./certs"
  # CA 证书有效期（天）
  ca_validity_days: 3650
  # 服务器证书有效期（天）
  cert_validity_days: 365

storage:
  # 数据库文件路径
  db_path: "./data/sessions.db"
  # 最大会话保存数量
  max_sessions: 10000

log:
  # 日志级别: debug, info, warn, error
  level: "info"
  # 日志文件路径（留空输出到控制台）
  file: ""

# 系统代理（仅 Windows 支持自动设置/恢复）
system_proxy:
  # 启动后自动启用系统代理（指向 GoFiddler 代理地址）
  enabled: false
  # 系统代理模式: "http" 或 "pac"
  mode: "http"
  # 退出时恢复原系统代理设置（建议保持 true）
  restore_on_exit: true
  # 启动时若检测到上次遗留状态文件（可能异常退出），先自动恢复
  restore_on_startup: true
  # HTTP 模式 bypass（分号分隔；兼容旧格式）
  bypass: "localhost;127.0.0.1;<local>"
  # HTTP 模式 bypass（列表；优先于 bypass 字符串）
  http_bypass:
    - localhost
    - 127.*
    - <local>
  # PAC URL（支持 http(s):// 或 file://；留空使用内置 /proxy.pac）
  pac_url: ""
  # PAC 脚本内容（留空使用默认模板；支持占位符 %mixed-host%/%mixed-port% 等）
  pac_script: ""
  # 状态文件路径；留空则默认放到 sessions.db 同目录（data/sysproxy_state.json）
  state_path: ""
```

配置说明（与 Web UI “设置”一致）：
- **推荐修改方式**：Web UI 右上角 **“设置”** 中修改并保存，会写回 `configs/config.yaml`。
- **保存后的生效规则**：`proxy.enable_mitm`、`storage.max_sessions` 会尝试**热生效**；其余配置通常需要**重启 GoFiddler**。
- **保存后的生效规则**：`proxy.enable_mitm`、`proxy.mitm_*`、`storage.max_sessions` 会尝试**热生效**；其余配置通常需要**重启 GoFiddler**。
- **系统代理的“立即应用”**：当系统代理已启用时，修改 `system_proxy.mode/bypass/http_bypass/pac_url/pac_script` 后，需要在设置中点击 **“立即应用配置”**（或重新启用系统代理）才能同步到系统代理。

## API 接口

### 会话管理

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /api/sessions | 获取会话列表 |
| GET | /api/sessions/:id | 获取会话详情 |
| DELETE | /api/sessions/:id | 删除会话 |
| DELETE | /api/sessions | 清空所有会话 |

### 规则管理

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /api/rules | 获取所有规则 |
| POST | /api/rules | 添加规则 |
| PUT | /api/rules/:id | 更新规则 |
| DELETE | /api/rules/:id | 删除规则 |

### 断点管理

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /api/breakpoints | 获取断点配置 |
| POST | /api/breakpoints/config | 添加断点配置 |
| POST | /api/breakpoints/enabled | 启用/禁用断点 |
| GET | /api/breakpoints/pending | 获取等待处理的断点 |
| POST | /api/breakpoints/:id/resolve | 处理断点 |

### WebSocket

连接 `/api/ws` 可以实时接收会话更新。

## 项目结构

```
fiddler/
├── cmd/fiddler/          # 程序入口
├── internal/
│   ├── api/              # REST API 和 Web UI
│   ├── capture/          # 系统级抓包
│   ├── cert/             # 证书管理
│   ├── modifier/         # 请求修改和断点
│   ├── proxy/            # HTTP/HTTPS 代理
│   └── session/          # 会话存储
├── configs/              # 配置文件
├── certs/                # 证书目录
└── web/                  # 前端源码（可选）
```

## 技术栈

- **后端**: Go, Gin, GORM, goproxy, gopacket
- **前端**: Vue 3, Vite, Tailwind CSS, Pinia
- **数据库**: SQLite
- **实时通信**: WebSocket

## 注意事项

1. **权限**: 系统级抓包可能需要管理员/root 权限
2. **证书安全**: CA 证书私钥应妥善保管，不要泄露
3. **隐私**: 仅用于合法的调试目的，不要用于监控他人

## 许可证

MIT License