# barox Switch Test Companion Internes Engineering-Werkzeug zur strukturierten Evaluation neuer Switch-Modelle. Das Tool führt das Testteam Schritt für Schritt durch alle Testkategorien, SFP-Prüfungen und Szenarien, dokumentiert Ergebnisse und Nachweise, berechnet eine transparente technische Empfehlung und erzeugt einen professionellen **barox Switch Evaluation Report** als PDF. Grundlage der Testinhalte ist die mitgelieferte Excel-Checkliste `docs/Switch_Test_Checkliste.xlsx` (Blätter *Switch Test Checklist*, *SFP*, *Szenarien*), die in versionierte Vorlagen importiert wird. --- ## Funktionsumfang (Version 1) - **Geführter Testmodus (Assistent)** – Stammdaten → Umgebung → Topologie → Testfälle → SFP-Matrix → Szenarien → Zusammenfassung → Report. - **Excel-Import** der Checkliste in **versionierte** Vorlagen. Bestehende Testläufe bleiben bei einem Neu-Import unverändert (Snapshot-Kopie). - **150 Testfälle** in 15 Kategorien, **18 SFP-Module**, **10 Szenarien** – vollständig aus der Excel übernommen. - **Vorlagen (Profile)**: benannte Test-Auswahlen je Gerätetyp (z. B. L2-Switch, L3-Switch, Medienkonverter). Beim Anlegen eines Testlaufs wird eine Vorlage gewählt; nur deren Tests werden geladen. - Pro Testfall: Status, Priorität, Bewertung (1–10), Ist-Ergebnis, Messwerte, Notizen, interne Bemerkung, Hersteller-Rückfrage, Nachweise (Uploads). - **SFP-Testmatrix** mit DOM/DDM-Werten, Hot-Plug, Link/Speed/Duplex. - **Szenarien** mit Testziel, Voraussetzungen, Schritten, Messwerten, Bewertung. - **Findings** entstehen automatisch aus fehlgeschlagenen / teilweise bestandenen Tests; manuelle Findings ebenfalls möglich. - **Automatische Empfehlung** (Freigeben / Nachbessern / Ablehnen) mit transparenter Begründung; manuell überschreibbar mit Pflichtbegründung. - **Dashboard** mit Kennzahlen, Fortschritt, Ampelstatus, letzten Aktivitäten. - **PDF-Report** im barox Corporate Design (Deckblatt, Executive Summary, Empfehlung, Findings, Detailtabellen, SFP-Matrix, Szenarien, Anhänge). - **Rollen & Rechte** (Admin / Tester / Viewer), **MS365-Anmeldung** (OIDC) und lokale Anmeldung. - **Audit-Log**, **CSRF-Schutz**, Prepared Statements, Upload-Validierung. - **Automation**: SNMP-System-Info (sysName/sysDescr/sysUpTime) und ein **SSH-Command-Runner** – pro Test kann ein Prüf-Kommando hinterlegt werden (Admin → Test-Katalog); im Assistenten wird einmal die SSH-Verbindung hergestellt und der Check je Test per Klick ausgeführt. Ausgabe wird als Nachweis (.log) gespeichert, bei hinterlegtem Erwartungsmuster wird der Status automatisch gesetzt. Weitere Adapter sind vorbereitet (Version 2). - **Dokumenten-Extraktion (lokale KI)**: Originaldokument hochladen (Datenblatt, Config-Export, Prüfbericht) – eine lokale, OpenAI-kompatible LLM liest die Switch-Stammdaten aus und füllt leere Felder automatisch. --- ## Technischer Stack | Bereich | Technologie | |----------------|---------------------------------------------------------| | Sprache | PHP 8.1+ (getestet mit 8.5), keine Framework-Abhängigkeit | | Datenbank | MySQL 8 / MariaDB 10.4+ (InnoDB, utf8mb4) | | Webserver | Apache 2.4 (Ubuntu) mit `mod_rewrite` | | PDF | dompdf (optional, via Composer) mit HTML-Druck-Fallback | | Auth | Lokale Benutzer + Microsoft 365 / Entra ID (OpenID Connect) | | Frontend | Serverseitiges PHP-Templating, barox Design System (CSS) | Die Anwendung folgt einer schlanken **MVC-Struktur** ohne externe Framework-Abhängigkeit. Ein eigener PSR-4-Autoloader funktioniert auch ohne Composer; Composer wird nur für dompdf (PDF) benötigt. --- ## Projektstruktur ``` app/ Controllers/ HTTP-Controller (inkl. Admin/) Core/ Framework (Router, DB, Auth, View, Session, CSRF, …) Middleware/ Authenticate, RequirePermission, RedirectIfAuthenticated Models/ Table-Data-Gateway-Modelle Services/ Geschäftslogik (Import, Metrics, Empfehlung, Report, PDF) Automation/ Automation-Adapter (SNMP aktiv, weitere vorbereitet) Views/ PHP-Templates (Layouts, Partials, Seiten, Report) bootstrap.php Autoloader, Env, Config, Fehlerbehandlung, Session helpers.php View-Hilfsfunktionen (e, url, asset, csrf_field, …) routes.php Routen-Definition assets/ barox Design System, Fonts, Logos, app.css, app.js config/ config.php (liest aus .env) database/migrations/ SQL-Schema (001_schema.sql) docs/ Excel-Checkliste + INSTALL.md public/ Web-Root (index.php Front-Controller, .htaccess) scripts/ CLI: migrate, import_excel, seed, create_admin, genkey storage/ Uploads (test-runs/), Logs, Import-Ablage ``` --- ## Schnellstart (lokal) Voraussetzung: PHP 8.1+, MySQL erreichbar, Composer (für PDF). ```bash cp .env.example .env php scripts/genkey.php # Ausgabe in .env als APP_KEY eintragen # .env: DB-Zugang, APP_URL, AUTH_MODE anpassen composer install # optional, aktiviert native PDF-Erzeugung php scripts/migrate.php # Schema anlegen php scripts/seed.php # Rollen, Einstellungen, Excel-Import php scripts/create_admin.php "Admin" admin@barox.ch "GeheimesPasswort10+" # Entwicklungsserver (Web-Root = public/) php -S 127.0.0.1:8000 -t public public/index.php ``` Aufruf: → Anmeldung mit dem angelegten Admin. > Der eingebaute PHP-Server liefert `/assets` automatisch aus. Unter Apache > wird dafür ein `Alias` gesetzt – siehe [docs/INSTALL.md](docs/INSTALL.md). Beispieldaten (Demo-Testlauf) erzeugen: ```bash php scripts/seed.php --demo ``` Die vollständige **Ubuntu-Installationsanleitung** steht in [docs/INSTALL.md](docs/INSTALL.md). --- ## Rollen & Rechte | Recht / Rolle | Admin | Tester | Viewer | |----------------------------|:----:|:------:|:------:| | Testläufe ansehen | ✔ | ✔ | ✔ | | Reports herunterladen | ✔ | ✔ | ✔ | | Testläufe anlegen/bearbeiten | ✔ | ✔ | | | Tests durchführen, Uploads | ✔ | ✔ | | | Reports generieren | ✔ | ✔ | | | Findings verwalten | ✔ | ✔ | | | SNMP-Automation ausführen | ✔ | ✔ | | | Excel importieren | ✔ | | | | Vorlagen / Benutzer / Einstellungen | ✔ | | | | Testläufe / Reports löschen | ✔ | | | Die Zuordnung ist zentral in `app/Core/Auth.php` (`PERMISSIONS`) definiert. --- ## Bewertungslogik (Empfehlung) Berechnet in `app/Services/RecommendationEngine.php`: - ≥ 2 kritische Tests fehlgeschlagen → **Ablehnen** - 1 kritischer Test fehlgeschlagen → mind. **Nachbessern** - Sicherheitsrelevante Tests fehlgeschlagen → mind. **Nachbessern** (≥ 2 → Ablehnen) - Wichtige Tests blockiert → mind. **Nachbessern** - Ø-Bewertung < 6 → **Ablehnen**; 6–8 → **Nachbessern**; ≥ 8 ohne kritische Fehler → **Freigeben** Die Begründung wird im Report transparent aufgeführt. Tester können die Empfehlung manuell überschreiben – dann ist eine Begründung Pflicht. --- ## Begriffe: Tests, Katalog & Vorlagen - **Test** – ein einzelner Prüfpunkt (z. B. „802.1Q VLAN", „PoE Budget"). - **Test-Katalog** – die Gesamtheit aller Tests (sowie SFP-Module und Szenarien), importiert aus der Excel-Checkliste; pro Import **versioniert**. Bearbeitung unter *Admin → Test-Katalog*. - **Vorlage** – eine **benannte Auswahl von Tests** aus dem Katalog, z. B. „L2-Switch", „L3-Switch" oder „Medienkonverter". Verwaltung unter *Admin → Vorlagen*. Beim Anlegen eines Testlaufs wird **eine Vorlage gewählt** (oder der gesamte Katalog); nur deren Tests, Szenarien und SFP-Module werden in den Testlauf kopiert. Man kann beliebig viele Vorlagen anlegen und je Vorlage die passenden Tests, Szenarien und SFP-Module an-/abwählen (Datenmodell: `profiles`, `profile_tests`, `profile_scenarios`, `profile_sfps`; Migration `002_profiles.sql`). ## Vorlagen-Versionierung (wichtig) Jeder Excel-Import legt eine **neue `template_version`** an und setzt sie aktiv. Beim Anlegen eines Testlaufs werden die Testfälle, SFP-Module und Szenarien der aktiven Version **als Kopie** in den Testlauf geschrieben (Tabellen `test_cases`, `sfp_test_results`, `scenario_results`). Ein späterer Re-Import verändert daher **keine** bestehenden Testläufe. --- ## Automation-Roadmap (Version 2) Version 1 arbeitet manuell. Die Architektur (`app/Services/Automation/`, `ProbeInterface`, `AutomationRegistry`) ist so ausgelegt, dass folgende Adapter ohne strukturelle Änderung ergänzt werden können: SNMP Walk/Set/Trap, SSH Command Runner, Ping-Checks, iPerf, LLDP-Discovery, SFP-DOM-Auslesung, CPU/RAM/Temperatur-Monitoring, PoE-Status, Firmware-Auslesung, Umschaltzeit- Messung, WebGUI-Erreichbarkeit. Aktiv ist bereits der **SNMP-System-Info-Prototyp**. --- ## Getroffene Annahmen Da die Excel nur Kategorie + Testname liefert, wurden sinnvolle Standards ergänzt und hier dokumentiert: 1. **Prioritäten** werden beim Import je Kategorie vorbelegt (z. B. Security/PoE/ Multicast/Performance = *Hoch*, Hardware/QoS = *Mittel*); ausgewählte Tests (Default Credentials, Firmware Upgrade, Ring Recovery, RFC2544 u. a.) gelten als *Kritisch*. Alle Werte sind pro Vorlage im Admin-Bereich editierbar. 2. **Sicherheitsrelevanz**: Tests der Kategorie *Security* werden als sicherheitsrelevant markiert (fließt in die Empfehlung ein). 3. Die Kategorie-Schreibweisen der Excel („Layer 1/ 2“, „Layer 1/2“) werden zu **„Layer 1/2“** vereinheitlicht; „Layer 2“ bleibt eigenständig. 4. SFP-Matrix und Szenarien werden pro Testlauf mit je einer Zeile pro Vorlageneintrag vorbefüllt; weitere SFP-Zeilen lassen sich ergänzen. 5. **Report-ID**-Format: `BAROX-STC--`. 6. Die ID-Token-Verarbeitung bei MS365 nutzt den serverseitigen Code-Austausch über TLS und prüft `state`/`nonce`; eine zusätzliche JWKS-Signaturprüfung ist für Version 2 vorgesehen. --- ## Dokumenten-Extraktion mit lokaler LLM Im Assistenten-Schritt **Stammdaten** kann ein Originaldokument hochgeladen werden. Der `DocumentExtractor` extrahiert daraus Text und lässt die konfigurierte lokale LLM die Switch-Stammdaten als JSON zurückgeben; nur **leere** Felder werden befüllt (bestehende Eingaben bleiben unangetastet), das Dokument wird als Nachweis gespeichert. Konfiguration in der `.env`: ```dotenv LLM_ENABLED=true LLM_BASE_URL=http://192.168.200.102:1234/v1 LLM_MODEL=allura-forge_llama-3.3-8b-instruct LLM_API_KEY= LLM_TIMEOUT=600 ``` Text-Extraktion je Dateityp (serverseitige Werkzeuge, optional): | Typ | Werkzeug | |-----|----------| | TXT/CSV/LOG/MD/XML/JSON | direkt (kein Werkzeug nötig) | | DOCX | integriert (reines PHP) | | PDF | `pdftotext` → `sudo apt install poppler-utils` | | PNG/JPG (OCR) | `tesseract` → `sudo apt install tesseract-ocr tesseract-ocr-deu` | Ohne das jeweilige Werkzeug meldet das Tool klar, was zu installieren ist – die übrigen Funktionen bleiben unberührt. Das Modell `llama-3.3-8b-instruct` ist rein textbasiert; für PDFs/Bilder wird der Text daher zuvor extrahiert (nicht als Bild an die LLM gesendet). ### SSH-Prüfbefehle aus dem Hersteller-CLI-Dokument generieren Pro Testlauf kann im Schritt **Stammdaten** ein **Hersteller-CLI-Dokument** (Kommandoreferenz/Handbuch) hochgeladen werden. Der `DocCheckGenerator` liest den Text ein und erzeugt daraus je Testfall passende **SSH-Prüfbefehle** (`check_command`) inkl. Erwartungsmuster. Da Handbücher sehr groß sind und das lokale Modell ein begrenztes Kontextfenster hat, wird **pro Test ein leichtes Retrieval** gemacht: nur die relevantesten Doku-Abschnitte (Stichwort-Scoring) gehen an die LLM. Zwei Wege: - **UI**: im Schritt *Testfälle* pro Kategorie *„⚙ Befehle generieren"* (Blöcke zu 8 Tests, damit kein Web-Timeout entsteht; mehrfach klicken für den Rest). - **CLI (empfohlen für Bulk)**: zuverlässig ohne Web-Timeout: ```bash php scripts/generate_checks.php [Kategorie] [--overwrite] ``` Generiert wird nur in den **Testlauf** (dessen `test_cases`), nicht in den Katalog; bestehende Kommandos bleiben erhalten (außer `--overwrite`). Ergebnisse im Assistenten prüfen und bei Bedarf anpassen. ## Sicherheit Passwort-Hashing (`password_hash`), CSRF-Token bei allen schreibenden Requests, serverseitige Rechteprüfung (Middleware + Rollen), Upload-Whitelist nach Endung **und** MIME, begrenzte Upload-Größe, Prepared Statements durchgängig, Secrets ausschließlich in `.env`, Maskierung sensibler Felder im Log. Für den Produktivbetrieb ist **HTTPS Pflicht** (siehe INSTALL.md). --- ## Lizenz Proprietär – interne Nutzung bei barox Kommunikation AG.