log-guardian/README.md

Log Guardian

Private Loki-backed service for log monitoring, alerting, and guarded remediation.

Current implementation includes the Phase 1 foundations:

• watches configured LogQL rules;
• records incidents when thresholds are met;
• enforces per-rule cooldowns;
• protects the UI with basic auth while leaving /healthz open;
• provides Loki label/query diagnostics;
• supports UI-configurable alert channels with real ntfy delivery;
• keeps remediation in dry-run by default;
• includes local-only Ollama analysis support, disabled by default.

Run locally

cp .env.example .env
# edit env values, then export them or use your shell dotenv helper
go run ./cmd/server

Open http://localhost:8080.

Configuration

Variable	Default	Purpose
LOG_GUARDIAN_ADDR	:8080	HTTP listen address.
LOG_GUARDIAN_DATA_PATH	/data/config.json	Local JSON config.
LOG_GUARDIAN_POLL_INTERVAL	1m	Rule evaluation interval.
LOG_GUARDIAN_DRY_RUN_ACTIONS	true	Prevents real remediation actions.
LOG_GUARDIAN_AUTH_USERNAME / LOG_GUARDIAN_AUTH_PASSWORD	empty	Required basic auth credentials for UI/API routes except /healthz.
LOKI_URL	http://loki:3100	Loki base URL.
LOKI_TENANT_ID	empty	Optional Loki tenant header.
LOKI_USERNAME / LOKI_PASSWORD	empty	Optional basic auth.
LOG_GUARDIAN_ANALYSIS_PROVIDER	none	none or local-only ollama.
LOG_GUARDIAN_OLLAMA_URL / LOG_GUARDIAN_OLLAMA_MODEL	http://ollama:11434 / llama3.1	Local Ollama analysis config.

Initial Loki setup

A starter Loki + Promtail stack is in deploy/loki/:

cd deploy/loki
docker compose up -d

Promtail is configured to discover Docker containers and attach useful labels:

• container
• service
• stack
• stream

Example LogQL rules:

{service="api"} |= "error"
{stack="second-brain"} |~ "(?i)(panic|fatal|exception)"
{container=~".*postgres.*"} |= "database system is ready"

Deploy in Portainer

Use deploy/portainer-stack.yml with values from deploy/portainer.env.example.

Keep this set while testing:

LOG_GUARDIAN_DRY_RUN_ACTIONS=true
LOG_GUARDIAN_ANALYSIS_PROVIDER=none

Build and validate

make ci-fast

Safety model

Automatic remediation is intentionally constrained:

1. A rule must match.
2. The configured threshold must be exceeded.
3. The action must be explicitly enabled on that rule.
4. Global dry-run must be disabled.
5. Future AI recommendations are advisory unless a rule explicitly allows a matching action type.

Do not enable production remediation until a later phase explicitly approves concrete action types and guardrails.