Technical Add-on MS Defender Advanced Hunting

When updating from v0.1.x to v0.2.x, please re-setup the credentials

1. Overview

This App can use Advanced Hunting with their query format (KQL) through Microsoft Defender for Endpoint API.

Microsoft offers three APIs for Microsoft Defender Endpoint to use Advanced Hunting.

Microsoft Defender for Endpoint
Microsoft Defender XDR
Microsoft Graph REST API

This app can automatically recognize which API endpoint you choose, and query it.
If two or three are used in a single app, this app will give priority to "Microsoft Defender for Endpoint".

Please refer this for more detail about the endpoint.

Microsoft Defender for Endpoint

2. Installation

2.1 Account Settings

Description of the Account Settings page

Label	Description
Account name	Required. Set unique name for this credential.
Client ID	Required. Set Application (Client) ID.
Client Secret	Required. Set Client Secret.
Tenant ID	Required. Set Directory (Tenant) ID.
Default Credential	Optional. If checked, this app use this credentail as default.
Request read timeout (in seconds)	Optional. This means the read timeout for API request. Default value is 60s.
Request connection timeout (in seconds)	Optional. This means the connection timeout for API request. Default value is 10s.
Request retry num	Optional. This means the number of retry for API request when API returns server error. Default value is 0.

3. Usage

Command	Type	Description
advhunt	Generating Command	Fetch data using Advanced Hunting query

3.1 advhunt command

Returns a list of query results that you set your Advanced Hunting query.

Options	Description
query	Required. Set your Advanced Hunting Query
renew	Optional. If it set as "True", this app will force to update an access token.
cred	Optional. Set the unique credential name you want to use. - Not set: use the default credential which is checked in setup page. - Single value: use the specified value. e.g. cred="cred1" - Multi value: use the specified comma separated value. e.g. cred="cred1,cred2" - set `all`: use all credentials. e.g. cred="all"

Example 1
- If you want to search the word contains \, please use \\\\\\\ or \\\x5c in SPL.

| advhunt query="DeviceFileEvents
  | where Timestamp > ago(1d)
  | where FolderPath matches regex 'C:\\\x5cUsers' or FolderPath matches regex 'C:\\\\\\\Users'
  | project Timestamp, DeviceId, DeviceName, ActionType, FolderPath, FileName"
| spath input=_raw

Example 2
- Force to renew the access token.

| advhunt renew=True query="AlertInfo 
  | where Timestamp > ago(3d) 
  | limit 2" 
| spath input=_raw

Example 3
- Query an advanced hunting using the result of the previous SPL

| makeresults 
| eval ActionType = "AntivirusReport,HogeReport"
| makemv delim="," ActionType
| mvexpand ActionType
| mvcombine ActionType
| eval query = "('" . mvjoin(ActionType, "', '") . "')"
| map search="| advhunt query=\"DeviceEvents | where ActionType has_any $query$ \" | spath input=_raw | table * "

Example 4
- Query to multiple tenants.
- If you have multi tenants and want to query againt them, you can use this option.
  - Please set each credentail in setup page and use the name in cred="<here>"

| advhunt cred="tenant1_cred,tenant2_cred" query="AlertInfo"

Example 5
- use subserach pattern.

| advhunt [| makeresults 
  | eval query = "DeviceFileEvents
    | where Timestamp > ago(1d)
    | limit 1"
  | return query ]
| spath

4. Note

Required privileges

To use this app, users need following privileges.
- list_storage_passwords
- admin_all_objects
If you don't want to grant the user "admin_all_objects", there are three workarounds:
1. Update local.meta and grant the user "edit_storage_passwords".
  - Contents to add to local.meta
    [passwords] access = read : [*], write : [*]
2. Create a report to update an access token for Microsoft Endpoint in passwords.conf by the user who has "admin_all_objects" every 30 minutes. This allows normal users to simply use the current valid access token in passwords.conf and it's enough for the normal user to grant only list_storage_passwords.
3. Just stop to grant the user "admin_all_objects" and do nothing. In this case, this app try to communicate with Microsoft for getting new access token in every advhunt command. This makes the command run slower.

Differences between each Endpoint

If you choose "Microsoft Defender for Endpoint", you can't query againt some schema.
- ex. AlertInfo, AlertEvidence

Restriction of Microsoft Endpoint

Limitation, Quotas and resource allocation of API
- Microsoft Defender for Endpoint Advanced hunting API
  - Limitations
- Microsoft Defender XDR Advanced hunting API
  - Quotas and resource allocation
- Use the Microsoft Graph security API
  - Quotas and resource allocation

5. Debug

Please check the internal log.

index=_internal source="*advanced_hunting*" NOT "__init__"

6. Relase History

v0.2.1

Add retry and timeout settings for API request

v0.2

Change setting GUI, password and config architecture. This change affected existing config file.
Add Graph API capability
fix bug

v0.1.2-0.1.3

Update splunk sdk

v0.1.1

Fix for the cloud compatibility check

v0.1.0

This is a miner version up.
Fix to be able to query for multiple tenants using cred option.
Caution: This version does not have backward compatibility. Please set your credential again.

MS Defender Advanced Hunting

0

#22