vpsik-lab/vpsGuard

# vpsGuard Agent **Lightweight intelligent security agent for VPS protection.** Detects SSH brute-force, enriches with threat intelligence (AbuseIPDB, AlienVault OTX), and blocks attackers via nftables dynamic sets. **Binary size**: 7.4 MB · **Idle RAM**: ~8 MB · **Block latency**: <100ms ## What is this? vpsGuard **Agent** is the on-premise component that runs on your VPS. It monitors SSH logs, scores threat activity using a hybrid model, and blocks attackers. The **Central Platform** (Phase B — in development) will provide a managed threat intelligence feed that agents can pull from. See [`docs/AGENT-API-CONTRACT.md`](docs/AGENT-API-CONTRACT.md) for the interface between them. ## Features - **Real-time monitoring** — auth.log + systemd journal - **Hybrid scoring** — Behavioral (30%) + AbuseIPDB (25%) + OTX (20%) + Temporal (10%) + Central Feed (15%) - **Configurable thresholds** — Block, rate-limit, quarantine scores + behavior window/limit + temporal TTL all via `config.yaml` - **nftables blocking** — Dynamic sets with auto-expire (IPv4 + IPv6 dual-stack) - **IP Whitelist** — Protect critical IPs from accidental blocking - **SHA256 verification** — install.sh verifies binary checksums before install - **Works offline** — Fully functional without internet - **Telegram + Email alerts** — Rich HTML notifications - **Tamper alerts** — Watchdog fires immediate Telegram/Email on config checksum mismatch - **Daily reports** — Optional Telegram report every 24h with security summary - **Log integrity** — Hash chain for audit log tamper detection - **Self-protecting** — Watchdog, systemd sandbox, config integrity, AppArmor profile - **One-command deploy** — Under 30 seconds - **Full uninstall** — `bash install.sh --uninstall` undoes everything - **VPS hardening** — Optional `deploy/harden.sh` (SSH, UFW, BBR, sysctl, auditd, AppArmor, Docker, auto-updates, process accounting) - **Persistent cache** — SQLite IP reputation cache survives service restarts - **CLI management** — `--list-blocked`, `--unblock `, `--status` commands - **Metrics endpoint** — `/metrics` in Prometheus text format + JSON (`?format=json`) - **Secrets via env vars** — API keys and passwords via `VPSGUARD_*` env vars (no plain-text in config) ## Project Status | Phase | Component | Status | Description | |-------|-----------|--------|-------------| | **A** | Agent (this repo) | ✅ **v0.3.0 — Stable** | On-premise SSH protection, hybrid scoring, nftables blocking, VPS hardening, daily reports | | **B** | Central Platform | 🔜 In development | Managed threat intelligence feed, agent telemetry, geo-targeted blocking | | **C** | Dashboard & Analytics | 📋 Planned | Web dashboard, multi-agent management, attack visualization | The Agent is fully functional standalone. Phase B/C are **separate projects** — the Agent's behaviour is unaffected if they never ship. ## License & Editions vpsGuard is **open-core**: the Agent is free and open-source under **GNU AGPLv3**. | Feature | Free (AGPLv3) | Paid (Platform) | |---------|---------------|-----------------| | SSH brute-force detection | ✅ | ✅ | | Local hybrid scoring | ✅ | ✅ | | nftables auto-blocking | ✅ | ✅ | | Threat intel (AbuseIPDB + OTX) | ✅ | ✅ | | Telegram + Email alerts | ✅ | ✅ | | Configurable thresholds | ✅ | ✅ | | All source code available | ✅ (AGPLv3) | ❌ (proprietary) | | **Central threat feed** | ❌ (requires Platform) | ✅ (submission-based) | | Global IP reputation network | ❌ | ✅ | | Multi-agent dashboard | ❌ | ✅ | | Priority support | ❌ | ✅ | **Zero telemetry**: the free Agent never phones home — no outbound connections unless you configure AbuseIPDB/OTX APIs. ## Quick Start # 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 # Edit: set API keys, notification tokens, etc. # TIP: use env vars for secrets instead of 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 (while agent is running) 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 Or use the install script: # Requires root/sudo: curl -sSL https://raw.githubusercontent.com/vpsik-lab/vpsGuard/main/deploy/install.sh | sudo bash For unattended installation (non-root with sudo): curl -sSL https://raw.githubusercontent.com/vpsik-lab/vpsGuard/main/deploy/install.sh | sudo bash -s -- --unattended See [`docs/AGENT-DEPLOYMENT.md`](docs/AGENT-DEPLOYMENT.md) for full installation options. ## Documentation | Doc | Description | |-----|-------------| | [`AGENT-ARCHITECTURE.md`](docs/AGENT-ARCHITECTURE.md) | Internal architecture, components, event flow | | [`AGENT-SCORING.md`](docs/AGENT-SCORING.md) | Scoring formula, thresholds, edge cases | | [`AGENT-DEPLOYMENT.md`](docs/AGENT-DEPLOYMENT.md) | Install, configure, manage, troubleshoot | | [`AGENT-API-CONTRACT.md`](docs/AGENT-API-CONTRACT.md) | Contract between Agent and Central Platform | | [`THREAT_MODEL.md`](docs/THREAT_MODEL.md) | Threat model, trust boundaries, attack scenarios | | [`TEST-COVERAGE.md`](docs/TEST-COVERAGE.md) | Unit test inventory (19 files, 136 tests) | | [`RFC-0001-event-model.md`](docs/RFC-0001-event-model.md) | Event schema specification | ## Quality | Metric | Status | |--------|--------| | **Tests** | 146 test functions across 20 files — all 12 packages pass | | **Race detection** | `go test -race ./...` ✅ (CI enforces) | | **Static analysis** | `go vet ./...` ✅ | | **Build** | `go build ./...` ✅ amd64 / arm64 / arm | | **Test docs** | [`docs/TEST-COVERAGE.md`](docs/TEST-COVERAGE.md) | ## Requirements - Ubuntu 20.04+ or Debian 11+ - systemd - nftables ## Project Structure ├── 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 ## License GNU AGPLv3

标签：EVTX分析