MICROSOFT DEFENDER PER ENDPOINT API con PowerShell

  • Articolo

Si applica a:

Importante

Le funzionalità di ricerca avanzata non sono incluse in Defender per le aziende.

Se si desidera provare Microsoft Defender per endpoint, iscriversi a una versione di valutazione gratuita.

Nota

Se si è un cliente del governo degli Stati Uniti, usare gli URI elencati in Microsoft Defender per endpoint per i clienti del governo degli Stati Uniti.

Consiglio

Per ottenere prestazioni migliori, è possibile usare il server più vicino alla posizione geografica:

  • 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

Se si desidera provare Microsoft Defender per endpoint, iscriversi a una versione di valutazione gratuita.

Scenario completo con più API di Microsoft Defender per endpoint.

In questa sezione vengono condivisi gli esempi di PowerShell per

  • Recuperare un token
  • Usare il token per recuperare gli avvisi più recenti in Microsoft Defender per endpoint
  • Per ogni avviso, se l'avviso ha priorità media o alta ed è ancora in corso, controllare il numero di volte in cui il dispositivo si è connesso all'URL sospetto.

Prerequisito: è prima di tutto necessario creare un'app.

Istruzioni di preparazione

  • Aprire una finestra di PowerShell.
  • Se i criteri non consentono di eseguire i comandi di PowerShell, è possibile eseguire il comando seguente:
    Set-ExecutionPolicy -ExecutionPolicy Bypass

Per altre informazioni, vedere la documentazione di PowerShell

Ottenere il token

Eseguire quanto segue:

  • $tenantId: ID del tenant per conto del quale si vuole eseguire la query, ovvero la query viene eseguita sui dati di questo tenant

  • $appId: ID dell'app Microsoft Entra (l'app deve disporre dell'autorizzazione "Esegui query avanzate" per Defender per endpoint)

  • $appSecret: segreto dell'app Microsoft Entra

  • $suspiciousUrl: URL

$tenantId = '00000000-0000-0000-0000-000000000000' # Paste your own tenant ID here
$appId = '11111111-1111-1111-1111-111111111111' # Paste your own app ID here
$appSecret = '22222222-2222-2222-2222-222222222222' # Paste your own app secret here
$suspiciousUrl = 'www.suspiciousUrl.com' # Paste your own URL here

$resourceAppIdUri = 'https://securitycenter.onmicrosoft.com/windowsatpservice'
$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
$aadToken = $authResponse.access_token


#Get latest alert
$alertUrl = "https://api.securitycenter.microsoft.com/api/alerts?`$top=10"
$headers = @{ 
    'Content-Type' = 'application/json'
    Accept = 'application/json'
    Authorization = "Bearer $aadToken" 
}
$alertResponse = Invoke-WebRequest -Method Get -Uri $alertUrl -Headers $headers -ErrorAction Stop
$alerts =  ($alertResponse | ConvertFrom-Json).value

$machinesToInvestigate = New-Object System.Collections.ArrayList

Foreach($alert in $alerts)
{
    #echo $alert.id $alert.machineId    $alert.severity $alert.status

    $isSevereAlert = $alert.severity -in 'Medium', 'High'
    $isOpenAlert = $alert.status -in 'InProgress', 'New'
    if($isOpenAlert -and $isSevereAlert)
    {
        if (-not $machinesToInvestigate.Contains($alert.machineId))
        {
            $machinesToInvestigate.Add($alert.machineId) > $null
        }
    }
}

$commaSeparatedMachines = '"{0}"' -f ($machinesToInvestigate -join '","')

$query = "NetworkCommunicationEvents
| where MachineId in ($commaSeparatedMachines)
| where RemoteUrl  == `"$suspiciousUrl`"
| summarize ConnectionsCount = count() by MachineId"

$queryUrl = "https://api.securitycenter.microsoft.com/api/advancedqueries/run"

$queryBody = ConvertTo-Json -InputObject @{ 'Query' = $query }
$queryResponse = Invoke-WebRequest -Method Post -Uri $queryUrl -Headers $headers -Body $queryBody -ErrorAction Stop
$response =  ($queryResponse | ConvertFrom-Json).Results
$response

Vedere anche

Consiglio

Per saperne di più, Engage con la community Microsoft Security nella community tech: Microsoft Defender per endpoint Tech Community.