Microsoft Defender for Endpoint-ohjelmointirajapinta – Hei maailma

Huomautus

Jos olet Yhdysvaltain valtionhallinnon asiakas, käytä Microsoft Defender for Endpoint lueteltuja URI-tunnuksia Yhdysvaltain valtionhallinnon asiakkaille.

Vihje

Paranna suorituskykyä api.security.microsoft.com käyttämisen sijaan käyttämällä palvelinta, joka on lähempänä maantieteellistä sijaintiasi:

• 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
• aea.api.security.microsoft.com

Hanki ilmoituksia yksinkertaisella PowerShell-komentosarjalla

Kuinka kauan esimerkin läpivienti kestää?

Se kestää vain 5 minuuttia kahdessa vaiheessa:

• Sovelluksen rekisteröinti
• Käytä esimerkkejä: vaatii vain lyhyen PowerShell-komentosarjan kopioinnin tai liittämisen

Tarvitsenko yhteyden muodostamiseen käyttöoikeuden?

Sovelluksen rekisteröintivaihetta varten sinulla on oltava asianmukainen rooli määritettynä Microsoft Entra vuokraajassasi. Lisätietoja rooleista on kohdassa Käyttöoikeusasetukset.

Vaihe 1 – Luo sovellus Microsoft Entra ID

1. Kirjaudu Azure-portaaliin.

2. Siirry kohtaan Microsoft Entra ID>Sovelluksen rekisteröinnit>Uusi rekisteröinti.

   

3. Valitse rekisteröintilomakkeessa sovellukselle nimi ja valitse sitten Rekisteröi.

4. Anna sovelluksesi käyttää Defender for Endpointia ja määritä sille Kaikkien ilmoitusten luku - oikeus:

   • Valitse sovellussivulla Ohjelmointirajapinnan käyttöoikeudetLisääkäyttöoikeus-ohjelmointirajapinnat>>, joita organisaationi käyttää > tyyppiä WindowsDefenderATP, ja valitse WindowsDefenderATP.

     Huomautus

     WindowsDefenderATP ei näy alkuperäisessä luettelossa. Sinun on alettava kirjoittaa sen nimeä tekstiruutuun, jotta näet sen näkyvän.

     

   • Valitse Sovelluksen käyttöoikeudet>Alert.Read.All ja valitse sitten Lisää käyttöoikeuksia.

     

     Tärkeää

     Sinun on valittava tarvittavat käyttöoikeudet. Lue kaikki ilmoitukset on vain esimerkki.

     Esimerkki:

     • Jos haluat suorittaa kehittyneitä kyselyitä, valitse Suorita kehittyneet kyselyt -käyttöoikeus.
     • Jos haluat eristää koneen, valitse Eristä kone -käyttöoikeus.
     • Voit selvittää, minkä käyttöoikeuden tarvitset, katso sen ohjelmointirajapinnan Käyttöoikeudet-osiota , johon haluat soittaa.

5. Valitse Myönnä suostumus.

   Huomautus

   Aina, kun lisäät käyttöoikeuden, sinun on napsautettava Myönnä suostumus , jotta uusi käyttöoikeus tulee voimaan.

   

6. Lisää sovellukselle salaisuus.

   Valitse Varmenteet & salaisuuksia, lisää kuvauksen salauskoodiin ja valitse Lisää.

   Tärkeää

   Kun olet valinnut Lisää, kopioi luotu salaisen koodin arvo. Et voi noutaa sen jälkeen, kun olet poistunut.

   

7. Kirjoita ylös sovellustunnus ja vuokraajatunnus.

   Siirry sovellussivulla kohtaan Yleiskatsaus ja kopioi seuraavat:

   

Valmis! Olet rekisteröinyt sovelluksen!

Vaihe 2 – Hanki tunnus sovelluksen avulla ja käytä tätä tunnusta ohjelmointirajapinnan käyttämiseen

Vihje

Jotkin Microsoft Defender for Endpoint-ohjelmointirajapinnat edellyttävät edelleen käyttöoikeustietueita vanhalle resurssille https://api.securitycenter.microsoft.com. Jos tunnuksen käyttäjäryhmä ei vastaa ohjelmointirajapinnan odottamaa resurssia, pyynnöt epäonnistuvat parametrilla 403 Forbidden, vaikka ohjelmointirajapinnan päätepiste käyttää kohdetta https://api.security.microsoft.com.

Kopioi seuraava komentosarja PowerShell ISE:hen tai tekstieditoriin ja tallenna se nimellä Get-Token.ps1. Tämän komentosarjan suorittaminen luo tunnuksen ja tallentaa sen työkansioon nimellä Latest-token.txt.

# This code gets the application context token and saves it to a file named "Latest-token.txt" in the current directory.

$tenantId = '' ### Paste your tenant ID here
$appId = '' ### Paste your Application (client) ID here
$appSecret = '' ### Paste your Application secret (App key) here to test, and then store it in a safe place!

$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

Tunnuksen vahvistaminen

1. Luo tiedosto suorittamalla Latest-token.txt komentosarja.
2. Avaa https://jwt.ms/selaimessa ja kopioi sitten tunnus (kohteen sisältö Latest-token.txt) alla olevasta Anna tunnus -ruudusta.
3. Etsi Koodatun tunnuksen välilehdestä roolit -osa ja varmista, että se sisältää Alert.Read.All-käyttöoikeudet seuraavassa kuvassa esitetyllä tavalla:

Haetaan hälytykset!

• Seuraava komentosarja käyttää Get-Token.ps1 ohjelmointirajapintaa ja saa ilmoituksia viimeisten 48 tunnin ajalta.
• Tallenna tämä komentosarja samaan kansioon, jonka tallensit edellisessä komentosarjassa Get-Token.ps1.
• Komentosarja luo kaksi tiedostoa (json ja csv), joiden tiedot ovat samassa kansiossa komentosarjojen kanssa.

# 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 created previously.
# Learn more about other query options and filters: https://learn.microsoft.com/defender-endpoint/api/get-alerts.
$url = "https://api.security.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 web request 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

Kaikki on valmista! Onnistui:

• Luotu ja rekisteröity ja sovellus.
• Sovellukselle myönnetty oikeus lukea ilmoituksia.
• Yhdistetty ohjelmointirajapintaan.
• Olemme käyttäneet PowerShell-komentosarjaa viimeisen 48 tunnin aikana luotujen ilmoitusten palauttamiseen.

Aiheeseen liittyviä artikkeleita

• Microsoft Defender for Endpoint ohjelmointirajapinnat
• Microsoft Defender for Endpoint käyttäminen sovelluskontekstin avulla
• Käyttöoikeus Microsoft Defender for Endpoint käyttäjäkontekstin avulla

Vihje

Haluatko tietää lisää? Ota yhteyttä Microsoft Security -yhteisöön Tech Community -yhteisössä: Microsoft Defender for Endpoint Community.