CORE TopoGen

Genera topologie di rete CORE riproducibili da file XML di scenario utilizzando una ricca GUI Web o un'interfaccia a riga di comando.

Indice dei contenuti

• Punti salienti
• Schermate
• Avvio rapido
  • Prerequisiti
  • Installa le dipendenze
  • Avvia la Web UI
  • Esegui la CLI
• Flusso di lavoro dell'anteprima completa
• Approfondimento delle funzionalità
  • Semantica di pianificazione
  • Connettività router e aggregazione
  • Traffico, segmentazione e servizi
  • Report e artefatti
• Panoramica dell'architettura
• Risoluzione dei problemi
• Documentazione aggiuntiva
• Contributi
• Citazione

Punti salienti

• Pianificazione a fonte unica – modifica gli scenari nel browser o in qualsiasi editor XML e riproduci i risultati con la CLI.
• Anteprime deterministiche – un seed RNG opzionale fissa l'espansione degli host, il posizionamento dei router, la connettività, i servizi, la segmentazione e l'assegnazione delle vulnerabilità.
• Dock di log in tempo reale – trasmetti in streaming l'output delle esecuzioni, filtra per livello o testo/regex e attiva/disattiva il follow automatico per le esecuzioni lunghe.
• Policy di topologia avanzate – mesh R2R per voce di routing, aggregazione R2S, limiti di raggruppamento degli host e re-homing degli switch.
• Artefatti su disco – script di traffico, regole di segmentazione, definizioni docker-compose, report Markdown e riepiloghi JSON vengono scritti in posizioni prevedibili per l'ispezione.
• Compatibile con Hardware-in-the-Loop – gestisci gli allegati HITL direttamente nell'editor; le opzioni sono limitate a router/switch esistenti o al provisioning di un nuovo router per mantenere topologie deterministiche.

Schermate

Visualizza la galleria di immagini della WebUI docs/screenshots.md.

Avvio rapido

Prerequisiti

• Python 3.10+ (3.11 consigliato)
• CORE 9.2 o successivo con core-daemon in esecuzione
• Docker (opzionale) per il reverse proxy nginx/envoy o per i target compose delle vulnerabilità

Installa le dipendenze

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

Avvia la Web UI

python main.py

• Visita http://127.0.0.1:9090 per impostazione predefinita (il target compose del reverse proxy nginx è https://localhost).
• Al primo avvio viene creato un account coreadmin / coreadmin; cambialo subito in Profilo → Cambia password.
• Configura i reverse proxy TLS con make host-web, make host-web-nginx o make host-web PROXY=envoy. Lo script di supporto scripts/dev_gen_certs.sh genera certificati autofirmati con supporto SAN.
• Nota sull'editor HITL: il menu a tendina “Attach to” ora offre Existing Router, Existing Switch o New Router. La scelta legacy New Switch è stata rimossa per prevenire il fan-out di switch nascosti; gli scenari salvati che la usano vengono normalizzati a durante il caricamento.

Esegui la CLI

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

Opzioni principali:

• --scenario NAME seleziona una voce di scenario specifica
• --host / --port sovrascrive l'endpoint gRPC di CORE (default 127.0.0.1:50051)
• --layout-density {compact|normal|spacious} regola la spaziatura della mappa
• --seg-include-hosts, --seg-allow-docker-ports, --nat-mode, --dnat-prob ottimizzano la segmentazione
• --traffic-pattern, --traffic-rate, --traffic-content sovrascrivono i default del traffico

Flusso di lavoro dell'anteprima completa

1. Salva XML – L'editor salva automaticamente, ma premere “Salva XML” garantisce anteprime coerenti.
2. (Opzionale) Imposta il seed – Inserisci un seed intero per ottenere un output di topologia deterministico.
3. Genera anteprima completa – Mostra i conteggi router/host, le policy R2R/R2S, la segmentazione, i servizi, il traffico e le assegnazioni delle vulnerabilità prima di qualsiasi chiamata CORE.
4. Rivedi le sezioni strutturate – Alterna tra schede strutturate e JSON grezzo; la cronologia conserva le ultime 25 anteprime nella memoria locale.
5. Esegui (Seed) – Avvia la CLI in modo asincrono, trasmette i log nel dock e scrive un report Markdown in ./reports/.

Approfondimento delle funzionalità

Semantica di pianificazione

• La pianificazione degli host rispetta le righe Base Hosts (densità) e Count; i metadati vengono scritti nell'XML (base_nodes, additive_nodes, combined_nodes, ecc.) per garantire la fedeltà del round-trip.
• La pianificazione di router e vulnerabilità acquisisce i conteggi derivati rispetto a quelli espliciti tramite explicit_count, derived_count e total_planned.
• A livello di scenario, scenario_total_nodes riepiloga gli host, i router e i target di vulnerabilità pianificati.
• Gli helper dei parser espongono i metadati a livello di programmazione: core_topo_gen.parsers.planning_metadata.parse_planning_metadata().
• I piani Hardware-in-the-Loop conservano le preferenze per scenario (stato di abilitazione, elenco interfacce, scelta di collegamento). Gli allegati vengono normalizzati in existing_router, existing_switch o new_router; i valori legacy vengono forzati a così le anteprime rimangono deterministiche e le sovrapposizioni di switch non vengono sintetizzate implicitamente.

Connettività router e aggregazione

• Il r2r_mode per singolo elemento di routing supporta Exact, Uniform, NonUniform, Min, Max e le mesh legacy legate a --router-mesh-style.
• Le policy R2S (r2s_mode, r2s_edges, r2s_hosts_min/max opzionali) raggruppano gli host dietro switch dedicati, con “Exact=1” che aggrega tutti gli host per router in un unico switch.
• Il JSON dell'anteprima e le statistiche di runtime catturano i gradi dei router, i conteggi di aggregazione e i coefficienti di Gini per verifiche rapide del bilanciamento.

Traffico, segmentazione e servizi

• Gli script di traffico finiscono in /tmp/traffic (con i servizi associati) e rispettano le sovrascritture per pattern, rate, jitter e suggerimenti di contenuto.
• Gli script di segmentazione finiscono in /tmp/segmentation insieme a segmentation_summary.json; la modalità NAT, la probabilità DNAT, l'inclusione degli host e le autorizzazioni delle porte docker sono configurabili.
• Le vulnerabilità Docker collegano file docker-compose per nodo in /tmp/vulns, con metadati incorporati nei nodi CORE.
• I plugin di traffico personalizzati possono registrarsi tramite core_topo_gen.plugins.traffic.register() per un codice mittente/ricevente su misura.

Report e artefatti

• I report Markdown (./reports/scenario_report_<timestamp>.md) elencano le statistiche di topologia, i metadati di pianificazione, i risultati di segmentazione e gli artefatti di runtime. Ogni esecuzione genera anche un riepilogo JSON accanto al file Markdown (scenario_report_<timestamp>.json) più CSV di connettività per esecuzione quando sono disponibili i dati sui gradi dei router.
• La cronologia delle esecuzioni viene salvata in outputs/run_history.json per la pagina Report.
• L'eliminazione sicura conserva i report e rimuove gli output associati in outputs/ quando gli scenari vengono eliminati tramite la GUI.

Panoramica dell'architettura

Risoluzione dei problemi

• **core-python non trovato** – imposta WEBUI_PYprima dimake host-webo affidati apython3; il backend ripiega su sys.executable` se necessario.
• Cartella certificati TLS vuota (nginx/certs) – esegui scripts/dev_gen_certs.sh o make dev-certs prima di avviare nginx tramite compose.
• core-daemon non raggiungibile` – verifica lo stato del daemon e host/porta; la modale di esecuzione della GUI mostrerà subito i problemi di connessione.
• Vulnerabilità Docker saltate – assicurati che le immagini siano state scaricate/pullate tramite il catalogo delle vulnerabilità e che Docker sia disponibile sull'host.
• Il dock dei log non scorre automaticamente – fai clic sul toggle “Follow Off/On” per riattivare il follow automatico.

Documentazione aggiuntiva

• API.md – endpoint REST esposti dal backend della Web UI
• SCENARIO_XML_SCHEMA.md – Guida allo schema ed esempi

Contributi

Pull request e segnalazioni di problemi sono benvenute! Prima di inviare modifiche, esegui i target pytest pertinenti (pytest -q) e mantieni aggiornata la documentazione quando il comportamento cambia.

Cita il nostro lavoro:

@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}

}