Professor-Archbishop/tracefish

# Tracefish

一款使用纯 Kotlin 编写的、终端优先的 HAR 文件分析与提取工具。

## 概述 **tracefish** 允许开发者和分析师完全通过命令行，对记录的 Web 浏览器网络流量进行切片、检查和提取数据。它可编译为单个、可移植的独立 JAR 文件，使其易于运行并集成到本地开发者工作流中。 ## 功能 * **弹性解析：** 将嘈杂的浏览器 HAR 导出文件映射为干净、强类型的结构，同时忽略特定于系统/浏览器的扩展。 * **请求检查与过滤：** 按域名主机、HTTP 方法、响应状态或路径片段查看、搜索和过滤网络事务。 * **详细提取：** 检查完整的 header payload 并自动解码和格式化输出 JSON 响应体。 * **延迟时间线图表：** 渲染水平的 ASCII 瀑布时间线，显示请求执行的重叠和延迟瓶颈。 * **客户端代码生成：** 将任何记录的网络请求转换为可运行的 `curl`、Python `requests` 或原生 Kotlin `java.net.http` 客户端代码片段。 * **二进制资产导出：** 提取并解码 base64 编码的响应资产（如图片、PDF 或字体），并将它们直接写入您的磁盘。 * **流量指标：** 生成关于总传输数据、平均请求延迟和状态码分布的高阶分析，并提供打印完整记录的选项。 * **自动脱敏：** 立即移除敏感的 header 和 cookie，以安全地共享已清理的日志。 ## 安装与设置 ### 前置条件 * **Java Runtime：** 您的机器上必须安装 Java 21 或更高版本。 ### 快速下载与运行 使用 `wget` 直接从此存储库中提取已编译的 JAR 文件： ``` wget https://github.com/Professor-Archbishop/tracefish/raw/main/tracefish.jar ``` *(或者，如果您偏好使用 `curl`)：* ``` curl -L https://github.com/Professor-Archbishop/tracefish/raw/main/tracefish.jar -o tracefish.jar ``` 下载完成后，您可以使用 `java -jar` 直接运行任何命令： ``` java -jar tracefish.jar -f samples/example.har inspect ``` ## 从任意位置运行 tracefish（可选） 要使用 `tracefish` 命令从任何目录运行 JAR 文件，您可以在您的终端配置文件中设置一个 shell alias： 1. **将 JAR 保存到本地文件夹：** mkdir -p ~/.local/bin mv tracefish.jar ~/.local/bin/ 2. **添加 alias 配置：** * **对于 Zsh（macOS 和现代 Linux 上的默认项）：** echo 'alias tracefish="java -jar $HOME/.local/bin/tracefish.jar"' >> ~/.zshrc source ~/.zshrc * **对于 Bash（旧版 Linux 设置中的标准配置）：** echo 'alias tracefish="java -jar $HOME/.local/bin/tracefish.jar"' >> ~/.bashrc source ~/.bashrc 3. **直接运行命令：** tracefish -f samples/example.har inspect ## 命令参考 在以下所有命令中，请将 `traffic.har` 替换为目标 HAR 文件的路径。 ### 1. 查看所有请求 (`inspect`) 渲染一个样式化的表格，显示所有记录的连接（索引、方法、URL、状态、大小、时间）。 ``` java -jar tracefish.jar -f traffic.har inspect ``` ### 2. 过滤事务 (`filter`) 按域名主机、HTTP 动词、状态码或路径片段隔离请求。 ``` java -jar tracefish.jar -f traffic.har filter --method POST java -jar tracefish.jar -f traffic.har filter --host fonts.gstatic.com ``` ### 3. 渲染并发时间线 (`timeline`) 生成一个 ASCII 水平瀑布图，说明请求的并发和瓶颈。 ``` java -jar tracefish.jar -f traffic.har timeline ``` ### 4. 提取详细的 header 与响应体 (`extract`) 使用列表索引或部分 URL 匹配来查看请求的 header 和格式化的 JSON 响应体。 ``` java -jar tracefish.jar -f traffic.har extract 0 java -jar tracefish.jar -f traffic.har extract "/api/v1/auth" ``` ### 5. 生成客户端代码片段 (`codegen`) 构建可复制粘贴的 `curl`、`python` 或 `kotlin` 请求代码。 ``` java -jar tracefish.jar -f traffic.har codegen 5 --lang python ``` ### 6. 导出二进制资产 (`export-asset`) 解码并提取 base64 编码的响应 payload（如图标或图片）并将其保存到您的机器上。 ``` java -jar tracefish.jar -f traffic.har export-asset 12 -o output_image.png ``` ### 7. 分析性能与流量指标 (`stats`) 显示上传/下载量、平均响应时间、最活跃的顶级主机域以及命中次数最多的 endpoint 路径。 ``` # 精简版 dashboard java -jar tracefish.jar -f traffic.har stats # 完整的、未过滤的 domain 和 path 清单 java -jar tracefish.jar -f traffic.har stats -a ``` ### 8. 跨追踪搜索 (`grep`) 扫描请求 URL、请求体和响应体以查找字符串或 regex，并输出格式化的文本匹配项。 ``` java -jar tracefish.jar -f traffic.har grep "sodar" ``` ### 9. 清理日志 (`scrub`) 编辑（遮盖）敏感的身份验证密钥、bearer token、密码和 cookie，并将安全结果保存到文件中。 ``` java -jar tracefish.jar -f traffic.har scrub -o clean_trace.har ``` ### 10. 审计凭据与 cookie (`headers` / `cookies`) 显示整个追踪记录中涉及安全敏感的属性。 ``` java -jar tracefish.jar -f traffic.har headers java -jar tracefish.jar -f traffic.har cookies ``` ### 11. 编译 OpenAPI schema 骨架 (`export`) 将您捕获的流量记录编译为 OpenAPI 3.0 YAML 规范骨架。 ``` java -jar tracefish.jar -f traffic.har export -o openapi.yaml ``` ## 许可证 基于 Apache-2.0 许可证分发。更多信息请参见 `LICENSE`。 ## 开发者 * **作者：** Dennis Nganga (**professor Archbishop**) * **GitHub：** [Professor-Archbishop](https://github.com/Professor-Archbishop) * **联系方式：** beyonddennisdreams@gmail.com * **代码库：** [https://github.com/Professor-Archbishop/tracefish](https://github.com/Professor-Archbishop/tracefish)

标签：HAR, JS文件枚举, Kotlin, SOC Prime, 开发工具, 文档结构分析, 网络流量分析