byliu-labs/egress-guard

# egress-guard **阻止恶意的 `pip install` 窃取您的 AWS 密钥、SSH 密钥和 `.env` 机密 —— 同时不影响您的浏览器或日常工作。** 这是一个轻量级的跨平台出站防火墙，它在精心策划的允许列表下过滤脚本和 shell 流量，同时保留日常 GUI 应用程序不受影响。安装后，内核将出站 TLS 重定向到本地守护程序，该守护程序从 TLS ClientHello 中读取 SNI 主机名（无需解密），根据多层允许列表进行检查，然后选择将连接拼接通过或丢弃。     ``` any process kernel pf rule egress-guardd ───────────────── ────────────────── ────────────────── curl, python, ──443──> redirect to ──TCP──> parse SNI from node, sh, ... localhost:8443 TLS ClientHello │ ┌─────────────┼─────────────┐ ▼ ▼ ▼ allowlist hit? known-bad? unknown? splice drop+log drop+log (transparent) ``` ## 起因 在 **2026 年 3 月**，PyPI 上发布了一个名为 `litellm` (1.82.8) 的恶意版本，该版本在每次启动 Python 解释器时都会自动执行窃取凭证的代码——无需 `import litellm`。它窃取了 SSH 密钥、`~/.aws/credentials`、`~/.gitconfig`、shell 历史记录、Kubernetes 机密、加密钱包文件和云 IMDS 令牌，然后通过硬编码的 `curl` POST 请求，将所有内容经 HTTPS 加密并外泄至 `models.litellm.cloud`。([futuresearch.ai 报告](https://futuresearch.ai/blog/no-prompt-injection-required/)) 任何在那一天于任何机器（笔记本电脑、CI 运行器、开发容器）上运行过 `pip install litellm` 的人，其凭证都被静默窃取了。要检测到此情况，您必须注意到发往一个您从未听过的域名的异常出站 TCP/443 流量，而且这发生在一个您没有监控的进程树中。 现在，针对 PyPI / npm / RubyGems / crates.io 的此类供应链攻击已司空见惯。每次事件的破坏性是灾难性的；而每个用户遇到事件的概率不仅低而且不可预测。egress-guard 就是为此提供的保险。 ## 适用人群？ - **在同时存有云凭证、SSH 密钥或 `.env` 文件的机器上运行 `pip install`、`npm install`、`cargo install` 或 `bundle install` 的开发者。**（这也涵盖了大多数开发者。） - **小型团队中具有安全意识的人员**，他们没有专门的安全组织，无法实际部署 Cilium 或付费的终端安全套件到单台笔记本电脑上。 - **ML 研究员和数据科学家**，他们的工作流程是“pip install 论文中用到的任何东西并运行 notebook”——攻击面很大，且通常使用带有云凭证的机器进行训练。 - **开源贡献者**，他们会克隆不熟悉的仓库并运行其构建/测试命令。 - **任何运行 CI 工作负载的人**，在稳定的运行器上执行（计划在 v1.0 中通过 CI Docker 镜像支持——目前优先支持笔记本电脑）。 如果您曾经在拥有一台包含任何重要内容访问权限的机器上输入 `pip install` 时感到过一丝担忧，那么这个工具就是为您准备的。 ## 为什么不直接使用 X？ | 工具 | 它的作用 | 为什么在此场景下不太合适 | |---|---|---| | **Little Snitch** (macOS, 付费) | 带有提示的应用程序级防火墙 | 仅限 macOS，售价 $59。提示疲劳：全新安装后，会对每一个 (进程, 目标) 对进行提示——大多数用户会养成下意识点击“允许”的习惯，从而破坏了安全性。egress-guard 附带精心策划的豁免应用目录（浏览器、Slack、系统服务），因此它只过滤脚本/shell 流量——这才是真正的攻击面。*(进程身份 + 豁免目录将于 v0.2 推出。)* | | **OpenSnitch** (Linux, 免费) | 与 Little Snitch 模型相同 | 仅限 Linux，同样存在提示疲劳问题。优秀的先例——egress-guard 借鉴了其思路。 | | **pf / iptables / nftables (DIY)** | 带有允许列表规则的原生内核防火墙 | 维护 PyPI、GitHub、npm、CDN、身份验证提供者、遥测等服务的允许列表确实令人痛苦。几乎没人这么做。 | | **Kubernetes NetworkPolicy / Cilium** | Pod / 集群出站允许列表 | 对于单个工作站来说属于生产级的过度设计。对 k8s 之外的 (如 GitHub Actions、GitLab Runner) 开发笔记本电脑或 CI 运行器没有帮助。 | | **仅限容器的开发** (devcontainers 等) | 网络隔离的工作负载 | 真正的防御，但也需要真正的生活方式改变。许多开发者不会采用；它是互补的，而非替代品。 | | **DNS 沉洞 / hosts 文件阻止列表** | 拒绝对已知恶意域名的查找 | 很容易被绕过：恶意软件硬编码一个 IP 地址。应用内的 DoH 完全可以避开。它属于被动的——只能捕获已知威胁。 | | **“不要运行不受信任的代码”** | 🙏 | 这不是一个安全模型。整个供应链问题的核心就在于，您信任了一个包，但它在维护者遭到入侵后变成了恶意软件。 | | **egress-guard** | 跨平台、默认带策划规则、专门过滤脚本/shell进程的主机名允许列表防火墙 | 安装时只需一次 sudo 提示。默认豁免浏览器/Slack/Spotify *(v0.2)*。开箱即用的合理允许列表 (PyPI、GitHub、npm、常见的 LLM API)。MIT 许可证，Go 单一二进制文件，免费。 | ## 快速演示 ``` # 构建并安装（仅需一次 sudo 提示） make build sudo ./bin/egress-guard install # 启动守护进程（由 launchd 登录时自动启动；为清晰起见，展示了手动运行的方式） ./bin/egress-guard start & # 在另一个终端中 — 实时观察 decisions ./bin/egress-guard tail ``` ``` {"ts":"2026-04-30T15:30:01Z","action":"allow","host":"pypi.org","dest_ip":"151.101.0.223","dest_port":443} {"ts":"2026-04-30T15:30:02Z","action":"allow","host":"files.pythonhosted.org","dest_ip":"151.101.1.63","dest_port":443} {"ts":"2026-04-30T15:30:14Z","action":"deny","reason":"host_not_allowlisted","host":"models.litellm.cloud","dest_ip":"203.0.113.42","dest_port":443} {"ts":"2026-04-30T15:30:14Z","action":"deny","reason":"host_not_allowlisted","host":"models.litellm.cloud","dest_ip":"203.0.113.42","dest_port":443} ``` 合法软件包的 `pip install` 成功了。而恶意的 `.pth` 载荷对 `models.litellm.cloud` 发起的 `curl` 请求在内核层即被丢弃——连接根本未能建立。 ## 前置条件 (v0.1.0) - macOS 11 (Big Sur) 或更高版本 — Apple Silicon 和 Intel 均受支持 - Go 1.22+ 用于从源码构建（计划在 v1.0 推出 Homebrew tap） - 一次性使用 `sudo` 安装 pf 规则 Linux、Windows 及 CI Docker 支持已在[路线图](ROADMAP.md)中。 ## 安装 从[发布页面](https://github.com/byliu-labs/egress-guard/releases/tag/v0.1.0)下载预构建的二进制文件，或从源码构建： ``` git clone https://github.com/byliu-labs/egress-guard cd egress-guard make build sudo ./bin/egress-guard install # one sudo prompt — installs pf anchor + LaunchAgent ``` LaunchAgent 会使守护程序在登录时自动启动。要立即手动运行它： ``` ./bin/egress-guard start ``` 要干净地卸载： ``` sudo ./bin/egress-guard uninstall ``` ## 命令 | 命令 | 作用 | |---|---| | `egress-guard install` | 安装 pf 锚点 + LaunchAgent。需要 `sudo`。 | | `egress-guard uninstall` | 移除以上两者。需要 `sudo`。 | | `egress-guard start` | 在前台运行守护程序（通常由 launchd 执行此操作）。 | | `egress-guard status` | 报告是否已安装内核规则。 | | `egress-guard allow ` | 将一个主机添加到用户允许列表。可重复执行。 | | `egress-guard deny ` | 将一个主机添加到用户拒绝列表。可重复执行。 | | `egress-guard tail` | 实时跟踪 JSONL 阻止日志。 | | `egress-guard version` | 打印版本字符串。 | 主机名模式支持三种形式： - `api.openai.com` — 精确匹配 - `*.github.com` — 任何子域名（匹配 `api.github.com`，不匹配 `github.com`） - `**.github.com` — 注册域名及其所有子域名 ## 配置 | 文件 | 用途 | |---|---| | (内嵌) | 内置的默认允许列表 — LLM API、包注册表、代码托管、云身份验证、强制门户探测 | | `~/.config/egress-guard/allowlist.toml` | 用户全局覆盖；`allow` / `deny` 子命令会写入此文件 | | `~/.local/state/egress-guard/blocked.log` | JSONL 只追加的决策日志 | | `/etc/pf.anchors/egress-guard` | pf 锚点文件 — 由 `install` / `uninstall` 自动管理，请勿手动编辑 | | `~/Library/LaunchAgents/com.byliu.egress-guard.plist` | 用于登录时自动启动的 LaunchAgent | **解析顺序，最具体的优先：** 已知恶意拒绝列表 → 用户拒绝列表 → 用户允许列表 → 内置默认列表 → 其他情况一律拒绝。 要完全覆盖内置默认列表（例如，从默认允许中移除 LLM API），请将嵌入的 `configs/defaults.toml` 复制到 `~/.config/egress-guard/allowlist.toml` 并进行编辑。针对项目的 `.egress.toml` 计划在 v0.3 中推出。 ## 什么被过滤，什么没有 (v0.1) **v0.1 会过滤一切。**目前尚无进程身份识别——来自任何进程的每个出站 TCP/443 连接都会经过 SNI 检查和允许列表查找。这包括您的浏览器，这意味着**发往任何不在默认允许列表中的目标的浏览器流量将被阻止**，直到您将浏览器访问的主机添加到允许列表。 在实践中，这意味着： - 大多数包管理器和开发工作流都能正常运行（PyPI、npm、GitHub、常见的云身份验证均在默认允许列表中） - 休闲的网页浏览会受到严重限制，除非您随时将访问的域名加入允许列表 - 我们所关注的那类恶意软件包攻击能被可靠地阻止 **v0.2** 引入了进程身份层和豁免应用目录（默认豁免浏览器、Slack、Spotify、系统服务）。到那时，威胁模型将变为“专门过滤脚本和 shell 进程；保留用户日常应用不受干扰”。到那时，该项目才会变得对非开发人员友好。 如果 v0.1 的严格限制对您的机器来说过于激进，最简单的解决办法就是等待 v0.2（下一个里程碑——请参阅 [ROADMAP.md](ROADMAP.md))。 ## 威胁模型 简而言之：防御**您机器上试图将机密发送到未经授权目的地的非特权代码。**这涵盖了受损的 PyPI / npm / RubyGems / crates.io 软件包、从不受信任来源运行的恶意 shell 脚本、安装后钩子以及 `.pth` 风格的自动执行载荷。 不在范围内：已拥有 root 权限的攻击者、内核漏洞利用、侧信道、浏览器扩展、通过用户未重定向的 UDP / ICMP / 非 443 端口进行的数据外泄。 完整的模型详见 [SECURITY.md](SECURITY.md)——包括残余风险（例如执行并伪装成豁免二进制文件）以及披露策略。 ## 常见问题解答 ### 这会解密我的 TLS 流量吗？ 不会。egress-guard 仅从 TLS ClientHello 中读取 SNI 主机名——它在传输过程中是明文的，因为服务器需要它来选择证书。我们从不安装 CA 证书，从不破坏证书固定，也从不查看加密隧道内部的任何内容。 ### 会破坏我的 VPN 吗？ 测试通过：全隧道 VPN (NordVPN、Mullvad、WireGuard、OpenVPN、IPSec)，Tailscale (UDP 协调不受影响；通过 Tailscale 的应用级 HTTPS 会像任何 443 流量一样被过滤)。内核规则在 VPN 封装数据包之前触发，因此守护程序自身的拼接连接可以正常使用 VPN。 需要显式设置：非 443 端口上的企业 HTTP 代理（设置 `HTTPS_PROXY=http://localhost:8443` 并将企业代理主机名放入允许列表），处于透明模式的本地拦截代理（Charles、Proxyman——在安装时会被拒绝），发往非本地解析器的 DoH/DoT（需将解析器主机名加入允许列表）。 ### 它能与 sing-box / ClashX / V2Ray / 其他 TUN 模式透明代理一起工作吗？ **目前不能**——而且这种失败是静默的。如果您正在运行 TUN 模式透明代理，内核会在 PF 的重定向规则生效之前，通过该工具的 `utun*` 接口路由所有出站 TCP。egress-guard 的守护程序仍在运行，install 命令依然报告成功，但没有任何流量会到达守护程序，因此它无法执行任何操作。 如何判断您是否受此影响：`route -n get default` 报告 `interface: utun*`，或者 `host example.com` 返回 `198.18.0.0/15` 中的地址（一个常见的 FakeIP 范围）。如果符合其中任何一条，egress-guard 将作用。 应对方法：在需要 egress-guard 保护时停止 TUN 代理，或者依赖 TUN 代理自身的允许列表功能。这两个工具在根本上都想成为内核的出站守门人，而 PF 只能有一个胜出者。 架构上的修复方案是将 egress-guard 从 PF 迁移到 macOS 网络扩展（用于套接字层过滤的 `NEFilterDataProvider`，或用于 DNS 层过滤的 `NEDNSProxyProvider`）。这两种方式都将在路由决策之前生效，并能与 TUN 代理共存。这是一个真正的转变——系统扩展打包、Apple Developer Program 注册、向 Apple 申请托管授权——目前尚未承诺在哪个特定版本中实现。如果这阻碍了您的配置使用，请开启一个 issue。 ### 为什么需要 sudo？ 只需一次。为了在内核层安装 pf 规则。之后，守护程序将以您的身份非特权运行。卸载同样只需一次 sudo。之所以必须在内核层（而不是仅仅使用 `HTTPS_PROXY` 环境变量）是因为，恶意代码可以在外泄之前轻松地 `unset HTTPS_PROXY`；而内核规则无法从用户空间绕过。 ### 这不会破坏我的浏览器吗？ 在 v0.1 中，是的，部分会——浏览器也会被过滤，您需要将访问的域名加入允许列表。v0.2 增加了基于进程身份的豁免应用处理机制，因此浏览器默认被豁免。那是下一个里程碑。 ### 我可以暂时禁用它吗？ 可以： ``` sudo pfctl -a egress-guard -F all # flush our pf anchor's rules; daemon keeps running but does nothing ``` 重新启用： ``` sudo /usr/local/bin/egress-guard install # rewrites the anchor ``` 要彻底卸载，请使用 `sudo egress-guard uninstall`。 ### 默认允许列表中有哪些主机名？ LLM API (`api.anthropic.com`、`api.openai.com` 等)，包注册表 (`pypi.org`、`registry.npmjs.org`、`crates.io`、`rubygems.org`、`formulae.brew.sh`)，代码托管 (GitHub、GitLab、Bitbucket)，知名的云身份验证端点 (AWS STS、Azure AD、Google OAuth)，以及强制门户探测（以便酒店 WiFi 登录仍能正常工作）。完整列表：[`configs/defaults.toml`](configs/defaults.toml)。您可以通过编辑 `~/.config/egress-guard/allowlist.toml` 进行覆盖。 ### 如何查看被阻止的内容？ ``` egress-guard tail ``` 阻止日志位于 `~/.local/state/egress-guard/blocked.log`，格式为 JSONL。每一个决策（允许和拒绝）都会记录主机名、原始目标 IP/端口以及原因。 ### 有 Linux 版本吗？ 目前还没有（v0.1 仅限 darwin）。v0.1.1 将增加对 Linux 的支持——平台接口已经定义好，pf 代码的结构可以直接平滑移植到 `nftables`。Windows 已在 v1.x 的路线图上；Windows Filtering Platform 具有不同的语义，需要重新进行一次设计。 ### 这能在 CI 中使用吗？ 目前还不能。内核规则模式不能直接适应 GitHub Actions / GitLab Runner / CircleCI。v1.0 将发布一个预配置了守护程序的 Docker 基础镜像 (`egress-guard/ci:latest`)，以支持临时运行器，并通过项目的 `.egress.toml` 进行配置。请参阅 [ROADMAP.md](ROADMAP.md)。 ### 这与 anon-proxy 有何不同？ [anon-proxy](https://github.com/byliu-labs/anon_proxy) 是一个*内容清理器*——它理解 LLM API 协议并在请求离开设备之前屏蔽 PII。egress-guard 是一个*传输守门人*——它不关心数据包里的内容，只关心它要去哪里以及来自谁。两者是互补的基础设施，属于独立的项目。同时运行两者可以实现“没有东西能离开主机，即使离开了也被涂抹过敏感信息。” ### 如果你们不发布 v0.2 怎么办？ 当前的 v0.1 代码很小（约 3 MB 二进制文件，专注的 Go 模块），端到端地涵盖了核心安全原语。任何人都可以分叉并继续推进路线图。MIT 许可证，无贡献者协议，无遥测，无上游服务。代码库就是事实来源。 ### egress-guard 会看到我的密码 / API 密钥 / 表单提交内容吗？ 不会——请参阅上文的“这会解密我的 TLS 流量吗”。守护程序只能看到 TLS 握手字节和 SNI 主机名。其他一切都是不透明的。 ## 报告漏洞 请参阅 [SECURITY.md](SECURITY.md)。对于安全工具而言，*静默报告*通常优于公开的 issue——请先电子邮件联系维护者。 ## 路线图 - **v0.1.x** — Linux 平台对齐（接口已定义，实现已存根） - **v0.2** — 进程身份层 + 豁免应用目录 + 提示 UX（“非专家默认开启”里程碑）—— **已发布于 2026-05-01** - **v0.3** — 学习模式、针对项目的 `.egress.toml`、逃生舱 `run` 命令、`doctor` 自检 - **v1.0** — 联合/签名目录、IOC 威胁情报源集成、CI Docker 镜像、Homebrew tap - **v1.x** — Windows 移植、anon-proxy 捆绑包、团队模式 SaaS、行为启发式 完整的逐版本详情见 [ROADMAP.md](ROADMAP.md)。版本计划之外的延期待办事项：[TODOS.md](TODOS.md)。 ## 文档索引 | 文档 | 用途 | |---|---| | [DESIGN.md](DESIGN.md) | 完整的架构、威胁模型、配置、VPN/代理兼容性、攻击者模型 | | [ROADMAP.md](ROADMAP.md) | 逐版本路线图 | | [CHANGELOG.md](CHANGELOG.md) | 发布了什么，何时发布的 | | [SECURITY.md](SECURITY.md) | 威胁模型 + 披露策略 | | [TODOS.md](TODOS.md) | 延期待办事项 | | `docs/plans/` | 各版本的实现计划 | ## 许可证 [MIT](LICENSE) © Boyu Liu。欢迎提交 Issues 和 PR——这是一个年轻的项目，反馈是改进它的最快途径。

标签：AWS密钥保护, DLP, .env文件保护, EVTX分析, Go语言开发, IP 地址批量处理, macOS安全, NAC, PyPI恶意包防护, SSH密钥保护, TLS SNI过滤, 凭据保护, 出站防火墙, 开源安全工具, 恶意流量拦截, 文档安全, 日志审计, 流量劫持, 网络安全, 网络访问控制, 逆向工程平台, 透明代理, 隐私保护