使用適用於端點Microsoft Defender API

文章
06/25/2024

適用於：

重要事項

商務用Defender不包含進階搜捕功能。

想要體驗適用於端點的 Microsoft Defender 嗎？注册免費試用版。

注意事項

如果您是美國政府客戶，請使用適用於美國政府客戶的 Microsoft Defender 中所列的 URI。

提示

為了獲得更好的效能，您可以使用更接近您地理位置的伺服器：

us.api.security.microsoft.com
eu.api.security.microsoft.com
uk.api.security.microsoft.com
au.api.security.microsoft.com
swa.api.security.microsoft.com
ina.api.security.microsoft.com

此頁面描述如何建立應用程式，以程式設計方式代表使用者存取適用於端點的 Defender。

如果您需要以程式設計方式存取 Microsoft適用於端點的 Defender，而沒有使用者，請參閱使用應用程式內容存取適用於端點Microsoft Defender。

如果您不確定需要哪一個存取權，請閱讀簡介頁面。

Microsoft適用於端點的 Defender 會透過一組程式設計 API 公開其大部分的數據和動作。這些 API 可讓您根據適用於端點的 Microsoft Defender 功能，將工作流程自動化並進行創新。 API 存取需要 OAuth2.0 驗證。如需詳細資訊，請參閱 OAuth 2.0 授權碼流程。

一般而言，您需要採取下列步驟來使用 API：

建立 Microsoft Entra 應用程式
使用此應用程式取得存取令牌
使用令牌存取適用於端點的Defender API

此頁面說明如何建立 Microsoft Entra 應用程式、取得適用於端點的 Defender Microsoft存取令牌，以及驗證令牌。

注意事項

代表使用者存取 Microsoft Defender for Endpoint API 時，您需要正確的應用程式許可權和用戶權力。如果您不熟悉適用於端點Microsoft Defender 上的用戶權力，請參閱使用角色型訪問控制管理入口網站存取。

提示

如果您具有在入口網站中執行動作的許可權，您就有許可權可在 API 中執行動作。

建立應用程式

登入 Azure 入口網站。
流覽至 [Microsoft登錄][應用程式>註冊>][新增註冊]。

當 [ 註冊應用程式] 頁面出現時，輸入應用程式的註冊資訊：

名稱 - 輸入對應用程式用戶顯示的有意義的應用程式名稱。

支援的帳戶類型 - 選取您希望應用程式支援的帳戶。

支援的帳戶類型	描述
僅限此組織目錄中的帳戶	如果您要建置企業營運 (LOB) 應用程式，請選取此選項。如果您未在目錄中註冊應用程式，則無法使用此選項。此選項會對應至僅限 Entra-Microsoft單一租使用者。除非您在目錄外部註冊應用程式，否則此選項是預設選項。如果應用程式在目錄外部註冊，預設值為 Microsoft多租用戶和個人Microsoft帳戶。
任何組織目錄中的帳戶	如果您想要以所有商務和教育客戶為目標，請選取此選項。此選項會對應至僅限Microsoft租使用者。如果您將應用程式註冊為 Microsoft 僅限 Entra 單一租使用者，您可以將其更新為 Microsoft Entra 多租使用者，並透過 [ 驗證 ] 刀鋒視窗回到單一租使用者。
任何組織目錄和個人Microsoft帳戶中的帳戶	選取此選項以將目標設為最廣泛的客戶集合。此選項會對應至Microsoft多租用戶和個人Microsoft帳戶。如果您將應用程式註冊為 Microsoft多租使用者和個人Microsoft帳戶，則無法在 UI 中變更此專案。相反地，您必須使用應用程式指令清單編輯器來變更支援的帳戶類型。

重新導向 URI (選擇性) - 選取您要建置的應用程式類型、 Web 或 公用用戶端 (行動 & 桌面) ，然後輸入應用程式的重新導向 URI (或回復 URL) 。
- 針對 Web 應用程式，提供您應用程式的基底 URL。例如， http://localhost:31544 可能是在本機電腦上執行之 Web 應用程式的 URL。使用者會使用此 URL 來登入 Web 用戶端應用程式。
- 針對公用用戶端應用程式，提供 Microsoft Entra ID 用來傳回令牌回應的 URI。輸入應用程式特定的值，例如 myapp://auth。
若要查看 Web 應用程式或原生應用程式的特定範例，請參閱我們的快速入門。

完成時，選取 [ 註冊]。

允許您的應用程式存取適用於端點Microsoft Defender，並指派其「讀取警示」許可權：
- 在應用程式頁面上，選取 [API 許可權>][新增許可權>API 我的組織使用> 類型 WindowsDefenderATP ]，然後在 WindowsDefenderATP 上選取。
  
  注意事項
  
  WindowsDefenderATP 不會出現在原始清單中。開始在文字框中寫入其名稱，以查看其出現。
- 選擇 [委派的>許可權警示]。讀>取 [新增許可權]。
重要事項

選取相關的許可權。讀取警示只是一個範例。

例如：
- 若要執行進階查詢，請選取 [ 執行進階查詢權 限]。
- 若要隔離裝置，請選取 [隔離機器 許可權]。
- 若要判斷您需要的許可權，請在您想要呼叫的 API 中檢視 [許可權] 區段。
- 選 取 [授與同意]。
  
  注意事項
  
  每次新增許可權時，您都必須選取 [ 授與同意 ]，新許可權才會生效。
記下您的應用程式識別碼和租用戶標識碼。

在您的應用程式頁面上，移至 [ 概觀 ] 並複製下列資訊：

取得存取權杖

如需Microsoft Entra 令牌的詳細資訊，請參閱 Microsoft Entra 教學課程。

使用 C#

在應用程式中複製/貼上下列類別。

使用 AcquireUserTokenAsync 方法搭配您的應用程式識別碼、租使用者標識碼、使用者名稱和密碼來取得令牌。

namespace WindowsDefenderATP
{
    using System.Net.Http;
    using System.Text;
    using System.Threading.Tasks;
    using Newtonsoft.Json.Linq;

    public static class WindowsDefenderATPUtils
    {
        private const string Authority = "https://login.microsoftonline.com";

        private const string WdatpResourceId = "https://api.securitycenter.microsoft.com";

        public static async Task<string> AcquireUserTokenAsync(string username, string password, string appId, string tenantId)
        {
            using (var httpClient = new HttpClient())
            {
                var urlEncodedBody = $"resource={WdatpResourceId}&client_id={appId}&grant_type=password&username={username}&password={password}";

                var stringContent = new StringContent(urlEncodedBody, Encoding.UTF8, "application/x-www-form-urlencoded");

                using (var response = await httpClient.PostAsync($"{Authority}/{tenantId}/oauth2/token", stringContent).ConfigureAwait(false))
                {
                    response.EnsureSuccessStatusCode();

                    var json = await response.Content.ReadAsStringAsync().ConfigureAwait(false);

                    var jObject = JObject.Parse(json);

                    return jObject["access_token"].Value<string>();
                }
            }
        }
    }
}

驗證令牌

請確認您已取得正確的權杖：

將您在上一個步驟中取得的令牌複製/貼到 JWT 中，以便將它譯碼。
驗證您取得具有所需應用程式許可權的『scp』宣告。
在下列螢幕快照中，您可以在教學課程中看到從應用程式取得的已譯碼令牌：

使用令牌存取適用於端點Microsoft Defender API

選擇您想要使用的 API - 支援Microsoft適用於端點的 Defender API。
在您傳送至「Bearer {token}」的 HTTP 要求中設定 Authorization 標頭 (Bearer 是授權配置) 。
令牌的到期時間為 1 小時， (您可以傳送多個具有相同令牌) 的要求。

使用 C# 傳送要求以取得警示清單的範例：

var httpClient = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Get, "https://api.securitycenter.microsoft.com/api/alerts");

request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);

var response = httpClient.SendAsync(request).GetAwaiter().GetResult();

// Do something useful with the response

另請參閱

提示

想要深入了解? 在我們的技術社群中與Microsoft安全性社群互動：Microsoft適用於端點的Defender技術社群。

分享方式：