CORE TopoGen

Erzeugen Sie reproduzierbare CORE-Netzwerktopologien aus Szenario-XML-Dateien über eine umfangreiche Web-GUI oder eine Befehlszeilenschnittstelle.

Inhaltsverzeichnis

• Highlights
• Screenshots
• Schnellstart
  • Voraussetzungen
  • Abhängigkeiten installieren
  • Web-UI starten
  • CLI ausführen
• Workflow für die vollständige Vorschau
• Detaillierte Funktionen
  • Planungssemantik
  • Router-Konnektivität & Aggregation
  • Datenverkehr, Segmentierung und Dienste
  • Berichte & Artefakte
• Architekturübersicht
• Fehlerbehebung
• Weitere Dokumentation
• Mitwirken
• Zitieren

Highlights

• Planung aus einer einzigen Quelle – Bearbeiten Sie Szenarien im Browser oder in einem beliebigen XML-Editor und reproduzieren Sie Ergebnisse mit der CLI.
• Deterministische Vorschauen – Ein optionaler RNG-Seed legt Host-Erweiterung, Router-Platzierung, Konnektivität, Dienste, Segmentierung und Schwachstellenzuweisung fest.
• Live-Log-Dock – Streamen Sie die Ausgabe von Läufen, filtern Sie nach Stufe oder Text/Regex und schalten Sie die automatische Verfolgung für lange Läufe um.
• Umfangreiche Topologie-Richtlinien – R2R-Vermaschungen pro Routing-Element, R2S-Aggregation, Grenzen für Host-Gruppierung und Switch-Re-Homing.
• Artefakte auf der Festplatte – Verkehrsskripte, Segmentierungsregeln, Docker-Compose-Definitionen, Markdown-Berichte und JSON-Zusammenfassungen werden an vorhersehbaren Orten zur Prüfung gespeichert.
• Hardware-in-the-Loop-freundlich – Verwalten Sie HITL-Anbindungen direkt im Editor; die Optionen sind auf vorhandene Router/Switches oder die Bereitstellung eines neuen Routers beschränkt, um Topologien deterministisch zu halten.

Screenshots

Die Bildergalerie der WebUI finden Sie unter docs/screenshots.md.

Schnellstart

Voraussetzungen

• Python 3.10+ (3.11 empfohlen)
• CORE 9.2 oder neuer mit laufendem core-daemon
• Docker (optional) für nginx/envoy-Reverse-Proxy oder Compose-Ziele für Schwachstellen

Abhängigkeiten installieren

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Web-UI starten

python main.py

• Standardmäßig unter http://127.0.0.1:9090 erreichbar (Reverse-Proxy-nginx-Compose-Targets https://localhost).
• Beim ersten Start wird ein Konto coreadmin / coreadmin angelegt; ändern Sie es sofort unter Profil → Passwort ändern.
• Konfigurieren Sie TLS-Reverse-Proxys mit make host-web, make host-web-nginx oder make host-web PROXY=envoy. Das Hilfsskript scripts/dev_gen_certs.sh erstellt selbstsignierte Zertifikate mit SAN-Unterstützung.
• Hinweis zum HITL-Editor: Das Dropdown „Anhängen an“ bietet jetzt Existing Router, Existing Switch oder New Router an. Die alte Option New Switch wurde entfernt, um verstecktes Switch-Fan-out zu verhindern; gespeicherte Szenarien, die diese verwenden, werden beim Laden zu normalisiert.

CLI ausführen

python -m core_topo_gen.cli --xml path/to/scenario.xml --seed 42 --verbose

Beliebte Optionen:

• --scenario NAME – einen bestimmten Szenario-Eintrag auswählen
• --host / --port – den CORE-gRPC-Endpunkt überschreiben (Standard: 127.0.0.1:50051)
• --layout-density {compact|normal|spacious} – den Kartenabstand anpassen
• --seg-include-hosts, --seg-allow-docker-ports, --nat-mode, --dnat-prob – Segmentierung feinjustieren
• --traffic-pattern, --traffic-rate, --traffic-content – Datenverkehrsstandards überschreiben

Workflow für die vollständige Vorschau

1. XML speichern – Der Editor speichert automatisch, aber das Klicken auf „XML speichern“ gewährleistet konsistente Vorschauen.
2. (Optional) Seed festlegen – Geben Sie einen ganzzahligen Seed ein, um eine deterministische Topologieausgabe zu erhalten.
3. Vollständige Vorschau erzeugen – Zeigt Router-/Host-Anzahl, R2R/R2S-Richtlinien, Segmentierung, Dienste, Datenverkehr und Schwachstellenzuweisungen vor jedem CORE-Aufruf.
4. Strukturierte Abschnitte prüfen – Wechseln Sie zwischen strukturierten Karten und Roh-JSON; der Verlauf speichert die letzten 25 Vorschauen im lokalen Speicher.
5. Ausführen (Seed) – Startet die CLI asynchron, streamt Protokolle in das Dock und schreibt einen Markdown-Bericht nach ./reports/.

Detaillierte Funktionen

Planungssemantik

• Die Host-Planung berücksichtigt Basis-Hosts (Dichte) und Anzahl-Zeilen; Metadaten werden für Round-Trip-Treue in XML geschrieben (base_nodes, additive_nodes, combined_nodes, usw.).
• Die Router- und Schwachstellenplanung erfasst abgeleitete vs. explizite Zählungen über explicit_count, derived_count und total_planned.
• Auf Szenarioebene fasst scenario_total_nodes geplante Hosts, Router und Schwachstellenziele zusammen.
• Parser-Hilfsfunktionen machen Metadaten programmatisch verfügbar: core_topo_gen.parsers.planning_metadata.parse_planning_metadata().
• Hardware-in-the-Loop-Pläne speichern Pro-Szenario-Präferenzen (aktivierter Zustand, Schnittstellenliste, Anbindungswahl). Anbindungen werden auf existing_router, existing_switch oder new_router normalisiert; alte -Werte werden zu umgewandelt, sodass Vorschauen deterministisch bleiben und Switch-Overlays nicht implizit synthetisiert werden.

Router-Konnektivität & Aggregation

• Der r2r_mode pro Routing-Element unterstützt Exact, Uniform, NonUniform, Min, Max sowie ältere Vermaschungen, die an --router-mesh-style gebunden sind.
• R2S-Richtlinien (r2s_mode, r2s_edges, optional r2s_hosts_min/max) gruppieren Hosts hinter dedizierten Switches neu, wobei „Exact=1“ alle Hosts pro Router zu einem einzigen Switch aggregiert.
• Vorschau-JSON und Laufzeitstatistiken erfassen Router-Grade, Aggregationszahlen und Gini-Koeffizienten für schnelle Balance-Checks.

Datenverkehr, Segmentierung und Dienste

• Verkehrsskripte werden in /tmp/traffic abgelegt (mit begleitenden Diensten) und respektieren Überschreibungen für Muster, Rate, Jitter und Inhaltshinweise.
• Segmentierungsskripte werden in /tmp/segmentation zusammen mit einer segmentation_summary.json abgelegt; NAT-Modus, DNAT-Wahrscheinlichkeit, Host-Einbeziehung und Docker-Port-Freigaben sind konfigurierbar.
• Docker-Schwachstellen hängen pro Knoten Docker-Compose-Dateien in /tmp/vulns an, wobei Metadaten in CORE-Knoten eingebettet werden.
• Benutzerdefinierte Datenverkehrs-Plugins können sich über core_topo_gen.plugins.traffic.register() für maßgeschneiderten Sender-/Empfänger-Code registrieren.

Berichte & Artefakte

• Markdown-Berichte (./reports/scenario_report_<timestamp>.md) listen Topologiestatistiken, Planungsmetadaten, Segmentierungsergebnisse und Laufzeitartefakte auf. Jeder Lauf erzeugt zusätzlich eine JSON-Zusammenfassung neben der Markdown-Datei (scenario_report_<timestamp>.json) sowie pro Lauf Konnektivitäts-CSVs, wenn Router-Grad-Daten verfügbar sind.
• Der Laufverlauf wird für die Berichtsseite in outputs/run_history.json gespeichert.
• Die sichere Löschung behält Berichte, während zugehörige Ausgaben unter outputs/ bereinigt werden, wenn Szenarien über die GUI entfernt werden.

Architekturübersicht

Fehlerbehebung

• core-python not found – setzen Sie WEBUI_PY vor make host-web oder verlassen Sie sich auf python3; das Backend fällt bei Bedarf auf sys.executable zurück.
• Leerer TLS-Zertifikatsordner (nginx/certs) – führen Sie scripts/dev_gen_certs.sh oder make dev-certs aus, bevor Sie nginx komponieren.
• core-daemon nicht erreichbar – überprüfen Sie Daemon-Status und Host/Port; das GUI-Ausführungsmodal zeigt Verbindungsprobleme sofort an.
• Docker-Schwachstellen übersprungen – stellen Sie sicher, dass Images über den Schwachstellen-Katalog heruntergeladen/gezogen wurden und Docker auf dem Host verfügbar ist.
• Log-Dock scrollt nicht automatisch – klicken Sie auf den Umschalter „Follow Off/On“, um die automatische Verfolgung zu reaktivieren.

Weitere Dokumentation

• API.md – REST-Endpunkte, die vom Web-UI-Backend bereitgestellt werden
• SCENARIO_XML_SCHEMA.md – Schema-Durchlauf und Beispiele

Mitwirken

Pull Requests und Fehlerberichte sind willkommen! Bitte führen Sie vor dem Einreichen von Änderungen die relevanten pytest-Ziele (pytest -q) aus und halten Sie die Dokumentation aktuell, wenn sich das Verhalten ändert.

Zitieren Sie unsere Arbeit:

@article{rodriguez2025agentcyte,

title={AgentCyTE: Leveraging Agentic AI to Generate Cybersecurity Training & Experimentation Scenarios},

author={Rodriguez, Ana M and Acosta, Jaime and Kotal, Anantaa and Piplai, Aritran},

journal={Annual Computer Security Applications Conference Workshop (ACSACW)},

year={2025}

}