208 lines
5.0 KiB
Markdown
208 lines
5.0 KiB
Markdown
# 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
|
||
|
||
```text
|
||
.
|
||
├── 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
|
||
|
||
```bash
|
||
git clone https://dein-git-repo/wilcon-agent.git
|
||
cd wilcon-agent
|
||
```
|
||
|
||
### Schritt 2 – Virtuelle Umgebung (optional, empfohlen)
|
||
|
||
```bash
|
||
python3 -m venv venv
|
||
source venv/bin/activate
|
||
```
|
||
|
||
### Schritt 3 – Abhängigkeiten installieren
|
||
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
#### Optional:
|
||
|
||
Falls GPU-Informationen oder erweiterte CPU-/OS-Erkennung benötigt werden:
|
||
|
||
```bash
|
||
pip install gputil py-cpuinfo distro
|
||
```
|
||
|
||
---
|
||
|
||
## ▶️ Anwendung starten
|
||
|
||
```bash
|
||
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](http://localhost:5500/index.html)
|
||
(**Tipp:** Live Server in VS Code verwenden)
|
||
|
||
**Hinweis:** Alle API-Endpunkte erfordern den HTTP-Header `x-api-key`:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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](https://pytest.org) für automatisierte Tests.
|
||
|
||
### Struktur
|
||
|
||
```text
|
||
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
|
||
|
||
```python
|
||
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
|
||
|
||
```bash
|
||
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](mailto:email@example.com)]
|