noQuli/vetty

## ✨ 功能 - **硬件级隔离** — 代码运行在使用 KVM 的 Firecracker micro-VMs 中，而非容器 - **实时 syscall 监控** — 通过 `strace` 捕获每一个 `open`、`connect`、`exec`、`write` 并实时流式传输 - **HTTP/HTTPS 拦截** — 通过 mitmproxy 进行完整的请求/响应检查，包括 TLS 流量 - **桌面 GUI** — 基于 Electron + React 的仪表盘，提供实时事件时间线、过滤和详细检查功能 - **单命令启动** — 一个 `make run` 即可同时启动 daemon、GUI 和 VM - **极小占用** — micro-VMs 可在不到一秒的时间内完成启动，内存占用仅约 128 MB ## 📋 前置条件 | 需求 | 详情 | |---|---| | **操作系统** | 启用了 KVM 的 Linux (x86_64) | | **KVM** | 必须存在 `/dev/kvm` 且当前用户有写入权限 | | **Firecracker** | `firecracker` 二进制文件位于 `PATH` 中（[安装指南](https://github.com/firecracker-microvm/firecracker/blob/main/docs/getting-started.md)） | | **Rust** | 1.75+ 及 `x86_64-unknown-linux-musl` target | | **Node.js** | 18+ 及 npm | | **系统包** | `e2fsprogs` (`mkfs.ext4`)、`curl`、`sudo` | | **Python** | 3.8+（用于 mitmproxy HTTPS 拦截，可选） | | **mitmproxy** | 可选，用于检查 HTTPS 流量 |

快速安装依赖 (Debian/Ubuntu)

``` # System packages sudo apt update && sudo apt install -y e2fsprogs curl qemu-system-x86 # Rust curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh rustup target add x86_64-unknown-linux-musl # Node.js (通过 nvm) curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash nvm install 20 # Firecracker ARCH="$(uname -m)" release_url="https://github.com/firecracker-microvm/firecracker/releases" latest=$(basename $(curl -fsSLI -o /dev/null -w %{url_effective} ${release_url}/latest)) curl -L ${release_url}/download/${latest}/firecracker-${latest}-${ARCH}.tgz | tar -xz sudo mv release-${latest}-${ARCH}/firecracker-${latest}-${ARCH} /usr/local/bin/firecracker ```

## 🚀 快速开始 ``` # Clone 仓库 git clone https://github.com/noQuli/vetty.git cd vetty # 下载 VM assets (kernel + rootfs) make setup # Build 全部内容并使用 example code 运行 (daemon + GUI + VM) make run DIR=./sample-code ``` GUI 将自动打开，daemon 会在后台启动，同时会启动一个沙盒 VM，并将 `DIR` 指定的目录挂载到 VM 内部的 `/sandbox` 路径下。 ### 代码存放位置 Vetty 会运行你作为 `DIR` 传入的任何主机目录。 首次运行时，请使用内置的示例： ``` make run DIR=./sample-code ``` 在 VM 内部，该目录将出现在这里： ``` /sandbox ``` 因此，这个主机文件： ``` sample-code/my-file.py ``` 在 VM 中可以通过以下路径访问： ``` /sandbox/my-file.py ``` 要运行你自己的代码，请在主机上创建或选择任何目录，并将其传递给 `DIR`： ``` mkdir -p ./my-sandbox-code cp ./some-script.py ./my-sandbox-code/ make run DIR=./my-sandbox-code ``` ### 沙盒内部 (Guest VM) VM 启动后，你将进入 Alpine Linux 内部的一个 root shell。 以下是一些你可以执行的操作示例： ``` # 由于是 Alpine Linux，你可以安装 packages apk add python3 # 从 DIR 检查已挂载的代码 ls -la /sandbox # 在启用 tracing 的情况下运行命令 vetty-run python3 /sandbox/my-file.py vetty-run curl ifconfig.me ``` 任何以 `vetty-run` 为前缀的命令都会受到监控，其 syscall、网络事件和文件访问将立即显示在桌面 GUI 中！ | 步骤 | 执行内容 | |---|---| | `make setup` | 下载 Firecracker 内核并构建内置了 agent 的 Alpine rootfs | | `make run DIR=./sample-code` | 构建 Rust crates，安装 GUI 依赖，将 `DIR` 打包进 VM 代码磁盘，然后并行启动 daemon → GUI → VM | ## 🏗️ 架构 ``` ┌──────────────────────────────────────────────────────────────┐ │ Host Machine │ │ │ │ ┌────────────┐ ┌──────────────┐ ┌──────────────────┐ │ │ │ vetty CLI │───▶│ Disk Builder │ │ Electron GUI │ │ │ │ (Rust) │ │ (Rust) │ │ (React + TS) │ │ │ └──────┬─────┘ └──────────────┘ └────────┬─────────┘ │ │ │ │ WebSocket │ │ ▼ ▼ │ │ ┌──────────────┐ ┌──────────────────────────┐ │ │ │ Firecracker │◀── vsock ──▶│ vetty-daemon │ │ │ │ VM Launcher │ │ - vsock listener │ │ │ └──────┬───────┘ │ - REST API (:9876) │ │ │ │ │ - WebSocket stream │ │ │ ▼ │ - mitmproxy integration │ │ │ ┌─────────────────────┐ └──────────────────────────┘ │ │ │ Firecracker VM │ │ │ │ │ │ │ │ ┌───────────┐ │ │ │ │ │ vetty-run │──┐ │ │ │ │ │ (wrapper) │ │ │ │ │ │ └───────────┘ │ │ │ │ │ ┌─────────▼┐ │ │ │ │ │ strace │ │ │ │ │ └─────┬────┘ │ │ │ │ ▼ │ │ │ │ ┌──────────────┐ │ │ │ │ │ vetty-agent │───┼── vsock ──▶ host daemon │ │ │ │ (Rust) │ │ │ │ │ └──────────────┘ │ │ │ │ │ │ │ │ /sandbox (code) │ │ │ └─────────────────────┘ │ └──────────────────────────────────────────────────────────────┘ ``` ### 数据流 1. **CLI** 将你的源代码目录打包成 ext4 磁盘镜像 2. **VM Launcher** 使用 rootfs、kernel 和代码磁盘启动 Firecracker micro-VM 3. **Guest init** 挂载代码磁盘，启动 agent，并进入 shell 4. 用户运行 `vetty-run ` — 通过 `strace` 封装执行过程 5. **Agent** 解析 strace 输出，并通过 vsock 将结构化事件流式传输到主机 6. **Daemon** 接收事件并进行存储，然后通过 WebSocket 推送 7. **GUI** 实时渲染事件，并提供过滤、搜索和详细检查功能 ## 📁 项目结构 ``` vetty/ ├── crates/ │ ├── vetty-common/ # Shared protocol types and event definitions │ ├── vetty-disk/ # Builds ext4 code images from host directories │ ├── vetty-agent/ # Guest-side strace parser + vsock sender │ ├── vetty-vm/ # Firecracker VM launcher and serial relay │ ├── vetty-daemon/ # Host daemon: vsock + REST API + WebSocket │ └── vetty-cli/ # CLI entrypoint orchestrating all components ├── guest/ │ ├── init.sh # Guest boot/init script │ └── vetty-run.sh # Wrapper for traced execution ├── image/ │ ├── build-rootfs.sh # Builds Alpine rootfs with agent baked in │ ├── download-kernel.sh # Downloads pre-built Firecracker kernel │ └── download-rootfs.sh # Downloads pre-built rootfs (quickstart) ├── gui/ │ ├── electron/ # Electron main process │ └── src/ # React + TypeScript frontend ├── scripts/ │ └── vetty-mitmproxy-addon.py # mitmproxy addon for HTTPS interception ├── docs/ # Detailed technical documentation ├── sample-code/ # Example code for testing the sandbox ├── Makefile # Build and run orchestration └── Cargo.toml # Rust workspace configuration ``` ## 🔧 开发 ### 手动构建 ``` # Build 所有 host crates cargo build # Build guest agent (static musl binary) rustup target add x86_64-unknown-linux-musl cargo build --target x86_64-unknown-linux-musl --release -p vetty-agent # 安装 GUI 依赖 cd gui && npm install ``` ### 手动运行（需在独立终端） ``` # Terminal 1: 启动 daemon cargo run -p vetty-daemon # Terminal 2: 启动 GUI cd gui && npm run electron:dev # Terminal 3: 启动 sandbox cargo run -p vetty-cli -- --dir ./sample-code --rootfs ./image/rootfs.ext4 --kernel ./image/vmlinux ``` ### 构建目标 | 命令 | 描述 | |---|---| | `make build` | 构建所有 Rust crates（主机 + guest agent） | | `make build-host` | 仅构建主机 crates（debug 模式） | | `make build-agent` | 交叉编译 guest agent（musl，release 模式） | | `make gui-install` | 安装 GUI npm 依赖 | | `make setup` | 下载 kernel 并构建 rootfs | | `make run` | 构建并运行所有组件 | | `make clean` | 删除所有构建产物 | | `make lint` | 运行 clippy 和 eslint | | `make test` | 运行所有测试 | ### CLI 选项 ``` vetty --dir Source directory to sandbox (required) --rootfs Path to rootfs image [default: image/rootfs.ext4] --kernel Path to kernel binary [default: image/vmlinux] --memory VM memory in MB [default: 128] --cpus Number of vCPUs [default: 1] --firecracker

Path to firecracker binary [default: firecracker] --no-serial Don't attach serial console ``` ### 环境变量 | 变量 | 默认值 | 描述 | |---|---|---| | `VETTY_DAEMON_PORT` | `9876` | daemon REST/WS API 的端口 | | `VETTY_VSOCK_PATH` | `/tmp/vetty_v.sock` | vsock proxy 的 Unix socket 路径 | | `VETTY_DAEMON_BIN` | 自动检测 | 覆盖 daemon 二进制文件的路径 | | `RUST_LOG` | — | 标准 Rust 日志过滤 | ## 📖 文档 详细的技术文档可在 [`docs/`](docs/) 目录中找到： | 文档 | 描述 | |---|---| | [概述](docs/00-overview.md) | 架构和设计概述 | | [Workspace & Common](docs/01-workspace-and-common.md) | 共享类型和 workspace 设置 | | [Disk Builder](docs/02-disk-builder.md) | 代码磁盘镜像创建 | | [Guest Agent](docs/03-guest-agent.md) | Strace 解析器和 vsock 客户端 | | [VM Launcher](docs/04-vm-launcher.md) | Firecracker API 集成 | | [Host Daemon](docs/05-host-daemon.md) | 事件接收和 API server | | [CLI](docs/06-cli.md) | 命令行界面 | | [Guest Scripts & Rootfs](docs/07-guest-scripts-and-rootfs.md) | 启动脚本和镜像构建 | | [GUI](docs/08-gui.md) | Electron + React 前端 | | [Integration & Testing](docs/09-integration-and-testing.md) | 端到端测试 | | [Running](docs/10-running.md) | 执行指南 | | [Arguments](docs/11-arguments.md) | CLI 参数参考 | | [HTTPS Interception](docs/12-https-interception.md) | mitmproxy 设置 | ## 🔒 安全 Vetty 专为分析不受信任的代码而设计。其隔离模型依赖于： - **Firecracker micro-VMs** 及 KVM 硬件虚拟化技术 - **极简的 guest rootfs**（Alpine Linux，约 300 MB） - **无主机文件系统访问权限** — 代码通过独立的 ext4 磁盘镜像挂载 - **通过 NAT 进行网络通信** — 所有 guest 流量均通过主机的 tap 接口路由 有关我们的安全政策和负责任的披露流程，请参阅 [SECURITY.md](SECURITY.md)。 ## 贡献 我们欢迎你的贡献！请查阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解指南。 ## 📄 许可证 本项目基于 MIT 许可证授权 — 有关详情，请参阅 [LICENSE](LICENSE) 文件。

标签：Electron, IP 地址批量处理, Rust, 可视化界面, 安全沙箱, 微虚拟机, 流量拦截, 网络安全审计, 网络流量审计, 通知系统