inkdust2021/VibeGuard

# VibeGuard [](LICENSE) [](go.mod) [](https://github.com/inkdust2021/VibeGuard/actions/workflows/ghcr.yml) [](https://ghcr.io/inkdust2021/vibeguard) [](https://github.com/inkdust2021/VibeGuard/stargazers) English | [中文](README.zh-CN.md) VibeGuard 是一个 MITM HTTPS 代理，旨在保护在 vibecoding 过程中的敏感数据。 - 仅进程代理启动器：`vibeguard codex/claude/gemini/opencode/qwen` - 管理 UI：位于 `http://127.0.0.1:28657/manager/` 的规则和审计界面 - 针对 JSON 和 SSE 响应的占位符恢复 ## 主要特性 - **脱敏规则**：关键词规则（精确子串匹配）+ 可选的内置通用 PII 识别器（电子邮件/电话/信用卡/IBAN/SSN/IP/UUID 等）。 - **默认安全**：仅扫描最大 10MB 的类文本主体（例如 `application/json`）。 - **管理 UI**：在 `/manager/` 管理规则、证书、会话、每个请求的“脱敏命中”事件，并在 `#/logs` 实时查看调试日志。 - **管理认证**：管理 UI/API 受密码保护（首次访问 `/manager/` 时设置）。 - **静态加密（关键词）**：关键词/排除值使用从本地 CA 私钥派生的密钥加密存储在 `~/.vibeguard/config.yaml` 中（管理 UI 仍显示明文）。如果您重新生成 CA，旧的加密值将无法解密。 - **两种拦截模式**：`proxy.intercept_mode: global`（推荐用于大多数客户端）或 `targets`。 - **热重载**：来自管理 UI 的模式/目标更改无需重启即可生效。 ## 架构 ``` flowchart LR C[Client: Codex / Claude / IDE] -->|HTTPS via proxy| P[Proxy: MITM TLS] P -->|Request body| R[Redaction engine
Keywords + Generic PII] R -->|Placeholders| U[Upstream AI API] U -->|Response JSON/SSE| S[Restore engine] S -->|Restored response| C UI[Admin UI /manager/] -->|Edit rules| CFG[Config] CFG -->|Hot reload| R CFG -->|Intercept mode| P R <--> SES[Session store: TTL + WAL] S <--> SES P -->|Audit events| A[Audit] UI --> A ``` ## 集成 VibeGuard 可以在“仅进程”代理模式下启动的工具： - Codex CLI: `vibeguard codex` - Claude Code: `vibeguard claude` - Gemini CLI: `vibeguard gemini` - OpenCode: `vibeguard opencode` - Qwen CLI: `vibeguard qwen` ## 截图   ## 快速开始（从源码） ``` go run ./cmd/vibeguard init go run ./cmd/vibeguard start --foreground ``` ## 管理 UI 安全 - 首次访问 `http://127.0.0.1:28657/manager/` 时，系统会要求您设置管理员密码。 - 密码以 bcrypt 哈希形式存储在 `~/.vibeguard/admin_auth.json` 中（权限：`0600`）。 - 忘记密码？停止 VibeGuard，删除 `~/.vibeguard/admin_auth.json`，然后刷新 `/manager/` 以设置新密码。 - 保持管理 UI 绑定到 localhost（`127.0.0.1`），避免将端口暴露给局域网/公共网络。 ## 安装（脚本） macOS/Linux: ``` bash install.sh ``` 安装程序是交互式的（语言、PATH、CA 信任、自启动）。选择的语言会被管理 UI 和卸载脚本记住。 Windows (PowerShell): ``` powershell -ExecutionPolicy Bypass -File .\\install.ps1 ``` PowerShell 安装程序也是交互式的（并且会记住选择的语言）。 ## 卸载 macOS/Linux: ``` bash uninstall.sh bash uninstall.sh --purge ``` Windows (PowerShell): ``` powershell -ExecutionPolicy Bypass -File .\\uninstall.ps1 powershell -ExecutionPolicy Bypass -File .\\uninstall.ps1 -Purge ``` 卸载程序会尝试自动移除受信任的 CA（“VibeGuard CA”）。如果失败（例如权限问题），请手动移除。 ## Docker（推荐） 默认情况下，`docker-compose.yml` 使用来自 GHCR 的预构建镜像（仅绑定到 localhost）： ``` docker compose pull docker compose up -d ``` 更新（拉取最新镜像并重启）： ``` docker compose pull vibeguard docker compose up -d ``` 安全提示（推荐用于 vibecoding）：将 VibeGuard 状态保留在 *Docker 内部*（默认设置）。`docker-compose.yml` 为 `/root/.vibeguard` 使用 Docker 命名卷（`vibeguard-data`），因此默认情况下您的主机文件系统不会包含 CA 私钥或配置文件。避免将其更改为像 `~/.vibeguard:/root/.vibeguard` 这样的绑定挂载。如果您需要主机信任，仅导出 `ca.crt`（不要复制 `ca.key`）。 从源码构建（贡献者 / 在首个发布镜像存在之前）： ``` docker compose -f docker-compose.yml -f docker-compose.source.yml up -d --build ``` 提示：启用 BuildKit 可以加快源码重建速度： ``` DOCKER_BUILDKIT=1 docker compose -f docker-compose.yml -f docker-compose.source.yml build ``` 查看日志： ``` docker compose logs -f vibeguard ``` 主机上出现 `zsh: command not found: vibeguard`？ - 这在纯 Docker 模式下是预期的（`vibeguard` 二进制文件位于容器内）。 - 在容器内运行 CLI 命令： ``` docker compose exec -T vibeguard vibeguard --help docker compose exec -T vibeguard vibeguard version ``` 部署（从零开始）并导出 CA 证书： ``` git clone https://github.com/inkdust2021/VibeGuard.git cd VibeGuard docker compose pull docker compose up -d docker compose exec -T vibeguard cat /root/.vibeguard/ca.crt > vibeguard-ca.crt ``` 在您的主机上信任该 CA： - macOS（系统钥匙串）： ``` sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain vibeguard-ca.crt ``` - Linux（Debian/Ubuntu）： ``` sudo cp vibeguard-ca.crt /usr/local/share/ca-certificates/vibeguard-ca.crt sudo update-ca-certificates ``` - Windows（以管理员身份运行）： ``` certutil -addstore -f Root vibeguard-ca.crt ``` 客户端设置： - 代理 URL：`http://127.0.0.1:28657` - 管理 UI：`http://127.0.0.1:28657/manager/` 对于 CLI 助手，首选“仅进程”模式（不会影响您的整个终端）： - 如果您在主机上安装了 `vibeguard`： ``` vibeguard codex [args...] vibeguard claude [args...] vibeguard gemini [args...] vibeguard opencode [args...] vibeguard qwen [args...] vibeguard run [args...] ``` - 仅 Docker（主机上没有 `vibeguard`）：**不要**使用 `alias vibeguard='docker compose exec ... vibeguard'` 来运行 `vibeguard claude`（它会在容器内运行 `claude`，而容器内通常未安装该程序）。相反，将此 shell 函数添加到您的 `~/.zshrc`/`~/.bashrc`： ``` # 将其设置为克隆 VibeGuard 的目录（包含 docker-compose.yml） export VIBEGUARD_DOCKER_DIR="$HOME/Code/VibeGuard" export VIBEGUARD_PROXY_URL="http://127.0.0.1:28657" export VIBEGUARD_CA_CERT="$VIBEGUARD_DOCKER_DIR/vibeguard-ca.crt" vibeguard() { local sub="${1:-}" if [ -z "$sub" ]; then docker compose --project-directory "$VIBEGUARD_DOCKER_DIR" exec -T vibeguard vibeguard --help return fi shift || true case "$sub" in claude|codex|gemini|opencode|qwen) # Runs the assistant on the host, but only this process uses the proxy. HTTPS_PROXY="$VIBEGUARD_PROXY_URL" HTTP_PROXY="$VIBEGUARD_PROXY_URL" \ https_proxy="$VIBEGUARD_PROXY_URL" http_proxy="$VIBEGUARD_PROXY_URL" \ NO_PROXY="127.0.0.1,localhost" no_proxy="127.0.0.1,localhost" \ NODE_EXTRA_CA_CERTS="$VIBEGUARD_CA_CERT" \ "$sub" "$@" ;; run) HTTPS_PROXY="$VIBEGUARD_PROXY_URL" HTTP_PROXY="$VIBEGUARD_PROXY_URL" \ https_proxy="$VIBEGUARD_PROXY_URL" http_proxy="$VIBEGUARD_PROXY_URL" \ NO_PROXY="127.0.0.1,localhost" no_proxy="127.0.0.1,localhost" \ NODE_EXTRA_CA_CERTS="$VIBEGUARD_CA_CERT" \ "$@" ;; *) # Proxy management subcommands are executed inside the container. docker compose --project-directory "$VIBEGUARD_DOCKER_DIR" exec -T vibeguard vibeguard "$sub" "$@" ;; esac } ``` 对于 IDE/GUI 应用程序（Cursor 等），将应用程序的代理 URL 设置为 `http://127.0.0.1:28657`。 重置容器状态（重新生成 CA/配置；需要重新信任）： ``` docker compose down -v ``` ## 证书 要进行 MITM HTTPS，您的客户端必须信任生成的 CA： ``` go run ./cmd/vibeguard trust --mode system # may require sudo ``` ## 配置 - 全局：`~/.vibeguard/config.yaml` - 项目覆盖：`.vibeguard.yaml` - 覆盖路径：`VIBEGUARD_CONFIG=/path/to/config.yaml` ## CLI 完整命令参考：`CLI.md`。（此处也列出了所有内容。） 全局标志： - `-c, --config PATH`：配置文件（默认 `~/.vibeguard/config.yaml`）。 ### 启动代理服务（默认后台） ``` vibeguard start [--foreground] [-c PATH] ``` - 默认：作为后台服务/进程启动（如果可用）。 - `--foreground`：在前台运行（服务/调试）。 - 如果设置了 `--config`，它将在前台运行（以避免歧义）。 ### 停止代理服务/进程 ``` vibeguard stop [-c PATH] ``` ### 使用代理运行 Claude Code（仅进程） ``` vibeguard claude [args...] ``` ### 使用代理运行其他助手（仅进程） ``` vibeguard codex [args...] vibeguard gemini [args...] vibeguard opencode [args...] vibeguard qwen [args...] ``` ### 使用代理运行任何命令（仅进程） ``` vibeguard run [args...] ``` ### 初始化向导 ``` vibeguard init [-c PATH] ``` 交互式首次设置（配置 + CA）。 ### 信任 CA 证书（HTTPS MITM 所需） ``` vibeguard trust --mode system|user|auto [-c PATH] ``` 将生成的 CA 安装到信任存储中，以便客户端可以接受 MITM TLS。（可能需要 `sudo`/管理员权限。） ### 测试脱敏规则 ``` vibeguard test [pattern] [text] [-c PATH] ``` `pattern` 被视为关键词（精确子串匹配）。 示例： ``` vibeguard test "test123" "Please repeat the word I just said, and remove its first letter." ``` ### 版本 ``` vibeguard version ``` ### Shell 补全 ``` vibeguard completion bash|zsh|fish|powershell [--no-descriptions] ``` ### 帮助 ``` vibeguard --help vibeguard help [command] vibeguard [command] --help ``` ## 验证是否工作（Vibe coding） 1. 启动代理：`vibeguard start`（安装程序可以自动执行此操作）。 2. 信任一次 CA：`vibeguard trust --mode system`（可能需要 `sudo`/管理员权限）。 3. 通过 VibeGuard 启动您的工具（`vibeguard codex/claude/...`）或将您的 IDE/应用代理 URL 设置为 `http://127.0.0.1:28657`。 4. 在 `/manager/` 中，检查 **Audit** 面板：每个请求显示是否尝试了脱敏以及替换了多少匹配项。 ## 开发 ``` go test ./... go vet ./... gofmt -w . ``` ## Star 历史 [](https://www.star-history.com/#inkdust2021/VibeGuard&type=date&legend=top-left)

标签：AI安全, Chat Copilot, Claude, Codex, CVE检测, DLL注入, DLP, Docker容器, EVTX分析, EVTX分析, GHCR, Go语言, HTTPS代理, LLM工具, PII过滤, VibeCoding, 个人隐私, 中间人代理, 云计算, 大语言模型安全, 底层编程, 提示词注入防御, 攻击面发现, 敏感信息屏蔽, 数据脱敏, 日志审计, 本地代理, 机密管理, 流量审计, 程序破解, 网络安全, 网络安全, 规则引擎, 请求拦截, 隐私保护, 隐私保护, 静态密钥加密