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.
Гусь на свободе.
Untitled Goose Tool — это надёжный и гибкий инструмент для поиска угроз и реагирования на инциденты, который добавляет новые методы аутентификации и сбора данных для проведения полного расследования в средах Microsoft Entra ID, Azure и M365 заказчика. Untitled Goose Tool собирает дополнительные телеметрические данные из Microsoft Defender for Endpoint (MDE) и Defender for Internet of Things (IoT) (D4IoT).
Этот инструмент был разработан для помощи группам реагирования на инциденты: он экспортирует облачные артефакты после инцидента для сред, которые не передают журналы в SIEM (Security Information and Events Management) или другое долгосрочное решение для хранения журналов.
Дополнительные рекомендации по использованию Untitled Goose Tool см. в документе: Untitled Goose Tool Fact Sheet
Для запуска Untitled Goose Tool требуется 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
Роли IAM в подписке Azure```
- Reader
- Storage Blob Data Reader
- Storage Queue Data Reader
Убедитесь, что для субъекта-службы включена опция "Разрешить общедоступные клиентские потоки".
У нас есть скрипт 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. Если они не были сгенерированы с указанными выше параметрами, вам следует заполнить верхнюю секцию [auth], чтобы Untitled Goose Tool мог правильно выполнить аутентификацию в соответствующих ресурсах. Однако, если вам некомфортно вводить свои учётные данные в файл, вы можете удалить .auth и/или .auth_d4iot, и инструмент запросит учётные данные через консоль.
Минимальная конфигурация аутентификации выглядит так:``` [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
Чтобы включить определённые pull-запросы, вы можете изменить вхождения 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
Запустите с параметрами по умолчанию. По умолчанию он шифрует учётные данные/токены с помощью запрашиваемого пароля. Если поля не определены в конфигурации, то он также запросит их:```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/HEAD/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 и установите `ual` в разделе `m365` в значение `True`.
3. Запустите `goosey auth` с нужными параметрами.
4. Запустите `goosey honk` с нужными параметрами.
5. Вместо шагов 3–4 запустите `goosey autohonk` с нужными параметрами
### Рекомендации
1. Мы рекомендуем сначала запустить [скрипт настройки PowerShell](https://github.com/cisagov/untitledgoosetool/blob/HEAD/scripts/Create_SP.ps1) или заполнить .conf
2. Заполнение .auth и/или .auth_d4iot теперь необязательно.
3. Всегда запускайте `goosey auth` перед запуском `goosey honk` или `goosey d4iot`. `goosey autohonk` выполнит аутентификацию самостоятельно.
### Особые случаи использования
#### За прокси
Инструмент должен работать за прокси. При условии, что заданы соответствующие переменные окружения для cli```
https_proxy=<proxy_url>
http_proxy=<proxy_url>
Наличие % в пароле:
Решение: Убедитесь, что вы экранируете % в пароле с помощью %%.
Ошибка при попытке выполнить pip install . на Mac:
ModuleNotFoundError: No module named 'certifi'
Решение: Перейдите в папку «Программы», найдите папку вашей версии Python и дважды щелкните файл "Install Certificates.command" внутри папки Python, чтобы установить сертификат.
Почему Untitled Goose Tool возвращает два результата для правил почтового ящика Exchange Online и разрешений почтового ящика Exchange Online?
Решение: И вызовы API, и вызовы PowerShell являются надёжными и показывают разную информацию, поэтому мы решили оставить оба.
Ошибка после выполнения некоторых вызовов 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:
Мы приветствуем ваш вклад! Подробности см. здесь.
Этот проект находится в общественном достоянии во всём мире.
Этот проект находится в общественном достоянии на территории Соединённых Штатов, а авторские и смежные права на произведение во всём мире отменяются через объявление об общественном достоянии CC0 1.0 Universal.
Все вклады в этот проект будут публиковаться в соответствии с лицензией CC0. Отправляя pull request, вы соглашаетесь с этим отказом от авторских прав.
УВЕДОМЛЕНИЕ
Этот программный пакет («программное обеспечение» или «код») был создан правительством Соединённых Штатов и не является объектом авторского права на территории Соединённых Штатов. Все остальные права защищены. Вы можете использовать, изменять или распространять код любым способом. Однако вы не можете впоследствии заявлять авторские права на распространяемый код. Правительство Соединённых Штатов не претендует на авторские права на вносимые вами изменения и не будет ограничивать распространение ваших добросовестных изменений в программном обеспечении. Если вы решите обновить или распространять код, включите это уведомление вместе с кодом. Если применимо, мы просим вас указывать Агентство по кибербезопасности и защите инфраструктуры следующим образом: «Оригинальный код разработан Агентством по кибербезопасности и защите инфраструктуры (CISA), Министерство внутренней безопасности США».
ИСПОЛЬЗУЙТЕ ЭТО ПРОГРАММНОЕ ОБЕСПЕЧЕНИЕ НА СВОЙ РИСК. ЭТО ПРОГРАММНОЕ ОБЕСПЕЧЕНИЕ ПОСТАВЛЯЕТСЯ БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ, ЯВНЫХ ИЛИ ПОДРАЗУМЕВАЕМЫХ. ПРАВИТЕЛЬСТВО СОЕДИНЁННЫХ ШТАТОВ НЕ НЕСЁТ НИКАКОЙ ОТВЕТСТВЕННОСТИ ЗА ИСПОЛЬЗОВАНИЕ ИЛИ НЕПРАВИЛЬНОЕ ИСПОЛЬЗОВАНИЕ ЭТОГО ПРОГРАММНОГО ОБЕСПЕЧЕНИЯ ИЛИ ЕГО ПРОИЗВОДНЫХ.
ЭТО ПРОГРАММНОЕ ОБЕСПЕЧЕНИЕ ПРЕДОСТАВЛЯЕТСЯ «КАК ЕСТЬ». ПРАВИТЕЛЬСТВО СОЕДИНЁННЫХ ШТАТОВ НЕ БУДЕТ УСТАНАВЛИВАТЬ, УДАЛЯТЬ, ЗАПУСКАТЬ ИЛИ ПОДДЕРЖИВАТЬ ЭТО ПРОГРАММНОЕ ОБЕСПЕЧЕНИЕ ПО ВАШЕМУ ЗАПРОСУ. ЕСЛИ ВЫ НЕ УВЕРЕНЫ В ТОМ, КАК ЭТО ПРОГРАММНОЕ ОБЕСПЕЧЕНИЕ БУДЕТ ВЗАИМОДЕЙСТВОВАТЬ С ВАШЕЙ СИСТЕМОЙ, НЕ ИСПОЛЬЗУЙТЕ ЕГО.
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.
Решение: Эти сообщения не являются проблемами. Вызов Azure Compliance Results всё равно завершится. Вызов Azure Information Protection Policies не является критической ошибкой. Вызов 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." и завершится без проблем (кроме спама в консоли).
Чрезмерное количество ошибок 429 во время goosey honk
Решение: Untitled Goose Tool быстро столкнётся с ограничениями Graph API клиента (tenant); это ограничение, которое Microsoft накладывает на вызовы Graph API.