REST API を使用して Windows Defender ATP のアラートをプルする

適用対象

Windows Defender ATP をご試用になる場合は、 無料試用版にサインアップしてください。

Windows Defender ATP は、ポータルからアラートをプルする OAuth 2.0 プロトコルをサポートしています。

一般に、OAuth 2.0 プロトコルは、4 種類のフローをサポートしています。

  • 承認付与フロー
  • 暗黙的なフロー
  • クライアント資格情報フロー
  • リソース オーナー フロー

OAuth の仕様について詳しくは、「OAuth の Web サイト」をご覧ください。

Windows Defender ATP は、Azure Active Directory (AAD) を認証サーバーとして使用して、ポータルから一般的なアラートへのアクセスを取得するための_承認付与フロー_と_クライアント資格情報フロー_をサポートしています。

_承認付与フロー_は、ユーザー資格情報を使用して承認コードを取得します。次にこれはアクセス トークンを取得するために使用されます。

_クライアント資格情報フロー_は、クライアントの資格情報を使用して、Windows Defender ATP エンドポイント URL に対して認証を行います。 このフローは、OAuth クライアントが、ユーザー資格情報を必要としない API への要求を作成するシナリオに適しています。

Windows Defender ATP API で次の方法を使って、JSON 形式でアラートをプルします。

注意

Windows Defender セキュリティ センターでは、アラートと同様の検出を 1 つのアラートにマージします。 この API は、独自グループ化とフィルターを適用することを有効にする設定すると、クエリ パラメーターに基づいて、生の形式でアラートの検出をプルします。

開始する前に

  • Windows Defender ATP エンドポイントを呼び出してアラートをプルする前に、Azure Active Directory (AAD) で SIEM 統合アプリケーションを有効にする必要があります。 詳しくは、「Windows Defender ATP で SIEM 統合を有効にする」をご覧ください。

  • Azure アプリケーション登録で、次の値を記録します。 これらの値を使って、サービスまたはデーモン アプリで、OAuth フローを構成する必要があります。

    • アプリケーション ID (アプリケーションに固有)
    • アプリ キーまたはシークレット (アプリケーションに固有)
    • アプリの OAuth 2.0 トークン エンドポイント
      • Azure 管理ポータルの下部のアプリのページで [エンドポイントの表示] をクリックして、この値を見つけます。 エンドポイントは次の例のように表示されます: https://login.microsoftonline.com/{tenantId}/oauth2/token

アクセス トークンを取得する

エンドポイントへの呼び出しを作成する前に、アクセス トークンを取得する必要があります。

アクセス トークンを使って保護されたリソースにアクセスします。ここでは Windows Defender ATP のアラートです。

アクセス トークンを取得するには、トークン発行エンドポイントに POST 要求を行う必要があります。 要求の例を次に示します。


POST /72f988bf-86f1-41af-91ab-2d7cd011db47/oauth2/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

resource=https%3A%2F%2Fgraph.windows.net&client_id=35e0f735-5fe4-4693-9e68-3de80f1d3745&client_secret=IKXc6PxB2eoFNJ%2FIT%2Bl2JZZD9d9032VXz6Ul3D2WyUQ%3D&grant_type=client_credentials

応答にはアクセス トークンと有効期限の情報が含まれます。

{
  "token_type": "Bearer",
  "expires_in": "3599",
  "ext_expires_in": "0",
  "expires_on": "1488720683",
  "not_before": "1488720683",
  "resource": "https://graph.windows.net",
  "access_token":"eyJ0eXaioJJOIneiowiouqSuzNiZ345FYOVkaJL0625TueyaJasjhIjEnbMlWqP..."
}

Windows Defender ATP API への要求の access_token フィールドで、値を使えるようになりました。

要求

アプリはアクセス トークンを使用して、Windows Defender ATP API への認証された要求を行うことができます。 アプリでは、各要求の承認ヘッダーにアクセス トークンを追加する必要があります。

要求の構文

メソッド 要求 URI
GET 地域に該当する URI を使用します。

EU の場合: https://wdatp-alertexporter-eu.windows.com/api/alerts
米国の場合: https://wdatp-alertexporter-us.windows.com/api/alerts

要求ヘッダー

ヘッダー 説明
Authorization string 必須。 Bearer <トークン> という形式の Azure AD アクセス トークン。

要求パラメーター

オプションのクエリ パラメーターを使用して、応答で返されるデータの量を指定して制御します。 パラメーターを指定せずには、このメソッドを呼び出す場合、応答には、最後の 2 時間で、組織内のすべてのアラートが含まれています。

名前 説明
DateTime?sinceTimeUtc 文字列 バインドされたアラートを取得、フィールドに基づく低い時間を定義します。
LastProcessedTimeUtc
時間の範囲になります: から sinceTimeUtc 時刻を現在の時刻。

注:: 指定しない場合、最近の 2 時間以内に生成されたすべてのアラートを取得します。
DateTime かどうか untilTimeUtc。 string バインドされたアラートを取得上の時間を定義します。
時間の範囲になります: からsinceTimeUtcまでの時間untilTimeUtc時間。

: 既定値が、現在の時刻になりますが指定されていないときです。
前の文字列 string 次の時間範囲内でアラートをプル: から(current_time - ago)までの時間current_time時間。

ISO 8601形式の継続時間に基づいて値を設定する必要があります。
例: ago=PT10M 過去 10 分後に受信したアラートを取得します。
int?limit 整数 取得するアラートの数を定義します。 定義された数に基づき、最近のアラートを取得します。

注:: 指定しない場合、時間の範囲内で利用可能なすべてのアラートを取得します。
machinegroups String アラートをプルするには、コンピューターのグループを指定します。

: 指定しない場合、すべてのコンピューター グループからのアラートを取得します。

例:

https://wdatp-alertexporter-eu.securitycenter.windows.com/api/Alerts/?machinegroups=UKMachines&machinegroups=FranceMachines
DeviceCreatedMachineTags string レジストリから 1 つのコンピューターのタグ。
CloudCreatedMachineTags string Windows Defender セキュリティ センターで作成されたコンピューターのタグ。

要求の例

次の例は、組織内のすべてのアラートを取得する方法を示しています。

GET  https://wdatp-alertexporter-eu.windows.com/api/alerts
Authorization: Bearer <your access token>

次の例は、2016 年 9 月 12 日 0 時 0 分 0 秒以降の、最近 20 個のアラートを取得する要求です。

GET  https://wdatp-alertexporter-eu.windows.com/api/alerts?limit=20&sinceTimeUtc=2016-09-12T00:00:00.000
Authorization: Bearer <your access token>

応答

戻り値は、アラート オブジェクトの JSON 形式の配列です。

戻り値の例を次に示します。

{"AlertTime":"2017-01-23T07:32:54.1861171Z",
"ComputerDnsName":"desktop-bvccckk",
"AlertTitle":"Suspicious PowerShell commandline",
"Category":"SuspiciousActivity",
"Severity":"Medium",
"AlertId":"636207535742330111_-1114309685",
"Actor":null,
"LinkToWDATP":"https://securitycenter.windows.com/alert/636207535742330111_-1114309685",
"IocName":null,
"IocValue":null,
"CreatorIocName":null,
"CreatorIocValue":null,
"Sha1":"69484ca722b4285a234896a2e31707cbedc59ef9",
"FileName":"powershell.exe",
"FilePath":"C:\\Windows\\SysWOW64\\WindowsPowerShell\\v1.0",
"IpAddress":null,
"Url":null,
"IoaDefinitiondId":"7f1c3609-a3ff-40e2-995b-c01770161d68",
"UserName":null,
"AlertPart":0,
"FullId":"636207535742330111_-1114309685:9DE735BA9FF87725E392C6DFBEB2AF279035CDE229FCC00D28C0F3242C5A50AF",
"LastProcessedTimeUtc":"2017-01-23T11:33:45.0760449Z",
"ThreatCategory":null,
"ThreatFamily":null,
"ThreatName":null,
"RemediationAction":null,
"RemediationIsSuccess":null,
"Source":"Windows Defender ATP",
"Md5":null,
"Sha256":null,
"WasExecutingWhileDetected":null,
"FileHash":"69484ca722b4285a234896a2e31707cbedc59ef9",
"IocUniqueId":"9DE735BA9FF87725E392C6DFBEB2AF279035CDE229FCC00D28C0F3242C5A50AF"}

コード例

アクセス トークンを取得する

次のコード例は、アクセス トークンを取得し、Windows Defender ATP API を呼び出す方法を示しています。

AuthenticationContext context = new AuthenticationContext(string.Format("https://login.windows.net/{0}/oauth2", tenantId));
ClientCredential clientCredentials = new ClientCredential(clientId, clientSecret);
AuthenticationResult authenticationResult  = context.AcquireToken(resource, clientCredentials);

トークンを使用してアラート エンドポイントに接続する

HttpClient httpClient = new HttpClient();
httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(authenticationResult.AccessTokenType, authenticationResult.AccessToken);
HttpResponseMessage response = httpClient.GetAsync("https://wdatp-alertexporter-eu.windows.com/api/alert").GetAwaiter().GetResult();
string alertsJson = response.Content.ReadAsStringAsync().Result;
Console.WriteLine("Got alert list: {0}", alertsJson);

エラー コード

Windows Defender ATP REST API は、無効な要求によって、次のエラー コードを返します。

HTTP エラー コード 説明
401 無効な要求、またはトークンが無効です。
403 未承認例外 - ドメインのいずれかがテナント管理者によって管理されていないか、またはテナントの状態が削除されています。
500 サービスのエラーです。

関連トピック