CORE TopoGen

풍부한 Web GUI 또는 명령줄 인터페이스를 사용하여 시나리오 XML 파일에서 재현 가능한 CORE 네트워크 토폴로지를 생성합니다.

목차

• 주요 기능
• 스크린샷
• 빠른 시작
  • 사전 요구 사항
  • 의존성 설치
  • Web UI 실행
  • CLI 실행
• 전체 미리보기 워크플로
• 기능 심층 분석
  • 계획 의미론
  • 라우터 연결 및 집계
  • 트래픽, 분할 및 서비스
  • 보고서 및 산출물
• 아키텍처 개요
• 문제 해결
• 추가 문서
• 기여
• 인용

주요 기능

• 단일 소스 계획 – 브라우저 또는 모든 XML 편집기에서 시나리오를 편집하고 CLI로 결과를 재현합니다.
• 결정적 미리보기 – 선택적 RNG 시드가 호스트 확장, 라우터 배치, 연결, 서비스, 분할 및 취약점 할당을 고정합니다.
• 실시간 로그 독 – 실행 출력을 스트리밍하고, 수준 또는 텍스트/정규식으로 필터링하며, 긴 실행을 위해 자동 팔로우를 전환합니다.
• 풍부한 토폴로지 정책 – 라우팅 항목별 R2R 메시, R2S 집계, 호스트 그룹화 범위 및 스위치 재배치.
• 디스크의 산출물 – 트래픽 스크립트, 분할 규칙, docker-compose 정의, Markdown 보고서 및 JSON 요약이 검사를 위해 예측 가능한 위치에 기록됩니다.
• Hardware-in-the-Loop 친화적 – 편집기에서 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 계정이 생성됩니다. 즉시 Profile → Change Password에서 변경하세요.
• make host-web, make host-web-nginx 또는 make host-web PROXY=envoy로 TLS 역방향 프록시를 구성합니다. 도우미 스크립트 scripts/dev_gen_certs.sh는 SAN을 지원하는 자체 서명 인증서를 발급합니다.
• HITL 편집기 참고: “Attach to” 드롭다운은 이제 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 저장 – 편집기가 자동 저장하지만 “Save 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().
• Hardware-in-the-Loop 계획은 시나리오별 기본 설정(활성화 상태, 인터페이스 목록, 첨부 선택)을 유지합니다. 첨부는 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 및 런타임 통계는 라우터 차수, 집계 수 및 Gini 계수를 캡처하여 빠른 균형 검사를 지원합니다.

트래픽, 분할 및 서비스

• 트래픽 스크립트는 /tmp/traffic에 생성되며(동반 서비스 포함) 패턴, 속도, 지터 및 콘텐츠 힌트에 대한 재정의를 따릅니다.
• 분할 스크립트는 segmentation_summary.json과 함께 /tmp/segmentation에 생성됩니다. NAT 모드, DNAT 확률, 호스트 포함 및 docker 포트 허용은 구성 가능합니다.
• Docker 취약점은 CORE 노드에 메타데이터가 포함된 노드별 docker-compose 파일을 /tmp/vulns에 첨부합니다.
• 맞춤형 트래픽 플러그인은 core_topo_gen.plugins.traffic.register()를 통해 등록하여 고유한 송신자/수신자 코드를 사용할 수 있습니다.

보고서 및 산출물

• Markdown 보고서(./reports/scenario_report_<timestamp>.md)는 토폴로지 통계, 계획 메타데이터, 분할 결과 및 런타임 산출물을 열거합니다. 각 실행은 Markdown 파일과 함께 JSON 요약(scenario_report_<timestamp>.json)을 생성하며, 라우터 차수 데이터가 있는 경우 실행별 연결 CSV도 생성합니다.
• 실행 기록은 Reports 페이지를 위해 outputs/run_history.json에 저장됩니다.
• 안전한 삭제는 GUI에서 시나리오를 제거할 때 outputs/ 아래의 관련 출력을 정리하면서 보고서는 유지합니다.

아키텍처 개요

문제 해결

• **core-python 찾을 수 없음** – make host-web전에WEBUI_PY를 설정하거나 python3에 의존하세요. 백엔드는 필요한 경우 sys.executable`로 폴백합니다.
• 빈 TLS 인증서 폴더 (nginx/certs) – nginx를 구성하기 전에 scripts/dev_gen_certs.sh 또는 make dev-certs를 실행하세요.
• core-daemon 연결 불가` – 데몬 상태와 호스트/포트를 확인하세요. GUI 실행 모달이 연결 문제를 즉시 표시합니다.
• Docker 취약점 건너뜀 – 취약점 카탈로그를 통해 이미지를 다운로드/풀하고 호스트에서 Docker를 사용할 수 있는지 확인하세요.
• 로그 독 자동 스크롤 안 됨 – “Follow Off/On” 토글을 클릭하여 자동 팔로우를 다시 활성화하세요.

추가 문서

• API.md – Web UI 백엔드가 노출하는 REST 엔드포인트
• SCENARIO_XML_SCHEMA.md – 스키마 설명 및 예제

기여

Pull request 및 이슈 보고를 환영합니다! 변경 사항을 제출하기 전에 관련 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}

}