cisagov/untitledgoosetoolUntitled Goose Tool is a robust and flexible hunt and incident response tool that adds novel authentication and data gathering methods in order to run a full investigation against a customer’s Azure Active Directory (AzureAD), Azure, and M365 environments.
L'oca è in libertà.
Untitled Goose Tool è uno strumento di threat hunting e incident response robusto e flessibile che aggiunge nuovi metodi di autenticazione e raccolta dati per eseguire un'indagine completa sugli ambienti Microsoft Entra ID, Azure e M365 di un cliente. Untitled Goose Tool raccoglie telemetria aggiuntiva da Microsoft Defender for Endpoint (MDE) e Defender for Internet of Things (IoT) (D4IoT).
Questo strumento è stato progettato per assistere i team di risposta agli incidenti esportando gli artefatti cloud dopo un incidente per ambienti che non stanno acquisendo i log in un SIEM (Security Information and Events Management) o in un'altra soluzione di conservazione a lungo termine per i log.
Per ulteriori indicazioni su come utilizzare Untitled Goose Tool, consultare: Untitled Goose Tool Fact Sheet
Per eseguire Untitled Goose Tool con Python è richiesto Python >= 3.9. Python 3.12 è fortemente consigliato in quanto garantisce un logging migliore.
Su una macchina Windows, dovrai assicurarti di avere installato il pacchetto ridistribuibile Microsoft Visual C++ (14.x) prima di eseguire lo strumento.
È inoltre consigliato eseguire Untitled Goose Tool all'interno di un ambiente virtuale.
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
### Requisiti
Per eseguire Untitled Goose Tool sono necessarie le seguenti autorizzazioni EntraID/M365, che forniscono accesso in sola lettura al tenant.
Nota: l'account utente deve essere un account cloud-only (non sincronizzato con l'ambiente on-premise); questo garantirà che il processo di accesso rimanga lo stesso tra gli ambienti per lo strumento.
Un account utente cloud-only e il relativo service principal EXO con le seguenti autorizzazioni:
Exchange Online Admin Center```
- View-Only Audit Logs
- View-Only Configuration
- View-Only Recipients
- User Options
Un'entità servizio (service principal) con le seguenti autorizzazioni:
Autorizzazioni API``` Log Analytics API
Microsoft Threat Protection:
WindowsDefenderATP:
Microsoft Graph:
Office 365 Exchange Online
Ruoli IAM della sottoscrizione Azure```
- Reader
- Storage Blob Data Reader
- Storage Queue Data Reader
Make sure to enable "Allow public client flows" for the service principal.
We have a setup powershell script to setup a service principal with the needed permissions. Additionally the association of the Azure Service Principal with m365 can only be done via powershell currently and is needed for some of the m365 log collection.
Below is an example of running the script which will output the goosey conf command you need to run to build the config files with the proper information```powershell
PS > Write-Host "Creating a new Goose Application and Users"
PS > ./Create_SP.ps1 -AppName GooseApp -Create
Inoltre, lo script può eliminare l'Applicazione quando hai finito di usarla.```powershell
PS > Write-Host "Creating a new Goose Application and Users"
PS > ./Create_SP.ps1 -AppName GooseApp -Delete
Per installare, clona il repository e poi esegui un 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 richiede parametri di autenticazione e configurazione. Per creare automaticamente il file di configurazione, esegui quanto segue dopo l'installazione.```sh $ goosey conf
Una versione di questo comando verrà generata quando lo script di installazione PowerShell viene eseguito per creare/configurare il service principal. Di seguito è riportato un esempio con valori dei parametri fittizi.```sh
$ goosey conf --config_tenant=5fd146ad-8b31-4afa-a72f-6f71df5c7173 --config_subscriptionid=all --auth_appid=24fd6377-79e0-445d-838b-3eaa60d3ca21
Dopo questo, i file .auth, .conf, .auth_d4iot e .d4iot_conf dovrebbero essere collocati nella tua directory corrente. Questi file sono utilizzati da Untitled Goose Tool. A meno che non siano stati generati con i parametri sopra indicati, dovresti compilare la sezione superiore [auth] affinché Untitled Goose Tool possa autenticarsi correttamente alle risorse appropriate. Tuttavia, se non ti senti a tuo agio nell'inserire le tue credenziali in un file, puoi scegliere di eliminare .auth e/o .auth_d4iot e il tool ti chiederà le credenziali tramite console.
L'autenticazione minimale essenziale è simile a:``` [auth]
username=
password=
appid=
clientsecret=
La configurazione minimale è la seguente:```
[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
L'autenticazione D4IoT minimale appare così:``` [auth]
username=
password=
sensor_token=
mgmt_token=
La configurazione di D4IoT appare così:```
[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
Per abilitare pull specifici, puoi cambiare le occorrenze di False in True (senza distinzione tra maiuscole e minuscole).
$ 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
Esegui con le impostazioni predefinite. Per impostazione predefinita, crittografa le credenziali/i token con una password richiesta. Se i campi non sono definiti nella configurazione, verranno richiesti anche quelli:```sh
$ goosey auth
Esegui con debug e gestione non sicura dell'autenticazione abilitati:```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
Esegui con le impostazioni predefinite:```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
Esegui con le opzioni predefinite:```sh $ goosey honk
Esegui con il logging di debug abilitato, output nella directory `my_outputs`, e abilita tutte le chiamate 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)
### Flusso di lavoro predefinito consigliato
1. Installa lo strumento `pip install .`
2. (Facoltativo) Esegui lo [script PowerShell di configurazione](https://github.com/cisagov/untitledgoosetool/blob/HEAD/scripts/Create_SP.ps1) per configurare il service principal per il tuo tenant
3. Usa il comando `goosey conf` generato. Oppure eseguilo semplicemente senza parametri
4. Compila il file .auth con le tue credenziali (se non hai usato l'output dello script PowerShell)
5. Compila le informazioni di configurazione e imposta le chiamate desiderate a `True` nel file .conf.
6. Esegui `goosey auth` con i parametri desiderati.
7. Esegui `goosey honk` con i parametri desiderati.
8. In alternativa ai passaggi 6-7, esegui `goosey autohonk` con i parametri desiderati
### Flusso di lavoro consigliato per la chiamata UAL
1. Passaggi 1-4 precedenti
2. Apri il file .conf e imposta `ual` nella sezione `m365` su `True`.
3. Esegui `goosey auth` con i parametri desiderati.
4. Esegui `goosey honk` con i parametri desiderati.
5. In alternativa ai passaggi 3-4, esegui `goosey autohonk` con i parametri desiderati
### Considerazioni
1. Consigliamo di eseguire lo [script PowerShell di configurazione](https://github.com/cisagov/untitledgoosetool/blob/HEAD/scripts/Create_SP.ps1) o di compilare prima il file .conf
2. La compilazione di .auth e/o .auth_d4iot è ora facoltativa.
3. Esegui sempre `goosey auth` prima di eseguire `goosey honk` o `goosey d4iot`. `goosey autohonk` esegue l'autenticazione da solo.
### Casi d'uso speciali
#### Dietro un proxy
Lo strumento dovrebbe funzionare dietro un proxy. Purché siano impostate le appropriate variabili d'ambiente per la cli.```
https_proxy=<proxy_url>
http_proxy=<proxy_url>
Avere % nella password:
Soluzione: Assicurati di eseguire l'escape di % nella password con %%.
Errore durante il tentativo di pip install . su Mac:
ModuleNotFoundError: No module named 'certifi'
Soluzione: Vai nella cartella Applicazioni, trova la cartella della tua versione di Python e fai doppio clic sul file "Install Certificates.command" all'interno della cartella di Python per installare il certificato.
Perché Untitled Goose Tool restituisce due risultati per le regole della cassetta postale di Exchange Online e per le autorizzazioni delle cassette postali di Exchange Online?
Soluzione: Sia le chiamate API che quelle PowerShell sono robuste e mostrano informazioni diverse, quindi abbiamo deciso di mantenerle entrambe.
Errore dopo l'esecuzione di alcune chiamate ad Azure Security Center:
Risultati di conformità di 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.
Criteri di protezione delle informazioni di Azure:
Error: Operation returned an invalid status 'Not Found'
Accogliamo con piacere i contributi! Consulta qui per i dettagli.
Questo progetto è nel pubblico dominio mondiale.
Questo progetto è nel pubblico dominio negli Stati Uniti e i diritti d'autore e i diritti correlati nel lavoro in tutto il mondo sono rinunciati tramite la dedica CC0 1.0 Universal al pubblico dominio.
Tutti i contributi a questo progetto saranno rilasciati sotto la dedica CC0. Inviando una pull request, accetti di rispettare questa rinuncia agli interessi di copyright.
AVVISO
Questo pacchetto software ("software" o "codice") è stato creato dal Governo degli Stati Uniti e non è soggetto a copyright negli Stati Uniti. Tutti gli altri diritti sono riservati. Puoi usare, modificare o ridistribuire il codice in qualsiasi modo. Tuttavia, non puoi successivamente detenere il copyright sul codice così come distribuito. Il Governo degli Stati Uniti non rivendica alcun copyright sulle modifiche che apporti, né limiterà la distribuzione di modifiche legittime al software. Se decidi di aggiornare o ridistribuire il codice, includi questo avviso con il codice. Ove pertinente, ti chiediamo di attribuire il merito alla Cybersecurity and Infrastructure Security Agency con la seguente dichiarazione: "Codice originale sviluppato dalla Cybersecurity and Infrastructure Security Agency (CISA), Dipartimento della Sicurezza Interna degli Stati Uniti."
USA QUESTO SOFTWARE A TUO RISCHIO. QUESTO SOFTWARE NON HA ALCUNA GARANZIA, ESPRESSA O IMPLICITA. IL GOVERNO DEGLI STATI UNITI NON SI ASSUME ALCUNA RESPONSABILITÀ PER L'USO O L'USO IMPROPRIO DI QUESTO SOFTWARE O DEI SUOI DERIVATI.
QUESTO SOFTWARE È OFFERTO "COSÌ COM'È". IL GOVERNO DEGLI STATI UNITI NON INSTALLERÀ, RIMUOVERÀ, GESTIRÀ O SUPPORTERÀ QUESTO SOFTWARE SU TUA RICHIESTA. SE NON SEI SICURO DI COME QUESTO SOFTWARE INTERAGIRÀ CON IL TUO SISTEMA, NON USARLO.
Valutazioni di Azure:
Discriminator source is absent or null, use base class ResourceDetails.
Sub-valutazioni di Azure:
Subtype value GeneralVulnerability has no mapping, use base class AdditionalData.
Subtype value SqlVirtualMachineVulnerability has no mapping, use base class AdditionalData.
Soluzione: Questi messaggi non sono problemi. La chiamata per i risultati di conformità di Azure verrà comunque completata. La chiamata per i criteri di protezione delle informazioni di Azure non è un errore critico. La chiamata per le valutazioni di Azure riempie la console con un avviso di una riga: "Discriminator source is absent or null, use base class ResourceDetails" e verrà completata senza problemi (a parte lo spam nella console). La chiamata per le sub-valutazioni di Azure riempie la console con un avviso di una riga: "Subtype value GeneralVulnerability has no mapping, use base class AdditionalData." o "Subtype value SqlVirtualMachineVulnerability has no mapping, use base class AdditionalData." e verrà completata senza problemi (a parte lo spam nella console).
Quantità eccessiva di errori 429 durante goosey honk
Soluzione: Untitled Goose Tool incontrerà rapidamente i limiti delle API Graph di un tenant; questo è un limite imposto da Microsoft sulle chiamate alle API Graph.