API Elenca avvisi
Si applica a:
- Microsoft Defender per endpoint Piano 1
- Microsoft Defender per endpoint Piano 2
- Microsoft Defender XDR
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
Descrizione DELL'API
Recupera una raccolta di avvisi.
Supporta le query OData V4.
Operatori supportati da OData:
$filteron:alertCreationTime,lastUpdateTime,incidentId,InvestigationId,id,asssignedTo,detectionSource,lastEventTime,status,severityecategoryproprietà.$topcon un valore massimo di 10.000$skip$expandDievidence- Vedere gli esempi nelle query OData con Microsoft Defender per endpoint.
Limitazioni
È possibile ottenere gli avvisi aggiornati per ultimo in base al periodo di conservazione configurato.
La dimensione massima della pagina è 10.000.
Le limitazioni di frequenza per questa API sono 100 chiamate al minuto e 1.500 chiamate all'ora.
Autorizzazioni
Per chiamare questa API è necessaria una delle autorizzazioni seguenti. Per altre informazioni, inclusa la scelta delle autorizzazioni, vedere Usare le API Microsoft Defender per endpoint.
| Tipo di autorizzazione | Autorizzazione | Nome visualizzato autorizzazioni |
|---|---|---|
| Applicazione | Alert.Read.All | Read all alerts |
| Applicazione | Alert.ReadWrite.All | Read and write all alerts |
| Delegato (account aziendale o dell'istituto di istruzione) | Alert.Read | Read alerts |
| Delegato (account aziendale o dell'istituto di istruzione) | Alert.ReadWrite | Read and write alerts |
Nota
Quando si ottiene un token usando le credenziali utente:
- L'utente deve disporre almeno dell'autorizzazione del ruolo seguente:
View Data(Per altre informazioni, vedere Create e gestire i ruoli) - La risposta include solo gli avvisi associati ai dispositivi a cui l'utente può accedere, in base alle impostazioni del gruppo di dispositivi (vedere Create e gestire i gruppi di dispositivi per altre informazioni)
La creazione di gruppi di dispositivi è supportata in Defender per endpoint Piano 1 e Piano 2.
Richiesta HTTP
GET /api/alerts
Intestazioni di richiesta
| Nome | Tipo | Descrizione |
|---|---|---|
| Autorizzazione | Stringa | Bearer {token}. Obbligatorio. |
Corpo della richiesta
Vuoto
Risposta
In caso di esito positivo, questo metodo restituisce 200 OK e un elenco di oggetti avviso nel corpo della risposta.
Esempio 1 - Predefinito
Richiesta
Ecco un esempio della richiesta.
GET https://api.securitycenter.microsoft.com/api/alerts
Risposta
Ecco un esempio della risposta.
Nota
L'elenco di risposte illustrato qui può essere troncato per brevità. Tutti gli avvisi verranno restituiti da una chiamata effettiva.
{
"@odata.context": "https://api.securitycenter.microsoft.com/api/$metadata#Alerts",
"value": [
{
"id": "da637308392288907382_-880718168",
"incidentId": 7587,
"investigationId": 723156,
"assignedTo": "secop123@contoso.com",
"severity": "Low",
"status": "New",
"classification": "TruePositive",
"determination": null,
"investigationState": "Queued",
"detectionSource": "WindowsDefenderAv",
"category": "SuspiciousActivity",
"threatFamilyName": "Meterpreter",
"title": "Suspicious 'Meterpreter' behavior was detected",
"description": "Malware and unwanted software are undesirable applications that perform annoying, disruptive, or harmful actions on affected machines. Some of these undesirable applications can replicate and spread from one machine to another. Others are able to receive commands from remote attackers and perform activities associated with cyber attacks.\n\nA malware is considered active if it is found running on the machine or it already has persistence mechanisms in place. Active malware detections are assigned higher severity ratings.\n\nBecause this malware was active, take precautionary measures and check for residual signs of infection.",
"alertCreationTime": "2020-07-20T10:53:48.7657932Z",
"firstEventTime": "2020-07-20T10:52:17.6654369Z",
"lastEventTime": "2020-07-20T10:52:18.1362905Z",
"lastUpdateTime": "2020-07-20T10:53:50.19Z",
"resolvedTime": null,
"machineId": "12ee6dd8c833c8a052ea231ec1b19adaf497b625",
"computerDnsName": "temp123.middleeast.corp.microsoft.com",
"rbacGroupName": "MiddleEast",
"aadTenantId": "a839b112-1253-6432-9bf6-94542403f21c",
"threatName": null,
"mitreTechniques": [
"T1064",
"T1085",
"T1220"
],
"relatedUser": {
"userName": "temp123",
"domainName": "DOMAIN"
},
"comments": [
{
"comment": "test comment for docs",
"createdBy": "secop123@contoso.com",
"createdTime": "2020-07-21T01:00:37.8404534Z"
}
],
"evidence": []
}
...
]
}
Esempio 2 - Ottenere 10 avvisi più recenti con prove correlate
Richiesta
Ecco un esempio della richiesta.
GET https://api.securitycenter.microsoft.com/api/alerts?$top=10&$expand=evidence
Risposta
Ecco un esempio della risposta.
Nota
L'elenco di risposte illustrato qui può essere troncato per brevità. Tutti gli avvisi verranno restituiti da una chiamata effettiva.
{
"@odata.context": "https://api.securitycenter.microsoft.com/api/$metadata#Alerts",
"value": [
{
"id": "da637472900382838869_1364969609",
"incidentId": 1126093,
"investigationId": null,
"assignedTo": null,
"severity": "Low",
"status": "New",
"classification": null,
"determination": null,
"investigationState": "Queued",
"detectionSource": "WindowsDefenderAtp",
"detectorId": "17e10bbc-3a68-474a-8aad-faef14d43952",
"category": "Execution",
"threatFamilyName": null,
"title": "Low-reputation arbitrary code executed by signed executable",
"description": "Binaries signed by Microsoft can be used to run low-reputation arbitrary code. This technique hides the execution of malicious code within a trusted process. As a result, the trusted process might exhibit suspicious behaviors, such as opening a listening port or connecting to a command-and-control (C&C) server.",
"alertCreationTime": "2021-01-26T20:33:57.7220239Z",
"firstEventTime": "2021-01-26T20:31:32.9562661Z",
"lastEventTime": "2021-01-26T20:31:33.0577322Z",
"lastUpdateTime": "2021-01-26T20:33:59.2Z",
"resolvedTime": null,
"machineId": "111e6dd8c833c8a052ea231ec1b19adaf497b625",
"computerDnsName": "temp123.middleeast.corp.microsoft.com",
"rbacGroupName": "A",
"aadTenantId": "a839b112-1253-6432-9bf6-94542403f21c",
"threatName": null,
"mitreTechniques": [
"T1064",
"T1085",
"T1220"
],
"relatedUser": {
"userName": "temp123",
"domainName": "DOMAIN"
},
"comments": [
{
"comment": "test comment for docs",
"createdBy": "secop123@contoso.com",
"createdTime": "2021-01-26T01:00:37.8404534Z"
}
],
"evidence": [
{
"entityType": "User",
"evidenceCreationTime": "2021-01-26T20:33:58.42Z",
"sha1": null,
"sha256": null,
"fileName": null,
"filePath": null,
"processId": null,
"processCommandLine": null,
"processCreationTime": null,
"parentProcessId": null,
"parentProcessCreationTime": null,
"parentProcessFileName": null,
"parentProcessFilePath": null,
"ipAddress": null,
"url": null,
"registryKey": null,
"registryHive": null,
"registryValueType": null,
"registryValue": null,
"accountName": "name",
"domainName": "DOMAIN",
"userSid": "S-1-5-21-11111607-1111760036-109187956-75141",
"aadUserId": "11118379-2a59-1111-ac3c-a51eb4a3c627",
"userPrincipalName": "temp123@microsoft.com",
"detectionStatus": null
},
{
"entityType": "Process",
"evidenceCreationTime": "2021-01-26T20:33:58.6133333Z",
"sha1": "ff836cfb1af40252bd2a2ea843032e99a5b262ed",
"sha256": "a4752c71d81afd3d5865d24ddb11a6b0c615062fcc448d24050c2172d2cbccd6",
"fileName": "rundll32.exe",
"filePath": "C:\\Windows\\SysWOW64",
"processId": 3276,
"processCommandLine": "rundll32.exe c:\\temp\\suspicious.dll,RepeatAfterMe",
"processCreationTime": "2021-01-26T20:31:32.9581596Z",
"parentProcessId": 8420,
"parentProcessCreationTime": "2021-01-26T20:31:32.9004163Z",
"parentProcessFileName": "rundll32.exe",
"parentProcessFilePath": "C:\\Windows\\System32",
"ipAddress": null,
"url": null,
"registryKey": null,
"registryHive": null,
"registryValueType": null,
"registryValue": null,
"accountName": null,
"domainName": null,
"userSid": null,
"aadUserId": null,
"userPrincipalName": null,
"detectionStatus": "Detected"
},
{
"entityType": "File",
"evidenceCreationTime": "2021-01-26T20:33:58.42Z",
"sha1": "8563f95b2f8a284fc99da44500cd51a77c1ff36c",
"sha256": "dc0ade0c95d6db98882bc8fa6707e64353cd6f7767ff48d6a81a6c2aef21c608",
"fileName": "suspicious.dll",
"filePath": "c:\\temp",
"processId": null,
"processCommandLine": null,
"processCreationTime": null,
"parentProcessId": null,
"parentProcessCreationTime": null,
"parentProcessFileName": null,
"parentProcessFilePath": null,
"ipAddress": null,
"url": null,
"registryKey": null,
"registryHive": null,
"registryValueType": null,
"registryValue": null,
"accountName": null,
"domainName": null,
"userSid": null,
"aadUserId": null,
"userPrincipalName": null,
"detectionStatus": "Detected"
}
]
},
...
]
}
Vedere anche
Query OData con Microsoft Defender per endpoint
Consiglio
Per saperne di più, Engage con la community Microsoft Security nella community tech: Microsoft Defender per endpoint Tech Community.
Commenti e suggerimenti
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedere https://aka.ms/ContentUserFeedback.
Invia e visualizza il feedback per