itm-kitware/alignment-cage-challenge-2为论文《Alignment of Autonomous Cyber Defense Agents via Adaptive Policy Shaping》更新的 CybORG CAGE 2 环境
我们论文 Alignment of Autonomous Cyber Defense Agents via Adaptive Policy Shaping 的代码。本仓库扩展了 CybORG CAGE Challenge 2，用于研究如何将自主防御者引导至运营优先级，同时保持其防御网络的能力。
原始 CAGE 2 挑战使用 CAGE 奖励来评估蓝方防御者对抗内置红方智能体的表现。此修改版本增加了运营目标、修改后的攻击者策略以及蓝方防御者的对齐方法。模拟器和实验脚本仍保留在 CybORG/ 目录结构中。原始 CAGE 2 指南保留了原始挑战的描述。
修改后的网络除用户、企业、运营和防御者主机外，还包括认证（Auth）、数据库（Database）和前端（Front）服务器。这些服务器代表通过机密性（C）、完整性（I）和可用性（A）表达的运营优先级：
| 服务器类型 | 运营优先级 |
|---|---|
认证（Auth） | 机密性、完整性、可用性 |
数据库（Database） | 机密性、可用性 |
前端（Front） | 完整性、可用性 |
弹性评分改编自 Cadet 等人 Quantitative Resilience Modeling for Autonomous Cyber Defense。实现基于相关的 CyberResilience 代码。
我们的弹性指标记录每一步的 CIA 下降，并将其组合为归一化的弹性下降，默认权重为机密性 0.6、完整性 0.2、可用性 0.2。它还为基于属性的策略和对齐分析对候选蓝方动作进行评分。生成的场景为 CIA 关键服务器分配零普通 CAGE 主机奖励值，从而可以分别评估运营对齐和一般网络防御性能。
对 CAGE 2 代码库所做的其他内部更改详见实验 README。
原始的 Meander 和 B-line 攻击者经过扩展，以针对新增的运营服务器，并支持生成网络规模中的主机名。评估使用五种对抗者：
| 论文对抗者 | Python 类 | 影响目标 |
|---|---|---|
| M-CIA | RedMeanderAgent_Combination_CIA | CIA 关键的 Auth、Database 和 Front 服务器 |
| M-CAGE | RedMeanderAgent_Combination_CAGE | 其他有助于 CAGE 性能的合格已入侵主机 |
| Bline-C | B_lineAgent_Resilience_C | Auth 或 Database 服务器 |
| Bline-I | B_lineAgent_Resilience_I | Auth 或 Front 服务器 |
| Bline-A | B_lineAgent_Resilience_A | Auth、Database 或 Front 服务器 |
训练使用 RedMeanderAgent_Combination，它在每次影响选择决策时以相等概率在 CIA 和 CAGE 影响目标之间进行选择。B-line 变体在每个回合中选择一次目标服务器类型，并从观测中解析匹配的主机。参见 Meander_Resilience.py 和 B_line_resilience.py。
使用 Python 3.10 或更新版本，并安装 uv。在仓库根目录下：
uv sync
cd CybORG
uv sync 会创建项目环境并安装 CybORG 及其依赖项。使用 uv run ... 运行脚本，使用 uv run bash ... 运行 shell 启动器；无需手动激活环境。
| 位置 | 内容 |
|---|---|
CybORG/CybORG/ | 模拟器、智能体、奖励、指标、场景及上游测试 |
CybORG/experiment_configs/ | 测试时、训练时、自适应、扩展及红队智能体评估配置 |
CybORG/train_agents.py | 训练基线或奖励塑形的蓝队智能体 |
CybORG/test_experiment.py | 评估基线、固定及自适应策略 |
CybORG/test_experiment_training_time.py | 评估在训练期间对齐的智能体 |
CybORG/alignment_analysis.py | 计算对齐分数并分析奖励权衡 |
CybORG/CybORG/Shared/Scenarios/scenario_generation.py | 生成具有可配置主机种群和奖励设置的场景 |
使用 train_agents.py 针对混合游荡攻击者训练 PPO 防御者。PPOAgent 训练基线；AlignedPPOAgent 为选定的 CIA 属性添加奖励项。训练时奖励在论文中称为 lambda，在 CLI 中仅称为 alpha；它与测试时插值权重是分开的。
要为 base 训练一个基线检查点：
uv run python train_agents.py \
--scenario scalability_experiments/base \
--agent_type PPOAgent \
--red_agent RedMeanderAgent_Combination \
--alpha 0 --seed 0 --game_steps 200 --training_iter 500000 \
--agent_export checkpoints/PPO_base_0_seed0
要训练一个对齐保密性的防御者，并设置奖励为 1.5：
uv run python train_agents.py \
--scenario scalability_experiments/base \
--agent_type AlignedPPOAgent \
--red_agent RedMeanderAgent_Combination \
--alignment_attribute C --alpha 1.5 \
--seed 0 --game_steps 200 --training_iter 500000 \
--agent_export checkpoints/PPO_base_1.5_C_seed0
完整的训练扫描：
uv run bash experiment_configs/train_agents/train_base.sh
uv run bash experiment_configs/train_agents/train_trainingtime_alignment.sh
这些启动器覆盖 base、hosts_2、hosts_3 和 hosts_4，训练种子为 0 1 2 3 4。检查点保存在 CybORG/checkpoints/ 下，基线模型命名为 PPO_{scenario}_0_seed{seed}.zip，奖励塑形智能体命名为 PPO_{scenario}_{bonus}_{attribute}_seed{seed}.zip。保存检查点后，train_agents.py 还会运行一次简短评估。日志记录默认禁用；在 Python 训练命令中添加 --wandb 即可启用。
评估脚本加载训练好的检查点，并让智能体针对配置的红色对手运行。提供的配置使用 100 个回合、从 42 开始的评估种子以及五个训练种子。对于 base、hosts_2、hosts_3 和 hosts_4，回合步长上限分别为 200、300、400 和 500 步。
test_experiment.py 评估 Blue Monitor 和 PPO 基线，以及固定或自适应测试时对齐：
# Baselines and fixed test-time interpolation
uv run python test_experiment.py --config experiment_configs/base.yaml
uv run python alignment_analysis.py --config experiment_configs/base.yaml
# Adaptive test-time policy selection
uv run python test_experiment.py --config experiment_configs/adaptive_alpha_config/base/cia.yaml
uv run python alignment_analysis.py --config experiment_configs/adaptive_alpha_config/base/cia.yaml
test_experiment_training_time.py 评估奖励塑形后的检查点：
uv run python test_experiment_training_time.py --config experiment_configs/training_time_config/base.yaml
uv run python alignment_analysis.py --config experiment_configs/training_time_config/base.yaml
在运行配置之前，先训练该配置所请求的所有检查点。要运行完整的评估与分析扫描：
uv run bash experiment_configs/run_all.sh
uv run bash experiment_configs/run_training_time_experiments.sh
uv run bash experiment_configs/export_alignment_analysis.sh
有关方法和对手配置，请参阅配置指南。
已包含生成的场景，因此运行所提供的实验无需进行生成：
CybORG/CybORG/Shared/Scenarios/scalability_experiments/，并为蓝方智能体使用 AlignedReward。CybORG/CybORG/Shared/Scenarios/scalability_eval_scenarios/，并使用 HybridAvailabilityConfidentiality 来衡量普通 CAGE 性能。两个文件夹均包含以下论文场景。每个场景都有三个子网（User、Enterprise 和 Operational）；总数包含一台防御者主机。下面的 Operational 主机将 Op_Server 和 Op_Host 合并计算，与 CIA 关键服务器分开统计。
| 场景文件 | User 主机 | Enterprise 主机 | Operational 主机 | Auth | Database | Front | Defender | 主机总数 |
|---|---|---|---|---|---|---|---|---|
base.yaml | 5 | 3 | 4 | 1 | 1 | 1 | 1 | 16 |
hosts_2.yaml | 10 | 6 | 8 | 2 | 2 | 2 | 1 | 31 |
hosts_3.yaml | 15 | 9 | 12 | 3 | 3 | 3 | 1 | 46 |
hosts_4.yaml | 20 | 12 | 16 | 4 | 4 | 4 | 1 | 61 |
使用 scenario_generation.py 创建自定义场景。例如，以下命令会创建一个新的 31 主机训练场景：
uv run python CybORG/Shared/Scenarios/scenario_generation.py \
--export_path CybORG/Shared/Scenarios/scalability_experiments/custom \
--operational_n 8 --enterprise_n 6 --user_n 10 --resilience_n 2 \
--blue_reward AlignedReward
--resilience_n 是每种 CIA 关键服务器类型的数量，因此 2 会创建两台 Auth、两台 Database 和两台 Front 服务器。生成器还接受奖励级别（--operational_w、--enterprise_w、--user_w、--resilience_w）和子网放置选项（--operational_s、--enterprise_s、--user_s、--resilience_s、--defender_s）。子网索引为 Enterprise 0、Operational 1 和 User 2。当前生成器保留这三个子网；--subnets 目前尚不会改变它们的数量。
现有的训练场景启动器可以重新生成 base 到 hosts_5，并覆盖这些训练 YAML 文件：
uv run bash CybORG/Shared/Scenarios/generate_resilience_scenario.sh
四个论文评估场景的动作空间映射已包含在 CybORG/CybORG/Shared/Scenarios/scalability_eval_scenarios/action_spaces/ 中。使用以下命令在没有训练检查点的情况下重新生成它们：
uv run python export_action_space_mapping.py
如果您觉得这项工作有用，请考虑引用我们的论文：