homelab-configs/apps/home-security-agent/README.md

# EL-KADI Home Security Agent

**Autonome** security agent voor thuis — zonder Wazuh, Uptime Kuma, n8n of Security Mesh.

De agent:
1. **Observeert** zelf (HTTP/TCP, Docker, Proxmox, LAN-gateway)
2. **Redeneert** (OpenAI met tools, of regels zonder API-key)
3. **Onthoudt** incidenten (SQLite, dedupe)
4. **Meld** via **Telegram**

## Starten

```bash
cd /volume1/docker/homelab-configs/apps/home-security-agent
cp .env.example .env
# Vul TELEGRAM_BOT_TOKEN en TELEGRAM_CHAT_ID in
# Optioneel: OPENAI_API_KEY voor agentische modus

docker-compose up -d --build
```

Eén run testen:

```bash
docker-compose run --rm security-agent python -m agent.main once
```

## Configuratie

| Bestand | Doel |
|---------|------|
| `config/targets.yaml` | Wat gemonitord wordt |
| `config/policies.yaml` | Interval, quiet hours, severity |
| `.env` | Telegram + OpenAI |

## Agentische modus (LLM)

Met `OPENAI_API_KEY` krijgt het model tools (`probe_tcp`, `probe_http`, `probe_proxmox`) en mag zelf verifiëren voordat het alert=true zet.

Zonder key: **regel-engine** (down services → Telegram).

## Uitbreiden

Voeg in `targets.yaml` services toe. Voor diepere agent-gedrag later:

- SSH-log tail (auth failures)
- Proxmox API (VM status) als aparte tool
- LAN device discovery + `known_hosts` whitelist
- Lokale Ollama (`AGENT_MODEL` + OpenAI-compatible URL)

## Dashboard

Alle observaties gaan naar **PostgreSQL** (`agent.observation_runs`, `agent.findings`, `agent.incidents`).

Bekijk ze in **Homelab Command**: http://192.168.1.105:8765/dashboard#security (tab Security → Home Security Agent).

Eénmalig schema:

```bash
docker exec -i postgres-homelab psql -U mo -d homelab < migrations/004_home_agent_observations.sql
# Postgres draait op VM 102: ssh mo@192.168.1.105 → docker exec postgres-homelab psql ...
```

Of vanuit homelab-command: `scripts/apply_mesh_migrations.sh` (past alle `migrations/*.sql` toe).

## Architectuur

```
┌─────────────┐     ┌──────────────┐     ┌────────────┐     ┌──────────┐
│  Observer   │────▶│    Brain     │────▶│ PostgreSQL │────▶│ Dashboard│
│ (eigen      │     │ LLM + tools  │     │ agent.*    │     │ :8765     │
│  probes)    │     │ of regels    │     └────────────┘     └──────────┘
└─────────────┘     └──────┬───────┘            │
                           │                    │
                    ┌──────▼───────┐     ┌──────▼───────┐
                    │ SQLite state │     │  Telegram    │
                    │ dedupe       │     │  meldingen   │
                    └──────────────┘     └──────────────┘
```