Microsoft Defender для API конечных точек с помощью PowerShellMicrosoft Defender for Endpoint APIs using PowerShell

Применяется к: Microsoft Defender для конечной точкиApplies to: Microsoft Defender for Endpoint

Хотите испытать Microsoft Defender для конечной точки?Want to experience Microsoft Defender for Endpoint? Зарегистрився для бесплатной пробной.Sign up for a free trial.

Примечание

Если вы клиент правительства США, используйте URL-адреса, указанные в Microsoft Defender для конечных точек для государственных клиентов США.If you are a US Government customer, please use the URIs listed in Microsoft Defender for Endpoint for US Government customers.

Совет

Для улучшения производительности можно использовать сервер ближе к географическому расположению:For better performance, you can use server closer to your geo location:

  • api-us.securitycenter.microsoft.comapi-us.securitycenter.microsoft.com
  • api-eu.securitycenter.microsoft.comapi-eu.securitycenter.microsoft.com
  • api-uk.securitycenter.microsoft.comapi-uk.securitycenter.microsoft.com

Хотите испытать Microsoft Defender для конечной точки?Want to experience Microsoft Defender for Endpoint? Зарегистрився для бесплатной пробной.Sign up for a free trial.

Полный сценарий с использованием нескольких API из Microsoft Defender для конечной точки.Full scenario using multiple APIs from Microsoft Defender for Endpoint.

В этом разделе мы делимся примерами PowerShell сIn this section, we share PowerShell samples to

  • Извлечение маркераRetrieve a token
  • Использование маркера для получения последних оповещений в Microsoft Defender для конечной точкиUse token to retrieve the latest alerts in Microsoft Defender for Endpoint
  • Для каждого оповещения, если оповещение имеет средний или высокий приоритет и все еще находится в процессе выполнения, проверьте, сколько раз устройство подключено к подозрительному URL-адресу.For each alert, if the alert has medium or high priority and is still in progress, check how many times the device has connected to suspicious URL.

Обязательное условие. Сначала необходимо создать приложение.Prerequisite: You first need to create an app.

Инструкции по подготовкеPreparation instructions

  • Откройте окно PowerShell.Open a PowerShell window.
  • Если политика не позволяет запускать команды PowerShell, можно выполнить приведенную ниже команду:If your policy does not allow you to run the PowerShell commands, you can run the below command:
    Set-ExecutionPolicy -ExecutionPolicy Bypass
    

Дополнительные сведения см. в документации PowerShellFor more information, see PowerShell documentation

Get tokenGet token

Запустите ниже:Run the below:

  • $tenantId: ID клиента, от имени которого требуется выполнить запрос (то есть запрос будет работать на данных этого клиента)$tenantId: ID of the tenant on behalf of which you want to run the query (i.e., the query will be run on the data of this tenant)

  • $appId: ID приложения AAD (приложение должно иметь разрешение "Выполнить расширенные запросы" в Defender для конечной точки)$appId: ID of your AAD app (the app must have 'Run advanced queries' permission to Defender for Endpoint)

  • $appSecret: Секрет приложения Azure AD$appSecret: Secret of your Azure AD app

  • $suspiciousUrl: URL-адрес$suspiciousUrl: The 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

См. такжеSee also