njk464/untitledgoosetool
GitHub: njk464/untitledgoosetool
CISA开源的微软云环境取证与事件响应工具，用于批量导出Entra ID、Azure、M365、Defender等平台的安全日志与配置数据。
Stars: 0 | Forks: 0
Untitled Goose Tool
鹅已出笼。
## 目录
- [关于](#about)
- [入门指南](#getting-started)
- [前置条件](#prerequisites)
- [系统要求](#requirements)
- [安装](#installing)
- [使用说明](#usage)
- [配置](#config)
- [GUI](#gui)
- [认证](#auth)
- [Csv](#csv)
- [Honk](#honk)
- [Messagetrace](#messagetrace)
- [推荐的默认工作流](#recommended-default-workflow)
- [针对带时间界限的 UAL 调用的推荐工作流](#recommended-workflow-for-ual-call-with-time-bounds)
- [注意事项](#considerations)
- [已知问题](#known-issues)
- [致谢](#acknowledgements)
- [贡献](#contributing)
- [许可证](#license)
- [法律免责声明](#legal-disclaimer)
## 关于
Untitled Goose Tool 是一款强大且灵活的猎杀与事件响应工具，它通过增加新颖的认证和数据收集方法，以便对客户的 Microsoft Entra ID、Azure 和 M365 环境进行全面调查。Untitled Goose Tool 还从 Microsoft Defender for Endpoint (MDE) 和 Defender for Internet of Things (IoT) (D4IoT) 收集额外的遥测数据。
该工具旨在通过在事件发生后导出云环境 artifacts 来协助事件响应团队，适用于那些未将日志摄取到安全信息与事件管理 (SIEM) 或其他长期日志存储解决方案中的环境。
有关如何使用 Untitled Goose Tool 的更多指导，请参阅：[Untitled Goose Tool 事实表](https://www.cisa.gov/resources-tools/resources/untitled-goose-tool-fact-sheet)
## 入门指南
### 前置条件
运行 Python 版的 Untitled Goose Tool 需要 Python >= 3.9。强烈推荐使用 Python 3.12，因为它能提供更好的日志记录。
在 Windows 机器上，您需要确保在运行该工具之前已安装 Microsoft Visual C++ redistributable package (14.x)。
也建议在虚拟环境中运行 Untitled Goose Tool。
#### Mac OSX
```
pip3 install virtualenv
virtualenv -p python3 .venv
source .venv/bin/activate
```
#### Linux
```
# 您可能需要先运行 sudo apt-get install python3-venv
python3 -m venv .venv
source .venv/bin/activate
```
#### Windows
```
# 您也可以使用 py -3 -m venv .venv
python -m venv .venv
.venv\Scripts\activate
```
### 系统要求
运行 Untitled Goose Tool 需要以下 EntraID/M365 权限，并为其提供对租户的只读访问权限。
请注意：用户帐户应为纯云帐户（不同步到本地环境），这将确保该工具在不同环境中的登录过程保持一致。
一个纯云用户帐户及关联的具有以下权限的 EXO 服务主体：
Exchange Online Admin Center
```
- View-Only Audit Logs
- View-Only Configuration
- View-Only Recipients
- User Options
```
一个具有以下权限的服务主体：
API Permissions
```
Log Analytics API
- Data.Read (Application)
Microsoft Threat Protection:
- AdvancedHunting.Read.All (Application)
WindowsDefenderATP:
- AdvancedQuery.Read.All (Application)
- Alert.Read.All (Application)
- Library.Manage (Application)
- Machine.Read.All (Application)
- SecurityRecommendation.Read.All (Application)
- Software.Read.All (Application)
- Ti.ReadWrite (Application)
- Vulnerability.Read.All (Application)
Microsoft Graph:
- APIConnectors.Read.All (Application)
- AuditLog.Read.All (Application)
- ConsentRequest.Read.All (Application)
- Directory.Read.All (Application)
- Domain.Read.All (Application)
- IdentityProvider.Read.All (Application)
- IdentityRiskEvent.Read.All (Application)
- IdentityRiskyServicePrincipal.Read.All (Application)
- IdentityRiskyUser.Read.All (Application)
- MailboxSettings.Read (Application)
- Policy.Read.All (Application)
- Policy.Read.PermissionGrant (Application)
- Reports.Read.All (Application)
- RoleManagement.Read.All (Application)
- SecurityActions.Read.All (Application)
- SecurityAlert.Read.All (Application)
- SecurityEvents.Read.All (Application)
- UserAuthenticationMethod.Read.All (Application)
Office 365 Exchange Online
- Exchange.ManageAsApp (Application)
```
Azure Subscription IAM Roles
```
- Reader
- Storage Blob Data Reader
- Storage Queue Data Reader
```
确保为服务主体启用“Allow public client flows”。
我们提供了一个 [setup powershell script](scripts/Create_SP.ps1) 来设置具有所需权限的服务主体。此外，Azure Service Principal 与 m365 的关联目前只能通过 powershell 完成，这对于某些 m365 日志收集是必需的。
下面是运行脚本的示例，它将输出构建包含正确信息的配置文件所需的 `goosey conf` 命令
```
PS > Write-Host "Creating a new Goose Application and Users"
PS > ./Create_SP.ps1 -AppName GooseApp -Create
```
此外，当您使用完毕后，脚本可以删除该应用程序
```
PS > Write-Host "Creating a new Goose Application and Users"
PS > ./Create_SP.ps1 -AppName GooseApp -Delete
```
### 安装
要安装，请克隆仓库，然后进行 pip install：
#### 常规安装
```
git clone https://github.com/cisagov/untitledgoosetool.git
cd untitledgoosetool
python3 -m pip install .
```
#### Docker
```
docker build . -t goosey
docker run -it -v $PWD:/workdir goosey goosey honk --debug
```
## 使用说明
### 配置
Untitled Goose Tool 需要认证参数和配置。要自动构建配置文件，请在安装后运行以下命令。
```
$ goosey conf
```
运行 powershell 安装脚本来创建/设置服务主体时，会生成此命令的一个版本。下面是一个使用伪参数值的示例
```
$ goosey conf --config_tenant=5fd146ad-8b31-4afa-a72f-6f71df5c7173 --config_subscriptionid=all --auth_appid=24fd6377-79e0-445d-838b-3eaa60d3ca21
```
在此之后，`.auth`、`.conf`、`.auth_d4iot` 和 `.d4iot_conf` 文件应放置在您的当前目录中。这些文件由 Untitled Goose Tool 使用。除非是使用上述参数生成的，否则您应该填写顶部的 `[auth]` 部分，以便 Untitled Goose Tool 能够正确验证到相应的资源。但是，如果您不愿意将凭据输入文件中，您可以选择删除 `.auth` 和/或 `.auth_d4iot`，工具将通过控制台提示您输入凭据。
最简 auth 文件如下所示：
```
[auth]
# 您账户的用户名。例如：AAD_upn@example.onmicrosoft.com
username=
# 您账户的密码。例如：AAD_password
password=
# 您服务主体的应用程序 ID
appid=
# 您服务主体的客户端密钥值（不是密钥 ID）
clientsecret=
```
最简 config 文件如下所示：
```
[config]
# 您 AAD 租户的租户 ID
tenant=
# 如果您拥有 GCC High 租户
us_government=False
# 如果您拥有带 MDE 的 GCC 租户
mde_gcc=False
# 如果您拥有带 MDE 的 GCC High 租户
mde_gcc_high=False
# 如果您的 M365 租户是政府租户
exo_us_government=False
# 如果您想检查所有的 Azure 订阅，请将其设置为 All，否则请输入您的 Azure 订阅 ID。对于多个 ID，请用逗号分隔，不要有空格
subscriptionid=All
[filters]
# 格式应为 YYYY-MM-DD。如果未设置，将默认为日志保留的最早日期
date_start=
# 格式应为 YYYY-MM-DD。将默认为当天
date_end=
[variables]
# 用于 ual API 请求的阈值。指定每次会话拉取的最大结果数。可以在 100 - 50000 之间。该 API 经过优化，阈值越大返回结果越快，但如果发生错误，必须重复整个会话，因为返回的结果未排序。我们建议使用 5000 作为阈值，但可以根据需要调整
ual_threshold=5000
# 异步运行的 ual 协程/任务的最大数量。最小值为 1。
max_ual_tasks=5
# ual 搜索的额外时间范围的开始日期。原因是 ual 拉取时间最长，虽然您不希望最旧的数据过期，但您可能想查看另一个时间段，而不想等待 ual 到达该点并拉取日志。格式应为 YYY-MM-DD
ual_extra_start=
# ual 搜索的额外时间范围的结束日期。原因是 ual 拉取时间最长，虽然您不希望最旧的数据过期，但您可能想查看另一个时间段，而不想等待 ual 到达该点并拉取日志。格式应为 YYY-MM-DD
ual_extra_end=
# 每次查询拉取日志数量的阈值。通常尽量将其最大化，因为 KQL 查询有速率限制。
mde_threshold=10000
# 可以是 'table' 或 'machine'。'table' 将直接从 mde 表中提取而不进行过滤。而 'machine' 将按 'machine' 进行过滤；对于大型租户，'machine' 可能是首选，因为对整个表进行时间限定可能会导致问题。
mde_query_mode=table
[azure]
# 转储 azure 活动日志
activity_log=False
# 返回所有 azure 订阅
all_azure_subscriptions=False
# 转储 insights bastion 审计日志
bastion_logs=False
# 转储 Azure 配置信息
configs=False
# 转储 D4IOT 门户配置
d4iot_portal_configs=False
# 从警报转储 D4IOT 门户 pcaps
d4iot_portal_pcap=False
# 转储 key_vault 的 insights 审计事件
key_vault_log=False
# 转储 insights 网络安全组流事件
nsg_flow_logs=False
[entraid]
# 转储 Entra ID 审计日志
entraid_audit=False
# 转储 Entra ID 预配日志
entraid_provisioning=False
# 转储 Entra ID 配置文件
configs=False
# 从 identity protection 转储风险检测。要获得完整结果，至少需要 Microsoft Entra ID P1 许可证和 Microsoft Entra Workload ID 高级许可证。
risk_detections=False
# 转储风险用户和服务主体信息。要获得完整结果，至少需要 Microsoft Entra ID P2 许可证和 Microsoft Entra Workload ID 高级许可证。
risky_objects=False
# 转储安全操作、警报和分数
security=False
# 转储交互式 登录日志
signins_adfs=False
# 转储托管身份 登录日志
signins_msi=False
# 转储非交互式 登录日志
signins_rt=False
# 转储服务主体 登录日志
signins_sp=False
[m365]
# 获取 Exchange 发现信息
ediscovery_info=False
# 获取组织安装的所有应用程序
exo_addins=False
# 获取 EXO 配置信息
exo_config_info=False
# 转储 Exchange Online 角色组和角色组成员信息。
exo_groups=False
# 获取为所有用户收件箱定义的所有 messageRule 对象
exo_inboxrules=False
# 转储 Exchange Online 邮箱信息
exo_mailbox=False
# 获取 m365 移动设备信息
exo_mobile_devices=False
# 使用 Search-UnifiedAuditLog api 转储去年的 UAL。之前的 ual api 目前已弃用。
ual=False
[mde]
# 转储 incidents 和 alerts 的结果。
advanced_hunting_alerts_incidents=False
# 转储 advanced hunting 查询的结果。
advanced_hunting_query=False
# 转储 advanced hunting API 查询的结果。
advanced_identity_hunting_query=False
# 转储 alerts
alerts=False
# 转储 indicators
indicators=False
# 转储 investigations
investigations=False
# 转储库文件
library_files=False
# 转储已知机器 vulnerabilities
machine_vulns=False
# 转储装有 mde 的机器
machines=False
# 转储 mde recommendations
recommendations=False
# 转储已知已安装软件
software=False
```
最简 D4IoT auth 文件如下所示：
```
[auth]
# D4IoT 传感器登录页面的用户名
username=
# D4IoT 传感器登录页面的密码
password=
# 输入您的 D4IoT 传感器 API token
sensor_token=
# 输入您的 D4IoT 管理控制台 API token
mgmt_token=
```
D4IoT config 文件如下所示：
```
[config]
# 输入您的 D4IoT 传感器 IP
d4iot_sensor_ip=
# 输入您的 D4IoT 管理控制台 IP
d4iot_mgmt_ip=
[d4iot]
# 转储管理 alerts
mgmt_alerts=False
# 转储管理设备
mgmt_devices=False
# 转储管理传感器捕获的 pcap
mgmt_pcap=False
# 转储管理传感器信息
mgmt_sensor_info=False
# 转储传感器 alerts
sensor_alerts=False
# 收集所有设备连接
sensor_device_connections=False
# 转储传感器设备已知 cves
sensor_device_cves=False
# 转储传感器设备已知 vulnerabilities
sensor_device_vuln=False
# 转储传感器设备
sensor_devices=False
# 转储传感器事件
sensor_events=False
# 转储传感器操作 vulnerabilities
sensor_operational_vuln=False
# 转储传感器 pcap
sensor_pcap=False
# 转储传感器安全 vulnerabilities
sensor_security_vuln=False
```
要启用特定的拉取操作，您可以将 `False` 更改为 `True`（不区分大小写）。
### 认证
```
$ goosey auth --help
NAME
goosey auth - Untitled Goose Tool Authentication
SYNOPSIS
goosey auth
DESCRIPTION
Untitled Goose Tool Authentication
FLAGS
--authfile=AUTHFILE
Default: '.ugt_auth'
File to store the authentication tokens and cookies
--d4iot_authfile=D4IOT_AUTHFILE
Default: '.d4iot_auth'
File to store the authentication cookies for D4IoT
-c, --config=CONFIG
Default: '.conf'
Path to config file
--auth=AUTH
Default: '.auth'
File to store the credentials used for authentication
--d4iot_auth=D4IOT_AUTH
Default: '.auth_d4iot'
File to store the D4IoT credentials used for authentication
--d4iot_config=D4IOT_CONFIG
Default: '.d4iot_conf'
-r, --revoke=REVOKE
Default: False
Revoke sessions for user with authentication tokens and cookies
--interactive=INTERACTIVE
Default: False
Interactive mode for Selenium. Default to headless
--debug=DEBUG
Default: False
Enable debug logging
--d4iot=D4IOT
Default: False
Run the authentication portion for d4iot
--insecure=INSECURE
Default: False
Disable secure authentication handling (file encryption)
-u, --user_auth=USER_AUTH
Default: False
Authenticate with the user credentials and collect the session tokens
```
使用默认值运行。默认情况下，它将使用提示输入的密码加密凭据/token。如果字段未在配置中定义，则也会提示输入这些字段：
```
$ goosey auth
```
启用调试和不安全认证处理运行：
```
$ goosey auth --debug --insecure
```
### Csv
```
$ goosey csv --help
NAME
goosey csv - Create csv files mapping GUIDs to text
SYNOPSIS
goosey csv
DESCRIPTION
Create csv files mapping GUIDs to text
FLAGS
-o, --output_dir=OUTPUT_DIR
Default: 'output/entraid/'
The directory where the goose files are located
-r, --result_dir=RESULT_DIR
Default: 'output/csvs/'
Directory for storing the results
-d, --debug=DEBUG
Default: False
Enable debug logging
```
使用默认值运行：
```
$ goosey csv
```
### Honk
```
$ goosey honk --help
NAME
goosey honk - Untitled Goose Tool Information Gathering
SYNOPSIS
goosey honk
DESCRIPTION
Untitled Goose Tool Information Gathering
FLAGS
--authfile=AUTHFILE
Default: '.ugt_auth'
File to store the authentication tokens and cookies
-c, --config=CONFIG
Default: '.conf'
Path to config file
--auth=AUTH
Default: '.auth'
File to store the credentials used for authentication
-o, --output_dir=OUTPUT_DIR
Default: 'output'
Directory for storing the results
-r, --reports_dir=REPORTS_DIR
Default: 'reports'
Directory for storing debugging/informational logs
--debug=DEBUG
Default: False
Enable debug logging
--dry_run=DRY_RUN
Default: False
Dry run (do not do any API calls)
--azure=AZURE
Default: False
Set all of the Azure calls to true
--entraid=ENTRAID
Default: False
Set all of the Entra ID calls to true
--m365=M365
Default: False
Set all of the M365 calls to true
--mde=MDE
Default: False
Set all of the MDE calls to true
```
使用默认选项运行：
```
$ goosey honk
```
启用调试日志，输出到目录 `my_outputs`，并启用所有 Azure 调用：
```
$ goosey honk --debug --output-dir my_outputs --azure
```
### Autohonk
```
$ goosey autohonk --help
NAME
goosey autohonk - Untitled Goose Tool Information Gathering. With auto authentication! This will never stop until you tell it to.
SYNOPSIS
goosey autohonk
DESCRIPTION
Untitled Goose Tool Information Gathering. With auto authentication! This will never stop until you tell it to.
FLAGS
--authfile=AUTHFILE
Default: '.ugt_auth'
File to store the authentication tokens and cookies
-c, --config=CONFIG
Default: '.conf'
Path to config file
--auth=AUTH
Default: '.auth'
File to store the credentials used for authentication
-o, --output_dir=OUTPUT_DIR
Default: 'output'
Directory for storing the results
-r, --reports_dir=REPORTS_DIR
Default: 'reports'
Directory for storing debugging/informational logs
-d, --debug=DEBUG
Default: False
Enable debug logging
--azure=AZURE
Default: False
Set all of the Azure calls to true
--entraid=ENTRAID
Default: False
Set all of the Entra ID calls to true
--m365=M365
Default: False
Set all of the M365 calls to true
--mde=MDE
Default: False
Set all of the MDE calls to true
-i, --insecure=INSECURE
Default: False
Disable secure authentication handling (file encryption)
```
### 推荐的默认工作流
1. 安装工具 `pip install .`
2. （可选）运行 [setup powershell script](scripts/Create_SP.ps1) 为您的租户设置服务主体
3. 使用输出的 `goosey conf` 命令。或者直接不带参数运行它
4. 使用您的凭据填写 .auth 文件（如果您没有使用 powershell 脚本的输出）
5. 填写配置信息，并将 .conf 文件中所需的调用设置为 `True`。
6. 使用所需参数运行 `goosey auth`。
7. 使用所需参数运行 `goosey honk`。
8. 代替步骤 6-7，使用所需参数运行 `goosey autohonk`
### 针对 UAL 调用的推荐工作流
1. 上面的步骤 1-4
2. 打开 .conf 文件并将 `m365` 部分下的 `ual` 设置为 `True`。
3. 使用所需参数运行 `goosey auth`。
4. 使用所需参数运行 `goosey honk`。
5. 代替步骤 3-4，使用所需参数运行 `goosey autohonk`
### 注意事项
1. 我们建议先运行 [setup powershell script](scripts/Create_SP.ps1) 或填写 .conf
2. 填写 .auth 和/或 .auth_d4iot 现在是可选的。
3. 始终在运行 `goosey honk` 或 `goosey d4iot` 之前运行 `goosey auth`。`goosey autohonk` 将自行执行认证。
### 特殊用例
#### 代理后运行
该工具应能在代理后运行。只要设置了适当的 cli 环境变量
```
https_proxy=
http_proxy=
```
### 已知问题
1. 密码中包含 `%`：
**解决方案：** 确保使用 `%%` 对密码中的 `%` 进行转义。
2. 在 Mac 上尝试 `pip install .` 时出错：
ModuleNotFoundError: No module named 'certifi'
**解决方案：** 转到您的应用程序文件夹，找到您的 python 版本文件夹，然后双击 python 文件夹内的 "Install Certificates.command" 文件以安装证书。
3. 为什么 Untitled Goose Tool 对 Exchange Online 收件箱规则和 Exchange Online 邮箱权限返回两个结果？
**解决方案：** API 和 PowerShell 调用都很健壮且显示不同的信息，因此我们决定保留两者。
4. 运行某些 Azure Security Center 调用后出错：
Azure Compliance Results:
Error: (MissingSubscription) The request did not have a subscription or a valid tenant level resource provider.
Code: MissingSubscription
Message: The request did not have a subscription or a valid tenant level resource provider.
Azure Information Protection Policies:
Error: Operation returned an invalid status 'Not Found'
Azure Assessments:
Discriminator source is absent or null, use base class ResourceDetails.
Azure SubAssessments:
Subtype value GeneralVulnerability has no mapping, use base class AdditionalData.
Subtype value SqlVirtualMachineVulnerability has no mapping, use base class AdditionalData.
**解决方案：** 这些消息不是问题。Azure 合规性结果调用仍将完成。Azure 信息保护策略调用不是严重错误。Azure 评估调用会在控制台中刷屏显示一行警告："Discriminator source is absent or null, use base class ResourceDetails"，并将无问题完成（除了控制台刷屏）。Azure 子评估调用会在控制台中刷屏显示一行警告："Subtype value GeneralVulnerability has no mapping, use base class AdditionalData." 或 "Subtype value SqlVirtualMachineVulnerability has no mapping, use base class AdditionalData." 并将无问题完成（除了控制台刷屏）。
5. 在 `goosey honk` 期间出现大量 429 错误
**解决方案：** Untitled Goose Tool 会很快遇到租户的 Graph API 限制；这是 Microsoft 对 Graph API 调用的限制。
## 致谢
- Claire Casalnova
- Jordan Eberst
- Nicholas Kantor
- Wellington Lee
- Victoria Wallace
## 许可证
本项目属于全球范围内的[公共领域](LICENSE)。
本项目在美国境内属于公共领域，并通过 [CC0 1.0 Universal public domain dedication](https://creativecommons.org/publicdomain/zero/1.0/) 放弃了全球范围内的版权及相关权利。
对本项目的所有贡献都将根据 CC0 奉献发布。通过提交 pull request，您即表示同意遵守此版权利益放弃声明。
## 法律免责声明
通知
本软件包（“软件”或“代码”）由美国政府创建，在美国境内不受版权保护。保留所有其他权利。您可以以任何方式使用、修改或重新分发代码。但是，您不得随后将按原分发的代码申请版权。美国政府不对您所做的更改主张版权，也不会限制您分发对软件的善意更改。如果您决定更新或重新分发代码，请将此通知包含在代码中。在相关情况下，我们要求您使用以下声明注明网络安全和基础设施安全局：“Original code developed by the Cybersecurity and Infrastructure Security Agency (CISA), U.S. Department of Homeland Security.”
使用本软件的风险自负。本软件不提供任何明示或暗示的保证。美国政府不对本软件或其衍生作品的使用或误用承担任何责任。
本软件按“原样”提供。美国政府不会应您的要求安装、删除、操作或支持本软件。如果您不确定本软件将如何与您的系统交互，请勿使用。标签：AI合规, Azure, CISA, D4IoT, Defender for IoT, EDR, Entra ID, Incident Response, MDE, Microsoft 365, Microsoft Defender, Python, SIEM补充, 云端调查, 命令控制, 数字取证, 数据采集, 无后门, 日志导出, 脆弱性评估, 自动化脚本, 请求拦截, 身份安全, 逆向工具