Untitled Goose Tool

鹅已出笼。

关于

Untitled Goose Tool 是一款强大且灵活的狩猎与事件响应工具，它引入了新颖的身份验证和数据收集方法，以便针对客户的 Microsoft Entra ID、Azure 和 M365 环境进行全面调查。Untitled Goose Tool 还会从 Microsoft Defender for Endpoint (MDE) 和 Defender for Internet of Things (IoT) (D4IoT) 收集额外的遥测数据。

该工具旨在通过导出事件发生后的云工件，帮助事件响应团队处理那些未将日志摄取到安全信息和事件管理 (SIEM) 或其他长期日志解决方案的环境。

有关如何使用 Untitled Goose Tool 的更多指导，请参阅：Untitled Goose Tool 概况介绍

入门

先决条件

运行 Untitled Goose Tool 需要 Python >= 3.9。强烈建议使用 Python 3.12，因为它能提供更好的日志记录。

在 Windows 机器上，你需要确保在运行该工具之前已安装 Microsoft Visual C++ 可再发行组件包 (14.x)。

还建议在虚拟环境中运行 Untitled Goose Tool。

Mac OSX```sh

pip3 install virtualenv virtualenv -p python3 .venv source .venv/bin/activate

#### Linux```sh
# You may need to run sudo apt-get install python3-venv first
python3 -m venv .venv
source .venv/bin/activate

Windows```console

You can also use 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 权限``` 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 订阅 IAM 角色```
- Reader
- Storage Blob Data Reader
- Storage Queue Data Reader

请务必为服务主体启用“允许公共客户端流”。

我们提供了一个 setup powershell script 来创建具有所需权限的服务主体。此外，目前将 Azure 服务主体与 m365 的关联只能通过 PowerShell 完成，而某些 m365 日志收集需要此关联。

下面是一个运行该脚本的示例，脚本会输出你需要运行的 goosey conf 命令，以便使用正确信息构建配置文件。```powershell PS > Write-Host "Creating a new Goose Application and Users" PS > ./Create_SP.ps1 -AppName GooseApp -Create

此外，脚本还可以在您使用完该应用程序后将其删除。```powershell
PS > Write-Host "Creating a new Goose Application and Users"
PS > ./Create_SP.ps1 -AppName GooseApp -Delete

安装

要安装，请克隆仓库，然后执行 pip install：

常规安装```sh

git clone https://github.com/cisagov/untitledgoosetool.git cd untitledgoosetool python3 -m pip install .

#### Docker```sh
docker build . -t goosey
docker run -it -v $PWD:/workdir goosey goosey honk --debug

用法

配置

Untitled Goose Tool 需要认证参数和配置。要自动生成配置文件，请在安装后运行以下命令。```sh $ goosey conf

当运行 PowerShell 安装脚本以创建/设置服务主体时，将生成此命令的一个版本。下面是一个带有代替参数值的示例。```sh
$ 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]

The username of your account. ex: [email protected]

username=

The password of your account. ex: AAD_password

password=

The application ID of your service principal

appid=

The client secret value of your service principal (not the secret ID)

clientsecret=

极简配置如下：```
[config]
# The tenant ID of your AAD tenant
tenant=
# If you have a GCC High tenant
us_government=False
# If you have a GCC tenant with MDE
mde_gcc=False
# If you have a GCC High tenant with MDE
mde_gcc_high=False
# If your M365 tenant is a government tenant
exo_us_government=False
# If you want to check all of your Azure subscriptions, set this to All, otherwise enter your Azure subscription ID. For multiple IDs, separate it with commas, no spaces
subscriptionid=All

[filters]
# Format should be YYYY-MM-DD. If not set will default to the earliest date for log retention
date_start=
# Format should be YYYY-MM-DD. Will default to the present day
date_end=

[variables]
# Threshold used for ual API requests. Specifies the maximum results pulled per session. Can be between 100 - 50000. The api is optimized to return results faster the larger the threshold, but the whole session has to be repeated if an error occurs as the results are not returned sorted. We recommend 5000 as the threshold, but this can be toggled with
ual_threshold=5000
# Maximum number of ual coroutines/tasks to have running asynchronously. Minimum value is 1.
max_ual_tasks=5
# Start date for an extra time frame for ual to search. Reason for this is because ual takes the longest to pull and while you don't want the oldest data to roll off, you may want to look at another timeframe and do not want to wait for ual to get there and pull the logs. Format should be YYY-MM-DD
ual_extra_start=
# End date for an extra time frame for ual to search. Reason for this is because ual takes the longest to pull and while you don't want the oldest data to roll off, you may want to look at another timeframe and do not want to wait for ual to get there and pull the logs. Format should be YYY-MM-DD
ual_extra_end=
# Threshold for how many logs to pull per query. Usually want to try to max this out as KQL queries are rate limited.
mde_threshold=10000
# can be either 'table' or 'machine'. 'table' will pull directly from the mde tables without filtering. While 'machine' will filter by 'machine' with large tenants 'machine' will likely be prefered as time bounding on the entire table will likely cause issues.
mde_query_mode=table

[azure]
# Dumps activity log from azure
activity_log=False
# Returns all azure subscriptions
all_azure_subscriptions=False
# Dump insights bastion audit logs
bastion_logs=False
# Dump Azure configuration information
configs=False
# Dump D4IOT portal configs
d4iot_portal_configs=False
# Dump D4IOT portal pcaps from alerts
d4iot_portal_pcap=False
# Dump insights audit events for key_vault
key_vault_log=False
# Dump insights network security group flow events
nsg_flow_logs=False

[entraid]
# Dumps Entra ID Audit logs
entraid_audit=False
# Dumps Entra ID provisioning logs
entraid_provisioning=False
# Dumps Entra ID configuration files
configs=False
# Dumps risk detections from identity protection. Requires a minimum of Microsoft Entra ID P1 license and Microsoft Entra Workload ID premium license for full results.
risk_detections=False
# Dumps risky users and service principal information. Requires a minimum of Microsoft Entra ID P2 license and Microsoft Entra Workload ID premium license for full results.
risky_objects=False
# Dump security actions, alerts, and scores
security=False
# Dump interactive (adfs) sign in logs
signins_adfs=False
# Dump managed identity (msi) sign in logs
signins_msi=False
# Dump non-interactive (rt) sign in logs
signins_rt=False
# Dump service principal (sp) signin logs
signins_sp=False

[m365]
# Get Exchange discovery information
ediscovery_info=False
# Get all of the applications installed for the organization
exo_addins=False
# Get EXO config information
exo_config_info=False
# Dumps Exchange Online Role Group and Role Group Members information.
exo_groups=False
# Get all the messageRule objects defined for all users' inboxes
exo_inboxrules=False
# Dumps Exchange Online Mailbox Information
exo_mailbox=False
# Get information on m365 mobile devices
exo_mobile_devices=False
# Dumps UAL for last year using Search-UnifiedAuditLog api. Previous ual api is currently deprecated.
ual=False

[mde]
# Dumps the results from incidents and alerts.
advanced_hunting_alerts_incidents=False
# Dumps the results from advanced hunting queries.
advanced_hunting_query=False
# Dumps the results from advanced hunting API queries.
advanced_identity_hunting_query=False
# Dump alerts
alerts=False
# Dump indicators
indicators=False
# Dump investigations
investigations=False
# Dump library files
library_files=False
# Dump known machine vulnerabilities
machine_vulns=False
# Dump machines with mde
machines=False
# Dump mde recommendations
recommendations=False
# Dump known installed software
software=False

D4IoT 的极简认证如下：``` [auth]

username=

password=

Enter your D4IoT sensor API token

sensor_token=

Enter your D4IoT management console API token

mgmt_token=

D4IoT 的配置如下：```
[config]
# Enter your D4IoT sensor IP
d4iot_sensor_ip=
# Enter your D4IoT management console IP
d4iot_mgmt_ip=

[d4iot]
# Dump management alerts
mgmt_alerts=False
# Dump management devices
mgmt_devices=False
# Dump management sensor pcap captured
mgmt_pcap=False
# Dump management sensor information
mgmt_sensor_info=False
# Dump sensor alerts
sensor_alerts=False
# Collect all device connections
sensor_device_connections=False
# Dummp sensor device known cves
sensor_device_cves=False
# Dump sensor device known vulnerabilities
sensor_device_vuln=False
# Dump sensor devices
sensor_devices=False
# Dump sensor events
sensor_events=False
# Dump sensor operation vulnerabilities
sensor_operational_vuln=False
# Dump sensor pcap
sensor_pcap=False
# Dump sensor security vulnerabilities
sensor_security_vuln=False

要启用特定的拉取功能，你可以将 False 改为 True（不区分大小写）。

认证```sh

$ 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

使用默认设置运行。默认情况下，它会通过提示输入的密码对凭据/令牌进行加密。如果配置中未定义这些字段，它也会提示输入这些字段：```sh
$ goosey auth

启用调试和不安全的身份验证处理来运行：```sh $ goosey auth --debug --insecure

### Csv```sh
$ goosey csv --help
NAME
    goosey csv - Create csv files mapping GUIDs to text

SYNOPSIS
    goosey csv <flags>

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

使用默认设置运行：```sh $ goosey csv

### Honk```sh
$ goosey honk --help
NAME
    goosey honk - Untitled Goose Tool Information Gathering

SYNOPSIS
    goosey honk <flags>

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

使用默认选项运行：```sh $ goosey honk

使用启用了调试日志记录的配置运行，输出到目录 `my_outputs`，并启用所有 Azure 调用：```sh
$ goosey honk --debug --output-dir my_outputs --azure

Autohonk```sh

$ 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 脚本](https://github.com/cisagov/untitledgoosetool/blob/HEAD/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 脚本](https://github.com/cisagov/untitledgoosetool/blob/HEAD/scripts/Create_SP.ps1) 或先填写 .conf 文件
2. 现在填写 .auth 和/或 .auth_d4iot 是可选的。
3. 在运行 `goosey honk` 或 `goosey d4iot` 之前，始终先运行 `goosey auth`。`goosey autohonk` 会自行执行身份验证。

### 特殊用例

#### 在代理后面

该工具应能在代理后面正常工作。只要为 cli 设置了相应的环境变量```
https_proxy=<proxy_url>
http_proxy=<proxy_url>

已知问题

密码中包含 %：

解决方案： 请确保使用 %% 转义密码中的 %。
在 Mac 上尝试 pip install . 时出错：
```
ModuleNotFoundError: No module named 'certifi'
```
解决方案： 前往你的应用程序文件夹，找到对应 Python 版本的文件夹，然后双击 python 文件夹中的 “Install Certificates.command” 文件以安装证书。
为什么 Untitled Goose Tool 对 Exchange Online 收件箱规则和 Exchange Online 邮箱权限会返回两个结果？

解决方案： API 调用和 PowerShell 调用都很可靠且展示的信息不同，因此我们决定同时保留两者。

运行某些 Azure Security Center 调用后出现错误：

Azure 合规性结果：

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 信息保护策略：

Error: Operation returned an invalid status 'Not Found'

Azure 评估：

Discriminator source is absent or null, use base class ResourceDetails.

Azure 子评估：

致谢

Claire Casalnova
Jordan Eberst
Nicholas Kantor
Wellington Lee
Victoria Wallace

贡献

我们欢迎贡献！请参阅此处了解详情。

许可证

本项目位于全球公共领域。

本项目在美国属于公共领域，并透过 CC0 1.0 通用公共领域贡献放弃全球范围内的版权及相关权利。

对本项目的所有贡献都将依据 CC0 贡献声明发布。提交拉取请求即表示你同意遵守此版权利益豁免。

法律免责声明

声明

本软件包（“software”或“code”）由美国政府创建，在美国境内不受版权保护。保留所有其他权利。你可以以任何方式使用、修改或重新分发该代码。但是，你不得随后对分发中的代码主张版权。美国政府对你所做的更改不主张版权，也不会限制你分发对软件的善意更改。如果你决定更新或重新分发该代码，请随代码附上本声明。在相关情况下，我们要求你按以下声明注明网络安全与基础设施安全局：“原始代码由美国国土安全部网络安全与基础设施安全局 (CISA) 开发。”

使用本软件风险自负。本软件不提供任何明示或暗示的担保。美国政府不对本软件或其衍生品的使用或误用承担任何责任。

本软件按“现状”提供。美国政府不会应你的要求安装、移除、操作或支持本软件。如果你不确定本软件将如何与你的系统交互，请不要使用它。

untitledgoosetool

最受欢迎