Installation

Installation

secwatch is a single Python app. The fastest path is the install wizard; you can also configure it by hand.

Requirements

• Python 3.11+
• A reverse-proxy access log to read (Traefik JSON, nginx combined, Caddy JSON, or a custom format via regex) — or any app access log.
• Optional: Docker (image CVE scanning + container watch), an OpenAI-compatible LLM endpoint (AI analysis), and nft or nginx if you want those ban actuators.

Option A — install wizard (recommended)

git clone https://github.com/Paco5687/secwatch && cd secwatch
python -m venv .venv && . .venv/bin/activate && pip install -r requirements.txt

python -m secwatch.install

The wizard:

1. Asks for the port to serve the dashboard on.
2. Creates a local admin login (username + password → stored only as a hash).
3. Auto-detects your reverse proxy + access log, app hosts, network topology (→ trusted nets), running images, web dirs, and any local LLM endpoint.
4. Writes a reviewable secwatch.yaml (chmod 600).
5. Can generate a systemd unit so it starts on boot.

Then open http://SERVER-IP:PORT/ and sign in. Review secwatch.yaml before relying on it — auto-detection is best-effort.

Option B — manual setup

git clone https://github.com/Paco5687/secwatch && cd secwatch
python -m venv .venv && . .venv/bin/activate && pip install -r requirements.txt

cp secwatch.example.yaml secwatch.yaml
# edit secwatch.yaml — at minimum set paths.access_log and log_source.type
python -m secwatch.main

Prefer a starting point? python -m secwatch.init probes your host and prints a draft secwatch.yaml you can edit.

See Configuration for what to set.

Running as a service (systemd)

The installer can write this for you. A minimal user or system unit looks like:

[Unit]
Description=secwatch — self-hosted security monitor
After=network-online.target

[Service]
WorkingDirectory=/opt/secwatch
ExecStart=/opt/secwatch/.venv/bin/python -m secwatch.main
Restart=on-failure

[Install]
WantedBy=multi-user.target

systemctl enable --now secwatch      # system unit
# or, for a user unit:
systemctl --user enable --now secwatch

The working tree is what runs — restart the service after changing code or secwatch.yaml.

Docker

docker compose up -d

See Deployment for mounts, resource limits, and the all/core/agent modes.

Upgrading

secwatch notifies when a newer version is published (it never auto-updates your code). To upgrade a git checkout:

git pull
. .venv/bin/activate && pip install -r requirements.txt   # in case deps changed
systemctl restart secwatch

Your secwatch.yaml, database, and dashboard-added log sources are untouched by an upgrade.