LLM Analysis

LLM Analysis (optional)

secwatch can send a compact evidence pack of recent traffic to any OpenAI-compatible endpoint and get back a plain-language assessment: a threat level, a summary, specific findings, and hardening recommendations. It appears in the dashboard's AI traffic analysis card.

This is off by default. Not every homelab runs an LLM, and secwatch is fully useful without one.

Enable

secwatch talks to any OpenAI-compatible /chat/completions endpoint — a local runner or a hosted API. Same config either way; a hosted API just adds a key.

Local model (private — nothing leaves your box)

llm:
  enabled: true
  base_url: http://127.0.0.1:11434/v1   # Ollama; also vLLM / LM Studio / llama.cpp
  model: your-model
  alert_threat: elevated                 # alert at this threat level or higher

Hosted API (OpenAI, OpenRouter, Together, Groq, Azure, …)

llm:
  enabled: true
  base_url: https://api.openai.com/v1
  model: gpt-4o-mini
  api_key_file: /path/to/.secrets/llm-api-key   # key read from a file, not inline

The key is sent as Authorization: Bearer <key>. Provide it three ways (in order of precedence): the SECWATCH_LLM_API_KEY env var, llm.api_key inline, or llm.api_key_file (a file containing the raw key — keeps the secret out of your config; put it somewhere gitignored like .secrets/).

Other knobs:

• json_mode: true (default) asks for a structured JSON reply via response_format. A few providers reject that — set json_mode: false and secwatch still parses the JSON out of the reply.
• temperature (default 0.2) and max_tokens (default 2000) are configurable.
• If a call fails, the dashboard's AI analysis view shows the provider's actual error (e.g. an auth or model-name problem), so it's easy to fix.

The install wizard auto-detects a local endpoint if one is running, but always leaves LLM disabled until you turn it on.

Privacy: a hosted API means the evidence pack (traffic metadata — see below) leaves your box to that provider. If that's not acceptable, use a local model.

What gets sent

A bounded evidence pack: aggregated traffic stats, top talkers/paths/user-agents (capped), and recent notable events — plus reverse-DNS for talkers. It does not ship your whole log. Review the size caps in the llm.* section of secwatch.example.yaml if you want to tighten what leaves the box, and prefer a local model if traffic metadata shouldn't go to a third party.

When it runs

• On an interval (default every 6h), after some traffic has accumulated.
• On demand — click Analyze now in the dashboard.

If the analysis rates the situation at or above alert_threat, secwatch sends an alert.

Steering it

Two site-config lists keep the analysis focused on your environment:

known_legitimate_endpoints:   # paths that are legit by design — don't flag
  - "/api/health"
active_mitigations:           # defenses already in place — don't re-recommend
  - "Cloudflare in front of all public hosts"

LLM output is advisory — verify before acting on a recommendation.