tech
f5d4852ad8
Root cause of a real production failure on the first live install
(wap-proxy, 2026-07-25): DB_PASSWORD was generated with
`openssl rand -base64 24`, which can produce '/', '+', or '=' --
docker-compose.yml then naively interpolated the raw password into
postgres://postgres:${DB_PASSWORD}@db:5432/..., and a generated
password containing '/' broke the connection string outright. The API
never became healthy; log ingestion failed completely.
- install.sh now generates with `openssl rand -hex 32` (always
[0-9a-f], can't produce this class of character). Same fix applied
everywhere else openssl-rand-base64-24 was referenced.
- docker-compose.yml no longer builds DATABASE_URL by string
interpolation -- DB_PASSWORD is passed as its own var and the API
assembles the connection string safely internally using
net/url.UserPassword (proper percent-encoding), a second,
independent layer so the installer doesn't rely on the password
generator alone. See the matching argus-appliance commit for the
Go-side change and its regression test.
- backup.sh/healthcheck.sh/restore.sh/uninstall.sh still defaulted
ARGUS_INSTALL_DIR to $HOME/argus, inconsistent with install.sh/
update.sh's own /opt/argus default (changed in an earlier commit
this session) -- confirmed live on the same install: healthcheck.sh
and uninstall.sh reported "no installation found" when run from the
real, correct directory. All five scripts now agree on /opt/argus.
Corresponding argus-appliance fix (config.go's buildDatabaseURL, v3.73.1)
already built and pushed to git-cloud.weboria.eu/weboria/argus-api.
277 lines
12 KiB
Markdown
277 lines
12 KiB
Markdown
<div align="center">
|
||
|
||
# ARGUS Enterprise Web Security Platform
|
||
|
||
### A real-time security operations platform for the modern web edge
|
||
|
||
[](LICENSE)
|
||
[]()
|
||
|
||
[](https://nginx.org/)
|
||
[](https://modsecurity.org/)
|
||
[](https://coreruleset.org/)
|
||
[]()
|
||
|
||
<p align="center">
|
||
<strong>Enterprise-grade protection for the modern web edge — in the same league as Fortinet,
|
||
Palo Alto, and F5, purpose-built for how applications are actually attacked today.</strong><br/>
|
||
<strong>Reverse proxy. Web Application Firewall. Bot and AI-crawler defense. DNS security.
|
||
Real-time threat intelligence. Live attack visualization. Incident investigation. One
|
||
appliance, one dashboard, zero blind spots.</strong>
|
||
</p>
|
||
|
||
<p align="center">
|
||
<a href="#-key-features">✨ Features</a> •
|
||
<a href="#-installation">🚀 Installation</a> •
|
||
<a href="#-operations">🛠 Operations</a> •
|
||
<a href="#-licensing--support">📄 Licensing & Support</a>
|
||
</p>
|
||
|
||
---
|
||
|
||
</div>
|
||
|
||
## ✨ Key Features
|
||
|
||
### 🛡️ Web Application Firewall
|
||
ModSecurity v3 running the full OWASP Core Rule Set, tunable across paranoia levels 1–4 per
|
||
site — start permissive on a new application, tighten as you learn its traffic. Detection-only
|
||
or blocking mode per host, per-rule exceptions for known false positives, and a Rule Health
|
||
view that tracks which rules are actually earning their keep versus generating noise, so tuning
|
||
is based on evidence, not guesswork.
|
||
|
||
### 🧠 ANIS Threat Intelligence
|
||
ARGUS ships connected by default to **ANIS (Argus Network Intelligence Server)**, Weboria's
|
||
community-powered reputation network: every ARGUS deployment that opts in contributes
|
||
confirmed-attacker IPs and receives the aggregated blocklist back in return, so your appliance
|
||
gets smarter from day one using signal from every other protected site — no license key
|
||
required for the free Community tier. Every dashboard, investigation view, and auto-ban
|
||
decision is enriched with live ANIS reputation scoring. A license key upgrades the tier —
|
||
manage it entirely from Threat Intel → ANIS Connection in the dashboard, or turn the
|
||
integration off entirely from the same page.
|
||
|
||
### 🌐 Attack Origin Visualization
|
||
A live global map of inbound attacks — real-time arcs from source to your infrastructure,
|
||
color-coded by severity, with a running feed of top attacking countries and IPs. Pause, rewind,
|
||
and replay historical traffic, or click straight through to any single event's full detail.
|
||
|
||
### 🔎 Incident Investigation
|
||
Pivot from any IP, log line, or dashboard event straight into that entity's complete history —
|
||
every affected host it touched, every rule it triggered, its geography and ASN, and its live
|
||
ANIS reputation score — all in one place, without losing your position in whatever you were
|
||
looking at.
|
||
|
||
### 🤖 Bot & AI-Crawler Defense
|
||
Automatically blocks known-bad bots and scrapers, with a maintained allowlist so legitimate
|
||
search engines are never caught in the net. Purpose-built detection for AI crawlers (GPTBot,
|
||
ClaudeBot, and similar) lets you choose exactly which ones are welcome. Escalating challenge
|
||
modes — silent browser verification, proof-of-work, visual CAPTCHA — apply exactly as much
|
||
friction as suspicious traffic actually warrants, backed by a live risk-scoring engine so the
|
||
decision is never a coin flip.
|
||
|
||
### 🧬 DNS Security Engine
|
||
Passive DNS intelligence starts working the moment your first site is protected — no network
|
||
reconfiguration required — scoring every domain your traffic touches for DGA patterns,
|
||
fast-flux infrastructure, and other red flags, and cross-referencing that against real WAF
|
||
activity for a much stronger signal than either check alone. An optional embedded resolver adds
|
||
network-wide DNS tunneling detection, NXDOMAIN-flood protection, and automatic sinkholing for
|
||
sites that want DNS-layer coverage too.
|
||
|
||
### 🌍 GeoIP & Cloud-Provider Access Control
|
||
Allow or block traffic by country or hosting provider, with live visual feedback as you tune
|
||
the policy — see exactly what would have been blocked before you commit to it.
|
||
|
||
### 🔒 Automated SSL
|
||
Let's Encrypt with automatic renewal, including wildcard certificates via DNS-01 challenge
|
||
across major DNS providers (Cloudflare, DuckDNS, Dynu, and more) — certificates that never
|
||
expire on your watch.
|
||
|
||
### ⚡ Rate Limiting & Auto-Ban
|
||
Configurable per-IP/per-URI rate limits, automatic banning on repeated WAF violations, and
|
||
community-intelligence-driven blocking via ANIS — layered defenses that reinforce each other
|
||
rather than working in isolation.
|
||
|
||
### 👥 Enterprise User Management
|
||
Role-based access control, per-user session management, forced password resets, account
|
||
lock/unlock as a reversible incident-response tool, mandatory MFA for administrators, and a
|
||
complete audit trail of every login and admin action — everything a security team needs to
|
||
administer access with confidence.
|
||
|
||
### 📊 Real-Time Operations Dashboard
|
||
Live traffic, security events, and system health updated continuously — a true operations
|
||
console, not a page you have to remember to refresh. Guided, role-based dashboard profiles (SOC
|
||
Analyst, Security Administrator, Network Administrator, Executive Overview) put the right view
|
||
in front of the right person automatically.
|
||
|
||
### 🎯 Guided Security Policy Center
|
||
Every protection module — WAF, DNS, GeoIP, Bot Protection, Rate Limiting, SSL/TLS, and more —
|
||
comes with one-click policy tiers from Home to Maximum Protection, a plain-language impact
|
||
preview before you apply anything, and an honest posture score that tells you exactly what's
|
||
configured, what's missing, and why it matters. No security expertise required to deploy with
|
||
confidence.
|
||
|
||
### 🔀 Load Balancing & Stream Proxying
|
||
Multiple backend servers with active health checks, plus TCP/UDP stream proxying with optional
|
||
SNI routing for non-HTTP services.
|
||
|
||
### 🔮 Modern Protocol Support
|
||
HTTP/3 (QUIC) and post-quantum-ready TLS (ML-KEM hybrid key exchange) — ready for where the web
|
||
is headed, not just where it's been.
|
||
|
||
---
|
||
|
||
## 🚀 Installation
|
||
|
||
### Requirements
|
||
|
||
- A Linux host with Docker Engine 24.0+ and the Docker Compose plugin (`docker compose`)
|
||
- 2 vCPU / 4 GB RAM minimum for evaluation; see production sizing guidance in `docs/` for
|
||
real traffic volumes
|
||
- Ports 80/443 available for the reverse proxy, and 81 for the admin panel (all configurable)
|
||
|
||
### One-line install
|
||
|
||
```bash
|
||
curl -fsSL https://git-cloud.weboria.eu/weboria/argus-installer/raw/branch/main/install.sh | bash
|
||
```
|
||
|
||
This downloads the deployment files, generates secure database/application secrets, creates the
|
||
required Docker network, pulls the production images, starts ARGUS, and prints your admin
|
||
login at the end. Installs to `/opt/argus` by default — set `ARGUS_INSTALL_DIR` first to change
|
||
that.
|
||
|
||
### Manual install
|
||
|
||
If you'd rather see every step:
|
||
|
||
```bash
|
||
mkdir -p /opt/argus/docker-socket-proxy && cd /opt/argus
|
||
curl -fsSL https://git-cloud.weboria.eu/weboria/argus-installer/raw/branch/main/docker-compose.yml -o docker-compose.yml
|
||
curl -fsSL https://git-cloud.weboria.eu/weboria/argus-installer/raw/branch/main/env.example -o .env
|
||
curl -fsSL https://git-cloud.weboria.eu/weboria/argus-installer/raw/branch/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 -hex 32)/" .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://<your-server-address>: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.
|
||
|
||
### Next steps after install
|
||
|
||
1. Open the administration panel at the access URL printed at the end of install.
|
||
2. Complete the first-run setup wizard — regional settings and a guided review of every
|
||
protection module.
|
||
3. Confirm your administrator password was rotated (the installer does this automatically).
|
||
4. Configure domains and reverse proxy hosts under **Proxy Hosts**.
|
||
5. Review the ANIS threat intelligence connection under **Threat Intel** — on by default
|
||
against the public Community Edition hub.
|
||
6. Review security policies in the **Security Policy Center**.
|
||
|
||
---
|
||
|
||
## 🛠 Operations
|
||
|
||
All lifecycle management is Docker-based — five scripts cover day-to-day operation, downloaded
|
||
once alongside `docker-compose.yml` (the one-line installer already does this for you), then run
|
||
from `/opt/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 |
|
||
|
||
You never manually download application files or modify containers directly — every update is
|
||
delivered as a new published image version.
|
||
|
||
### Upgrading
|
||
|
||
```bash
|
||
cd /opt/argus
|
||
docker compose pull
|
||
docker compose up -d
|
||
```
|
||
|
||
(`./update.sh` wraps the same two commands with a before/after version check.) This is the only
|
||
supported upgrade path; there is no separate migration step to run.
|
||
|
||
### Backups
|
||
|
||
```bash
|
||
cd /opt/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
|
||
|
||
ARGUS connects to **ANIS**, Weboria's threat-intelligence hub, to share confirmed attacker IPs
|
||
and receive a community blocklist in return. Enabled by default against the public Community
|
||
Edition hub — no license key required. Set `ANIS_ENABLED=false` in `.env` to turn this off
|
||
entirely. A license key upgrades the tier — set it from Threat Intel → ANIS Connection in the
|
||
dashboard, not from `.env`.
|
||
|
||
---
|
||
|
||
## 📚 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://<your-server-address>: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` | Threat-intel hub integration | `true` |
|
||
|
||
Full list with descriptions in `env.example`. ANIS's URL is fixed (`https://anis.weboria.eu`,
|
||
not configurable) and its license key is dashboard-only — neither is an env var.
|
||
|
||
---
|
||
|
||
## 📄 Licensing & Support
|
||
|
||
ARGUS is commercial software licensed by Weboria — see [LICENSE](LICENSE). Third-party
|
||
open-source components retain their own licenses — see
|
||
[THIRD_PARTY_LICENSES.md](THIRD_PARTY_LICENSES.md) and [NOTICE](NOTICE).
|
||
|
||
For licensing questions or support, contact the **Weboria Support Portal**.
|
||
|
||
---
|
||
|
||
<div align="center">
|
||
<sub>© 2025-2026 Weboria. ARGUS Enterprise Web Security Platform.</sub>
|
||
</div>
|