Sdílet prostřednictvím


Microsoft Defender for Endpoint API – Hello World

Platí pro:

Chcete vyzkoušet Defender pro Endpoint? Zaregistrujte se a získejte bezplatnou zkušební verzi,

Poznámka

Pokud jste zákazníkem státní správy USA, použijte identifikátory URI uvedené v programu Microsoft Defender for Endpoint pro zákazníky státní správy USA.

Tip

Pro lepší výkon můžete použít server blíže k vašemu geografickému umístění:

  • 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

Získání upozornění pomocí jednoduchého skriptu PowerShellu

Jak dlouho trvá projít tímto příkladem?

Trvá to jenom 5 minut ve dvou krocích:

  • Registrace aplikace
  • Příklady použití: Vyžaduje pouze zkopírování a vložení krátkého skriptu PowerShellu.

Potřebuji oprávnění k připojení?

Pro fázi registrace aplikace musíte mít ve svém tenantovi Microsoft Entra přiřazenou roli Globální správce .

Krok 1 – vytvoření aplikace v Microsoft Entra ID

  1. Přihlaste se na portál Microsoft Azure.

  2. Přejděte na Microsoft Entra ID>Registrace> aplikacíNová registrace.

    Možnost Registrace aplikací v podokně Spravovat v Centru pro správu Microsoft Entra

  3. V registračním formuláři zvolte název vaší aplikace a pak vyberte Zaregistrovat.

  4. Povolte aplikaci přístup k Defenderu for Endpoint a přiřaďte jí oprávnění Číst všechna upozornění :

    • Na stránce vaší aplikace vyberte Oprávnění> rozhraní APIPřidatrozhraní API oprávnění>, která moje organizace používá>, zadejte WindowsDefenderATP a vyberte WindowsDefenderATP.

      Poznámka

      WindowsDefenderATP se nezobrazuje v původním seznamu. Aby se zobrazilo, musíte začít psát jeho název do textového pole.

      Možnost Oprávnění rozhraní API v podokně Spravovat v Centru pro správu Microsoft Entra

    • Zvolte Oprávnění> aplikaceAlert.Read.All a pak vyberte Přidat oprávnění.

      Typ oprávnění a podokna nastavení na stránce Požádat o oprávnění rozhraní API

      Důležité

      Musíte vybrat příslušná oprávnění. Číst všechna upozornění je jenom příklad.

      Příklady:

      • Pokud chcete spustit rozšířené dotazy, vyberte oprávnění Ke spouštění rozšířených dotazů.
      • Pokud chcete izolovat počítač, vyberte oprávnění Izolovat počítač.
      • Pokud chcete zjistit, jaké oprávnění potřebujete, přečtěte si část Oprávnění v rozhraní API, které vás zajímá volat.
  5. Vyberte Udělit souhlas.

    Poznámka

    Pokaždé, když přidáte oprávnění, musíte kliknout na Udělit souhlas , aby se nové oprávnění projevilo.

    Možnost udělení souhlasu s oprávněními v Centru pro správu Microsoft Entra

  6. Přidejte do aplikace tajný kód.

    Vyberte Certifikáty & tajných kódů, přidejte popis tajného kódu a vyberte Přidat.

    Důležité

    Po kliknutí na Přidat zkopírujte vygenerovanou hodnotu tajného kódu. Jakmile odejdete, nebudete moct načíst.

    Položka nabídky Certifikáty & tajné kódy v podokně Spravovat v Centru pro správu Microsoft Entra

  7. Poznamenejte si ID aplikace a ID tenanta.

    Na stránce aplikace přejděte na Přehled a zkopírujte následující:

    Podokno podrobností o aplikaci v položce nabídky Přehled v Centru pro správu Microsoft Entra

Hotovo! Úspěšně jste zaregistrovali aplikaci!

Krok 2 – Získání tokenu pomocí aplikace a použití tohoto tokenu pro přístup k rozhraní API

  • Zkopírujte následující skript do prostředí PowerShell ISE nebo do textového editoru a uložte ho jako Get-Token.ps1.

  • Spuštěním tohoto skriptu se vygeneruje token a uloží ho do pracovní složky pod názvem Latest-token.txt.

    # 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 = '' ### Paste your tenant ID here
    $appId = '' ### Paste your Application ID here
    $appSecret = '' ### 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
    
  • Kontrola sanity:

    • Spusťte skript.
    • V prohlížeči přejděte na: https://jwt.ms/.
    • Zkopírujte token (obsah souboru Latest-token.txt).
    • Vložte do horního pole.
    • Vyhledejte část role. Vyhledejte roli Alert.Read.All .

    Podokno Dekódovaný token pro jwt.ms

Pojďme získat upozornění!

  • Následující skript používá Get-Token.ps1 pro přístup k rozhraní API a dostává upozornění za posledních 48 hodin.

  • Uložte tento skript do stejné složky, kterou jste uložili předchozí skript Get-Token.ps1.

  • Skript vytvoří dva soubory (json a csv) s daty ve stejné složce jako skripty.

    # Returns Alerts created in the past 48 hours.
    
    $token = ./Get-Token.ps1       #run the script Get-Token.ps1  - make sure you are running this script from the same folder of Get-Token.ps1
    
    # Get Alert from the last 48 hours. Make sure you have alerts in that time frame.
    $dateTime = (Get-Date).ToUniversalTime().AddHours(-48).ToString("o")
    
    # The URL contains the type of query and the time filter we create above
    # Read more about [other query options and filters](get-alerts.md).
    $url = "https://api.securitycenter.microsoft.com/api/alerts?`$filter=alertCreationTime ge $dateTime"
    
    # Set the WebRequest headers
    $headers = @{
        'Content-Type' = 'application/json'
        Accept = 'application/json'
        Authorization = "Bearer $token"
    }
    
    # Send the webrequest and get the results.
    $response = Invoke-WebRequest -Method Get -Uri $url -Headers $headers -ErrorAction Stop
    
    # Extract the alerts from the results.
    $alerts =  ($response | ConvertFrom-Json).value | ConvertTo-Json
    
    # Get string with the execution time. We concatenate that string to the output file to avoid overwrite the file
    $dateTimeForFileName = Get-Date -Format o | foreach {$_ -replace ":", "."}
    
    # Save the result as json and as csv
    $outputJsonPath = "./Latest Alerts $dateTimeForFileName.json"
    $outputCsvPath = "./Latest Alerts $dateTimeForFileName.csv"
    
    Out-File -FilePath $outputJsonPath -InputObject $alerts
    ($alerts | ConvertFrom-Json) | Export-CSV $outputCsvPath -NoTypeInformation
    

Všechno je hotové! Úspěšně jste provedli následující:

  • Vytvoření a registrace a aplikace
  • Udělené oprávnění této aplikaci ke čtení upozornění
  • Připojení rozhraní API
  • Použití skriptu PowerShellu k vrácení upozornění vytvořených za posledních 48 hodin

Tip

Chcete se dozvědět více? Spojte se s komunitou zabezpečení Microsoftu v naší technické komunitě: Technická komunita Microsoft Defenderu for Endpoint.