# Spilltea
[](https://ko-fi.com/anotherhadi)
- [什么是 Spilltea？](#what-is-spilltea)
- [法律免责声明](#legal-disclaimer)
- [功能](#features)
- [安装说明](#installation)
- [项目管理](#project-management)
- [配置](#configuration)
- [项目级配置](#per-project-configuration)
- [CLI 标志](#cli-flags)
- [插件系统](#plugin-system)
- [Vim / Neovim 集成](#vim--neovim-integration)
- [部署](#deployment)
- [技术栈](#tech-stack)
## 什么是 Spilltea？
Spilltea 是一个**原生于终端的 HTTP(S) 拦截代理**。它位于你的浏览器和互联网之间，让你无需离开终端即可检查、修改和重放流量。
它刻意保持极简。没有 Electron，没有浏览器，没有臃肿。只是一个快速、键盘驱动的工具，不会打扰你的工作流程。
## 法律免责声明
**本工具仅供教育目的及授权的安全测试使用。**
仅在你拥有或获得明确书面测试授权的系统和网络上使用 Spilltea。未经授权拦截网络流量可能违反当地法律（例如《计算机欺诈和滥用法》、GDPR 或你所在司法管辖区的同等立法）。
## 功能
- **拦截**：暂停传输中的请求和响应。在转发之前检查并修改它们（甚至可以使用你最喜欢的编辑器）。
- **HTTP 历史记录**：通过代理的每个请求都会被存储。浏览、搜索和过滤你的完整会话历史记录。
- **重放**：从历史记录中选择任何请求，根据需要进行修改，然后重新发送。适用于手动测试和快速迭代。
- **HTTPS 支持**（底层使用 go-mitmproxy）
- **类 Vim 导航**：整个界面完全由键盘驱动，拥有受 Vim 启发的快捷键。使用 `h/j/k/l` 进行移动，`gg`/`G` 跳转到顶部/底部，`/` 进行搜索，`q` 关闭面板等等。所有的键位绑定都可以通过配置文件完全自定义。
- 内置集成：
- **FFuf 导出**：直接从请求生成 ffuf 命令或配置，即刻开始 fuzzing。
- **cURL / HTTPie**：将任何请求作为 curl 或 httpie 命令复制到你的剪贴板。
- **Markdown 导出**：将任何请求及其响应导出为整洁的 Markdown 片段，可直接放入报告中。
## 安装说明
Go install
```
go install github.com/anotherhadi/spilltea/cmd/spilltea@latest
```
需要 Go 1.22+。二进制文件将被放置在 `$GOPATH/bin`（或 `~/go/bin`）中。
Nix（临时运行，无需安装）
```
nix run github:anotherhadi/spilltea
```
NixOS (flake)
将 spilltea 添加到你的 flake inputs 中：
```
inputs.spilltea.url = "github:anotherhadi/spilltea";
```
然后将该 package 添加到你的系统或 home-manager 的 packages 中：
```
environment.systemPackages = [ inputs.spilltea.packages.${pkgs.system}.default ];
```
## 项目管理
Spilltea 将工作组织为**项目**。每个项目映射到一个 SQLite 数据库文件，该文件存储该会话的所有拦截流量及日志文件。
在启动时，你可以选择：
- **新建项目**：输入一个名称，默认存储在 `~/.local/share/spilltea/
/` 中
- **现有项目**：从之前的项目列表中进行选择
- **临时项目**：无需名称，存储在 `/tmp/spilltea//` 中，并且会在你下次重启时被删除！
## 配置
Spilltea 完全通过位于 `~/.config/spilltea/config.yaml` 的 YAML 文件进行配置。
在[这里](./internal/config/default_config.yaml)查看包含所有选项的默认配置。
颜色和样式可以使用 [ilovetui](https://github.com/anotherhadi/ilovetui) 进行自定义，它可以一次更改所有兼容 TUI 应用程序的主题。
### 项目级配置
你可以通过在项目目录中放置一个 `config.yaml` 文件（例如 `~/.local/share/spilltea/projects/my-project/config.yaml`），在项目级别覆盖任何配置值。
只有该文件中存在的 key 会被覆盖；其他所有配置都会回退到全局 config。
优先级顺序为：
1. 全局 config (`~/.config/spilltea/config.yaml`)
2. 项目 config (`/config.yaml`)
3. CLI flags（始终具有最高优先级）
## CLI 标志
```
A minimal, terminal-based HTTP(S) proxy for pentesters and CTF players.
Usage:
spilltea [flags]
Flags:
--add-default-config copy the default config file to the config path and exit
--add-default-plugins copy built-in example plugins into the plugins dir and exit
-c, --config string path to config file
-h, --help help for spilltea
--host string proxy host (overrides config)
--plugins-dir string path to plugins dir (overrides config)
-p, --port int proxy port (overrides config)
-P, --project string project name to open directly, or "tmp" for a temporary session
--ssl-insecure skip TLS certificate verification (overrides config)
--upstream-proxy string upstream proxy URL, e.g. http://user:pass@host:8888 (overrides config)
-v, --version version for spilltea
```
## 插件系统
Spilltea 支持使用 **Lua** 编写的插件。插件默认从 `~/.config/spilltea/plugins/` 加载，不需要重新编译或访问源代码。
有关完整的参考和示例，请参阅[插件文档](./docs/plugins.md)或[插件示例](./plugins/)。
## Vim / Neovim 集成
Spilltea 与 Neovim 天然契合。如果你经常在编辑器中工作，这些插件可以让你在不切换上下文的情况下检查和转换捕获的流量：
- **[sttr.nvim](https://github.com/anotherhadi/sttr.nvim)**：直接在 Neovim 中对任何选定的文本运行字符串转换（base64、URL 编码/解码、hex、哈希等）。非常适合用于解码在代理历史记录中发现的值。
- **[jwt-tui.nvim](https://github.com/anotherhadi/jwt-tui.nvim)**：在浮动 TUI 窗口中解码和检查 JWT token。非常适合快速读取通过代理拦截到的 token。
这两个插件都是为了在终端工作流中显得原生化而构建的，就像 Spilltea 一样。
## 部署
spilltea **本地**运行用于渗透测试或 CTF 的机器上。没有独立的服务器组件。
如果你需要在远程机器（例如 VPS 或 pivot host）上运行 spilltea，请使用 SSH 端口转发：
```
ssh -L 8080:127.0.0.1:8080 user@remote-host
```
然后像往常一样将你的浏览器指向 `127.0.0.1:8080`。
## 技术栈
| Component | Library |
| ------------------ | --------------------------------------------------------- |
| TUI | [bubbletea](https://github.com/charmbracelet/bubbletea) |
| Styles | [lipgloss](https://github.com/charmbracelet/lipgloss) |
| Proxy / MITM / TLS | [go-mitmproxy](https://github.com/lqqyt2423/go-mitmproxy) |
| Storage | [modernc.org/sqlite](https://gitlab.com/cznic/sqlite) |
| Config | [viper](https://github.com/spf13/viper) |
| Plugins | [gopher-lua](https://github.com/yuin/gopher-lua) |
