cisagov/untitledgoosetoolUntitled Goose Toolは、堅牢で柔軟なハントおよびインシデント対応ツールであり、顧客のAzure Active Directory (AzureAD)、Azure、およびM365環境に対して完全な調査を実行するために、新しい認証方法とデータ収集方法を追加します。
The Goose is loose.
Untitled Goose Tool は、堅牢かつ柔軟なハントおよびインシデント対応ツールであり、顧客の Microsoft Entra ID、Azure、および M365 環境に対して完全な調査を実行するために、新しい認証方法とデータ収集方法を追加しています。Untitled Goose Tool は、Microsoft Defender for Endpoint (MDE) および Defender for Internet of Things (IoT) (D4IoT) から追加のテレメトリを収集します。
このツールは、インシデント後にクラウドアーティファクトをエクスポートすることで、ログを Security Information and Events Management (SIEM) やその他の長期的なログソリューションに取り込んでいない環境において、インシデント対応チームを支援するために設計されました。
Untitled Goose Tool の使用方法に関する詳細なガイダンスについては、以下を参照してください: Untitled Goose Tool Fact Sheet
Python で Untitled Goose Tool を実行するには、Python >= 3.9 が必要です。より良いログ記録が得られるため、Python 3.12 を強く推奨します。
Windows マシンでは、ツールを実行する前に Microsoft Visual C++ 再頒布可能パッケージ (14.x) がインストールされていることを確認する必要があります。
また、Untitled Goose Tool を仮想環境内で実行することも推奨します。
pip3 install virtualenv
virtualenv -p python3 .venv
source .venv/bin/activate
# You may need to run sudo apt-get install python3-venv first
python3 -m venv .venv
source .venv/bin/activate
# You can also use py -3 -m venv .venv
python -m venv .venv
.venv\Scripts\activate
Untitled Goose Tool を実行し、テナントへの読み取り専用アクセスを提供するには、以下の EntraID/M365 権限が必要です。
注意: ユーザーアカウントはクラウド専用アカウント（オンプレミス環境に同期されていないもの）である必要があります。これにより、ツールのログインプロセスが環境間で同一に保たれます。
クラウド専用ユーザーアカウントおよび関連する EXO サービスプリンシパルで、以下の権限が必要です:
Exchange Online 管理センター
- 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
サービスプリンシパルに対して「Allow public client flows」を有効にしてください。
必要な権限を持つサービスプリンシパルをセットアップするためのセットアップ用 PowerShell スクリプトを用意しています。さらに、Azure サービスプリンシパルと 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 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 によって使用されます。上記のパラメータで生成されたものでない限り、Untitled Goose Tool が適切なリソースに対して正しく認証できるように、先頭の [auth] セクションを記入する必要があります。ただし、認証情報をファイルに入力することに抵抗がある場合は、.auth や .auth_d4iot を削除して、代わりにコンソール経由でツールから認証情報の入力を求められるようにすることもできます。
最小限の認証設定は次のようになります:
[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
### Unified Audit Log Filters
You can fine-tune which Unified Audit Log (UAL) records are saved by setting UAL filter variables in the `[variables]` section of your `.conf` file. Use the `ual_`-prefixed variables below:
Note: The Operation, UserId, and ClientIP filters cannot be run together. You must start a separate UAL pull for each filter, and you may need to clear the bounds and state files when running duplicate timeframes.