Olvasás angol nyelven

Megosztás a következőn keresztül:


„Helló világ!” alkalmazás Microsoft Defender XDR REST API-hoz

Érintett szolgáltatás:

  • Microsoft Defender XDR

Fontos

Bizonyos információk az előzetesen forgalomba hozott termékre vonatkoznak, amely a kereskedelmi forgalomba kerülés előtt lényegesen módosulhat. A Microsoft nem vállal semmilyen, kifejezett vagy vélelmezett jótállást az itt megadott információkra vonatkozóan.

Incidensek lekérése egy egyszerű PowerShell-szkripttel

A projekt végrehajtása 5–10 percet vesz igénybe. Ez az időbecslés magában foglalja az alkalmazás regisztrálását és a PowerShell-mintaszkriptből származó kód alkalmazását.

Alkalmazás regisztrálása Microsoft Entra ID

  1. Jelentkezzen be az Azure-ba.

  2. Lépjen a Microsoft Entra ID>Alkalmazásregisztrációk>Új regisztráció elemre.

    Az Új regisztráció szakasz a Microsoft Defender portálon

  3. A regisztrációs űrlapon válassza ki az alkalmazás nevét, majd válassza a Regisztráció lehetőséget. Az átirányítási URI kiválasztása nem kötelező. A példa végrehajtásához nincs szükség rá.

  4. Az alkalmazás oldalán válassza az API-engedélyek>Engedély hozzáadása>API-kat>, írja be a Microsoft Threat Protection kifejezést, majd válassza a Microsoft Threat Protection lehetőséget. Az alkalmazás most már hozzáférhet Microsoft Defender XDR.

    Tipp.

    A Microsoft Threat Protection a Microsoft Defender XDR korábbi neve, és nem jelenik meg az eredeti listában. A megjelenítendő szövegmezőbe be kell írnia a nevét. Az API-k használatának szakasza a Microsoft Defender portalon

    • Válassza az Application permissions>Incident.Read.All elemet, majd az Engedélyek hozzáadása lehetőséget.

      Egy alkalmazás engedélypanelje a Microsoft Defender portálon

  5. Válassza a Rendszergazdai hozzájárulás megadása lehetőséget. Minden alkalommal, amikor hozzáad egy engedélyt, a rendszergazdai hozzájárulás megadása lehetőséget kell választania ahhoz, hogy érvénybe lépjen.

    A Rendszergazdai hozzájárulás megadása szakasz a Microsoft Defender portálon

  6. Adjon hozzá egy titkos kódot az alkalmazáshoz. Válassza a Tanúsítványok & titkos kulcsok lehetőséget, adjon hozzá egy leírást a titkos kódhoz, majd válassza a Hozzáadás lehetőséget.

    Tipp.

    A Hozzáadás lehetőség kiválasztása után válassza a létrehozott titkos kód értékének másolása lehetőséget. A kilépés után nem fogja tudni lekérni a titkos kulcsot.

    A titkos kód hozzáadása szakasz a Microsoft Defender portálon

  7. Jegyezze fel az alkalmazásazonosítót és a bérlőazonosítót biztonságos helyen. Ezek az alkalmazásoldal Áttekintés területén jelennek meg.

    A Microsoft Defender portál Áttekintés szakasza

Jogkivonat lekérése az alkalmazással, és a jogkivonat használata az API eléréséhez

A Microsoft Entra tokenekről az Microsoft Entra oktatóanyagban talál további információt.

Fontos

Bár az ebben a bemutatóalkalmazásban szereplő példa arra ösztönzi, hogy tesztelési célokra illessze be a titkos kulcs értékét, soha ne kódoljon titkos kódokat egy éles környezetben futó alkalmazásba. Egy harmadik fél felhasználhatja az Ön titkos kódját az erőforrások eléréséhez. Az Azure Key Vault segítségével biztonságban tarthatja az alkalmazás titkos kulcsát. Az alkalmazás védelmének gyakorlati példájáért lásd: Titkos kódok kezelése a kiszolgálóalkalmazásokban az Azure Key Vault használatával.

  1. Másolja ki az alábbi szkriptet, és illessze be a kedvenc szövegszerkesztőjébe. Mentse Get-Token.ps1néven. A kódot a PowerShell ISE-ben is futtathatja, de érdemes mentenie, mert a következő szakaszban az incidenslehívási szkript használatakor újra le kell futtatnunk.

    Ez a szkript létrehoz egy jogkivonatot, és menti azt a Latest-token.txtnevű munkamappába.

    # This script gets the app context token and saves it to a file named "Latest-token.txt" under the current directory.
    # Paste in your tenant ID, client ID and app secret (App key).
    
    $tenantId = '' # Paste your directory (tenant) ID here
    $clientId = '' # Paste your application (client) ID here
    $appSecret = '' # # Paste your own app secret here to test, then store it in a safe place!
    
    $resourceAppIdUri = 'https://api.security.microsoft.com'
    $oAuthUri = "https://login.windows.net/$tenantId/oauth2/token"
    $authBody = [Ordered] @{
      resource = $resourceAppIdUri
      client_id = $clientId
      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
    

A jogkivonat ellenőrzése

  1. Másolja és illessze be a kapott jogkivonatot a JWT-be a dekódolásához.

  2. A JWT a JSON Web Token rövidítése. A dekódolt jogkivonat számos JSON-formátumú elemet vagy jogcímet fog tartalmazni. Győződjön meg arról, hogy a dekódolt jogkivonaton belüli szerepkörjogcím tartalmazza a kívánt engedélyeket.

    Az alábbi képen egy alkalmazásból beszerzett dekódolt jogkivonatot láthat, amely Incidents.Read.Alla , Incidents.ReadWrite.Alla és AdvancedHunting.Read.All az engedélyekkel rendelkezik:

    A dekódolt jogkivonat szakasz a Microsoft Defender portálon

A legutóbbi incidensek listájának lekérése

Az alábbi szkript Get-Token.ps1 fogja használni az API eléréséhez. Ezután lekéri az elmúlt 48 órában legutóbb frissített incidensek listáját, és JSON-fájlként menti a listát.

Fontos

Mentse a szkriptet ugyanabban a mappában, amelybeGet-Token.ps1mentette.

# This script returns incidents last updated within the past 48 hours.

$token = ./Get-Token.ps1

# Get incidents from the past 48 hours.
# The script may appear to fail if you don't have any incidents in that time frame.
$dateTime = (Get-Date).ToUniversalTime().AddHours(-48).ToString("o")

# This URL contains the type of query and the time filter we created above.
# Note that `$filter` does not refer to a local variable in our script --
# it's actually an OData operator and part of the API's syntax.
$url = "https://api.security.microsoft.com/api/incidents`?`$filter=lastUpdateTime+ge+$dateTime"

# Set the webrequest headers
$headers = @{
    'Content-Type' = 'application/json'
    'Accept' = 'application/json'
    'Authorization' = "Bearer $token"
}

# Send the request and get the results.
$response = Invoke-WebRequest -Method Get -Uri $url -Headers $headers -ErrorAction Stop

# Extract the incidents from the results.
$incidents =  ($response | ConvertFrom-Json).value | ConvertTo-Json -Depth 99

# Get a string containing the execution time. We concatenate that string to the name 
# of the output file to avoid overwriting the file on consecutive runs of the script.
$dateTimeForFileName = Get-Date -Format o | foreach {$_ -replace ":", "."}

# Save the result as json
$outputJsonPath = "./Latest Incidents $dateTimeForFileName.json"

Out-File -FilePath $outputJsonPath -InputObject $incidents

Minden elkészült! Sikeresen elvégezte a következőt:

  • Létrehozott és regisztrált egy alkalmazást.
  • Engedélyt adott az alkalmazásnak a riasztások olvasására.
  • Csatlakozva az API-hoz.
  • Egy PowerShell-szkripttel visszaadta az elmúlt 48 órában frissített incidenseket.

Tipp.

Szeretne többet megtudni? Lépjen kapcsolatba a Microsoft biztonsági közösségével a technikai közösségünkben: Microsoft Defender XDR Tech Community.