vpsik-lab/vpsGuard
GitHub: vpsik-lab/vpsGuard
一款轻量级的 VPS 安全代理，通过混合评分模型实时检测 SSH 暴力破解并结合威胁情报利用 nftables 自动阻断攻击者。
Stars: 0 | Forks: 0
# vpsGuard Agent
**用于保护 VPS 的轻量级智能安全 agent。**
检测 SSH brute-force，结合威胁情报（AbuseIPDB、AlienVault OTX）进行丰富，并通过 nftables 动态集阻止攻击者。
**二进制文件大小**：7.4 MB · **空闲 RAM**：~8 MB · **阻断延迟**：<100ms
## 这是什么？
vpsGuard **Agent** 是运行在您的 VPS 上的本地组件。
它监控 SSH 日志，使用混合模型对威胁活动进行评分，并阻止攻击者。
**Central Platform**（阶段 B — 开发中）将提供托管的威胁情报源，供 agent 拉取。
有关它们之间的接口，请参见 [`docs/AGENT-API-CONTRACT.md`](docs/AGENT-API-CONTRACT.md)。
## 功能
- **实时监控** — auth.log + systemd journal
- **混合评分** — 行为 (30%) + AbuseIPDB (25%) + OTX (20%) + 时间 (10%) + 中央数据源 (15%)
- **可配置阈值** — 阻断、速率限制、隔离分数 + 行为窗口/限制 + 时间 TTL 均可通过 `config.yaml` 配置
- **nftables 阻断** — 具有自动过期功能的动态集（IPv4 + IPv6 双栈）
- **IP 白名单** — 保护关键 IP 免受意外阻断
- **SHA256 验证** — install.sh 在安装前验证二进制校验和
- **离线工作** — 无需互联网即可完全正常运行
- **Telegram + 电子邮件警报** — 丰富的 HTML 通知
- **防篡改警报** — Watchdog 在配置校验和不匹配时立即触发 Telegram/电子邮件
- **每日报告** — 可选的每 24 小时通过 Telegram 发送包含安全摘要的报告
- **日志完整性** — 用于审计日志篡改检测的哈希链
- **自我保护** — Watchdog、systemd 沙盒、配置完整性、AppArmor profile
- **一条命令部署** — 30 秒内完成
- **完全卸载** — `bash install.sh --uninstall` 撤销所有操作
- **VPS 加固** — 可选的 `deploy/harden.sh`（SSH、UFW、BBR、sysctl、auditd、AppArmor、Docker、自动更新、进程记账）
- **持久化缓存** — SQLite IP 信誉缓存在服务重启后依然存在
- **CLI 管理** — `--list-blocked`、`--unblock `、`--status` 命令
- **Metrics endpoint** — Prometheus 文本格式 + JSON (`?format=json`) 的 `/metrics`
- **通过环境变量传递机密信息** — API 密钥和密码通过 `VPSGUARD_*` 环境变量传递（配置文件中无明文）
## 项目状态
| 阶段 | 组件 | 状态 | 描述 |
|-------|-----------|--------|-------------|
| **A** | Agent（本仓库） | ✅ **v0.3.0 — 稳定版** | 本地 SSH 保护、混合评分、nftables 阻断、VPS 加固、每日报告 |
| **B** | Central Platform | 🔜 开发中 | 托管的威胁情报源、agent 遥测、地理定向阻断 |
| **C** | Dashboard & Analytics | 📋 计划中 | Web dashboard、多 agent 管理、攻击可视化 |
Agent 可完全独立运行。阶段 B/C 是**独立的项目** —— 即使它们从未发布，Agent 的行为也不会受到影响。
## 许可证与版本
vpsGuard 是**开放核心**的：Agent 是免费的，并根据 **GNU AGPLv3** 开源。
| 功能 | 免费版 (AGPLv3) | 付费版 (Platform) |
|---------|---------------|-----------------|
| SSH brute-force 检测 | ✅ | ✅ |
| 本地混合评分 | ✅ | ✅ |
| nftables 自动阻断 | ✅ | ✅ |
| 威胁情报 (AbuseIPDB + OTX) | ✅ | ✅ |
| Telegram + 电子邮件警报 | ✅ | ✅ |
| 可配置阈值 | ✅ | ✅ |
| 所有源代码可用 | ✅ (AGPLv3) | ❌ (专有) |
| **中央威胁情报源** | ❌（需要 Platform） | ✅（基于提交） |
| 全球 IP 信誉网络 | ❌ | ✅ |
| 多 agent dashboard | ❌ | ✅ |
| 优先支持 | ❌ | ✅ |
**零遥测**：免费的 agent 绝不回传数据 —— 除非您配置了 AbuseIPDB/OTX API，否则不会进行任何外部连接。
## 快速开始
```
# 1. Build
git clone https://github.com/vpsik-lab/vpsGuard.git
cd vpsGuard
go build -ldflags="-s -w" -o vpsGuard ./cmd/vpsGuard/
# 2. Configure
cp config.yaml /etc/vpsGuard/config.yaml
# 编辑：设置 API keys、notification tokens 等。
# 提示：对于 secrets，请使用 env vars 而不是 plain-text。
# export VPSGUARD_ABUSEIPDB_KEY=your-key
# export VPSGUARD_TELEGRAM_TOKEN=your-token
# 3. Run
sudo ./vpsGuard -config /etc/vpsGuard/config.yaml
# 4. CLI management（在 agent 运行时）
sudo ./vpsGuard --list-blocked # view all blocked IPs
sudo ./vpsGuard --unblock 1.2.3.4 # unblock an IP
./vpsGuard --status # check agent health
curl http://127.0.0.1:9090/metrics # Prometheus metrics
curl http://127.0.0.1:9090/metrics?format=json # JSON metrics
```
或使用安装脚本：
```
# 需要 root/sudo：
curl -sSL https://raw.githubusercontent.com/vpsik-lab/vpsGuard/main/deploy/install.sh | sudo bash
```
对于无人值守安装（具有 sudo 权限的非 root 用户）：
```
curl -sSL https://raw.githubusercontent.com/vpsik-lab/vpsGuard/main/deploy/install.sh | sudo bash -s -- --unattended
```
有关完整的安装选项，请参见 [`docs/AGENT-DEPLOYMENT.md`](docs/AGENT-DEPLOYMENT.md)。
## 文档
| 文档 | 描述 |
|-----|-------------|
| [`AGENT-ARCHITECTURE.md`](docs/AGENT-ARCHITECTURE.md) | 内部架构、组件、事件流 |
| [`AGENT-SCORING.md`](docs/AGENT-SCORING.md) | 评分公式、阈值、边缘情况 |
| [`AGENT-DEPLOYMENT.md`](docs/AGENT-DEPLOYMENT.md) | 安装、配置、管理、故障排除 |
| [`AGENT-API-CONTRACT.md`](docs/AGENT-API-CONTRACT.md) | Agent 与 Central Platform 之间的契约 |
| [`THREAT_MODEL.md`](docs/THREAT_MODEL.md) | 威胁模型、信任边界、攻击场景 |
| [`TEST-COVERAGE.md`](docs/TEST-COVERAGE.md) | 单元测试清单（19 个文件，136 个测试） |
| [`RFC-0001-event-model.md`](docs/RFC-0001-event-model.md) | 事件 schema 规范 |
## 质量
| 指标 | 状态 |
|--------|--------|
| **测试** | 跨 20 个文件的 146 个测试函数 —— 所有 12 个 package 均通过 |
| **竞态检测** | `go test -race ./...` ✅（CI 强制执行） |
| **静态分析** | `go vet ./...` ✅ |
| **构建** | `go build ./...` ✅ amd64 / arm64 / arm |
| **测试文档** | [`docs/TEST-COVERAGE.md`](docs/TEST-COVERAGE.md) |
## 要求
- Ubuntu 20.04+ 或 Debian 11+
- systemd
- nftables
## 项目结构
```
├── cmd/vpsGuard/main.go Entry point
├── internal/
│ ├── api/ Central feed pull client
│ ├── bootstrap/ System hardening
│ ├── config/ YAML config + validation
│ ├── engine/ Scorer, decision, memory
│ ├── firewall/ nftables manager
│ ├── monitor/ Log tailing, parsing, behavioral analysis
│ ├── notify/ Telegram + Email
│ ├── pipeline/ Event bus + event types
│ ├── rules/ YAML rules engine
│ ├── selfprotect/ Watchdog + health
│ └── threat/ AbuseIPDB, OTX, cache
├── deploy/
│ ├── install.sh One-command installer
│ ├── vpsGuard.service systemd unit
│ └── vpsGuard.logrotate Log rotation config
└── docs/ Documentation
```
## 许可证
GNU AGPLv3
标签：EVTX分析, nftables, VPS安全, 入侵防御, 威胁情报, 安全防护, 开发者工具, 日志审计, 自定义请求头, 防暴力破解