wilcon-agent/README.md

Wilcon Client Agent

Version: 0.3.3 Letzte Aktualisierung: 2025-06-29

🛍 Projektüberblick

Wilcon ist ein modularer Systemagent zur Überwachung von:

• System- und Hardwareinformationen
• Netzwerkdaten
• Laufenden Prozessen
• Benutzeraktivität (inkl. Steuerung via CLI)

Die Daten werden über eine REST-API bereitgestellt und in einem modernen Web-Dashboard dargestellt. Zusätzlich ist ein optionales CLI-Tool zur Benutzerkontrolle integriert (Safe Kiddo Agent).

---

📁 Projektstruktur

.
├── main.py                      # (Legacy) einfacher Info-Endpunkt
├── wilcon.py                   # FastAPI-Server mit API-Key-Schutz & CORS für 192.168.13.0/24
├── sysinfo.py                  # System- und Hardwareinfos (CPU, RAM, Disk, GPU, User)
├── netinf.py                   # Netzwerk- und Verbindungserfassung
├── proginfo.py                 # Prozessüberwachung mit Laufzeiten, CPU/RAM
├── user_control_agent.py       # CLI-Tool zur Benutzersteuerung
├── index.html                  # Web-Dashboard (Frontend)
├── style.css                   # Design für das Frontend
├── requirements.txt            # Abhängigkeiten (bereinigt, optional erweiterbar)
├── install_service.sh          # Installer für systemd (nicht mitgeliefert)
├── deploy.sh                   # Optionales Deploy-Skript (nicht mitgeliefert)
├── safe_kiddo_user_control.sh  # Hilfsskript für SafeKiddo CLI-Tool
└── tests/                      # Testverzeichnis mit pytest-Skripten

---

🚀 Installation

Voraussetzungen

• Python 3.9+
• Linux empfohlen (getestet unter Ubuntu)
• Root-Rechte für user_control_agent.py

Schritt 1 – Projekt klonen

git clone https://dein-git-repo/wilcon-agent.git
cd wilcon-agent

Schritt 2 – Virtuelle Umgebung (optional, empfohlen)

python3 -m venv venv
source venv/bin/activate

Schritt 3 – Abhängigkeiten installieren

pip install -r requirements.txt

Optional:

Falls GPU-Informationen oder erweiterte CPU-/OS-Erkennung benötigt werden:

pip install gputil py-cpuinfo distro

---

▶️ Anwendung starten

export WILCON_API_KEY=test123
uvicorn wilcon:app --host 0.0.0.0 --port 8080

Rufe dann das Webinterface auf unter: http://localhost:5500/index.html (Tipp: Live Server in VS Code verwenden)

Hinweis: Alle API-Endpunkte erfordern den HTTP-Header x-api-key:

curl -H "x-api-key: test123" http://localhost:8080/sysinfo

---

🌐 API-Endpunkte

Endpunkt	Beschreibung
/sysinfo	Hardware- und OS-Informationen
/netinfo	Netzwerk-Interfaces, IPs, Gateways, DNS
/procinfo	Laufende Prozesse mit CPU, RAM & Zeit

---

💡 Web-Dashboard

Das HTML-Dashboard bietet:

• Übersicht über Systemdaten
• Scrollbare und filterbare Tabellen
• Sortierbare Spalten (Prozesse, Netzwerk)
• GPU- und Benutzerinformationen

---

🔐 Safe Kiddo CLI (user_control_agent.py)

Ein Werkzeug zur lokalen Benutzerkontrolle, das u. a. folgende Funktionen bietet:

• Benutzer sperren/entsperren
• Countdown mit Sound & Benachrichtigung
• Shutdown nach Ablauf

Beispiel:

sudo python3 user_control_agent.py testuser disable --countdown --sound --time 30 --debug

Hinweis: notify-send, paplay o. ä. müssen installiert sein.

---

💠 Entwicklerhinweise

Logging

Jedes Modul loggt separat:

• ~/hardware_info.log
• ~/netinf.log
• ~/process_monitor.log
• ~/safe_kiddo_user_control.log

Debug-Modus

Alle CLI-Module und das Backend unterstützen --debug.

Hinweis zu hardware.py

Die Datei hardware.py war eine frühe Version von sysinfo.py und wurde durch letztere vollständig ersetzt. Sie kann aus dem Projekt entfernt werden.

Erweiterungsideen

• Authentifizierung (JWT, API-Key ✅)
• Langzeit-Logging (Prometheus, SQLite)
• Dockerisierung
• Web-Control für Safe Kiddo
• IP-basierte Netzwerkfilterung via allow_origin_regex ✅

---

🧪 Tests & Qualitätssicherung

Das Projekt nutzt pytest für automatisierte Tests.

Struktur

tests/
├── test_sysinfo.py     # Tests für System- und Hardwaredaten
├── test_netinf.py      # Tests für Netzwerkfunktionen
├── test_proginfo.py    # Tests für Prozessinformationen
└── test_api.py         # Tests für die FastAPI-Endpunkte

Beispiel-Test

from sysinfo import get_hardware_info

def test_sysinfo_contains_required_keys():
    data = get_hardware_info()
    assert "cpu" in data
    assert "ram" in data

Ausführung

pytest -v

---

🧑‍💻 Lizenz

Dieses Projekt ist derzeit privat. Für Open-Source-Freigabe bitte Lizenz ergänzen.

---

📞 Kontakt

Erstellt von [Dein Name] Kontakt: [email@example.com]