适用于 Microsoft Sentinel 中的 Jupyter Notebook 和 MSTICPy 的高级配置

项目
09/10/2024

本文介绍了在 Microsoft Sentinel 中使用 Jupyter Notebook 和 MSTICPy 时会用到的高级配置。

有关详细信息，请参阅使用 Jupyter Notebook 搜寻安全威胁和教程：开始使用 Microsoft Sentinel 中的 Jupyter Notebook 和 MSTICPy。

先决条件

本文是教程：开始使用 Microsoft Sentinel 中的 Jupyter Notebook 和 MSTICPy 的延续内容。建议先按此教程执行操作，然后继续进行以下所述的高级过程。

为 Microsoft 和 Microsoft Sentinel API 指定身份验证参数

本过程介绍如何在 msticpyconfig.yaml 文件中为 Microsoft Sentinel 和其他 Azure API 资源配置身份验证参数。

若要在 MSTICPy 设置编辑器中添加 Azure 身份验证和 Microsoft Sentinel API 设置：

转到下一个单元格，使用并运行以下代码：
```
mpedit.set_tab("Data Providers")
mpedit
```
在“数据提供程序”选项卡中，选择“AzureCLI”>“添加”。
选择要使用的身份验证方法：
- 尽管可以使用 Azure 默认值以外的方法集，但这种用法并非典型配置。
- 除非要使用“env”（环境变量）身份验证，否则请将“clientId”、“tenantiId”和“clientSecret”字段保留为空。
- MSTICPy 还支持使用客户端应用 ID 和机密进行身份验证，但不建议你这样做。在此类情况下，请直接在“数据提供程序”选项卡中定义“clientId”、“tenantId”和“clientSecret”字段。
选择“保存文件”以保存更改。

定义自动加载的查询提供程序

定义运行 nbinit.init_notebook 函数时 MSTICPy 要自动加载的任何所需的查询提供程序。

当频繁创作新的笔记本时，自动加载查询提供程序可以确保在加载其他组件（例如 Pivot 函数和 Notebooklets）之前加载所需的提供程序，从而节省时间。

若要添加自动加载的查询提供程序：

转到下一个单元格，使用并运行以下代码：
```
mpedit.set_tab("Autoload QueryProvs")
mpedit
```
在“自动加载 QueryProv”选项卡中：
- 对于 Microsoft Sentinel 提供程序，需指定要连接到的提供程序名称和工作区名称。
- 对于其他查询提供程序，仅指定提供程序名称。
每个提供程序还具有以下可选值：
- 自动连接：默认情况下，此选项定义为“True”，MSTICPy 会尝试在加载提供程序后立即对其进行身份验证。 MSTICPy 假设你已在设置中为提供程序配置凭据。
- 别名：当 MSTICPy 加载提供程序时，它会为提供程序分配 Python 变量名。默认情况下，Microsoft Sentinel 提供程序的变量名为 qryworkspace_name，其他提供程序的变量名为 qryprovider_name 。
  
  例如，如果为 ContosoSOC 工作区加载查询提供程序，则将在笔记本环境中创建名称为 qry_ContosoSOC 的查询提供程序。如果要使用更短或更容易键入和记住的内容，请添加别名。提供程序变量名称将为 qry_<alias>，其中 <alias> 将替换为所提供的别名。
  
  采用此机制加载的提供程序还会添加到 MSTICPy 的 current_providers 属性中，例如，以下代码中将会使用该属性：
```
import msticpy
msticpy.current_providers
```
选择“保存设置”以保存更改。

定义自动加载的 MSTICPy 组件

本过程介绍如何定义运行 nbinit.init_notebook 函数时 MSTICPy 自动加载的其他组件。

支持的组件按以下顺序包括：

TILookup：TI 提供程序库
GeoIP：想要使用的 GeoIP 提供程序
AzureData：用于查询有关 Azure 资源的详细信息的模块
AzureSentinelAPI： 用于查询 Microsoft Sentinel API 的模块
Notebooklets：msticnb 包中的 Notebooklets
Pivot：Pivot 函数

注意

组件按此顺序进行加载，因为 Pivot 组件需要加载查询和其他提供程序才能查找其附加到实体的 Pivot 函数。有关详细信息，请参阅 MSTICPy 文档。

若要定义自动加载的 MSTICPy 组件：

转到下一个单元格，使用并运行以下代码：
```
mpedit.set_tab("Autoload Components")
mpedit
```
在“自动加载组件”选项卡中，定义任何所需参数值。例如：
- GeoIpLookup。输入要使用的 GeoIP 提供程序的名称，“GeoLiteLookup”或“IPStack”。有关详细信息，请参阅添加 GeoIP 提供程序设置。
- AzureData 和 AzureSentinelAPI 组件。定义以下值：
  - auth_methods：替代 AzureCLI 的默认设置，并使用所选的方法进行连接。
  - Auto-connect：设置为 false，以在不连接的情况下加载。
  有关详细信息，请参阅为 Azure 和 Microsoft Sentinel API 指定身份验证参数。
- Notebooklets。 Notebooklets 组件具有单个参数块：AzureSentinel。
  
  使用以下语法指定 Microsoft Sentinel 工作区：workspace:\<workspace name>。工作区名称必须是“Microsoft Sentinel”选项卡中定义的工作区之一。
  
  如果要添加更多要发送到 notebooklets init 函数的参数，请将这些参数指定为以换行符分隔的键值对。例如：
```
workspace:<workspace name>
providers=["LocalData","geolitelookup"]
```
  有关详细信息，请参阅 MSTICNB (MSTIC Notebooklets) 文档。
某些组件（例如 TILookup 和 Pivot）不需要任何参数。
选择“保存设置”以保存更改。

在 Python 3.6 和 3.8 内核之间切换

如果要在 Python 3.65 和 3.8 内核之间切换，你可能会发现 MSTICPy 和其他包没有按预期方式安装。

当 !pip install pkg 命令在第一个环境中正确安装，但未在第二个环境中正确安装时，就可能出现这种情况。这会导致第二个环境无法导入或使用包。

建议不要使用 !pip install... 在 Azure ML 笔记本中安装包。改用以下选项之一：

在笔记本中使用 %pip line magic。运行：
```
%pip install --upgrade msticpy
```
从终端安装：
1. 在 Azure ML 笔记本中打开终端，并运行以下命令：
```
conda activate azureml_py38
pip install --upgrade msticpy
```
2. 关闭终端并重启内核。

为 msticpyconfig.yaml 文件设置环境变量

如果要在 Azure ML 中运行，且 msticpyconfig.yaml 文件位于用户文件夹的根目录中，则 MSTICPy 将自动查找这些设置。但是，如果要在其他环境中运行笔记本，请按照本部分中的说明设置一个指向配置文件位置的环境变量。

通过在环境变量中定义 msticpyconfig.yaml 文件的路径，可以将文件存储在已知位置，并确保始终加载相同的设置。

如果要将不同的设置用于不同的笔记本，请使用多个配置文件和多个环境变量。

确定 msticpyconfig.yaml 文件的位置，例如，位于 ~/.msticpyconfig.yaml 或 %userprofile%/msticpyconfig.yaml 中。

Azure ML 用户：如果将配置文件存储在 Azure ML 用户文件夹中，则 MSTICPy init_notebook 函数（在初始化单元格中运行）将自动查找并使用该文件，而无需设置 MSTICPYCONFIG 环境变量。

但是，如果此文件中还存储了机密，则建议将配置文件存储在计算本地驱动器中。计算内部存储仅创建计算的人员才可访问，而共享存储则是有权访问 Azure ML 工作区的所有人都可访问。

有关详细信息，请参阅什么是 Azure 机器学习计算实例？。
如果需要，请将 msticpyconfig.yaml 文件复制到所选位置。
将 MSTICPYCONFIG 环境变量设置为指向该位置。

使用以下过程之一来定义 MSTICPYCONFIG 环境变量。

例如，若要在 Windows 系统上设置 MSTICPYCONFIG 环境变量：

根据需要将 msticpyconfig.yaml 文件移动到计算实例。
打开“系统属性”对话框的“高级”选项卡。
选择“环境变量...”以打开“环境变量”对话框。
在“系统变量”区域中，选择“新建...”，并按如下所示定义值：
- 变量名称：定义为 MSTICPYCONFIG
- 变量值：输入 msticpyconfig.yaml 文件的路径

本过程介绍如何更新 .bashrc 文件，以在 Linux 系统上设置 MSTICPYCONFIG 环境变量。

根据需要将 msticpyconfig.yaml 文件移动到计算实例。
打开 Azure ML 终端（例如从 Microsoft Sentinel“笔记本”页打开）。
验证是否可以访问 msticpyconfig.yaml 文件。

在 Azure ML 终端中，当前目录应为装载在计算 Linux 系统中的 Azure ML 文件存储主目录。提示与以下示例类似：
```
azureuser@alicecontoso-azml7:~/cloudfiles/code/Users/alicecontoso$
```
通过输入 ls，列出主目录中的所有文件，包括 msticpyconfig.yaml 文件。
若要将 msticpyconfig.yaml 文件移动到计算文件存储，请输入：
```
mv msticpyconfig.yaml ~
```

使用以下过程之一编辑环境变量的 .bashrc 文件：

命令	步骤
vim	1.运行：`vim ~/.bashrc` 2.按 SHIFT+G > End，转到文件末尾。 3. 输入“a”并按 Enter，创建新行。 4.添加环境变量，然后按 ESC 返回到命令模式。 5.输入 :wq，保存文件。
Nano	1.运行：`nano ~/.bashrc` 1.按 ALT+/ 或 OPTION+/，转到文件末尾。 1.添加环境变量，然后保存文件。按 CTRL+X，然后按 Y。

添加以下环境变量之一：

如果移动了 msticpyconfig.yaml 文件，请运行 export MSTICPYCONFIG=~/msticpyconfig.yaml。
如果未移动 msticpyconfig.yaml 文件，请运行 export MSTICPYCONFIG=~/cloudfiles/code/Users/<YOURNAME>/msticpyconfig.yaml。

如果需要将 msticpyconfig.yaml 文件存储在 Azure ML 用户文件夹以外的其他位置，请使用以下选项之一：

位于用户文件夹根目录的 nbuser_settings.py 文件。虽然此过程比编辑 kernel.json 文件更简单且干扰性更低，但仅在开始运行笔记本代码时运行 init_notebook 函数，才能使用此过程。虽然这是默认行为，但如果在未先运行 init_notebook 的情况下运行笔记本代码，则 MSTICPy 可能找不到配置文件。
1. 在 Azure ML 终端中，在使用用户名的用户文件夹根目录下创建 nbuser_settings.py 文件。
2. 在 nbuser_settings.py 文件中，添加以下行：
```
  import os
  os.environ["MSTICPYCONFIG"] = "~/msticpyconfig.yaml"
```
此文件由 init_notebook 函数自动导入，用于为当前笔记本设置 MSTICPYCONFIG 环境变量。
Python 内核的 kernel.json 文件。如果计划手动运行笔记本且在开始时可能不调用 init_notebook 函数，则使用此过程。

提供 Python 3.6 和 Python 3.8 内核。如果同时使用这两个内核，请编辑这两个文件。
- Python 3.8 位置：/usr/local/share/jupyter/kernels/python38-azureml/kernel.json
- Python 3.6 位置：/usr/local/share/jupyter/kernels/python3-azureml/kernel.json
若要在 kernel.json 文件中设置环境变量：
1. 创建 kernel.json 文件的副本，并在编辑器中打开原始文件。可能需要使用 sudo 覆盖 kernel.json 文件，文件内容类似于以下示例：
```
{
   "argv": [
   "/anaconda/envs/azureml_py38/bin/python",
   "-m",
   "ipykernel_launcher",
   "-f",
   "{connection_file}"
   ],
   "display_name": "Python 3.8 - AzureML",
   "language": "python"
}
```
2. 在 "language" 项的后面添加以下此行："env": { "MSTICPYCONFIG": "~/msticpyconfig.yaml" }
  
  确保在 "language": "python" 行的末尾添加逗号。例如：
```
{
    "argv": [
    "/anaconda/envs/azureml_py38/bin/python",
    "-m",
    "ipykernel_launcher",
    "-f",
    "{connection_file}"
    ],
    "display_name": "Python 3.8 - AzureML",
    "language": "python",
    "env": { "MSTICPYCONFIG": "~/msticpyconfig.yaml" }
}
```

注意

对于 Linux 和 Windows 选项，需要重启 Jupyter 服务器，使之选取定义的环境变量。

后续步骤

有关详细信息，请参阅：

使用者	更多参考资料
MSTICPy	- MSTICPy 包配置 - MSTICPy 设置编辑器 - 配置笔记本环境。 - MPSettingsEditor 笔记本。注意：Azure-Sentinel-Notebooks GitHub 存储库还包含 msticpyconfig.yaml 模板文件，其中包含注释掉的部分，可能会对你了解设置有所帮助。
Microsoft Sentinel 和 Jupyter 笔记本	- 创建第一个 Microsoft Sentinel 笔记本（博客系列） - Jupyter Notebook 简介 - MSTICPy 文档 - Microsoft Sentinel Notebook 文档 - Infosec Jupyter 书籍 - Linux 主机资源管理器 Notebook 演练 - 为什么使用 Jupyter 进行安全调查 - 使用 Microsoft Sentinel 和 Notebook 进行安全调查 - Pandas 文档 - Bokeh 文档

通过