alleyviperandGitHub
44f662afc0
Builds the customer-facing distribution: a curated distribution/ directory containing only what an end customer needs (production docker-compose.yml with no build: sections, install.sh/update.sh/uninstall.sh/healthcheck.sh/ backup.sh/restore.sh, a customer-facing CHANGELOG.md, and README/LICENSE/ NOTICE/THIRD_PARTY_LICENSES) — pushed as the initial content of the new public alleyviper/argus repo. install.sh: detects OS, validates Docker/Compose, fetches all deployment files, generates a secure DB password, creates the required Docker network, pulls images, starts the stack, waits for health, and rotates the default admin/admin credentials via the auth API — printing the generated password once at the end. update.sh/healthcheck.sh/backup.sh/restore.sh/uninstall.sh formalize what was previously ad-hoc README snippets into real, safe-by-default scripts (uninstall.sh keeps data unless --remove-data is explicitly passed and confirmed; restore.sh requires typed confirmation and documents that it targets a fresh install, not a live merge). Added a sync-distribution job to release.yml: after a successful release, mirrors distribution/ into the public repo and creates a matching (customer-facing, commit-log-free) release marker there. Needs a one-time setup step — a fine-grained PAT scoped to alleyviper/argus added as the ARGUS_PUBLIC_REPO_TOKEN secret — the job cleanly no-ops until that's added. Not yet done: GHCR package visibility (argus-secure-api/-ui/-nginx) is still private, which blocks a genuine end-to-end curl-install test from a clean, unauthenticated environment — deferred at the user's request until they flip it manually (GitHub does not expose this via API).
222 lines
8.2 KiB
Markdown
222 lines
8.2 KiB
Markdown
<div align="center">
|
||
|
||
# ARGUS
|
||
|
||
### Enterprise Web Security Platform
|
||
|
||
[](LICENSE)
|
||
[](https://github.com/alleyviper/argus/pkgs/container/argus-secure-api)
|
||
|
||
[](https://nginx.org/)
|
||
[](https://modsecurity.org/)
|
||
[](https://coreruleset.org/)
|
||
[]()
|
||
|
||
<p align="center">
|
||
<strong>A real-time security operations platform for the modern web edge.<br/>
|
||
Reverse proxy, Web Application Firewall, bot defense, DNS protection, and live threat
|
||
investigation — in one appliance.</strong>
|
||
</p>
|
||
|
||
<p align="center">
|
||
<a href="#-key-features">✨ Features</a> •
|
||
<a href="#-installation">🚀 Installation</a> •
|
||
<a href="#-operations">🛠 Operations</a> •
|
||
<a href="#-api">📚 API</a>
|
||
</p>
|
||
|
||
---
|
||
|
||
</div>
|
||
|
||
## ✨ Key Features
|
||
|
||
### 🛡️ Web Application Firewall
|
||
ModSecurity v3 with the OWASP Core Rule Set. Paranoia levels 1–4, per-host rule exceptions,
|
||
detection-only or blocking modes.
|
||
|
||
### 🌐 Attack Origin Visualization
|
||
A live global map of inbound attacks — real-time arcs from source to your infrastructure,
|
||
severity-coded, with instant drill-down into any event's full detail.
|
||
|
||
### 🔎 Incident Investigation
|
||
Pivot from any IP, log line, or dashboard event straight into that entity's complete history —
|
||
affected hosts, triggered rules, geography, and live threat-intelligence reputation — without
|
||
losing your place.
|
||
|
||
### 🤖 Bot & AI-Crawler Defense
|
||
Blocks known-bad bots and AI scrapers automatically, with a search-engine allowlist so legitimate
|
||
crawlers are never affected. Escalating challenge modes (browser check, proof-of-work, visual
|
||
CAPTCHA) for suspicious traffic.
|
||
|
||
### 🧬 DNS Security Engine
|
||
An embedded forwarding DNS resolver with real-time threat detection — DGA domains, DNS
|
||
tunneling, fast-flux infrastructure, cache-poisoning attempts — and automatic mitigation via
|
||
sinkholing.
|
||
|
||
### 🌍 GeoIP & Cloud-Provider Access Control
|
||
Allow or block traffic by country or hosting provider, with live visual feedback.
|
||
|
||
### 🔒 Automated SSL
|
||
Let's Encrypt with automatic renewal, including wildcard certificates via DNS-01 challenge
|
||
(Cloudflare, DuckDNS, Dynu, and more).
|
||
|
||
### ⚡ Rate Limiting & Auto-Ban
|
||
Configurable per-IP/per-URI rate limits, automatic banning on repeated WAF violations, and
|
||
optional community threat-intelligence-driven blocking.
|
||
|
||
### 👥 Full User Management
|
||
Role-based access, per-user session control, forced password resets, account lock/unlock, MFA,
|
||
and a complete login history — everything a security team needs to administer access safely.
|
||
|
||
### 📊 Real-Time Operations Dashboard
|
||
Live traffic, security events, and system health, updated continuously — no manual refresh.
|
||
|
||
### 🔀 Load Balancing & Stream Proxying
|
||
Multiple backend servers with health checks, plus TCP/UDP stream proxying with optional SNI
|
||
routing.
|
||
|
||
### 🔮 Modern Protocol Support
|
||
HTTP/3 (QUIC) and post-quantum-ready TLS (ML-KEM hybrid key exchange).
|
||
|
||
---
|
||
|
||
## 🚀 Installation
|
||
|
||
### Requirements
|
||
|
||
- A Linux host with Docker 24.0+ and the Docker Compose plugin (`docker compose`)
|
||
- Ports 80/443 available for the reverse proxy, and 81 for the admin panel (all configurable)
|
||
|
||
### One-line install
|
||
|
||
```bash
|
||
curl -fsSL https://raw.githubusercontent.com/alleyviper/argus/main/install.sh | bash
|
||
```
|
||
|
||
This downloads the deployment files, generates a secure database password, creates the
|
||
required Docker network, pulls the production images, starts ARGUS, and prints your admin
|
||
login at the end. Installs to `~/argus` by default — set `ARGUS_INSTALL_DIR` first to change
|
||
that.
|
||
|
||
### Manual install
|
||
|
||
If you'd rather see every step:
|
||
|
||
```bash
|
||
mkdir -p ~/argus/docker-socket-proxy && cd ~/argus
|
||
curl -fsSL https://raw.githubusercontent.com/alleyviper/argus/main/docker-compose.yml -o docker-compose.yml
|
||
curl -fsSL https://raw.githubusercontent.com/alleyviper/argus/main/.env.example -o .env
|
||
curl -fsSL https://raw.githubusercontent.com/alleyviper/argus/main/docker-socket-proxy/haproxy.cfg.template -o docker-socket-proxy/haproxy.cfg.template
|
||
|
||
# Generate a secure database password
|
||
sed -i "s/DB_PASSWORD=.*/DB_PASSWORD=$(openssl rand -base64 24)/" .env
|
||
|
||
# ARGUS expects this network to already exist
|
||
docker network create argus-network
|
||
|
||
docker compose pull
|
||
docker compose up -d
|
||
```
|
||
|
||
Then log in at `https://localhost:81` with `admin` / `admin` and change the password
|
||
immediately — the one-line installer does this rotation for you automatically.
|
||
|
||
**Do not expose the admin panel (port 81) to the internet.** Keep it on your LAN/VPN, or put
|
||
it behind its own proxy host with access lists and 2FA enabled.
|
||
|
||
---
|
||
|
||
## 🛠 Operations
|
||
|
||
Five scripts cover day-to-day operation — download them once alongside `docker-compose.yml`
|
||
(the one-line installer already does this for you), then run from `~/argus` (or wherever you
|
||
installed):
|
||
|
||
| Script | Purpose |
|
||
|--------|---------|
|
||
| `./update.sh` | Pull the latest images and restart, with a before/after version check |
|
||
| `./healthcheck.sh` | Report the status of every component and the admin panel |
|
||
| `./backup.sh [dir]` | Back up the database and application data into one archive |
|
||
| `./restore.sh <archive>` | Restore a backup onto a fresh installation |
|
||
| `./uninstall.sh [--remove-data]` | Stop ARGUS; data is kept unless you explicitly opt in to removing it |
|
||
|
||
### Upgrading
|
||
|
||
```bash
|
||
cd ~/argus
|
||
./update.sh
|
||
```
|
||
|
||
New versions are published to GHCR as soon as they're released — `update.sh` always pulls the
|
||
current stable release. This is the only supported upgrade path; there is no separate migration
|
||
step to run.
|
||
|
||
### Backups
|
||
|
||
```bash
|
||
cd ~/argus
|
||
./backup.sh # writes argus-backup-<timestamp>.tar.gz to the current directory
|
||
./restore.sh <archive> # onto a fresh installation only — see the script's own header
|
||
```
|
||
|
||
### Resetting the admin password
|
||
|
||
```bash
|
||
docker compose exec api ./server reset-password
|
||
```
|
||
|
||
Add `--username <name>` to target a specific account, or `--password '...'` to set a known
|
||
value instead of generating one. See `docker compose exec api ./server reset-password --help`
|
||
for the rest of the options (clearing 2FA, etc.).
|
||
|
||
### Threat intelligence integration (optional)
|
||
|
||
ARGUS can connect to **ANIS**, a separately-deployed threat-intelligence hub, to share confirmed
|
||
attacker IPs and receive a community blocklist in return. It's off by default — set
|
||
`ANIS_ENABLED=true` and `ANIS_URL` in `.env` to turn it on. See the comments in `.env.example`
|
||
for the full set of options.
|
||
|
||
---
|
||
|
||
## 📚 API
|
||
|
||
ARGUS exposes a full REST API for automation. Authenticate with a JWT (`POST
|
||
/api/v1/auth/login`) for interactive use, or an API token (`Authorization: Bearer ng_<token>`,
|
||
created from the admin panel) for CI/CD and scripted access. Interactive API documentation is
|
||
served at `https://localhost:81/api/docs` once ARGUS is running.
|
||
|
||
---
|
||
|
||
## ⚙️ Environment Variables
|
||
|
||
| Variable | Description | Default |
|
||
|----------|-------------|---------|
|
||
| `DB_PASSWORD` | Database password | *(generated by the installer)* |
|
||
| `TZ` | Timezone | `UTC` |
|
||
| `UI_PORT` | Admin panel port | `81` |
|
||
| `NGINX_HTTP_PORT` / `NGINX_HTTPS_PORT` | Reverse-proxy listen ports | `80` / `443` |
|
||
| `API_HOST_PORT` | Internal API port exposed to the host | `9080` |
|
||
| `DNS_LISTEN_HOST` | DNS Security Engine bind address | `127.0.0.1` |
|
||
| `ANIS_ENABLED` / `ANIS_URL` | Optional threat-intel hub integration | `false` / *(empty)* |
|
||
|
||
Full list with descriptions in `.env.example`.
|
||
|
||
---
|
||
|
||
## 📄 License
|
||
|
||
This is proprietary, commercial software — see [LICENSE](LICENSE). Third-party open-source
|
||
components retain their own licenses — see [THIRD_PARTY_LICENSES](THIRD_PARTY_LICENSES) and
|
||
[NOTICE](NOTICE).
|
||
|
||
## 💬 Support
|
||
|
||
[GitHub Issues](https://github.com/alleyviper/argus/issues) — bug reports and feature requests.
|
||
|
||
---
|
||
|
||
<div align="center">
|
||
<sub>© 2025-2026 ARGUS — AI4SEC.</sub>
|
||
</div>
|