Add home-security-agent with PostgreSQL persistence for dashboard.

The autonomous agent writes all observations to agent.* tables consumed by Homelab Command on port 8765. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-17 21:57:16 +02:00
parent 43c4ed7a6d
commit 02b1d155d4
17 changed files with 1024 additions and 0 deletions
@@ -0,0 +1,78 @@
+# 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.211: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
+```
+
+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   │
+                    └──────────────┘     └──────────────┘
+```