Implement phase 1 foundations

2026-07-03 20:14:06 -08:00
commit 6f7549d439
39 changed files with 2221 additions and 0 deletions
@@ -0,0 +1,92 @@
+# 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
+
+```sh
+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/`:
+
+```sh
+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:
+
+```logql
+{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:
+
+```text
+LOG_GUARDIAN_DRY_RUN_ACTIONS=true
+LOG_GUARDIAN_ANALYSIS_PROVIDER=none
+```
+
+## Build and validate
+
+```sh
+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.