たれながし.info

とあるITエンジニアの備忘録

Microsoft Defender for Endpoint APIを使ってみる

PowerShellREST 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

事前準備

まず、最初にAzure ADに「アプリの登録」が必要です。

Azure ADの「アプリの登録」から「新規作成」をクリックする
f:id:tarenagashi_info:20210925035705p:plain


「名前」を入力し「登録」
f:id:tarenagashi_info:20210925035746p:plain


追加したアプリの情報「アプリケーションID」「テナントID」をメモしておく
f:id:tarenagashi_info:20210925035948p:plain


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


アクセス許可を与える
※「Alert.Read.All」と「Vulnerability.Read.All」を許可した
f:id:tarenagashi_info:20210925040426p:plain


「管理者の同意を与えます」をクリックする
f:id:tarenagashi_info:20210925040711p:plain


「証明書とシークレット」から「新しいクライアントシークレット」から「追加」する
f:id:tarenagashi_info:20210925040921p:plain


発行された「シークレット値」を認証で使用する
f:id:tarenagashi_info:20210925041031p:plain

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": []
		},