cisagov/untitledgoosetoolUntitled Goose Toolは、堅牢で柔軟なハントおよびインシデント対応ツールであり、顧客のAzure Active Directory (AzureAD)、Azure、およびM365環境に対して完全な調査を実行するために、新しい認証方法とデータ収集方法を追加します。
ガチョウは解き放たれた。
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 Fact Sheet を参照してください。
Untitled Goose Tool を Python で実行するには、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
#### Linux```sh
# You may need to run sudo apt-get install python3-venv first
python3 -m venv .venv
source .venv/bin/activate
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
Microsoft Threat Protection:
WindowsDefenderATP:
Microsoft Graph:
Office 365 Exchange Online
Azure サブスクリプション IAM ロール```
- Reader
- Storage Blob Data Reader
- Storage Queue Data Reader
サービスプリンシパルでは、必ず「Allow public client flows」を有効にしてください。
必要なアクセス許可を持つサービスプリンシパルを設定するためのセットアップPowerShellスクリプトがあります。さらに、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 を実行します:
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 によって使用されます。これが上記のパラメータで生成されていない場合は、Untitled Goose Tool が適切なリソースに正しく認証できるように、先頭のセクション [auth] を記入する必要があります。ただし、資格情報をファイルに入力することに抵抗がある場合は、.auth および/または .auth_d4iot を削除して、ツールがコンソール経由で資格情報の入力を求めるようにすることもできます。
最小限の auth の例は次のとおりです:``` [auth]
username=
password=
appid=
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=
sensor_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 に変更できます（大文字と小文字は区別されません）。
$ 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
デフォルトで実行します。デフォルトでは、プロンプトで入力されたパスワードを使用して資格情報/トークンを暗号化します。config にフィールドが定義されていない場合は、それらもプロンプトで要求されます:```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
$ 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. (任意) [セットアップ PowerShell スクリプト](https://github.com/cisagov/untitledgoosetool/blob/develop/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. 最初に [セットアップ PowerShell スクリプト](https://github.com/cisagov/untitledgoosetool/blob/develop/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 バージョンのフォルダを見つけて、その中の「Install Certificates.command」ファイルをダブルクリックして証明書をインストールしてください。
Untitled Goose Tool が Exchange Online の受信トレイルールと Exchange Online のメールボックス権限について 2 つの結果を返すのはなぜですか？
解決策: 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 Information Protection ポリシー:
Error: Operation returned an invalid status 'Not Found'
Azure アセスメント:
Discriminator source is absent or null, use base class ResourceDetails.
コントリビューションを歓迎します！ 詳細はこちらをご覧ください。
このプロジェクトは、全世界でパブリックドメインにあります。
このプロジェクトは米国内でパブリックドメインにあり、この作品に関する著作権および関連する権利は、CC0 1.0 ユニバーサル パブリックドメイン 奉献 により全世界で放棄されています。
このプロジェクトへのすべてのコントリビューションは、CC0 の奉献に基づいてリリースされます。プルリクエストを送信することにより、この著作権放棄に同意したものとみなされます。
通知
このソフトウェアパッケージ (「ソフトウェア」または「コード」) は、アメリカ合衆国政府によって作成されたものであり、米国内では著作権の対象ではありません。その他すべての権利は留保されます。このコードは、いかなる方法でも使用、変更、再配布することができます。ただし、配布されているコードに後から著作権を主張することはできません。アメリカ合衆国政府は、あなたが行った変更に対する著作権を主張しません。また、ソフトウェアに対する正当な変更の配布を制限することもありません。コードを更新または再配布する場合は、この通知をコードに含めてください。関連する場合には、次の文言で Cybersecurity and Infrastructure Security Agency へのクレジットを記載してください。「Original code developed by the Cybersecurity and Infrastructure Security Agency (CISA), U.S. Department of Homeland Security.」
このソフトウェアは自己責任で使用してください。このソフトウェアには、明示的または黙示的な保証は一切ありません。アメリカ合衆国政府は、このソフトウェアまたはその派生物の使用または誤用について一切の責任を負いません。
このソフトウェアは「現状のまま (AS-IS)」で提供されます。アメリカ合衆国政府は、お客様の要求に応じてこのソフトウェアのインストール、削除、操作、サポートは行いません。このソフトウェアがお使いのシステムとどのように相互作用するか不明な場合は、使用しないでください。
Azure サブアセスメント:
Subtype value GeneralVulnerability has no mapping, use base class AdditionalData.
Subtype value SqlVirtualMachineVulnerability has no mapping, use base class AdditionalData.
解決策: これらのメッセージは問題ではありません。Azure コンプライアンス結果の呼び出しは引き続き完了します。Azure Information Protection ポリシーの呼び出しは重大なエラーではありません。Azure アセスメントの呼び出しは、コンソールに「Discriminator source is absent or null, use base class ResourceDetails」という 1 行の警告を表示しますが、問題なく完了します (コンソールのスパム出力以外は)。Azure サブアセスメントの呼び出しは、コンソールに「Subtype value GeneralVulnerability has no mapping, use base class AdditionalData.」または「Subtype value SqlVirtualMachineVulnerability has no mapping, use base class AdditionalData.」という 1 行の警告を表示しますが、問題なく完了します (コンソールのスパム出力以外は)。
goosey honk 実行中に 429 エラーが多発する場合
解決策: Untitled Goose Tool は、テナントの Graph API 制限にすぐに達します。これは Microsoft が Graph API 呼び出しに設けている制限です。