# CatchApi

**Repository Path**: lusasky0323/catch-api

## Basic Information

- **Project Name**: CatchApi
- **Description**: CatchApi 是一款基于 Python 的轻量级桌面端网络流量拦截与分析工具。它通过集成本地代理核心（mitmproxy），能够根据用户预设的规则精准捕获 HTTP/HTTPS 报文，并提供优雅的可视化界面进行逻辑分析与展示。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-12-20
- **Last Updated**: 2025-12-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CatchApi - Python 可视化网络请求拦截器

![CatchApi](https://img.shields.io/badge/Python-3.8+-blue.svg)
![License](https://img.shields.io/badge/License-MIT-green.svg)

CatchApi 是一款基于 Python 的轻量级桌面端网络流量拦截与分析工具。它通过集成本地代理核心（mitmproxy），能够根据用户预设的规则精准捕获 HTTP/HTTPS 报文，并提供优雅的可视化界面进行逻辑分析与展示。

## ✨ 主要特性

- **🚀 零残留关闭**: 窗口关闭时自动恢复系统代理设置，不影响日常上网。
- **🎨 优质 UI 体验**: 使用 Tkinter 构建的现代化界面，支持高 DPI 缩放，提供深浅交替的栅格展示及柔和的选中交互效果。
- **🎯 精准过滤**: 基于 `config.json` 的精确 URL 匹配（智能忽略查询参数），只显示你关心的业务请求。
- **🔐 HTTPS 全量解密**: 支持 HTTPS 流量抓取，一键安装证书，轻松解密加密报文。
- **📂 深度解析**: 支持报文体 JSON 格式化显示，提供一键复制及 JSON 数据导出功能。

## 🛠️ 核心原理

1.  **代理核心**: 后台运行 `mitmproxy` 引擎，拦截并解析网络流量。
2.  **流量接管**: 启动拦截时自动配置 Windows WinINet 代理设置，确保流量流经代理。
3.  **智能筛选**: 根据配置文件对流经的 URL 进行正则或精确匹配，命中规则后推送到 GUI 展示。
4.  **补充信息处理**: 支持自定义逻辑处理器（`handlers.py`），根据响应内容生成业务特定的补充信息。

## 🚀 快速开始

### 1. 环境准备

确保您的系统已安装 Python 3.8+。下载本项目后，在根目录执行：

```bash
pip install -r requirements.txt
```

### 2. 配置文件说明 (`config.json`)

在程序同目录下创建或修改 `config.json`。

```json
{
  "enable_https": false, 
  "api_whitelist": [
    {
      "url": "http://example.com/api/user",
      "bizdomain": "取值：url对应的业务领域",
      "expectinfo": "取值：期望补充的信息内容",
      "expecttype": "取值：expectinfo对应的type"
    }
  ]
}
```
- `enable_https`: 是否开启 HTTPS 拦截（设为 `true` 后，首次拦截会提示安装证书）。
- `url`: 必填。待拦截的 API 地址（仅匹配 URL 路径部分）。
- `bizdomain`: 可选。业务域描述。
- `expectinfo`: 可选。预期在该报文中提取的信息描述。
- `expecttype`: 可选。用于 `handlers.py` 中分发不同业务提取逻辑的类型标识。

### 3. 操作指南

1.  **启动**: 执行 `python main.py`。
2.  **配置**: 确保 `config.json` 已填入你想要观察的 API。
3.  **开始**: 点击 **"开始拦截"**。按钮变红表示拦截已激活，系统代理已自动开启。
4.  **捕获**: 正常操作目标软件或浏览器，匹配到的请求将实时展现在左侧列表中。
5.  **分析**: 点击列表项查看右侧的 **"补充信息"**、**"请求报文"** 或 **"响应报文"**。
6.  **退出**: 点击 **"停止拦截"** 或直接关闭窗口，程序将自动还原系统代理。

## 📂 项目结构

```text
catchApi/
├── main.py            # 程序入口 (DPI 适配、GUI 循环)
├── config.json        # 用户配置文件 (白名单、开关)
├── src/
│   ├── gui/           # UI 相关组件
│   ├── core/          # 拦截核心逻辑 (Mitmproxy Addons)
│   ├── utils/         # 系统工具 (代理控制、证书安装)
│   └── config.py      # 配置管理类
└── requirements.txt   # 第三方依赖
```

## ❓ 常见问题

- **Q: 为什么浏览器提示“连接不安全”？**
    - A: 请在 `config.json` 中确认 `enable_https` 为 `true`，并按照提示安装 mitmproxy 根证书。
- **Q: 拦截开启后无法上网？**
    - A: 请检查 `main.py` 是否异常退出。正常退出或手动点击“停止拦截”会自动修复代理设置。如遇意外，可前往“Windows 设置 -> 代理”手动关闭。
- **Q: 无法捕获某些 API 请求？**
    - A: 确认 `config.json` 中填写的 `url` 是对应请求的地址，且不包含 `?` 及其后的查询参数。