CORE TopoGen

使用丰富的 Web GUI 或命令行界面，从场景 XML 文件生成可复现的 CORE 网络拓扑。

目录

• 高亮特性
• 截图
• 快速开始
  • 先决条件
  • 安装依赖
  • 启动 Web UI
  • 运行 CLI
• 完整预览工作流
• 功能深入解析
  • 规划语义
  • 路由器连接与聚合
  • 流量、分段与服务
  • 报告与产物
• 架构概述
• 故障排查
• 附加文档
• 贡献
• 引用

高亮特性

• 单一来源规划 – 在浏览器或任何 XML 编辑器中编辑场景，并通过 CLI 复现结果。
• 确定性预览 – 可选的 RNG 种子锁定主机扩展、路由器放置、连接性、服务、分段和漏洞分配。
• 实时日志坞 – 流式查看运行输出，按级别或文本/正则过滤，并为长时间运行切换自动跟随。
• 丰富的拓扑策略 – 每个路由项的 R2R 网格、R2S 聚合、主机分组边界和交换机重归属。
• 磁盘上的产物 – 流量脚本、分段规则、docker-compose 定义、Markdown 报告和 JSON 摘要会被写入可预期的位置以供检查。
• 硬件在环（HITL）友好 – 直接在编辑器中管理 HITL 附件；选项限制为现有路由器/交换机或配置新路由器，以保持拓扑确定性。

截图

查看 WebUI 图片库 docs/screenshots.md。

快速开始

先决条件

• Python 3.10+（推荐 3.11）
• CORE 9.2 或更新版本，并运行 core-daemon
• Docker（可选），用于 nginx/envoy 反向代理或漏洞 compose 目标

安装依赖

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

启动 Web UI

python main.py

• 默认访问 http://127.0.0.1:9090（反向代理 nginx compose 目标为 https://localhost）。
• 首次启动会初始化一个 coreadmin / coreadmin 账户；请立即在 个人资料 → 更改密码 下更改它。
• 使用 make host-web、make host-web-nginx 或 make host-web PROXY=envoy 配置 TLS 反向代理。辅助脚本 scripts/dev_gen_certs.sh 会签发支持 SAN 的自签名证书。
• HITL 编辑器说明：“附加到”下拉菜单现在提供 Existing Router、Existing Switch 或 New Router。旧版 New Switch 选项已被移除，以防止隐藏的交换机扇出；使用该选项保存的场景在加载时会规范化为 Existing Router。

运行 CLI

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

常用选项：

• --scenario NAME 选择特定的场景条目
• --host / --port 覆盖 CORE gRPC 端点（默认为 127.0.0.1:50051）
• --layout-density {compact|normal|spacious} 调整地图间距
• --seg-include-hosts、--seg-allow-docker-ports、--nat-mode、--dnat-prob 微调分段
• --traffic-pattern、--traffic-rate、--traffic-content 覆盖流量默认值

完整预览工作流

1. 保存 XML – 编辑器会自动保存，但点击“保存 XML”可确保预览一致。
2. （可选）设置种子 – 输入整数种子以获得确定性的拓扑输出。
3. 生成完整预览 – 在任何 CORE 调用之前，显示路由器/主机数量、R2R/R2S 策略、分段、服务、流量和漏洞分配。
4. 查看结构化部分 – 在结构化卡片和原始 JSON 之间切换；历史记录将最近 25 个预览存储在本地存储中。
5. 运行（种子） – 异步启动 CLI，将日志流式传输到日志坞，并将 Markdown 报告写入 ./reports/。

功能深入解析

规划语义

• 主机规划遵循基础主机（密度）和数量行；元数据会被写入 XML（base_nodes、additive_nodes、combined_nodes 等），以保证往返保真度。
• 路由器和漏洞规划通过 explicit_count、derived_count 和 total_planned 记录派生数量与显式数量。
• 场景级别的 scenario_total_nodes 汇总了计划的主机、路由器和漏洞目标。
• 解析器辅助函数以编程方式暴露元数据：core_topo_gen.parsers.planning_metadata.parse_planning_metadata()。
• 硬件在环（HITL）规划会持久化每个场景的偏好（启用状态、接口列表、附件选择）。附件规范化为 existing_router、existing_switch 或 new_router；旧版 new_switch 值会被强制转换为 existing_router，以便预览保持确定性，并且不会隐式合成交换机叠加。

路由器连接与聚合

• 每个路由项的 r2r_mode 支持 Exact、Uniform、NonUniform、Min、Max 以及与 --router-mesh-style 关联的旧版网格。
• R2S 策略（r2s_mode、r2s_edges、可选 r2s_hosts_min/max）将主机重新分组到专用交换机后面，其中“Exact=1”会将每个路由器的所有主机聚合到单个交换机中。
• 预览 JSON 和运行时统计信息捕获路由器度数、聚合计数和基尼系数，以便快速进行平衡检查。

流量、分段与服务

• 流量脚本生成到 /tmp/traffic（附带配套服务），并遵循对模式、速率、抖动和内容提示的覆盖。
• 分段脚本生成到 /tmp/segmentation，旁边有 segmentation_summary.json；NAT 模式、DNAT 概率、主机包含和 docker 端口许可均可配置。
• Docker 漏洞在 /tmp/vulns 中附加每个节点的 docker-compose 文件，并将元数据嵌入 CORE 节点。
• 自定义流量插件可以通过 core_topo_gen.plugins.traffic.register() 注册，以使用定制的发送方/接收方代码。

报告与产物

• Markdown 报告（./reports/scenario_report_<timestamp>.md）列举拓扑统计信息、规划元数据、分段结果和运行时产物。每次运行还会在 Markdown 文件旁边生成 JSON 摘要（scenario_report_<timestamp>.json），并在存在路由器度数数据时生成每次运行的连接性 CSV。
• 运行历史持久化在 outputs/run_history.json 中，供报告页面使用。
• 安全删除会在通过 GUI 移除场景时保留报告，同时清除 outputs/ 下的相关输出。

架构概述

故障排查

• **core-python 未找到** – 在 make host-web之前设置WEBUI_PY，或依赖 python3；如有需要，后端会回退到 sys.executable`。
• TLS 证书文件夹为空（nginx/certs） – 在通过 compose 启动 nginx 之前运行 scripts/dev_gen_certs.sh 或 make dev-certs。
• core-daemon 无法访问` – 验证守护进程状态及主机/端口；GUI 运行模态框会立即显示连接问题。
• Docker 漏洞被跳过 – 确保已通过漏洞目录下载/拉取镜像，并且主机上 Docker 可用。
• 日志坞不会自动滚动 – 点击“跟随 关/开”切换以重新启用自动跟随。

附加文档

• API.md – Web UI 后端暴露的 REST 端点
• SCENARIO_XML_SCHEMA.md – Schema 详解与示例

贡献

欢迎提交拉取请求和问题报告！请在提交更改之前运行相关的 pytest 目标（pytest -q），并在行为发生变化时保持文档更新。

引用我们的工作：

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

}