argus-installer/README.md

ARGUS

Enterprise Web Security Platform

A real-time security operations platform for the modern web edge.
Reverse proxy, Web Application Firewall, bot defense, DNS protection, and live threat investigation — in one appliance.

✨ Features • 🚀 Installation • 🛠 Operations • 📚 API

---

This is the public ARGUS installer repository. It contains no proprietary source code — only installation scripts, configuration templates, and public documentation. Application source lives in private repos under the Weboria organization on Gitea: argus-appliance and anis-intelligence-server. Build/release automation lives in argus-build. Never commit application source, internal docs, or credentials into this repo.

Known gap, not yet built: install.sh today pulls public GHCR images with no license validation — it does not yet implement the "validate license → authenticate against a private registry → pull official images" flow. That needs a licensing service and private-registry auth design before install.sh can be updated to match.

✨ 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

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:

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

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

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

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. Third-party open-source components retain their own licenses — see THIRD_PARTY_LICENSES and NOTICE.

💬 Support

GitHub Issues — bug reports and feature requests.

---

_{© 2025-2026 ARGUS — AI4SEC.}