alqithami/vchimera

# V-CHIMERA [](https://www.python.org/downloads/) [](https://opensource.org/licenses/MIT) [](https://arxiv.org/) **V-CHIMERA** is a reproducible research artifact for studying **organizational cyber crisis response under misinformation**. The repository models cyber operations and public communication as a coupled human-information-machine system, then evaluates how verified communication governance and immune-inspired regulation affect safety and performance. The project accompanies the paper **"V-CHIMERA: An Immune-Inspired Verified Framework for Organizational Cyber Crisis Response under Misinformation"** and is designed to support transparent experimentation, figure regeneration, and manuscript preparation. ## 图形摘要 ## 为什么这个存储库很重要 Traditional incident-response pipelines often treat technical containment and public communication as separate activities. V-CHIMERA brings them together in a single coupled framework. It models how cyber incidents shape rumor, trust, and reporting behavior, and how those social responses feed back into defender effectiveness. At the same time, it enforces communication safety constraints at runtime so that unsafe public messages are never executed. ## 核心能力 | Component | Description | |---|---| | **CyberCrisisGym-J** | A coupled cyber-social simulation environment that combines incident progression with online belief, trust, uncertainty, moderation, and reporting dynamics. | | **V-CHIMERA policies** | Baseline, coupled, shielded, and ablation policies for controlled comparison across scenarios. | | **Runtime protocol shield** | A safety layer that filters proposed communication actions according to evidence, uncertainty, cooldown, and disclosure rules. | | **Immune-gated coupling** | An immune-inspired controller that uses danger, tolerance, and memory to regulate when social feedback should influence operational response. | | **Reproducible experiment scripts** | Utilities for running the main journal experiments, sensitivity sweeps, and manuscript asset generation. | | **Paper sources** | Manuscript source files, references, figures, and table-generation scripts for paper-ready outputs. | ## 存储库结构 | Path | Purpose | |---|---| | `vchimera/` | Core package containing environments, coupling logic, protocol enforcement, metrics, policies, and optional adapters. | | `configs/` | Scenario definitions, calibration files, and experiment YAML configurations. | | `scripts/` | Experiment runners, sensitivity studies, smoke tests, and supporting utilities. | | `paper/` | Manuscript source, bibliography, figures, and generated paper assets. | | `runs/` | Experiment outputs created after execution. | ## 安装 The recommended environment is **Python 3.11 or newer**. ``` python -m venv .venv source .venv/bin/activate python -m pip install --upgrade pip pip install -r requirements.txt ``` ## 快速启动 The following commands cover the standard workflow from environment validation to experiment execution and paper asset generation. | Step | Command | Outcome | |---|---|---| | Smoke test | `python scripts/smoke_test.py` | Confirms that the basic environment and package wiring are functioning correctly. | | Main experiment suite | `python scripts/run_experiments.py --config configs/experiments/journal_main.yaml` | Produces a timestamped run directory under `runs/`. | | Sensitivity study | `python scripts/run_sensitivity.py --config configs/experiments/sensitivity.yaml` | Generates the data used for robustness and sensitivity figures. | | Paper assets | `python scripts/make_paper_assets.py --run_dir "$RUN_DIR" --paper_dir paper` | Writes tables and figure assets for manuscript integration. | | Figure regeneration | `python paper/scripts/regenerate_figures_bw_accent.py --episode_steps "$RUN_DIR/episode_steps.csv" --sensitivity runs/sensitivity_grid/sensitivity.csv --out_dir paper/figures` | Regenerates publication-style figures using the expected run outputs. | To retrieve the latest journal run directory automatically, use: ``` RUN_DIR=$(ls -td runs/journal_main_* | head -n 1) echo "$RUN_DIR" ``` ## 运行主实验 The default starter pack evaluates three representative crisis settings: `ransomware_rumor`, `outage_rumor`, and `exfiltration_scam`. These scenarios are intended to stress different combinations of cyber disruption, misinformation diffusion, trust erosion, and reporting behavior. ``` python scripts/run_experiments.py --config configs/experiments/journal_main.yaml ``` A typical run creates a directory of the form: ``` runs/journal_main_YYYYMMDD_HHMMSS/ ``` Within that directory, the key outputs are usually `summary.csv` and, when enabled, `episode_steps.csv`. ## 生成手稿输出 Once a run has completed, paper assets can be generated directly for manuscript integration. ``` python scripts/make_paper_assets.py --run_dir "$RUN_DIR" --paper_dir paper ``` This step writes tables and figure assets into the paper workspace so that the manuscript can be rebuilt without manual copy-paste steps. ## 编译手稿 Compiling the paper requires a local TeX distribution such as **TeX Live** or **MacTeX**. ``` python scripts/compile_paper.py --paper_dir paper --tex main.tex ``` A manual LaTeX workflow is also supported: ``` cd paper pdflatex -interaction=nonstopmode main.tex bibtex main pdflatex -interaction=nonstopmode main.tex pdflatex -interaction=nonstopmode main.tex ``` ## 可选的 CybORG 转移实验 The repository includes an adapter scaffold for the **CybORG** ecosystem. This backend is optional and must be installed separately if transfer experiments are required. ``` python scripts/run_experiments.py --config configs/experiments/cyborg_transfer.yaml ``` If the CybORG configuration depends on additional packages, install them in the same environment before running the transfer experiment. ## 可重复性 A dedicated reproducibility guide is available in [`REPRODUCIBILITY.md`](REPRODUCIBILITY.md). It should be used when recreating tables, figures, and paper outputs from raw runs. ## 引用 A `CITATION.cff` file can be included for software citation, and the accompanying manuscript should also be cited when the repository is used in academic work. ## 安全与范围 The default cyber backend is an **abstract incident simulator** intended for research evaluation. The repository is designed to study organizational response, misinformation-aware coordination, and communication governance. It is **not** a source of offensive payloads or operational exploitation guidance.

标签：arXiv, Cyber Crisis, CyberSocial, Graphical Abstract, Human-Information-Machine, Immune-Inspired Regulation, Incident Response, Misinformation Awareness, MIT License, Organizational Cyber Defense, Python仿真, Safety Constraints, Simulation Environment, Verified Communication, 不确定性建模, 事中安全约束, 人机耦合系统, 信任建模, 信息疫情, 免疫启发式框架, 可信沟通治理, 可复现研究, 图生成, 在线舆论, 开源研究, 社交仿真, 网络危机响应, 网络安全应急, 论文复现, 误信息防御, 谣言传播, 逆向工具