Untitled Goose Tool est un outil de chasse et de réponse aux incidents robuste et flexible qui ajoute des méthodes novatrices d'authentification et de collecte de données afin de mener une enquête complète sur les environnements Azure Active Directory (AzureAD), Azure et M365 d'un client.
L'oie est en liberté.
Untitled Goose Tool est un outil robuste et flexible de chasse aux menaces et de réponse aux incidents qui intègre de nouvelles méthodes d'authentification et de collecte de données afin de mener une enquête complète sur les environnements Microsoft Entra ID, Azure et M365 d'un client. Untitled Goose Tool recueille également des données de télémétrie supplémentaires à partir de Microsoft Defender for Endpoint (MDE) et de Defender for Internet of Things (IoT) (D4IoT).
Cet outil a été conçu pour aider les équipes de réponse aux incidents en exportant les artefacts cloud après un incident pour les environnements qui n'intègrent pas les journaux dans un Security Information and Events Management (SIEM) ou une autre solution de conservation à long terme des journaux.
Pour plus de conseils sur l'utilisation d'Untitled Goose Tool, consultez : Fiche d'information sur Untitled Goose Tool
Python >= 3.9 est requis pour exécuter Untitled Goose Tool avec Python. Python 3.12 est fortement recommandé car il permet une meilleure journalisation.
Sur une machine Windows, vous devez vous assurer que le package redistribuable Microsoft Visual C++ (14.x) est installé avant d'exécuter l'outil.
Il est également recommandé d'exécuter Untitled Goose Tool dans un environnement virtuel.
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
### Prérequis
Les autorisations EntraID/M365 suivantes sont requises pour exécuter Untitled Goose Tool et lui fournir un accès en lecture seule au locataire.
Veuillez noter : Le compte utilisateur doit être un compte exclusivement cloud (non synchronisé avec l'environnement sur site), cela garantira que le processus de connexion reste le même pour l'outil dans tous les environnements.
Un compte utilisateur exclusivement cloud et le principal de service EXO associé, avec les autorisations suivantes :
Exchange Online Admin Center```
- View-Only Audit Logs
- View-Only Configuration
- View-Only Recipients
- User Options
Un principal de service avec les autorisations suivantes :
Autorisations API``` Log Analytics API
Microsoft Threat Protection:
WindowsDefenderATP:
Microsoft Graph:
Office 365 Exchange Online
Azure Subscription IAM Roles```
- Reader
- Storage Blob Data Reader
- Storage Queue Data Reader
Assurez-vous d'activer « Allow public client flows » pour le principal de service.
Nous disposons d'un script PowerShell de configuration pour configurer un principal de service avec les permissions nécessaires. De plus, l'association du principal de service Azure avec m365 ne peut actuellement être effectuée que via PowerShell et est nécessaire pour une partie de la collecte des journaux m365.
Voici un exemple d'exécution du script qui affichera la commande goosey conf que vous devez exécuter pour créer les fichiers de configuration avec les informations appropriées.```powershell
PS > Write-Host "Creating a new Goose Application and Users"
PS > ./Create_SP.ps1 -AppName GooseApp -Create
De plus, le script peut supprimer l'Application lorsque vous avez terminé de l'utiliser```powershell
PS > Write-Host "Creating a new Goose Application and Users"
PS > ./Create_SP.ps1 -AppName GooseApp -Delete
Pour installer, clonez le dépôt puis exécutez 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 nécessite des paramètres d'authentification et une configuration. Pour générer automatiquement le fichier de configuration, exécutez ce qui suit après l'installation.```sh $ goosey conf
Une version de cette commande sera générée lorsque le script d'installation PowerShell sera exécuté pour créer/configurer le principal de service. Voici un exemple avec de fausses valeurs de paramètres```sh
$ goosey conf --config_tenant=5fd146ad-8b31-4afa-a72f-6f71df5c7173 --config_subscriptionid=all --auth_appid=24fd6377-79e0-445d-838b-3eaa60d3ca21
Après cela, les fichiers .auth, .conf, .auth_d4iot et .d4iot_conf doivent être placés dans votre répertoire courant. Ces fichiers sont utilisés par Untitled Goose Tool. Sauf si cela a été généré avec les paramètres ci-dessus, vous devez remplir la section supérieure [auth] afin que Untitled Goose Tool puisse s'authentifier correctement auprès des ressources appropriées. Cependant, si vous ne vous sentez pas à l'aise pour saisir vos identifiants dans un fichier, vous pouvez choisir de supprimer les fichiers .auth et/ou .auth_d4iot et l'outil vous demandera vos identifiants via la console à la place.
L'authentification minimale ressemble à :``` [auth]
username=
password=
appid=
clientsecret=
La configuration minimale ressemble à:```
[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'authentification D4IoT minimale ressemble à :``` [auth]
username=
password=
sensor_token=
mgmt_token=
La configuration D4IoT ressemble à :```
[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
Pour activer des pulls spécifiques, vous pouvez remplacer les occurrences de False par True (insensible à la casse).
$ 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
Exécutez avec les paramètres par défaut. Par défaut, il chiffrera les identifiants/jetons avec un mot de passe demandé à l'invite. Si les champs ne sont pas définis dans la configuration, il les demandera également :```sh
$ goosey auth
Exécutez avec le débogage et la gestion de l'authentification non sécurisée activés :```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
Exécuter avec les paramètres par défaut :```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
Exécutez avec les options par défaut :```sh $ goosey honk
Exécutez avec la journalisation de débogage activée, écrivez la sortie dans le répertoire `my_outputs`, et activez tous les appels 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)
### Flux de travail par défaut recommandé
1. Installez l'outil `pip install .`
2. (Facultatif) Exécutez le [script PowerShell de configuration](https://github.com/cisagov/untitledgoosetool/blob/develop/scripts/Create_SP.ps1) pour configurer le principal de service pour votre locataire
3. Utilisez la commande `goosey conf` générée. Ou exécutez-la simplement sans paramètres
4. Renseignez le fichier .auth avec vos informations d'identification (si vous n'avez pas utilisé la sortie du script PowerShell)
5. Renseignez les informations de configuration et définissez les appels souhaités sur `True` dans le fichier .conf.
6. Exécutez `goosey auth` avec les paramètres souhaités.
7. Exécutez `goosey honk` avec les paramètres souhaités.
8. Au lieu des étapes 6-7, exécutez `goosey autohonk` avec les paramètres souhaités
### Flux de travail recommandé pour l'appel UAL
1. Étapes 1-4 ci-dessus
2. Ouvrez le fichier .conf et définissez `ual` sous la section `m365` sur `True`.
3. Exécutez `goosey auth` avec les paramètres souhaités.
4. Exécutez `goosey honk` avec les paramètres souhaités.
5. Au lieu des étapes 3-4, exécutez `goosey autohonk` avec les paramètres souhaités
### Considérations
1. Nous recommandons d'exécuter le [script PowerShell de configuration](https://github.com/cisagov/untitledgoosetool/blob/develop/scripts/Create_SP.ps1) ou de remplir d'abord le .conf
2. Renseigner le .auth et/ou .auth_d4iot est désormais facultatif.
3. Exécutez toujours `goosey auth` avant d'exécuter `goosey honk` ou `goosey d4iot`. `goosey autohonk` effectuera l'authentification par lui-même.
### Cas d'utilisation particuliers
#### Derrière un proxy
L'outil devrait fonctionner derrière un proxy, à condition que les variables d'environnement appropriées soient définies pour la cli.```
https_proxy=<proxy_url>
http_proxy=<proxy_url>
Si le mot de passe contient % :
Solution : Assurez-vous d'échapper % dans le mot de passe avec %%.
Erreur lors de la tentative de pip install . sur Mac :
ModuleNotFoundError: No module named 'certifi'
Solution : Accédez à votre dossier Applications, trouvez le dossier de votre version de Python, puis double-cliquez sur le fichier "Install Certificates.command" dans le dossier Python pour installer le certificat.
Pourquoi Untitled Goose Tool renvoie-t-il deux résultats pour les règles de boîte de réception Exchange Online et les autorisations de boîte aux lettres Exchange Online ?
Solution : Les appels API et PowerShell sont tous deux robustes et affichent des informations différentes, nous avons donc décidé de conserver les deux.
Erreur après l'exécution de certains appels Azure Security Center :
Azure Compliance Results:
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 Policies:
Error: Operation returned an invalid status 'Not Found'
Azure Assessments:
Discriminator source is absent or null, use base class ResourceDetails.
Azure SubAssessments:
Subtype value GeneralVulnerability has no mapping, use base class AdditionalData.
Subtype value SqlVirtualMachineVulnerability has no mapping, use base class AdditionalData.
Solution : Ces messages ne sont pas des problèmes. L'appel des résultats de conformité Azure aboutira quand même. L'appel de politique Azure Information Protection n'est pas une erreur critique. L'appel d'évaluations Azure inonde la console avec un avertissement d'une ligne : "Discriminator source is absent or null, use base class ResourceDetails" et aboutira sans problème (hormis le spam de la console). L'appel de sous-évaluations Azure inonde la console avec un avertissement d'une ligne : "Subtype value GeneralVulnerability has no mapping, use base class AdditionalData." ou "Subtype value SqlVirtualMachineVulnerability has no mapping, use base class AdditionalData." et aboutira sans problème (hormis le spam de la console).
Quantité excessive d'erreurs 429 lors de goosey honk
Solution : Untitled Goose Tool rencontrera rapidement les limites de l'API Graph d'un locataire ; il s'agit d'une limitation imposée par Microsoft sur les appels à l'API Graph.
Nous accueillons les contributions ! Veuillez consulter ici pour plus de détails.
Ce projet est dans le domaine public mondial.
Ce projet est dans le domaine public aux États-Unis, et les droits d'auteur et droits connexes sur l'œuvre dans le monde entier sont abandonnés via la dédicace au domaine public CC0 1.0 Universal.
Toutes les contributions à ce projet seront publiées sous la dédicace CC0. En soumettant une pull request, vous acceptez de vous conformer à cette renonciation aux droits d'auteur.
AVIS
Ce package logiciel (« logiciel » ou « code ») a été créé par le gouvernement des États-Unis et n'est pas soumis au droit d'auteur aux États-Unis. Tous les autres droits sont réservés. Vous pouvez utiliser, modifier ou redistribuer le code de quelque manière que ce soit. Cependant, vous ne pouvez pas ensuite revendiquer le droit d'auteur sur le code tel qu'il est distribué. Le gouvernement des États-Unis ne revendique aucun droit d'auteur sur les modifications que vous apportez, et il ne restreindra pas non plus la distribution de modifications légitimes du logiciel. Si vous décidez de mettre à jour ou de redistribuer le code, veuillez inclure cet avis avec le code. Le cas échéant, nous vous demandons de créditer la Cybersecurity and Infrastructure Security Agency avec la déclaration suivante : "Original code developed by the Cybersecurity and Infrastructure Security Agency (CISA), U.S. Department of Homeland Security."
UTILISEZ CE LOGICIEL À VOS PROPRES RISQUES. CE LOGICIEL EST FOURNI SANS AUCUNE GARANTIE, EXPRESSE OU IMPLICITE. LE GOUVERNEMENT DES ÉTATS-UNIS N'ASSUME AUCUNE RESPONSABILITÉ POUR L'UTILISATION OU LA MAUVAISE UTILISATION DE CE LOGICIEL OU DE SES DÉRIVÉS.
CE LOGICIEL EST FOURNI « TEL QUEL ». LE GOUVERNEMENT DES ÉTATS-UNIS N'INSTALLERA PAS, NE SUPPRIMERA PAS, N'EXPLOITERA PAS ET NE SUPPORTERA PAS CE LOGICIEL À VOTRE DEMANDE. SI VOUS N'ÊTES PAS SÛR DE LA MANIÈRE DONT CE LOGICIEL INTERAGIRA AVEC VOTRE SYSTÈME, NE L'UTILISEZ PAS.