VeilGate

VeilGate 是一个开源欺骗代理，适用于希望通过提高自动安全探测成本而不在真实用户面前设置脆弱阻断规则的团队。

它位于 Web 应用之前，对每个请求进行评分，并选择三种结果之一：

• Real：将干净流量转发到上游应用。
• Challenge：要求可疑但模棱两可的客户端解决浏览器工作量证明。
• Tarpit：将高置信度代理流量分流到确定性虚假应用。

目标不是魔法般的不可攻破。目标是更好的经济学：让人类和正常自动化流畅运行，同时让 AI 辅助的扫描器将时间、代币和注意力浪费在可信的死胡同里。

功能

• 反向代理，支持 observe、challenge、tarpit 和阈值驱动的 auto 模式。
• 检测信号：可疑用户代理、稀疏浏览器头、蜜罐路径、定时规律性、扫描器路径、SQLi/XSS/OOB 标记、IP/UA 轮换、Cookie 行为、请求图形状、JA3/JA4 TLS 指纹、HTTP/2 指纹、金丝雀重放以及在线 ML 评分。
• 浏览器工作量证明挑战，同时支持 Cookie 和 X-Veilgate-Token 头 传输方式，使得跨域 SPA 可以解决挑战并在后续 API 调用中重新附加令牌。401 挑战响应支持 SPA：对于顶级导航返回 HTML，对于 fetch / XHR 上下文返回 JSON（包含内联解决 PoW 的元数据）。
• 操作员颁发的 HMAC 验证器链，用于无法解决 PoW 的服务器间客户端（参见 docs/how-to/server-to-server-hmac.md）。
• 影子应用响应，具有稳定的每个客户端虚假配置文件。
• 提示注入和诱饵载荷注入（用于 tarpit 响应）。
• SQLite 持久化：事件、特征汇总、审计日志和金丝雀。
• Prometheus 指标和指标监听器上的轻量级仪表盘。
• 可热重载的 YAML 规则文件，由独立的 veilgate-rules 社区仓库提供。

快速开始

选项 1 — 安装脚本（推荐）

下载二进制文件，安装 systemd 服务，安装社区规则，并以 observe 模式写入初始配置。

# 一行命令
curl -sSL https://veilgate.dev/install.sh | sudo bash -s -- --upstream http://localhost:3000

# 或者先下载再运行
curl -sSL https://veilgate.dev/install.sh -o install.sh
sudo ./install.sh --upstream http://localhost:3000

参数：

打包的配置使用 rules_dir: "~/.veilgate/rules"。在 systemd 下，VeilGate 以 veilgate 用户运行，其家目录为 /var/lib/veilgate，因此该路径解析为 /var/lib/veilgate/.veilgate/rules。

如果新安装时省略了 --secret，安装程序会在交互式终端上提示输入，否则生成随机密钥。如果服务用户不存在，安装程序会在交互式终端上询问是否创建，对于非交互式安装默认创建。

安装后：

systemctl status veilgate
journalctl -u veilgate -f

选项 2 — Docker

docker run -d --name veilgate \
  --network host \
  -v /etc/veilgate/veilgate.yaml:/etc/veilgate/veilgate.yaml:ro \
  -v ~/.veilgate/rules:/home/nonroot/.veilgate/rules \
  -e VEILGATE_SECRET=$(openssl rand -hex 32) \
  ghcr.io/c0oki3s/veilgate:latest -config /etc/veilgate/veilgate.yaml

选项 3 — 从源码构建

前提条件：Go 1.25.10 或更新版本。

git clone https://github.com/C0oki3s/veilgate.git
cd veilgate
make build
./veilgate -config configs/veilgate.yaml

默认情况下，VeilGate 监听 :8080，代理到 http://localhost:3000，并在 :9090 暴露指标。

默认配置以 observe 模式启动——在启用 challenge 或 tarpit 之前先建立正常流量基线。

运行模式

推荐推出顺序：

1. 先运行 observe 至少几天。
2. 审查指标和事件样本，排除误报。
3. 为模棱两可的流量启用 challenge。
4. 当阈值符合你的环境后启用 tarpit。

配置

从 configs/veilgate.yaml 开始：

listen: ":8080"
upstream: "http://localhost:3000"
mode: "observe"
rules_dir: "~/.veilgate/rules"

detector:
  score_challenge_threshold: 40
  score_tarpit_threshold: 70
  trusted_ips: []
  trusted_proxies: []

metrics:
  listen: ":9090"

完整参考：配置参考。

规则

VeilGate 不内置任何规则。二进制文件在启动时读取 rules_dir 并热重载更改；如果目录为空，则零检测信号启动。规则来自一个地方：

• veilgate-rules — 社区维护的规则包。install.sh 脚本在首次安装时自动克隆。你也可以使用内置的 update-rules 子命令手动更新——无需重建，无需重启：

# 将最新规则包安装到 ~/.veilgate/rules（默认位置）
veilgate update-rules

# 或者固定到某个发布标签
veilgate update-rules --dir ~/.veilgate/rules --version v1.2.0

# 列出可用发布版本
veilgate update-rules --list

安装后，VeilGate 的 fsnotify 监视器在大约 500 毫秒内检测到新文件。每个现有文件在被覆盖前会备份为 <名称>.bak（传递 --no-backup 可跳过）。安装的版本记录在 <rules_dir>/.rules-version.json 中，以便 CI 和操作员无需查阅 git 元数据即可检查运行版本。

将两个目录都视为安全策略——在生产环境部署前审查更改，尤其是 detector.yaml 和 ip_reputation.yaml。完整指南和回滚步骤： docs/how-to/install-community-rules.md。

文档

• 入门指南：本地运行和首次检查。
• 配置参考：veilgate.yaml 和规则文件。
• 部署：Linux/systemd 安装。
• 架构：请求流程和子系统设计。
• 运维：指标、仪表盘、告警、例行检查。
• 模型卡片：ML 信号行为和限制。
• 参考索引：完整的面向查询的参考页面。
• 社区规则：通过 veilgate update-rules 安装和更新社区维护的规则集。
• 威胁模型：VeilGate 能保护和不保护的内容。

安全注意事项

• 仅在你拥有或运营的系统前部署 VeilGate。
• 不要直接向公网暴露指标监听器。
• 在使用 challenge 或 tarpit 模式前设置 VEILGATE_SECRET 或 challenge.secret。VeilGate 拒绝在 observe 模式之外以默认挑战密钥启动。
• 将 rules/ 下的文件视为安全策略。审查并对其进行版本管理。
• 从保守的阈值开始，并根据观察到的流量进行调整。

开发

make test
make fmt
make build

顶层 tests 文件夹包含黑盒集成测试。包级私有单元测试位于对应包旁边，因为它们验证未导出的检测器、TLS 指纹、tarpit 和 ML 辅助函数。

许可证

Apache-2.0。参见 LICENSE。