Untitled Goose Tool

거위가 풀려났다.

소개

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를 참조하십시오.

시작하기

사전 요구 사항

Python으로 Untitled Goose Tool을 실행하려면 Python >= 3.9가 필요합니다. Python 3.12는 더 나은 로깅을 제공하므로 적극 권장됩니다.

Windows 머신에서는 도구를 실행하기 전에 Microsoft Visual C++ 재배포 가능 패키지(14.x)가 설치되어 있는지 확인해야 합니다.

또한 가상 환경 내에서 Untitled Goose Tool을 실행하는 것이 좋습니다.

Mac OSX```sh

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

Windows```console

You can also use py -3 -m venv .venv

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

Data.Read (Application)

Microsoft Threat Protection:

AdvancedHunting.Read.All (Application)

WindowsDefenderATP:

AdvancedQuery.Read.All (Application)
Alert.Read.All (Application)
Library.Manage (Application)
Machine.Read.All (Application)
SecurityRecommendation.Read.All (Application)
Software.Read.All (Application)
Ti.ReadWrite (Application)
Vulnerability.Read.All (Application)

Microsoft Graph:

APIConnectors.Read.All (Application)
AuditLog.Read.All (Application)
ConsentRequest.Read.All (Application)
Directory.Read.All (Application)
Domain.Read.All (Application)
IdentityProvider.Read.All (Application)
IdentityRiskEvent.Read.All (Application)
IdentityRiskyServicePrincipal.Read.All (Application)
IdentityRiskyUser.Read.All (Application)
MailboxSettings.Read (Application)
Policy.Read.All (Application)
Policy.Read.PermissionGrant (Application)
Reports.Read.All (Application)
RoleManagement.Read.All (Application)
SecurityActions.Read.All (Application)
SecurityAlert.Read.All (Application)
SecurityEvents.Read.All (Application)
UserAuthenticationMethod.Read.All (Application)

Office 365 Exchange Online

Exchange.ManageAsApp (Application)

Azure 구독 IAM 역할```
- Reader
- Storage Blob Data Reader
- Storage Queue Data Reader

서비스 주체에 대해 "Allow public client flows"를 반드시 활성화해야 합니다.

필요한 권한으로 서비스 주체를 설정하기 위한 설정 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을 실행하세요:

일반 설치```sh

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

Usage

Config

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에서 사용됩니다. 위의 매개변수로 생성되지 않은 경우, Untitled Goose Tool이 적절한 리소스에 올바르게 인증할 수 있도록 상단의 [auth] 섹션을 작성해야 합니다. 하지만 자격 증명을 파일에 입력하는 것이 불편하다면, .auth 및/또는 .auth_d4iot를 삭제하고 콘솔을 통해 도구가 자격 증명을 묻도록 할 수 있습니다.

기본 인증 형식은 다음과 같습니다:``` [auth]

The username of your account. ex: [email protected]

username=

The password of your account. ex: AAD_password

password=

The application ID of your service principal

appid=

The client secret value of your service principal (not the secret ID)

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=

Enter your D4IoT sensor API token

sensor_token=

Enter your D4IoT management console API 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로 변경하면 됩니다 (대소문자 구분 안 함).

인증```sh

$ 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

기본값으로 실행합니다. 기본적으로 자격 증명/토큰은 프롬프트에서 입력받은 비밀번호로 암호화됩니다. 해당 필드가 config에 정의되어 있지 않으면, 이들도 프롬프트로 입력받습니다:```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

Autohonk```sh

$ 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/develop/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 파일을 열고 `m365` 섹션 아래의 `ual`을 `True`로 설정하세요.
3. 원하는 매개변수로 `goosey auth`를 실행하세요.
4. 원하는 매개변수로 `goosey honk`를 실행하세요.
5. 3-4단계 대신 원하는 매개변수로 `goosey autohonk`를 실행하세요.

### 고려 사항

1. 먼저 [PowerShell 설정 스크립트](https://github.com/cisagov/untitledgoosetool/blob/develop/scripts/Create_SP.ps1)를 실행하거나 .conf를 작성할 것을 권장합니다.
2. .auth 및/또는 .auth_d4iot를 작성하는 것은 이제 선택 사항입니다.
3. `goosey honk` 또는 `goosey d4iot`를 실행하기 전에 항상 `goosey auth`를 실행하세요. `goosey autohonk`는 자체적으로 인증을 수행합니다.

### 특수 사용 사례

#### 프록시 뒤에서

이 도구는 프록시 뒤에서도 작동해야 합니다. CLI에 적절한 환경 변수가 설정되어 있는 한.```
https_proxy=<proxy_url>
http_proxy=<proxy_url>

알려진 문제

비밀번호에 %가 포함된 경우:

해결 방법: 비밀번호의 %를 %%로 이스케이프해야 합니다.
Mac에서 pip install .을 실행할 때 오류 발생:
```
ModuleNotFoundError: No module named 'certifi'
```
해결 방법: 응용 프로그램 폴더로 이동하여 Python 버전 폴더를 찾은 다음, Python 폴더 안의 "Install Certificates.command" 파일을 더블 클릭하여 인증서를 설치합니다.
Untitled Goose Tool이 Exchange Online 받은 편지함 규칙 및 Exchange Online 사서함 권한에 대해 두 개의 결과를 반환하는 이유는 무엇인가요?

해결 방법: API 호출과 PowerShell 호출 모두 강력하며 서로 다른 정보를 표시하므로 둘 다 유지하기로 결정했습니다.

특정 Azure Security Center 호출 실행 후 오류:

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.

Azure Information Protection 정책:

Error: Operation returned an invalid status 'Not Found'

Azure 평가:

Discriminator source is absent or null, use base class ResourceDetails.

감사의 말

Claire Casalnova
Jordan Eberst
Nicholas Kantor
Wellington Lee
Victoria Wallace

기여

기여를 환영합니다! 자세한 내용은 여기를 참조하세요.

라이선스

이 프로젝트는 전 세계적으로 퍼블릭 도메인에 있습니다.

법적 고지

고지

이 소프트웨어 패키지("소프트웨어" 또는 "코드")는 미국 정부가 작성했으며 미국 내에서 저작권의 적용을 받지 않습니다. 기타 모든 권리는 보유됩니다. 귀하는 코드를 어떠한 방식으로든 사용, 수정 또는 재배포할 수 있습니다. 그러나 배포된 형태의 코드에 대해 이후 저작권을 주장할 수 없습니다. 미국 정부는 귀하가 만든 변경 사항에 대해 저작권을 주장하지 않으며, 소프트웨어에 대한 정당한 변경의 배포를 제한하지 않습니다. 코드를 업데이트하거나 재배포하기로 결정한 경우 이 고지를 코드에 포함하십시오. 해당되는 경우, 다음 문구를 사용하여 사이버보안 및 인프라 보안국(Cybersecurity and Infrastructure Security Agency, CISA)을 표시해 주시기 바랍니다: “원본 코드는 미국 국토안보부(U.S. Department of Homeland Security)의 사이버보안 및 인프라 보안국(CISA)이 개발했습니다.”

이 소프트웨어는 본인의 책임 하에 사용하십시오. 이 소프트웨어는 명시적이거나 묵시적인 어떠한 보증도 제공하지 않습니다. 미국 정부는 이 소프트웨어 또는 그 파생물의 사용 또는 오용에 대해 어떠한 책임도 지지 않습니다.

이 소프트웨어는 "있는 그대로(AS-IS)" 제공됩니다. 미국 정부는 귀하의 요청에 따라 이 소프트웨어를 설치, 제거, 운영 또는 지원하지 않습니다. 이 소프트웨어가 시스템과 어떻게 상호 작용할지 확실하지 않은 경우 사용하지 마십시오.

untitledgoosetool

인기