Deployment

Deployment

secwatch runs fine as a plain Python process (see Installation). This page covers Docker and the split-deployment modes.

Docker

docker compose up -d

The provided docker-compose.yml documents the host mounts you'll need (the log file(s) to read, and — depending on your ban actuator — the proxy's dynamic config directory). The image runs as a non-root user with a healthcheck and resource limits.

Notes:

• The image does not bundle the Docker CLI. CVE scanning and container-watch degrade gracefully without it; mount the Docker socket (ideally read-only via a socket-proxy) and add the CLI, or use agent mode for host-level collectors.
• Mount only what secwatch needs to read. Least privilege keeps the internet-facing part small.

Modes

SECWATCH_MODE selects what a process runs:

Mode	Runs	Use it for
all	everything in one process (default)	the classic single-host setup
core	detection, dashboard, CVE, LLM, alerting, ban — no host collectors	an isolated container that shouldn't have deep host access
agent	only host collectors (auth/host/process/docker), forwarding events to a core	running on the host, feeding a containerized core

core + agent split

Run a low-privilege core (the web/detection brain, in a container) and a minimal agent on the host that has the deep access (reads auth.log, /proc, Docker) and forwards findings:

# on the host
SECWATCH_MODE=agent \
SECWATCH_CORE_URL=http://CORE-HOST:8931 \
SECWATCH_INGEST_TOKEN=shared-secret \
python -m secwatch.agent

The core accepts events at a token-gated POST /api/ingest (SECWATCH_INGEST_TOKEN must match). This keeps the internet-facing core low-privilege while the part that needs host access stays a small host process.

Self-maintenance

secwatch is built to be "set and forget":

• Health checks — database, disk, KEV freshness, ban actuator, and edge liveness are self-monitored and surfaced at GET /api/health.
• Retention — events and traffic history are pruned automatically.
• Log rotation — handled for the logs it tails.
• Update awareness — it notifies when a newer version is published but never auto-updates your code.