Microsoft Defender for Endpoint APIを使ってみる

PowerShellとREST APIでDefender for Endpointを操作してみる

はじめに

「Microsoft Defender for Endpoint」には「Microsoft Defender for Endpoint API」というREST APIがあります。アラート一覧の取得や脆弱性一覧の取得など各種操作ができます。

今回はクライアントにPowerShellを使って、「Microsoft Defender for Endpoint API」を実行してみます。

参考資料

下記資料を参考にしました。

使用できる機能一覧が記載されています。
docs.microsoft.com

Powershellのスクリプトサンプルが記載されています。
docs.microsoft.com

APIキーの取得

最初にAzure ADの「アプリの登録」から「APIキー」を取得します。

Azure ADの「アプリの登録」から「新規作成」をクリックする



「名前」を入力し「登録」



追加したアプリの情報「アプリケーションID」「テナントID」をメモしておく



「APIのアクセス許可」 > 「アクセス許可の追加」 > 「所属する組織で使用しているAPI」 > 「WindowsDefenderATP」を検索しクリックする



アクセス許可を与える
※「Alert.Read.All」と「Vulnerability.Read.All」を許可した



「管理者の同意を与えます」をクリックする



「証明書とシークレット」から「新しいクライアントシークレット」から「追加」する



発行された「シークレット値」を認証で使用する

APIの実行

API実行の基本的な流れは下記となります。

1. 認証の実施
   →認証トークンを取得
2. APIの実行
   →認証トークンをHeaderに記載し、機能毎のURLにHTTP REQUESTを送信
3. 結果の表示、保存

認証の実施

認証用のPowerShellスクリプトを作成します。

スクリプトを名前「Get-Token.ps1」で保存する
※メモした「テナントID」「アプリケーションID」「シークレット値」を記載する

# That code gets the App Context Token and save it to a file named "Latest-token.txt" under the current directory
# Paste below your Tenant ID, App ID and App Secret (App key).

$tenantId = 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' ### Paste your tenant ID here
$appId = 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' ### Paste your Application ID here
$appSecret = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' ### Paste your Application secret here

$resourceAppIdUri = 'https://api.securitycenter.microsoft.com'
$oAuthUri = "https://login.microsoftonline.com/$TenantId/oauth2/token"
$authBody = [Ordered] @{
     resource = "$resourceAppIdUri"
     client_id = "$appId"
     client_secret = "$appSecret"
     grant_type = 'client_credentials'
}
$authResponse = Invoke-RestMethod -Method Post -Uri $oAuthUri -Body $authBody -ErrorAction Stop
$token = $authResponse.access_token
Out-File -FilePath "./Latest-token.txt" -InputObject $token
return $token

スクリプトを実行すると認証トークン（JWT形式）が取得できる　※取得から60分有効

powershell -ExecutionPolicy Bypass .\Get-Token.ps1

認証トークンは「https://jwt.ms」でデコードして、有効期限やアクセス許可など確認できる

  ...
  "exp": 1632390256,
  ...
  "roles": [
    "Alert.Read.All",
    "Vulnerability.Read.All"
  ],
  ...

APIの実行

下記ページを参考にAPIで脆弱性一覧を取得してみます。
docs.microsoft.com


スクリプトを名前「Get-Vulnerabilities.ps1」で保存する

# 認証トークンの取得
$token = ./Get-Token.ps1

# HTTP Requestの送信先URL
$url = "https://api.securitycenter.microsoft.com/api/Vulnerabilities"

# HTTPヘッダ
$headers = @{ 
    'Content-Type' = 'application/json'
    Accept = 'application/json'
    Authorization = "Bearer $token"
}

# HTTP GETの送信
$response = Invoke-WebRequest -Method Get -Uri $url -Headers $headers -ErrorAction Stop

# 結果の出力
$response

$dateTimeForFileName = Get-Date -Format o | foreach {$_ -replace ":", "."}
$outputJsonPath = "./Vulnerabilities_$dateTimeForFileName.json"

$results = $response.Content
$results | Out-File -FilePath $outputJsonPath
$outputJsonPath

PowerShellで実行する

powershell -ExecutionPolicy Bypass .\Get-Vulnerabilities.ps1

結果の表示、保存

脆弱性一覧が、Responseの「Content」にJson形式で格納されている

StatusCode        : 200
StatusDescription : OK
Content           : {"@odata.context":"https://api.securitycenter.microsoft.com/api/$metadata#Vulnerabilities","value":
                    [{"id":"CVE-2021-37957","name":"CVE-2021-37957","description":"This vulnerability affects the follo
                    wi...
RawContent        : HTTP/1.1 200 OK
                    x-content-type-options: nosniff
                    x-request-id: 2739653b-0d05-4d78-862f-3f318e0d2ee6
                    OData-Version: 4.0
                    Strict-Transport-Security: max-age=31536000 ; includeSubDomains
                    Content-Lengt...
Forms             : {}
Headers           : {[x-content-type-options, nosniff], [x-request-id, 2739653b-0d05-4d78-862f-3f318e0d2ee6], [OData-Ve
                    rsion, 4.0], [Strict-Transport-Security, max-age=31536000 ; includeSubDomains]...}
Images            : {}
InputFields       : {}
Links             : {}
ParsedHtml        : System.__ComObject
RawContentLength  : 5596077

./Vulnerabilities_2021-09-23T18.58.15.6747327+09.00.json

取得した脆弱性情報の先頭1つ目

{
	"@odata.context": "https://api.securitycenter.microsoft.com/api/$metadata#Vulnerabilities",
	"value": [
		{
			"id": "CVE-2021-37957",
			"name": "CVE-2021-37957",
			"description": "This vulnerability affects the following vendors: Google, Ubuntu, Debian. To view more details about this vulnerability please visit the vendor website.",
			"severity": "High",
			"cvssV3": 8.8,
			"exposedMachines": 1,
			"publishedOn": "2021-09-21T00:00:00Z",
			"updatedOn": "2021-09-22T00:00:00Z",
			"publicExploit": false,
			"exploitVerified": false,
			"exploitInKit": false,
			"exploitTypes": [],
			"exploitUris": []
		},