# 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.