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.
O Ganso está solto.
Untitled Goose Tool é uma ferramenta robusta e flexível de caça e resposta a incidentes que adiciona novos métodos de autenticação e coleta de dados para executar uma investigação completa contra os ambientes Microsoft Entra ID, Azure e M365 do cliente. A Untitled Goose Tool coleta telemetria adicional do Microsoft Defender for Endpoint (MDE) e do Defender for Internet of Things (IoT) (D4IoT).
Esta ferramenta foi projetada para auxiliar equipes de resposta a incidentes, exportando artefatos da nuvem após um incidente para ambientes que não estão ingerindo logs em um Security Information and Events Management (SIEM) ou em outra solução de longo prazo para logs.
Para mais orientações sobre como usar a Untitled Goose Tool, consulte: Ficha Técnica da Untitled Goose Tool
Python >= 3.9 é necessário para executar a Untitled Goose Tool com Python. Python 3.12 é altamente recomendado, pois resulta em um logging melhor.
Em uma máquina Windows, você precisará garantir que o pacote redistribuível Microsoft Visual C++ (14.x) esteja instalado antes de executar a ferramenta.
Também é recomendado executar a Untitled Goose Tool dentro de um ambiente virtual.
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
### Requisitos
As seguintes permissões EntraID/M365 são necessárias para executar o Untitled Goose Tool e fornecer-lhe acesso somente leitura ao tenant.
Nota: a conta de usuário deve ser uma conta somente na nuvem (não sincronizada com o ambiente on-premise); isso garantirá que o processo de login permaneça o mesmo em todos os ambientes para a ferramenta.
Uma conta de usuário somente na nuvem e a entidade de serviço EXO associada, com as seguintes permissões:
Centro de Administração do Exchange Online```
- View-Only Audit Logs
- View-Only Configuration
- View-Only Recipients
- User Options
Um principal de serviço com as seguintes permissões:
Permissões de API``` Log Analytics API
Microsoft Threat Protection:
WindowsDefenderATP:
Microsoft Graph:
Office 365 Exchange Online
Funções de IAM da Assinatura do Azure```
- Reader
- Storage Blob Data Reader
- Storage Queue Data Reader
Certifique-se de habilitar "Allow public client flows" para a entidade de serviço.
Temos um script de configuração do PowerShell para configurar uma entidade de serviço com as permissões necessárias. Além disso, a associação da Entidade de Serviço do Azure com o m365 atualmente só pode ser feita via PowerShell e é necessária para parte da coleta de logs do m365.
Abaixo está um exemplo de execução do script, que exibirá o comando goosey conf que você precisa executar para criar os arquivos de configuração com as informações adequadas.```powershell
PS > Write-Host "Creating a new Goose Application and Users"
PS > ./Create_SP.ps1 -AppName GooseApp -Create
Além disso, o script pode excluir o Application quando você terminar de usá-lo.```powershell
PS > Write-Host "Creating a new Goose Application and Users"
PS > ./Create_SP.ps1 -AppName GooseApp -Delete
Para instalar, clone o repositório e depois faça um 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 requires authentication parameters and configuration. To automatically build the configuration file, run the following after installation.```sh $ goosey conf
Uma versão deste comando será gerada quando o script de instalação do powershell for executado para criar/configurar o service principal. Abaixo está um exemplo com valores de parâmetros falsos.```sh
$ goosey conf --config_tenant=5fd146ad-8b31-4afa-a72f-6f71df5c7173 --config_subscriptionid=all --auth_appid=24fd6377-79e0-445d-838b-3eaa60d3ca21
Depois disso, os arquivos .auth, .conf, .auth_d4iot e .d4iot_conf devem ser colocados no seu diretório atual. Esses arquivos são usados pela Untitled Goose Tool. A menos que isso tenha sido gerado com os parâmetros acima, você deve preencher a seção superior [auth] para que a Untitled Goose Tool possa autenticar corretamente nos recursos apropriados. No entanto, se você não se sentir confortável em inserir suas credenciais em um arquivo, você pode optar por excluir o .auth e/ou o .auth_d4iot e a ferramenta solicitará as credenciais pelo console.
A autenticação mínima tem a seguinte aparência:``` [auth]
username=
password=
appid=
clientsecret=
A configuração mínima tem a seguinte aparência:```
[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
A autenticação básica do D4IoT é assim:``` [auth]
username=
password=
sensor_token=
mgmt_token=
A configuração do D4IoT se parece com:```
[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
Para ativar pulls específicos, você pode alterar ocorrências de False para True (não diferencia maiúsculas de minúsculas).
$ 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
Execute com as configurações padrão. Por padrão, ele criptografará as credenciais/tokens com uma senha solicitada. Se os campos não estiverem definidos na configuração, ele também os solicitará:```sh
$ goosey auth
Execute com depuração e tratamento de autenticação insegura habilitados:```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
Execute com os padrões:```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
Execute com as opções padrão:```sh $ goosey honk
Execute com o log de depuração habilitado, envie a saída para o diretório `my_outputs` e habilite todas as chamadas do 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)
### Recommended Default Workflow
1. Instale a ferramenta `pip install .`
2. (Opcional) Execute o [script powershell de configuração](https://github.com/cisagov/untitledgoosetool/blob/HEAD/scripts/Create_SP.ps1) para configurar o service principal do seu locatário
3. Use o comando `goosey conf` gerado. Ou apenas execute-o sem parâmetros
4. Preencha o arquivo .auth com suas credenciais (se você não usou a saída do script powershell)
5. Preencha as informações de configuração e defina as chamadas desejadas no arquivo .conf como `True`.
6. Execute `goosey auth` com os parâmetros desejados.
7. Execute `goosey honk` com os parâmetros desejados.
8. Em vez dos passos 6-7, execute `goosey autohonk` com os parâmetros desejados
### Recommended Workflow for UAL Call
1. Passos 1-4 acima
2. Abra o arquivo .conf e defina `ual` na seção `m365` como `True`.
3. Execute `goosey auth` com os parâmetros desejados.
4. Execute `goosey honk` com os parâmetros desejados.
5. Em vez dos passos 3-4, execute `goosey autohonk` com os parâmetros desejados
### Considerations
1. Recomendamos executar o [script powershell de configuração](https://github.com/cisagov/untitledgoosetool/blob/HEAD/scripts/Create_SP.ps1) ou preencher o .conf primeiro
2. Preencher o .auth e/ou .auth_d4iot agora é opcional.
3. Sempre execute `goosey auth` antes de executar `goosey honk` ou `goosey d4iot`. O `goosey autohonk` realizará a autenticação por conta própria.
### Special Use Cases
#### Behind a proxy
A ferramenta deve funcionar atrás de um proxy. Desde que as variáveis de ambiente apropriadas para a CLI estejam definidas.```
https_proxy=<proxy_url>
http_proxy=<proxy_url>
Ter % na senha:
Solução: Certifique-se de escapar % na senha com %%.
Erro ao tentar pip install . quando você está no Mac:
ModuleNotFoundError: No module named 'certifi'
Solução: Vá para a pasta de aplicativos, encontre a pasta da sua versão do Python e clique duas vezes no arquivo "Install Certificates.command" dentro da pasta do Python para instalar o certificado.
Por que o Untitled Goose Tool retorna dois resultados para regras de caixa de entrada do Exchange Online e permissões de caixa de correio do Exchange Online?
Solução: Tanto as chamadas de API quanto as do PowerShell são robustas e mostram informações diferentes, então decidimos manter ambas.
Erro após executar determinadas chamadas do Azure Security Center:
Resultados de Conformidade do 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.
Políticas de Proteção de Informações do Azure:
Error: Operation returned an invalid status 'Not Found'
Aceitamos contribuições! Veja aqui para detalhes.
Este projeto está no domínio público mundial.
Este projeto está em domínio público nos Estados Unidos, e os direitos autorais e os direitos relacionados ao trabalho em todo o mundo são renunciados por meio da dedicação de domínio público Universal CC0 1.0.
Todas as contribuições para este projeto serão lançadas sob a dedicação CC0. Ao enviar um pull request, você concorda em cumprir esta renúncia de interesse de direitos autorais.
AVISO
Este pacote de software (“software” ou “código”) foi criado pelo Governo dos Estados Unidos e não está sujeito a direitos autorais nos Estados Unidos. Todos os outros direitos são reservados. Você pode usar, modificar ou redistribuir o código de qualquer forma. No entanto, você não pode posteriormente reivindicar direitos autorais sobre o código conforme distribuído. O Governo dos Estados Unidos não reivindica direitos autorais sobre as alterações que você efetuar, nem restringirá sua distribuição de alterações legítimas ao software. Se você decidir atualizar ou redistribuir o código, inclua este aviso com o código. Quando relevante, pedimos que você credite a Cybersecurity and Infrastructure Security Agency com a seguinte declaração: “Original code developed by the Cybersecurity and Infrastructure Security Agency (CISA), U.S. Department of Homeland Security.”
USE ESTE SOFTWARE POR SUA CONTA E RISCO. ESTE SOFTWARE NÃO ACOMPANHA NENHUMA GARANTIA, EXPRESSA OU IMPLÍCITA. O GOVERNO DOS ESTADOS UNIDOS NÃO ASSUME NENHUMA RESPONSABILIDADE PELO USO OU MAU USO DESTE SOFTWARE OU DE SEUS DERIVADOS.
ESTE SOFTWARE É OFERECIDO “NO ESTADO EM QUE SE ENCONTRA” (AS-IS). O GOVERNO DOS ESTADOS UNIDOS NÃO INSTALARÁ, REMOVERÁ, OPERARÁ OU FORNECERÁ SUPORTE PARA ESTE SOFTWARE A SEU PEDIDO. SE VOCÊ NÃO TIVER CERTEZA DE COMO ESTE SOFTWARE INTERAGIRÁ COM SEU SISTEMA, NÃO O UTILIZE.
Avaliações do Azure:
Discriminator source is absent or null, use base class ResourceDetails.
Subavaliações do Azure:
Subtype value GeneralVulnerability has no mapping, use base class AdditionalData.
Subtype value SqlVirtualMachineVulnerability has no mapping, use base class AdditionalData.
Solução: Essas mensagens não são problemas. A chamada de resultado de conformidade do Azure ainda será concluída. A chamada de política de proteção de informações do Azure não é um erro crítico. A chamada de avaliações do Azure enche o console com um aviso de uma linha: "Discriminator source is absent or null, use base class ResourceDetails" e será concluída sem problemas (além do spam no console). A chamada de subavaliações do Azure enche o console com um aviso de uma linha: "Subtype value GeneralVulnerability has no mapping, use base class AdditionalData." ou "Subtype value SqlVirtualMachineVulnerability has no mapping, use base class AdditionalData." e será concluída sem problemas (além do spam no console).
Quantidade excessiva de erros 429 durante goosey honk
Solução: O Untitled Goose Tool encontrará rapidamente as limitações da API Graph de um locatário; essa é uma limitação que a Microsoft impõe às chamadas da API Graph.