# CyberBattleSim

2021年4月8日：请参阅微软安全博客上的公告。

CyberBattleSim是一个实验性研究平台，用于研究在模拟的抽象企业网络环境中运行的自动化智能体之间的交互。该仿真提供了一个关于计算机网络和网络安全概念的高度抽象框架。其基于Python的Open AI Gym接口允许使用强化学习算法来训练自动化智能体。

仿真环境由固定的网络拓扑结构以及智能体可以利用以在网络中横向移动的一组漏洞参数化。攻击者的目的是通过利用部署在计算机节点中的漏洞来控制网络的一部分。当攻击者试图在网络中扩散时，防御者智能体会监控网络活动，尝试检测正在进行的任何攻击，并通过驱逐攻击者来减轻对系统的威胁。我们提供了一个基本的随机防御者，它根据预定义的成功概率来检测并缓解正在进行的攻击。我们通过重新映像受感染的节点来实现缓解，这一过程被抽象地建模为跨越多个仿真步骤的操作。

为了比较智能体的性能，我们关注两个指标：达到目标所花费的仿真步数，以及在整个训练周期内各仿真步骤的累积奖励。

项目目标

我们认为该项目是一个实验平台，用于研究自动化智能体在抽象仿真网络环境中的交互。通过将其开源，我们希望鼓励研究社区探索网络智能体在这些环境中如何交互与演化。

我们提供的仿真无疑较为简单，但这也有其优势。其高度抽象的特性使其无法直接应用于现实世界系统，从而为防止使用由此训练出的自动化智能体进行恶意行为提供了一种保障。同时，它的简单性使我们能够专注于想要研究的具体安全方面，并快速试验最新的机器学习和人工智能算法。

例如，当前的实现主要关注横向移动的网络攻击技术，旨在理解网络拓扑和配置如何影响这些技术。基于这一目标，我们认为没有必要对实际网络流量进行建模。这只是我们系统中一个显著的局限性示例，未来的研究贡献或许可以加以改进。

在算法方面，我们提供了一些基础智能体作为起点，但我们很想知道最先进的强化学习算法与它们相比会如何。我们发现，任何计算机系统固有的庞大动作空间对于强化学习来说都是一个特别的挑战，这与其他应用（如视频游戏或机器人控制）形成了鲜明对比。训练能够存储和检索凭据的智能体也是应用强化学习技术时面临的另一个挑战，因为通常智能体并不具备内部记忆功能。这些都是可以利用该仿真进行基准测试的研究领域。

其他感兴趣的方向还包括自主网络安全系统的负责任和伦理使用：如何设计一种能赋予防御者智能体内在优势的企业网络？如何开展旨在保护企业免受自主网络攻击的安全研究，同时防止此类技术被滥用？

文档

阅读项目的快速入门。

构建状态

类型	分支	状态
CI	master
Docker镜像	master

基准测试

请参阅基准测试文档。包含最新运行结果的Jupyter笔记本已通过专用标签提交至/notebooks/benchmarks (latest_benchmark)。

搭建开发环境

强烈建议在Linux环境下工作，可以直接在Linux上操作，也可以通过Windows上的WSL进行。虽然直接在Windows上运行Python仍然可行，但已不再被官方支持。

首先克隆仓库：

git clone https://github.com/microsoft/CyberBattleSim.git

操作系统组件

如果在运行notebook中的papermill工具时遇到以下错误（或者在运行orca --help时出现类似问题）：

/home/wiblum/miniconda3/envs/cybersim/lib/orca_app/orca: error while loading shared libraries: libXss.so.1: cannot open shared object file: No such file or directory

或其他共享库如libgdk_pixbuf-2.0.so.0， 则需要运行以下命令：

sudo apt install libnss3-dev libgtk-3-0 libxss1 libasound2-dev libgtk2.0-0 libgconf-2-4

在Linux或WSL上

这些说明已在Linux Ubuntu发行版上进行了测试（包括原生Ubuntu和WSL版本）。

如果尚未安装conda，需运行install_conda.sh脚本来安装。

bash install-conda.sh

安装完成后，打开一个新的终端并运行初始化脚本：

bash init.sh

这将创建一个名为cybersim的conda环境，其中包含所有必要的操作系统和Python依赖项。

要激活该环境，请运行：

conda activate cybersim

Windows子系统Linux

在Windows上推荐的开发环境是通过WSL。您需要先在Windows机器上安装Ubuntu WSL发行版，然后按照Linux部分的说明继续操作。

WSL中的Git认证

要进行Git认证，您可以选择使用SSH认证，或者使用credential-helper技巧自动生成PAT令牌。后者可以通过在WSL下运行以下命令来实现（更多信息请点击这里)：

git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/libexec/git-core/git-credential-manager.exe"

WSL上的Docker

若想在Docker容器中运行您的环境，我们建议通过Windows Subsystem for Linux (WSL)来运行docker，具体方法请参考：在WSL下的Windows上安装Docker。

Windows（不支持）

此方法已不再维护，请改用 WSL 子系统中的 Linux 环境运行。

不过，如果您坚持要在 Windows 上安装 Python 3.10，则可以在 PowerShell 提示符下运行 ./init.ps1 脚本。

使用 Docker 快速入门

最快捷的启动方式是通过 Docker 容器。

注意：出于许可原因，我们不会公开分发任何构建产物。特别是，以下命令中提到的 Docker 注册表 spinshot.azurecr.io 仅对项目维护者开放。

作为替代方案，您可以使用提供的 Dockerfile 自行重建 Docker 镜像，将生成的镜像发布到您自己的 Docker 注册表，并替换下方命令中的注册表名称。

从 Docker 注册表运行

commit=7c1f8c80bc53353937e3c69b0f5f799ebb2b03ee
docker login spinshot.azurecr.io
docker pull spinshot.azurecr.io/cyberbattle:$commit
docker run -it spinshot.azurecr.io/cyberbattle:$commit python -m cyberbattle.agents.baseline.run

重新构建 Docker 镜像

docker build -t cyberbattle:1.1 .
docker run -it -v "$(pwd)":/source --rm cyberbattle:1.1 python -m cyberbattle.agents.baseline.run

检查您的环境

运行以下命令以使用基线强化学习智能体进行模拟：

python -m cyberbattle.agents.baseline.run --training_episode_count 5 --eval_episode_count 3 --iteration_count 100 --rewardplot_width 80  --chain_size=4 --ownership_goal 0.2

python -m cyberbattle.agents.baseline.run --training_episode_count 5 --eval_episode_count 3 --iteration_count 100 --rewardplot_width 80  --chain_size=4 --reward_goal 50 --ownership_goal 0

如果一切设置正确，您应该会看到如下输出：

torch cuda available=True
###### DQL
Learning with: episode_count=1,iteration_count=10,ϵ=0.9,ϵ_min=0.1, ϵ_expdecay=5000,γ=0.015, lr=0.01, replaymemory=10000,
batch=512, target_update=10
  ## Episode: 1/1 'DQL' ϵ=0.9000, γ=0.015, lr=0.01, replaymemory=10000,
batch=512, target_update=10
Episode 1|Iteration 10|reward:  139.0|Elapsed Time: 0:00:00|###################################################################|
###### Random search
Learning with: episode_count=1,iteration_count=10,ϵ=1.0,ϵ_min=0.0,
  ## Episode: 1/1 'Random search' ϵ=1.0000,
Episode 1|Iteration 10|reward:  194.0|Elapsed Time: 0:00:00|###################################################################|
simulation ended
Episode duration -- DQN=Red, Random=Green
   10.00  ┼
Cumulative rewards -- DQN=Red, Random=Green
  194.00  ┼      ╭──╴
  174.60  ┤      │
  155.20  ┤╭─────╯
  135.80  ┤│     ╭──╴
  116.40  ┤│     │
   97.00  ┤│    ╭╯
   77.60  ┤│    │
   58.20  ┤╯ ╭──╯
   38.80  ┤  │
   19.40  ┤  │
    0.00  ┼──╯

Jupyter 笔记本

为了快速熟悉该项目，您可以打开其中一个提供的 Jupyter 笔记本，与 Gymnasium 环境进行交互式体验。

关于 .py 笔记本的说明：

• 我们的笔记本以 .py 文件形式提交到 Git 中。这些文件可以直接在 VSCode 或 Jupyter 中使用 Jupytext 扩展 打开并运行。
• 输出的 .ipynb 文件也可以使用 papermill 通过运行 bash 脚本 run_benchmark.sh 自动重新生成。
• 我们还会在单独的 Git 标签中发布包含完整输出和图表的相应 .ipynb 笔记本快照。 最新的 Jupyter 笔记本输出快照，包括基准测试结果，可通过以下 Git 标签访问：/notebooks/benchmarks (latest_benchmark)。

一些入门笔记本：

• “夺旗”玩具环境笔记本：

  • 随机智能体
  • 人类玩家交互式会话
  • 交互式会话——完全解题

• 链式环境笔记本：

  • 随机智能体

• 其他环境：

  • 与随机生成环境的交互式会话
  • 随机智能体在随机网络上玩耍

• 基准测试：以下笔记本展示了基线智能体在各种环境上的基准评估。

  • 在给定环境中进行基准测试
  • 在链式环境中与基础防御者一起进行基准测试
  • DQL 迁移学习评估
  • 带有凭据查找的 epsilon 贪婪策略
  • 表格 Q 学习

最新的 Jupyter 笔记本输出快照，包括基准测试结果，可通过以下 Git 标签访问：/notebooks/benchmarks (latest_benchmark)。

如何实例化 Gym 环境？

以下代码展示了如何创建 OpenAI Gym 环境 CyberBattleChain-v0 的实例，该环境基于 链式网络结构，包含 10 个节点（size=10），其中智能体的目标是获得网络的完全控制权（own_atleast_percent=1.0）或破坏 80% 的网络可用性 SLA（maintain_sla=0.80），同时网络由基于概率模型的基础防御者监控和保护（defender_agent=ScanAndReimageCompromisedMachines）：

import cyberbattle._env.cyberbattle_env

cyberbattlechain_defender =
  gym.make('CyberBattleChain-v0',
      size=10,
      attacker_goal=AttackerGoal(
          own_atleast=0,
          own_atleast_percent=1.0
      ),
      defender_constraint=DefenderConstraint(
          maintain_sla=0.80
      ),
      defender_agent=ScanAndReimageCompromisedMachines(
          probability=0.6,
          scan_capacity=2,
          scan_frequency=5))

要尝试其他网络拓扑结构，可以参考 chainpattern.py 定义您自己的机器和漏洞集合，然后在 模块初始化器 中添加条目，以声明并注册 Gym 环境。

贡献

本项目欢迎贡献和建议。大多数贡献都需要您签署贡献者许可协议（CLA），声明您有权且确实将您的贡献使用权授予我们。有关详细信息，请访问 https://cla.opensource.microsoft.com。

当您提交拉取请求时，CLA 机器人会自动判断您是否需要提供 CLA，并相应地标记 PR（例如状态检查、评论）。请按照机器人提供的指示操作。对于使用我们 CLA 的所有仓库，您只需执行此操作一次。

本项目已采用 微软开源行为准则。更多信息请参阅 行为准则常见问题解答 或通过电子邮件 opencode@microsoft.com 联系我们，以获取更多问题或意见。

贡献思路

以下是一些可能的贡献方向：增强仿真功能（基于事件的仿真、细化仿真等）、在现有仿真上训练强化学习算法、实现基准测试以评估和比较智能体的新颖性、添加更多网络生成模式以用于训练强化学习智能体、参与文档编写、修复 bug 等。

更多创意请参阅 维基页面。

引用本项目

@misc{msft:cyberbattlesim,
  Author = {Microsoft Defender 研究团队},
  Note = {由 Christian Seifert、Michael Betser、William Blum、James Bono、Kate Farris、Emily Goren、Justin Grana、Kristian Holsheimer、Brandon Marken、Joshua Neil、Nicole Nichols、Jugal Parikh 和 Haoran Wei 创建},
  Publisher = {GitHub},
  Howpublished = {\url{https://github.com/microsoft/cyberbattlesim}},
  Title = {CyberBattleSim},
  Year = {2021}
}

隐私说明

本项目不包含任何客户数据。所提供的模型和网络拓扑纯属虚构。使用本项目代码的用户需自行提供仿真所需的所有输入，并应确保拥有使用相关数据的必要权限。

商标

本项目可能包含与项目、产品或服务相关的商标或标识。未经授权使用微软商标或标识须遵守并遵循 微软商标与品牌指南。在本项目的修改版本中使用微软商标或标识时，不得造成混淆或暗示微软的赞助关系。任何第三方商标或标识的使用均应遵守该第三方的相关政策。

CyberBattleSim 快速上手指南

CyberBattleSim 是一个基于 Python 和 Open AI Gym 的研究平台，用于在模拟的企业网络环境中训练自动化智能体（攻击者与防御者），探索强化学习在网络安全领域的应用。

1. 环境准备

系统要求

• 推荐系统：Linux (如 Ubuntu) 或 Windows 下的 WSL (Windows Subsystem for Linux)。
• 不支持：直接在 Windows PowerShell 中运行（已不再维护）。
• 硬件：支持 CUDA 的 GPU 可加速训练（可选）。

前置依赖

确保系统已安装以下基础库（针对 Ubuntu/WSL）：

sudo apt install libnss3-dev libgtk-3-0 libxss1 libasound2-dev libgtk2.0-0 libgconf-2-4

2. 安装步骤

方法一：使用 Conda 环境（推荐）

1. 克隆仓库

   git clone https://github.com/microsoft/CyberBattleSim.git
   cd CyberBattleSim
   

2. 安装 Conda（如未安装）

   bash install-conda.sh
   

3. 初始化环境 运行初始化脚本，它将创建名为 cybersim 的 Conda 环境并安装所有依赖：

   bash init.sh
   

4. 激活环境

   conda activate cybersim
   

方法二：使用 Docker（最快捷）

如果你希望跳过本地环境配置，可以直接使用 Docker 容器。

注意：由于许可原因，官方镜像仓库 (spinshot.azurecr.io) 不公开。你需要使用项目提供的 Dockerfile 自行构建镜像。

1. 构建镜像

   docker build -t cyberbattle:1.1 .
   

2. 运行容器

   docker run -it -v "$(pwd)":/source --rm cyberbattle:1.1 python -m cyberbattle.agents.baseline.run
   

3. 基本使用

环境配置完成后，可以通过运行基准测试脚本来验证安装并启动简单的强化学习训练。

运行基准示例

以下命令将启动一个包含基线 RL 智能体（DQL）和随机搜索智能体的模拟过程：

python -m cyberbattle.agents.baseline.run --training_episode_count 5 --eval_episode_count 3 --iteration_count 100 --rewardplot_width 80  --chain_size=4 --ownership_goal 0.2

预期输出： 如果配置正确，你将看到类似以下的训练日志和奖励图表：

torch cuda available=True
###### DQL
Learning with: episode_count=1,iteration_count=10,ϵ=0.9,ϵ_min=0.1, ϵ_expdecay=5000,γ=0.015, lr=0.01, replaymemory=10000,
batch=512, target_update=10
  ## Episode: 1/1 'DQL' ϵ=0.9000, γ=0.015, lr=0.01, replaymemory=10000,
batch=512, target_update=10
Episode 1|Iteration 10|reward:  139.0|Elapsed Time: 0:00:00|###################################################################|
...
simulation ended
Cumulative rewards -- DQN=Red, Random=Green
  194.00  ┼      ╭──╴
  ...
    0.00  ┼──╯

交互式探索 (Jupyter Notebooks)

项目提供了多个 Jupyter Notebook 用于交互式实验。源代码以 .py 格式存储，可使用 VS Code 直接打开，或通过 jupytext 转换为 .ipynb。

推荐入门笔记：

• 随机智能体演示: notebooks/toyctf-random.py
• 人类玩家交互会话: notebooks/toyctf-blank.py
• 链式网络环境: notebooks/chainnetwork-random.py

如需查看带有完整运行结果和图表的最新笔记，请查阅仓库中的 latest_benchmark 标签页。