CORE TopoGen

Generate reproducible CORE network topologies from scenario XML files using a rich Web GUI or a command-line interface.

Highlights

Single-source planning – edit scenarios in the browser or any XML editor and reproduce results with the CLI.
Deterministic previews – optional RNG seed locks in host expansion, router placement, connectivity, services, segmentation, and vulnerability assignment.
Live log dock – stream run output, filter by level or text/regex, and toggle auto-follow for long runs.
Rich topology policies – per-routing-item R2R meshes, R2S aggregation, host grouping bounds, and switch re-homing.
Artifacts on disk – traffic scripts, segmentation rules, docker-compose definitions, Markdown reports, and JSON summaries are written to predictable locations for inspection.
Hardware-in-the-Loop friendly – manage HITL attachments directly in the editor; options are constrained to existing routers/switches or provisioning a new router to keep topologies deterministic.

View the WebUI images gallery docs/screenshots.md.

Python 3.10+ (3.11 recommended)
CORE 9.2 or newer with core-daemon running
Docker (optional) for nginx/envoy reverse proxy or vulnerability compose targets

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

python main.py

Visits http://127.0.0.1:9090 by default (reverse proxy nginx compose targets https://localhost).
First launch seeds an coreadmin / coreadmin account; change it immediately under Profile → Change Password.
Configure TLS reverse proxies with make host-web, make host-web-nginx, or make host-web PROXY=envoy. The helper script scripts/dev_gen_certs.sh issues self-signed certificates with SAN support.
HITL editor note: the “Attach to” dropdown now offers Existing Router, Existing Switch, or New Router. The legacy New Switch choice was removed to prevent hidden switch fan-out; saved scenarios using it are normalized to Existing Router during load.

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

Popular options:

--scenario NAME pick a specific scenario entry
--host / --port override the CORE gRPC endpoint (defaults 127.0.0.1:50051)
--layout-density {compact|normal|spacious} adjust map spacing
--seg-include-hosts, --seg-allow-docker-ports, --nat-mode, --dnat-prob fine-tune segmentation
--traffic-pattern, --traffic-rate, --traffic-content override traffic defaults

Save XML – The editor auto-saves, but hitting “Save XML” ensures consistent previews.
(Optional) Set seed – Enter an integer seed to get deterministic topology output.
Generate Full Preview – Shows router/host counts, R2R/R2S policies, segmentation, services, traffic, and vulnerability assignments before any CORE call.
Review structured sections – Toggle between structured cards and raw JSON; history stores the last 25 previews in local storage.
Run (Seed) – Launches the CLI asynchronously, streams logs into the dock, and writes a Markdown report to ./reports/.

Host planning honours Base Hosts (density) and Count rows; metadata is written into XML (base_nodes, additive_nodes, combined_nodes, etc.) for round-trip fidelity.
Router and vulnerability planning capture derived vs explicit counts via explicit_count, derived_count, and total_planned.
Scenario-level scenario_total_nodes summarises planned hosts, routers, and vulnerability targets.
Parser helpers expose metadata programmatically: core_topo_gen.parsers.planning_metadata.parse_planning_metadata().
Hardware-in-the-Loop plans persist per-scenario preferences (enabled state, interface list, attachment choice). Attachments normalize to existing_router, existing_switch, or new_router; legacy new_switch values are coerced to existing_router so previews remain deterministic and switch overlays aren’t synthesized implicitly.

Per-routing-item r2r_mode supports Exact, Uniform, NonUniform, Min, Max, and legacy meshes tied to --router-mesh-style.
R2S policies (r2s_mode, r2s_edges, optional r2s_hosts_min/max) regroup hosts behind dedicated switches, with “Exact=1” aggregating all hosts per router into a single switch.
Preview JSON and runtime stats capture router degrees, aggregation counts, and Gini coefficients for quick balance checks.

Traffic scripts land in /tmp/traffic (with companion services) and respect overrides for pattern, rate, jitter, and content hints.
Segmentation scripts land in /tmp/segmentation alongside a segmentation_summary.json; NAT mode, DNAT probability, host inclusion, and docker port allowances are configurable.
Docker vulnerabilities attach per-node docker-compose files in /tmp/vulns, with metadata embedded into CORE nodes.
Custom traffic plugins can register via core_topo_gen.plugins.traffic.register() for bespoke sender/receiver code.

Markdown reports (./reports/scenario_report_<timestamp>.md) enumerate topology stats, planning metadata, segmentation results, and runtime artefacts. Each run also emits a JSON summary alongside the Markdown file (scenario_report_<timestamp>.json) plus per-run connectivity CSVs when router degree data is available.
Run history is persisted in outputs/run_history.json for the Reports page.
Safe deletion keeps reports while purging associated outputs under outputs/ when scenarios are removed via the GUI.

Folder	Purpose
`core_topo_gen/cli.py`	CLI entry point; orchestrates parsing, planning, building, and report generation
`core_topo_gen/parsers/`	Modular XML parsers per scenario section (node info, routing, traffic, services, vulnerabilities, segmentation)
`core_topo_gen/builders/topology.py`	Builds star, multi-switch, and segmented topologies using CORE gRPC APIs
`core_topo_gen/utils/`	Supporting allocators, report writers, traffic/segmentation/service helpers
`webapp/`	Flask Web UI, templates, SSE log streaming, history persistence
`webapp/templates/partials/dock.html`	Persistent logs/XML dock with follow toggle and filters
`tests/`	Pytest suite covering planning semantics, policy enforcement, preview parity, and CLI behaviours
`docs/`	Additional documentation assets (screenshots, notes)