More than 1 year has passed since last update.

Microsoft Security Advent Calendar 2022Advent Calendar 2022Day 25

Microsoft セキュリティの運用で使える便利な API ３選

Last updated at 2022-12-24Posted at 2022-12-24

はじめに

API を制する者が運用を制する？

Microsoft 関連のセキュリティ運用をする中で、標準機能で実現出来ないニーズ (データ可視化、自動化など) が出てくるときがあります。そんな時は、Microsoft が用意している各種 API を活用することで、かゆいところに手が届く実装が出来る場合があります。

今回は、データ可視化や自動化などで実際にお客様の Microsoft セキュリティの運用を支援している立場から、セキュリティ運用で使える便利な API を 3 つ紹介します。
皆さまの Microsoft セキュリティの運用のヒントになれば幸いです！

Microsoft セキュリティ運用で使える API の種類

そもそも、一口に API と言ってもセキュリティ関連だけでも様々なものがありますので、一度整理しておきます。
正直あまり使い道がないものもありますが、リファレンスとしての意味合いで過去に使用したことがあるものを全て記載しておきます。
他にもセキュリティ運用で利用できる API があれば是非教えてください。

Microsoft Graph API

言わずと知れた最も有名な API で、おそらく Microsoft は細々とした全ての API を Graph API に統合したいと考えていると思います。
将来性もあるので、何らかの用途で API の利用を検討する時は最初に Graph API で実現できないかを検討します。

ユーザーやグループを作成したり Exchange に予定を作成したりと様々なことができますが、セキュリティ関連だとアラートを取得したりセキュアスコアの情報を取得したりといったことができます。また、Intune で管理しているデバイスの情報などにもアクセスできます。
セキュリティ関連の API のことを特に "Microsoft Graph Security API" と呼びます。

Endpoint：https://graph.microsoft.com
Reference：https://learn.microsoft.com/ja-jp/graph/api/overview

Office 365 Management Activity API

Office 365 (Exchange や SharePoint など) の監査ログを取得できる API です。

この API を利用するには最初に "サブスクリプション" を開始する必要があり、利用する際も「Content URI の取得をリクエストしてから、Content URI にリクエストして実際のログを取得する」という 2 ステップでログ取得をするという癖があります。
また、ログを取得する時間指定が厳密に実施できない (アクティビティが行われた時間ではなく "ログが利用可能になった" というふわっとした時間しか指定できない)、サポートが提供されない、ログが重複する、など正直ちょっと使いにくい API です。

しかし、後述するようにセキュリティ観点では Endpoint API のログを取得できるという大きなメリットがあります。

Endpoint：https://manage.office.com
Reference：https://learn.microsoft.com/ja-jp/office/office-365-management-api/office-365-management-activity-api-reference

Microsoft 365 Defender API

"Microsoft 365 Defender" という名前を冠しているので期待が持てそうですが、正直あまり使いどころはないです。

Kusto クエリで任意の観点でデータを取得出来る Advanced hunting を実行できますが、最近 Graph API でも出来るようになったのでそちらを使った方がいいと思います。

他には Microsoft 365 Defender のインシデントを取得したり、(アラートではなく) ログをストリーミングして他データストアに保管したりすることができますが、Microsoft Sentinel を使用している場合はネイティブで統合されているのでそちらを使うことが多く、この API が登場する機会は少ないです。

Endpoint：https://api.security.microsoft.com
Reference：https://learn.microsoft.com/ja-jp/microsoft-365/security/defender/api-overview

Microsoft Defender for Endpoint API

Windows や MacOS、iOS、Android などのエンドポイントを保護する Microsoft Defender for Endpoint の API です。

アラート、脆弱性、デバイスインベントリ、ソフトウェアインベントリなどのエンドポイント関連の情報を取得できる他、ネットワーク隔離、フルスキャン、ファイルの検疫などのアクションを実行することができます。
アラートの情報に関しては専用の API だけあってエンティティの情報含め最も詳細に取得するできる API です。

情報の取得については Graph API の Advanced hunting で何とかなりますし、自動アクションについてはあまり実装したいというシナリオが少ない (仮にあっても、Azure Logic Apps にコネクタが利用されているためそちらを使うことが多い) ため、こちらも API としてはあまり利用する機会が少ないです。

Endpoint：https://api.securitycenter.microsoft.com
Reference：https://learn.microsoft.com/ja-jp/microsoft-365/security/defender-endpoint/exposed-apis-list

Microsoft Sentinel REST API

Microsoft Sentinel は Microsoft 365 Defender とネイティブで統合されているだけでなく、あらゆるセキュリティソリューションのログを統合してセキュリティ運用全体をマネージできる SIEM で、その Microsoft Sentinel の API です。

もちろん Microsoft 365 Defender だけでもカスタムアラートの作成が可能ですが、Microsoft Sentinel を使用することで様々なログ (ドメインコントローラのセキュリティイベントログ、ネットワーク機器のログ、セキュリティインテリジェンスなど) と突合させてアラートを出力する分析ルールを作成したり、アラート出力後のアクションを自動化したりできます。

Microsoft Sentinel を運用する際に、ちょっとしたデータ (退職者情報、IP レンジ情報、許可ドメイン情報など) 保持するためにウォッチリストという機能を使うことがありますが、個人的にはこのウォッチリストを更新する際などによく利用する API です。

Endpoint：https://management.azure.com
Reference：https://learn.microsoft.com/ja-jp/rest/api/securityinsights/

Defender for Cloud Apps REST API

以前は Microsoft Cloud App Security (MCAS) と呼ばれていた CASB 製品である Microsoft Defender for Cloud Apps (MDA) の API です。

MDA は Office 365 や Box、Dropbox、Google、Slack などのクラウドアプリを統合してアクティビティログを集約し、それらのログからアラート (大量のダウンロード、不審な IP アドレスからのサインイン、ランサムウェアアクティビティなど) を生成することができます。

この API を使用することで、上記のアクティビティログを取得したり、クラウドアプリ内に保存されているファイルのリストを取得することなどが可能です。

Endpoint：https://contoso.us2.contoso.com ※テナント毎に異なります
Reference：https://learn.microsoft.com/ja-jp/defender-cloud-apps/api-introduction

Intune Data Warehouse API

デバイスの構成管理ソリューション (MDM) である Intune の API です。Graph API で Intune で管理しているデバイスの詳細情報を取得できる他、デバイスステータスの日次の履歴を取得することができます。

例えば、Intune のコンプライアンスポリシーやデバイスプロファイルの適用状況 (成功、失敗など) のサマリデータや、デバイス毎に OS バージョンが 1 カ月でどのように変動しているかなどを確認できます。

Graph API で思ったような情報を取得できなかった場合 (以前、Ethernet Mac Address を取得したいときにこの API しか取得できなかった時がありました) には利用を検討できますが、私はほぼ使うことはない API です。

Endpoint：https://api.manage.microsoft.com
Reference：https://learn.microsoft.com/ja-jp/mem/intune/developer/intune-data-warehouse-collections

Log Analytics REST API

Microsoft Sentinel がバックエンドで使用する Log Analytics を管理するための API です。(Sentinel は Log Analytics のラッパーとして動作します)

Log Analytics の設定管理は頻繁に行わないので UI で事足りますが、Log Analytics (イコール Sentinel) に溜まっているデータを取得したい場合に多用します。具体的には、Kusto クエリを HTTP のボディに指定して POST するとクエリの実行結果を json 形式で受け取ることができます。

ただ、Azure Logic Apps に標準でアクションが提供されているため、HTTP リクエストをカスタムで送信するよりも Logic Apps のアクションを使用することの方が多いです。

Endpoint：https://api.loganalytics.io
Reference：https://learn.microsoft.com/ja-jp/rest/api/loganalytics/

Log Analytics Data Collector API

前述のデータを取得するのとは逆で、Log Analytics にログデータを送信することができる API です。

こちらの API を使用して Log Analytics にデータを送ることができるため、ここで紹介しているような他の API (例えば、Office 365 Management Activity API) から取得したデータを Log Analytics に送信してカスタムテーブルにデータを溜めることができます。

カスタムテーブルとしてログを溜めることができれば、Microsoft 365 Defender のアラートやログと突合して相関分析することが可能になります。
こちらも Logic Apps に標準でアクションが提供されているため、そちらを使うことも多いです。

Endpoint：https://xxxxxxxxxx.ods.opinsights.azure.com ※テナント毎に異なります
Reference：https://learn.microsoft.com/ja-jp/azure/azure-monitor/logs/data-collector-api

なお、最近は Azure Monitor Log Ingest API という新しい方法でデータを取り込む API があるので、今後検討する際はそちらから検討してもよいと思います。
https://learn.microsoft.com/ja-jp/azure/azure-monitor/logs/custom-logs-migrate

API の基本的な使用方法

前セクションの最後に紹介した Data Collector API など一部の例外を除き、Microsoft の API は基本的に "アクセストークン" と呼ばれる認証情報を用いて利用します。

アクセストークンは OAuth 2.0 および OpenID Connect というモダンな認証標準で採用されている方法で、クライアントに許可する権限を管理者やユーザーが事前に同意している必要があるため、その範囲を超えたアクセスは許可されないという最小権限によるリソースアクセスを実装できる利点があります。

この辺の話はスキップしますが、下記の URL に整理されているので一応載せておきます。
https://learn.microsoft.com/ja-jp/azure/active-directory/develop/v2-overview

API は "アプリケーション" のアクセス許可を利用

API のリファレンスを見ていると、アクセス許可の種類として "委任" と "アプリケーション" の 2 つがあることに気づくと思います。

簡単に説明すると、"委任" は権限同意をする主体はユーザー自身で、"そのユーザーの情報に限って" 許可されたリソースにアクセスできるという方法です。

"アプリケーション" はテナント全体のコンテキストで許可されたリソースにアクセスできます。そのため、このアクセス許可を設定できるのは Azure AD の管理者だけです。各種ドキュメントでは "デーモン" や "デーモンアプリ" という表現で登場するときもあります。

セキュリティ運用という文脈 (特に自動化が目的である場合) ではテナント全体の情報にアクセスしたい場合がほとんどだと思いますので、基本的に "アプリケーション" のアクセス許可を利用することになります。

以降の説明はすべて "アプリケーション" の種類のアクセス許可を利用することを前提としています。

API 利用ステップ

API の利用方法は様々な記事やブログで紹介されているので割愛しますが、Azure AD においては大まかに下記のようなステップで各種 API を利用します。

Azure AD にアプリ登録する ⇒ クライアント ID とシークレットを生成
登録したアプリに API へのアクセス許可を設定する ⇒ どんな操作 (read/write など) を許可するかを設定
アクセストークンを取得する ⇒ 1 で生成したクライアント ID とシークレットを使用してアクセストークンを取得
API を利用する ⇒ 3 で取得したアクセストークンを使用して目的の API をコール

上記 2 のアクセス許可では前述のように "委任" ではなく "アプリケーション" を選択することをお忘れなく。

便利な API 3 選

前置きが長くなりましたが、セキュリティ運用で使える便利な API を 3 つご紹介します。

前提

Microsoft の API を使用するには、その裏で動作しているソリューションのライセンスが必要になります。Microsoft 365 E5 を持っていれば完璧です。
Advanced hunting を利用する場合には、Microsoft 365 Defender (https://security.microsoft.com) の Hunting > Advanced hunting に 1 回以上アクセスして最初に機能を有効化しておく必要があります。

1. userRegistrationDetails

こちらは 2022/12/25 現在は beta しか提供されていませんが、各ユーザーが MFA の登録が完了しているかどうかや、MFA の方法として何を登録しているか (アプリ、電話、Windows Hello for Business など)、また既定の方法は何かなどの情報を取得できます。

特にいいなと思う点は、この API で取得できる情報の中に "管理者かどうか" や "メンバーであるか (ゲストであるか)" というフラグも含まれていることです。
このようなフラグがあることで、「管理者で MFA の登録が完了していないのは誰だろう」「メンバーの中で MFA の登録が完了していないのは誰だろう」といった分析に必要なデータをこの API だけで取得できます。

さらにいいなと思う点は、この API で取得されるデータは Azure AD 上でサインインがブロックされていないユーザーに限定されている点です。
つまり、現時点で使用していないアカウントがある場合、サインインをブロックするとこの API ではデータが取得されなくなるので、実質的にリスクのあるユーザー (サインインがブロックされておらず、かつ MFA 未登録のユーザー) のみを取得できます。

こちらの API を使用して MFA 登録状況を分析してユーザーに登録を促していくことで、認証のセキュアスコアを向上させることができます。

Endpoint：https://graph.microsoft.com/beta/reports/authenticationMethods/userRegistrationDetails/
Reference：https://learn.microsoft.com/ja-jp/graph/api/authenticationmethodsroot-list-userregistrationdetails

アクセス許可

リクエスト例

GET https://graph.microsoft.com/beta/reports/authenticationMethods/userRegistrationDetails

レスポンス例

HTTP/1.1 200 OK
Content-Type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#reports/authenticationMethods/userRegistrationDetails",
    "value": [
        {
            "id": "c8096958-797c-44fa-8fde-a6fb62567cf0",
            "userPrincipalName": "tarot@contoso.com",
            "userDisplayName": "田中 太郎",
            "isSsprRegistered": true,
            "isSsprEnabled": true,
            "isSsprCapable": true,
            "isMfaRegistered": true,
            "isMfaCapable": true,
            "isPasswordlessCapable": true,
            "methodsRegistered": [
                "mobilePhone",
                "microsoftAuthenticatorPush",
                "softwareOneTimePasscode",
                "windowsHelloForBusiness"
            ],
            "defaultMethod": "microsoftAuthenticatorPush"
        }
    ]
}

2. runHuntingQuery

半年ほど前に beta として使用できるようになり、比較的最近リリースされた Graph API の 1 つです。Microsoft 365 Defender のデータを Kusto クエリを用いて取得することができます。
例えば、取得できる情報としては下記のようなものがあります。(一部)

アラート情報
ユーザー情報
サインインイベント
クラウドアプリのイベント
メールイベント
メールの添付ファイルの情報
メールの URL の情報
URL クリックの情報 (SafeLinks の設定必要)
デバイス情報 (MDE オンボード必要)
デバイスのネットワークイベント
デバイスのファイルイベント
デバイスのプロセスイベント
デバイスの脆弱性情報

上記のような認証、アプリ、メール、デバイスなどの様々なデータに単一の方法でアクセスすることができ、Kusto クエリを用いて柔軟なデータ取得が可能になります。

難点としては Kusto クエリとセットでリクエストする必要があるので、普段クエリを書かない人にとっては少しハードルがあると思います。しかし、普段から Microsoft Sentinel などで KQL を書いている人にとってはめちゃくちゃ使える API です。

Endpoint：https://graph.microsoft.com/v1.0/security/runHuntingQuery
Reference：https://learn.microsoft.com/ja-jp/graph/api/security-security-runhuntingquery

アクセス許可

リクエスト例

POST https://graph.microsoft.com/v1.0/security/runHuntingQuery

{
    "Query": "DeviceProcessEvents | project Timestamp, FileName, InitiatingProcessFileName"
}

レスポンス例

HTTP/1.1 200 OK
Content-type: application/json

{
    "schema": [
        {
            "Name": "Timestamp",
            "Type": "DateTime"
        },
        {
            "Name": "FileName",
            "Type": "String"
        },
        {
            "Name": "InitiatingProcessFileName",
            "Type": "String"
        }
    ],
    "results": [
        {
            "Timestamp": "2020-08-30T06:38:35.7664356Z",
            "FileName": "conhost.exe",
            "InitiatingProcessFileName": "powershell.exe"
        },
        {
            "Timestamp": "2020-08-30T06:38:30.5163363Z",
            "FileName": "conhost.exe",
            "InitiatingProcessFileName": "powershell.exe"
        }
    ]
}

3. Office 365 management activity API

上で紹介した 2 つは Graph API ですが、ここで紹介するのは Office 365 の監査ログを取得する API です。

Office 365 の API をセキュリティ運用で使用できる大きな理由は Endpoint DLP のログを取得できるからです。
Endpoint DLP は Microsoft 365 コンプライアンスの機能で、デバイス上からのデータ持ち出しを監査したりブロックしたりできます。例えば、USB へのコピーやクラウドへのアップロード、印刷などのログを取得したりブロックしたりといった感じです。

アクセストークンを使用するという意味では他の API と同じですが、ContentUri を取得してから実際のコンテンツ取得を行うなどの独特のお作法がありちょっと使いにくいのですが、Endpoint DLP が出力するログはセキュリティの分析という観点では非常に有効であり、今のところこのログを取得できる唯一の API であることからよく使用します。

Office 365 の様々なログが取得されるのですが、Endpoint DLP のログはレコードタイプ 63 というタイプで取得されます。

どのようなログを取得できるかについては下記の URL をご確認ください。
https://learn.microsoft.com/ja-jp/office/office-365-management-api/office-365-management-activity-api-schema#enum-auditlogrecordtype---type-edmint32

Endpoint：https://manage.office.com/
Reference：https://learn.microsoft.com/ja-jp/office/office-365-management-api/office-365-management-activity-api-reference

アクセス許可

リクエスト例 (contentUri 取得)

GET https://manage.office.com/api/v1.0/27e53040-58ee-440b-9e18-3cd1490b51c0/activity/feed/subscriptions/content?contentType=Audit.General&PublisherIdentifier=900c0ffa-3945-4a8c-a73e-0d32c07e9bd6&startTime=2023-01-01T00:00:00Z&endTime=2023-01-01T01:00:00Z

レスポンス例 (contentUri 取得)

HTTP/1.1 200 OK
Content-type: application/json

{
    "body": [
        {
            "contentUri": "https://manage.office.com/api/v1.0/27e53040-58ee-440b-9e18-3cd1490b51c0/activity/feed/audit/2023010100000000$2023010101000000$audit_general$Audit_General$jpn0015",
            "contentId": "2023010100000000$2023010101000000$audit_general$Audit_General$jpn0015",
            "contentType": "Audit.General",
            "contentCreated": "2023-01-01T00:01:30.000Z",
            "contentExpiration": "2023-01-06T23:59:33.000Z"
        }
    ]
}

リクエスト例 (Content 取得)

GET https://manage.office.com/api/v1.0/27e53040-58ee-440b-9e18-3cd1490b51c0/activity/feed/audit/2023010100000000$2023010101000000$audit_general$Audit_General$jpn0015

レスポンス例 (Content 取得)

HTTP/1.1 200 OK
Content-type: application/json

{
	"body": [
		{
			"SensitiveInfoTypeData": [],
			"SourceLocationType": 1,
			"Platform": 1,
			"Application": "chrome.exe",
			"FileExtension": "pdf",
			"DeviceName": "contosopc1",
			"MDATPDeviceId": "1dd62132c813f8f9b98919e36a041a3879e65072",
			"Sha1": "8c561f2ebac98a1f3fbf3d7b2f21e2784fbc8bfc",
			"Sha256": "44bac88e6343636266028651bfd9e2222a04a188ec0c037a730b757b7fcd9da7",
			"EnforcementMode": 1,
			"TargetPrinterName": "",
			"TargetDomain": "drive.google.com",
			"FileSize": 90600,
			"FileType": "PDF",
			"RMSEncrypted": false,
			"Hidden": false,
			"DlpAuditEventMetadata": {
				"DlpPolicyMatchId": "",
				"EvaluationTime": ""
			},
			"JitTriggered": false,
			"EvidenceFile": {
				"StorageName": "",
				"FullUrl": ""
			},
			"ObjectId": "C:\\Users\\username\\Downloads\\機密情報.pdf",
			"UserId": "tarot@contoso.com",
			"ClientIP": "10.10.10.10",
			"Id": "13bc250d-0a84-4f75-b79d-4980b9d488c8",
			"RecordType": 63,
			"CreationTime": "2023-01-01T00:33:47",
			"Operation": "FileUploadedToCloud",
			"OrganizationId": "27e53040-58ee-440b-9e18-3cd1490b51c0",
			"UserType": 0,
			"UserKey": "452ce3d4-8b15-4679-7751-06d3809c5b9b",
			"Workload": "Endpoint",
			"Version": 1,
			"Scope": 1
		}
	]
}

おわりに

本記事では Microsoft セキュリティの運用で使える API の紹介と、その中でも特に便利だと感じている API を 3 つ紹介しました。
ステップバイステップでの API 利用方法についてはたくさん記事が見つかりますが、Microsoft セキュリティの運用という観点から API を網羅的にまとめた記事はあまりないと思いますので、本ブログがお役に立てますと幸いです。

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up

Microsoft セキュリティの運用で使える便利な API ３選

目次

はじめに

API を制する者が運用を制する？

Microsoft セキュリティ運用で使える API の種類

Microsoft Graph API

Office 365 Management Activity API

Microsoft 365 Defender API

Microsoft Defender for Endpoint API

Microsoft Sentinel REST API

Defender for Cloud Apps REST API

Intune Data Warehouse API

Log Analytics REST API

Log Analytics Data Collector API

API の基本的な使用方法

API は "アプリケーション" のアクセス許可を利用

API 利用ステップ

便利な API 3 選

前提

1. userRegistrationDetails

アクセス許可

リクエスト例

レスポンス例

2. runHuntingQuery

アクセス許可

リクエスト例

レスポンス例

3. Office 365 management activity API

アクセス許可

リクエスト例 (contentUri 取得)

レスポンス例 (contentUri 取得)

リクエスト例 (Content 取得)

レスポンス例 (Content 取得)

おわりに