cisagov/untitledgoosetool
Untitled Goose Tool ist ein robustes und flexibles Tool für die Jagd und Incident Response, das neuartige Authentifizierungs- und Datenerfassungsmethoden hinzufügt, um eine vollständige Untersuchung der Azure Active Directory (AzureAD), Azure- und M365-Umgebungen eines Kunden durchzuführen.
Die Gans ist los.
Untitled Goose Tool ist ein robustes und flexibles Tool für Threat Hunting und Incident Response, das neuartige Authentifizierungs- und Datenerfassungsmethoden hinzufügt, um eine vollständige Untersuchung der Microsoft-Entra-ID-, Azure- und M365-Umgebungen eines Kunden durchzuführen. Untitled Goose Tool sammelt zusätzliche Telemetriedaten von Microsoft Defender for Endpoint (MDE) und Defender for Internet of Things (IoT) (D4IoT).
Dieses Tool wurde entwickelt, um Incident-Response-Teams zu unterstützen, indem es nach einem Vorfall Cloud-Artefakte für Umgebungen exportiert, die keine Protokolle in ein Security Information and Events Management (SIEM) oder eine andere langfristige Lösung für Protokolle aufnehmen.
Weitere Anleitungen zur Verwendung von Untitled Goose Tool finden Sie unter: Untitled Goose Tool Fact Sheet
Für die Ausführung von Untitled Goose Tool mit Python ist Python >= 3.9 erforderlich. Python 3.12 wird dringend empfohlen, da es zu einer besseren Protokollierung führt.
Auf einem Windows-Rechner müssen Sie vor der Ausführung des Tools sicherstellen, dass das Microsoft Visual C++ Redistributable-Paket (14.x) installiert ist.
Es wird außerdem empfohlen, Untitled Goose Tool in einer virtuellen Umgebung auszuführen.
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
### Anforderungen
Die folgenden EntraID/M365-Berechtigungen sind erforderlich, um das Untitled Goose Tool auszuführen, und gewähren ihm schreibgeschützten Zugriff auf den Mandanten.
Bitte beachten Sie: Das Benutzerkonto sollte ein Cloud-only-Konto sein (nicht mit der lokalen Umgebung synchronisiert). Dadurch wird sichergestellt, dass der Anmeldeprozess für das Tool in allen Umgebungen gleich bleibt.
Ein Cloud-only-Benutzerkonto und der zugehörige EXO-Dienstprinzipal mit den folgenden Berechtigungen:
Exchange Online Admin Center```
- View-Only Audit Logs
- View-Only Configuration
- View-Only Recipients
- User Options
Ein Dienstprinzipal mit den folgenden Berechtigungen:
API-Berechtigungen``` Log Analytics API
Microsoft Threat Protection:
WindowsDefenderATP:
Microsoft Graph:
Office 365 Exchange Online
IAM-Rollen für Azure-Abonnements```
- Reader
- Storage Blob Data Reader
- Storage Queue Data Reader
Stellen Sie sicher, dass Sie "Allow public client flows" für den Dienstprinzipal aktivieren.
Wir haben ein Setup-PowerShell-Skript, um einen Dienstprinzipal mit den benötigten Berechtigungen einzurichten. Darüber hinaus kann die Zuordnung des Azure-Dienstprinzipals zu m365 derzeit nur über PowerShell erfolgen und wird für einige der m365-Log-Sammlungen benötigt.
Unten finden Sie ein Beispiel für die Ausführung des Skripts, das den Befehl goosey conf ausgibt, den Sie ausführen müssen, um die Konfigurationsdateien mit den richtigen Informationen zu erstellen.```powershell
PS > Write-Host "Creating a new Goose Application and Users"
PS > ./Create_SP.ps1 -AppName GooseApp -Create
Zusätzlich kann das Skript die Anwendung löschen, wenn du sie nicht mehr benötigst.```powershell
PS > Write-Host "Creating a new Goose Application and Users"
PS > ./Create_SP.ps1 -AppName GooseApp -Delete
Zum Installieren das Repository klonen und anschließend eine pip-Installation durchführen:
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 erfordert Authentifizierungsparameter und Konfiguration. Um die Konfigurationsdatei automatisch zu erstellen, führen Sie nach der Installation Folgendes aus.```sh $ goosey conf
Eine Version dieses Befehls wird generiert, wenn das PowerShell-Installationsskript ausgeführt wird, um den Dienstprinzipal zu erstellen/einzurichten. Unten finden Sie ein Beispiel mit Beispiel-Parameterwerten.```sh
$ goosey conf --config_tenant=5fd146ad-8b31-4afa-a72f-6f71df5c7173 --config_subscriptionid=all --auth_appid=24fd6377-79e0-445d-838b-3eaa60d3ca21
Danach sollten die .auth-, .conf-, .auth_d4iot- und .d4iot_conf-Dateien in Ihrem aktuellen Verzeichnis abgelegt werden. Diese Dateien werden von Untitled Goose Tool verwendet. Sofern dies nicht mit den obigen Parametern erzeugt wurde, sollten Sie den oberen Abschnitt [auth] ausfüllen, damit sich Untitled Goose Tool ordnungsgemäß bei den entsprechenden Ressourcen authentifizieren kann. Wenn Sie sich jedoch nicht wohl dabei fühlen, Ihre Zugangsdaten in eine Datei einzugeben, können Sie optional die .auth- und/oder .auth_d4iot-Datei löschen und werden dann stattdessen vom Tool über die Konsole zur Eingabe der Zugangsdaten aufgefordert.
Die minimale Authentifizierung sieht wie folgt aus:``` [auth]
username=
password=
appid=
clientsecret=
Die Minimalkonfiguration sieht wie folgt aus:```
[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
Die minimale D4IoT-Authentifizierung sieht wie folgt aus:``` [auth]
username=
password=
sensor_token=
mgmt_token=
Die D4IoT-Konfiguration sieht wie folgt aus:```
[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
Um bestimmte Pulls zu aktivieren, können Sie Vorkommen von False in True ändern (Groß-/Kleinschreibung wird nicht beachtet).
$ 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
Mit den Standardeinstellungen ausführen. Standardmäßig verschlüsselt es die Zugangsdaten/Token mit einem abgefragten Passwort. Wenn die Felder nicht in der Konfiguration definiert sind, fragt es auch nach diesen:```sh
$ goosey auth
Mit aktiviertem Debug-Modus und unsicherer Authentifizierungsbehandlung ausführen:```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
Mit Standardeinstellungen ausführen:```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
Mit Standardoptionen ausführen:```sh $ goosey honk
Mit aktivierter Debug-Protokollierung ausführen, Ausgabe in das Verzeichnis `my_outputs` und alle Azure-Aufrufe aktivieren:```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)
### Empfohlener Standard-Workflow
1. Installiere das Tool `pip install .`
2. (Optional) Führe das [Setup-PowerShell-Skript](https://github.com/cisagov/untitledgoosetool/blob/develop/scripts/Create_SP.ps1) aus, um den Dienstprinzipal für deinen Mandanten einzurichten.
3. Verwende den ausgegebenen Befehl `goosey conf`. Oder führe ihn einfach ohne Parameter aus.
4. Fülle die .auth-Datei mit deinen Anmeldedaten aus (falls du nicht die Ausgabe des PowerShell-Skripts verwendet hast).
5. Fülle die Konfigurationsinformationen aus und setze die gewünschten Aufrufe in der .conf-Datei auf `True`.
6. Führe `goosey auth` mit den gewünschten Parametern aus.
7. Führe `goosey honk` mit den gewünschten Parametern aus.
8. Statt der Schritte 6-7 führe `goosey autohonk` mit den gewünschten Parametern aus.
### Empfohlener Workflow für UAL-Aufrufe
1. Schritte 1-4 oben
2. Öffne die .conf-Datei und setze `ual` im Abschnitt `m365` auf `True`.
3. Führe `goosey auth` mit den gewünschten Parametern aus.
4. Führe `goosey honk` mit den gewünschten Parametern aus.
5. Statt der Schritte 3-4 führe `goosey autohonk` mit den gewünschten Parametern aus.
### Hinweise
1. Wir empfehlen, zuerst das [Setup-PowerShell-Skript](https://github.com/cisagov/untitledgoosetool/blob/develop/scripts/Create_SP.ps1) auszuführen oder die .conf-Datei auszufüllen.
2. Das Ausfüllen der .auth- und/oder .auth_d4iot-Datei ist jetzt optional.
3. Führe `goosey auth` immer vor `goosey honk` oder `goosey d4iot` aus. `goosey autohonk` führt die Authentifizierung eigenständig durch.
### Besondere Anwendungsfälle
#### Hinter einem Proxy
Das Tool sollte hinter einem Proxy funktionieren, solange die entsprechenden Umgebungsvariablen für die cli gesetzt sind.```
https_proxy=<proxy_url>
http_proxy=<proxy_url>
Wenn das Passwort ein % enthält:
Lösung: Stellen Sie sicher, dass Sie % im Passwort mit %% escapen.
Fehler beim Versuch, pip install . auszuführen, wenn Sie auf einem Mac sind:
ModuleNotFoundError: No module named 'certifi'
Lösung: Gehen Sie zu Ihrem Programme-Ordner, suchen Sie den Ordner Ihrer Python-Version und doppelklicken Sie auf die Datei „Install Certificates.command“ im Python-Ordner, um das Zertifikat zu installieren.
Warum liefert das Untitled Goose Tool zwei Ergebnisse für Exchange Online-Posteingangsregeln und Exchange Online-Postfachberechtigungen?
Lösung: Sowohl die API- als auch die PowerShell-Aufrufe sind robust und zeigen unterschiedliche Informationen, daher haben wir beschlossen, beide beizubehalten.
Fehler nach dem Ausführen bestimmter Azure Security Center-Aufrufe:
Azure-Compliance-Ergebnisse:
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-Schutzrichtlinien:
Error: Operation returned an invalid status 'Not Found'
Azure-Bewertungen:
Discriminator source is absent or null, use base class ResourceDetails.
Azure-Unterbewertungen:
Subtype value GeneralVulnerability has no mapping, use base class AdditionalData.
Subtype value SqlVirtualMachineVulnerability has no mapping, use base class AdditionalData.
Lösung: Diese Meldungen sind keine Probleme. Der Aufruf der Azure-Compliance-Ergebnisse wird trotzdem abgeschlossen. Der Aufruf der Azure-Information-Schutzrichtlinien ist kein kritischer Fehler. Der Aufruf der Azure-Bewertungen spammt die Konsole mit einer einzeiligen Warnung: "Discriminator source is absent or null, use base class ResourceDetails" und wird ohne Probleme abgeschlossen (abgesehen vom Konsolen-Spam). Der Aufruf der Azure-Unterbewertungen spammt die Konsole mit einer einzeiligen Warnung: "Subtype value GeneralVulnerability has no mapping, use base class AdditionalData." oder "Subtype value SqlVirtualMachineVulnerability has no mapping, use base class AdditionalData." und wird ohne Probleme abgeschlossen (abgesehen vom Konsolen-Spam).
Übermäßige Anzahl von 429-Fehlern während goosey honk
Lösung: Das Untitled Goose Tool wird schnell auf die Graph-API-Limits eines Mandanten stoßen; dies ist eine Einschränkung, die Microsoft bei Graph-API-Aufrufen hat.
Wir freuen uns über Beiträge! Weitere Details finden Sie hier.
Dieses Projekt ist weltweit gemeinfrei.
Dieses Projekt ist in den Vereinigten Staaten gemeinfrei, und Urheberrechte und verwandte Schutzrechte an dem Werk weltweit werden durch die CC0 1.0 Universal Public Domain Dedication aufgehoben.
Alle Beiträge zu diesem Projekt werden unter der CC0-Dedication veröffentlicht. Mit dem Einreichen eines Pull Requests erklären Sie sich damit einverstanden, diesen Verzicht auf Urheberrechtsinteressen einzuhalten.
HINWEIS
Dieses Softwarepaket („Software“ oder „Code“) wurde von der Regierung der Vereinigten Staaten erstellt und unterliegt in den Vereinigten Staaten keinem Urheberrecht. Alle anderen Rechte sind vorbehalten. Sie dürfen den Code in beliebiger Weise verwenden, modifizieren oder weiterverbreiten. Sie dürfen den Code jedoch nicht im Nachhinein urheberrechtlich schützen, so wie er verteilt wird. Die Regierung der Vereinigten Staaten erhebt keinen Anspruch auf Urheberrecht an den von Ihnen vorgenommenen Änderungen und schränkt auch Ihre Weitergabe von rechtmäßigen Änderungen an der Software nicht ein. Wenn Sie die Software aktualisieren oder weiterverbreiten möchten, nehmen Sie bitte diesen Hinweis in den Code auf. Wo relevant, bitten wir Sie, die Cybersecurity and Infrastructure Security Agency mit folgendem Hinweis zu nennen: „Original code developed by the Cybersecurity and Infrastructure Security Agency (CISA), U.S. Department of Homeland Security.“
VERWENDEN SIE DIESE SOFTWARE AUF EIGENES RISIKO. DIESE SOFTWARE WIRD OHNE JEGLICHE GEWÄHRLEISTUNG BEREITGESTELLT, WEDER AUSDRÜCKLICH NOCH STILLSCHWEIGEND. DIE REGIERUNG DER VEREINIGTEN STAATEN ÜBERNIMMT KEINE HAFTUNG FÜR DIE VERWENDUNG ODER DEN MISSBRAUCH DIESER SOFTWARE ODER IHRER ABKÖMMLINGE.
DIESE SOFTWARE WIRD „WIE BESEHEN“ ANGEBOTEN. DIE REGIERUNG DER VEREINIGTEN STAATEN WIRD DIESE SOFTWARE AUF IHRE ANFORDERUNG HIN NICHT INSTALLIEREN, ENTFERNEN, BETREIBEN ODER WARTEN. WENN SIE SICH NICHT SICHER SIND, WIE DIESE SOFTWARE MIT IHREM SYSTEM INTERAGIERT, VERWENDEN SIE SIE NICHT.