CyberBattleSim - 一个实验和研究平台，用于研究抽象模拟网络环境中自动代理的交互。

Created at: 2020-11-18 07:18:59

Language: Jupyter Notebook

编号: https://github.com/microsoft/CyberBattleSim

License: MIT

网络对战模拟

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

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

模拟环境由固定网络拓扑和一组漏洞参数化，代理可以利用这些漏洞在网络中横向移动。攻击者的目标是通过利用植入计算机节点中的漏洞来获得部分网络的所有权。当攻击者想在整个网络中传播时，防御者代理会监视网络活动并尝试检测发生的任何攻击并通过驱逐攻击者来减轻对系统的影响。我们提供了一个基本的随机防御者，可以根据预先定义的成功概率来检测和缓解正在进行的攻击。我们通过重新成像受感染节点来实现缓解，这一过程被抽象建模为跨越多个模拟步骤的操作。

为了比较代理的性能，我们查看两个指标：为实现其目标所采取的模拟步骤数以及跨训练时期模拟步骤的累积奖励。

项目目标

我们将此项目视为一个实验平台，用于研究抽象模拟网络环境中自动代理的交互。通过将其开源，我们希望鼓励研究界调查网络代理如何在此类网络环境中交互和发展。

诚然，我们提供的模拟非常简单，但这有其优点。它的高度抽象性质禁止直接应用于现实世界的系统，从而提供了一种保护措施，防止潜在地恶意使用经过它训练的自动化代理。同时，它的简单性使我们能够专注于我们旨在研究的特定安全方面，并快速试验最近的机器学习和 AI 算法。

例如，当前的实施侧重于横向移动网络攻击技术，希望了解网络拓扑和配置如何影响它们。考虑到这一目标，我们认为没有必要对实际网络流量进行建模。这只是我们系统中一个重大限制的一个例子，未来的贡献可能想要解决。

在算法方面，我们提供了一些基本的代理作为起点，但我们很想知道最先进的强化学习算法与它们相比如何。我们发现，与视频游戏或机器人控制等其他应用程序相比，任何计算机系统固有的大动作空间对于强化学习来说都是一个特殊的挑战。训练可以存储和检索凭证的代理是应用 RL 技术时面临的另一个挑战，其中代理通常不具有内部记忆功能。这些是模拟可用于基准测试的其他研究领域。

其他感兴趣的领域包括自主网络安全系统的负责任和合乎道德的使用：如何设计一个企业网络，为防御代理提供内在优势？如何进行旨在保护企业免受自主网络攻击的安全研究，同时防止此类技术的恶意使用？

文档

阅读项目的快速介绍。

构建状态

类型	分支	地位
CI	掌握
Docker 镜像	掌握

基准

参见基准。

搭建开发环境

强烈建议直接或通过 Windows 上的 WSL 在 Linux 环境下工作。直接在 Windows 上运行 Python 应该可以工作，但不再受支持。

首先检查存储库：

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

在 Linux 或 WSL 上

这些说明在 Linux Ubuntu 发行版（本机和通过 WSL）上进行了测试。运行以下命令来设置你的开发环境并安装所有必需的依赖项（apt 和 pip 包）：

./init.sh

如果不存在，脚本会安装 python3.8。如果你运行的 Ubuntu 版本早于 20，它会自动添加一个额外的 apt 存储库来安装 python3.8。

该脚本将在子目录下创建一个虚拟 Python 环境

venv

，然后你可以使用

venv/bin/python

注意：如果你更喜欢全局安装中的 Python 而不是虚拟环境，那么你可以通过运行带有
./init.sh -n
. 这将在 Python 3.8 的系统范围安装上安装所有 Python 包。

适用于 Linux 的 Windows 子系统

Windows 上支持的开发环境是通过 WSL 实现的。你首先需要在 Windows 机器上安装 Ubuntu WSL 发行版，然后继续执行 Linux 说明（下一部分）。

来自 WSL 的 Git 身份验证

要使用 Git 进行身份验证，你可以使用基于 SSH 的身份验证，也可以使用凭据助手技巧来自动生成 PAT 令牌。后者可以通过在 WSL 下运行以下命令来完成（更多信息在这里）：

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

WSL 上的 Docker

要在 docker 容器中运行你的环境，我们建议

docker

使用以下说明通过 Linux 上的 Windows 子系统 (WSL)运行：在 WSL 下的 Windows 上安装 Docker。

Windows（不支持）

此方法不再维护，请改为在 WSL 子系统 Linux 环境下运行。但是，如果你坚持要从安装Python 3.8开始，请在 Powershell 提示符下运行

./init.ps1

脚本。

使用 Docker 快速入门

启动和运行的最快方法是通过 Docker 容器。

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

作为一种解决方法，你可以使用提供的自己重新创建 docker 镜像
Dockerfile
，将生成的镜像发布到你自己的 docker 注册表并替换以下命令中的注册表名称。

从 Docker 注册表运行

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

重新创建 Docker 镜像

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

Check your environment

Run the following command to run a simulation with a baseline RL agent:

python cyberbattle/agents/baseline/run.py --training_episode_count 1 --eval_episode_count 1 --iteration_count 10 --rewardplot_with 80  --chain_size=20 --ownership_goal 1.0

If everything is setup correctly you should get an output that looks like this:

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 notebooks

To quickly get familiar with the project, you can open one of the provided Jupyter notebooks to play interactively with the gym environments. Just start jupyter with

jupyter notebook

, or

venv/bin/jupyter notebook

if you are using a virtual environment setup.

'Capture The Flag' toy environment notebooks:
Chain environment notebooks:
- Random agent
Other environments:
- Interactive session with a randomly generated environment
- Random agent playing on randomly generated networks
Benchmarks:

The following notebooks show benchmark evaluation of the baseline agents on various environments.
The source
```
.py
```
-versions of the notebooks are best viewed in VSCode or in Jupyter with the Jupytext extension. The
```
notebooks
```
folder contains the corresponding
```
.ipynb
```
-notebooks with the entire output and plots. These can be regenerated via papermill using this bash script .
- Benchmarking on a given environment: source: output (Chain), output (Capture the flag)
- Benchmark on chain environments with a basic defender: source, output;
- DQL transfer learning evaluation: source, output;
- Epsilon greedy with credential lookups: source, output;
- 表格 Q 学习：来源；输出

如何实例化 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 在所有存储库中执行一次此操作。

该项目采用了Microsoft 开放源代码行为准则。有关更多信息，请参阅行为准则常见问题解答或联系opencode@microsoft.com以提出任何其他问题或意见。

贡献的想法

以下是关于如何贡献的一些想法：增强模拟（基于事件，改进模拟，...），在现有模拟上训练 RL 算法，实施基准以评估和比较代理的新颖性，添加更多网络生成模式以进行训练RL 代理开启，为文档做出贡献，修复错误。

有关更多想法，另请参阅wiki。

引用这个项目

@misc{msft:cyberbattlesim,
  Author = {Microsoft Defender Research Team.}
  Note = {Created by 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}
}

隐私注意事项

该项目不包括任何客户数据。提供的模型和网络拓扑纯属虚构。提供的代码的用户提供模拟的所有输入，并且必须具有使用任何提供的数据的必要权限。

商标

此项目可能包含项目、产品或服务的商标或徽标。Microsoft 商标或徽标的授权使用受并且必须遵循 Microsoft 的商标和品牌指南。在本项目的修改版本中使用 Microsoft 商标或徽标不得造成混淆或暗示 Microsoft 赞助。对第三方商标或徽标的任何使用均受这些第三方政策的约束。