Aggiungere, aggiornare o eliminare una definizione di analisi

Articolo
08/14/2024

Si applica a:

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

Si vuole provare Gestione vulnerabilità di Microsoft Defender? Altre informazioni su come iscriversi alla versione di valutazione dell'anteprima pubblica di Microsoft Defender Vulnerability Management.

Importante

Alcune informazioni in questo articolo fanno riferimento alle caratteristiche di un prodotto prima del rilascio, che possono essere modificate sostanzialmente prima della distribuzione al pubblico. Microsoft non fornisce alcuna garanzia, esplicita o implicita, in relazione alle informazioni contenute in questo documento.

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

Descrizione DELL'API

API per aggiungere, aggiornare o eliminare un'analisi autenticata.

Limitazioni

Le limitazioni di frequenza per questa API sono 100 chiamate al minuto e 1.500 chiamate all'ora.

È possibile pubblicare nei computer visualizzati per l'ultima volta in base al periodo di conservazione configurato.

Autorizzazioni

Per chiamare questa API è necessaria una delle autorizzazioni seguenti. Per altre informazioni, incluso come scegliere le autorizzazioni, vedere Usare le API di Defender per endpoint.

Tipo di autorizzazione	Autorizzazione	Nome visualizzato autorizzazioni
Applicazione	Machine.ReadWrite.All	Leggere e scrivere tutte le informazioni di analisi.
Delegato (account aziendale o dell'istituto di istruzione)	Machine.Read.Write	Leggere e scrivere tutte le informazioni di analisi.

Nota

Quando si ottiene un token usando le credenziali utente:

Per visualizzare i dati, l'utente deve disporre almeno dell'autorizzazione del ruolo seguente: ViewData o TvmViewData (vedere Creare e gestire ruoli per altre informazioni)
Per modificare i dati, l'utente deve disporre almeno dell'autorizzazione del ruolo seguente: ManageSecurity (Per altre informazioni, vedere Creare e gestire ruoli )

Richiesta HTTP

POST https://api.securitycenter.microsoft.com/api/DeviceAuthenticatedScanDefinitions

Intestazioni di richiesta

Nome	Tipo	Descrizione
Autorizzazione	Stringa	Bearer {token}. Obbligatorio.
Content-Type	stringa	application/json. Obbligatorio.

Corpo della richiesta

Nel corpo della richiesta specificare un oggetto JSON con i parametri seguenti:

Parametro	Tipo	Descrizione
scanType	Enumerazione	Tipo di analisi. I valori possibili sono: "Windows", "Network". Obbligatorio.
scanName	Stringa	Nome dell'analisi. Obbligatorio.
isActive	Booleano	Stato dell'analisi in esecuzione. Obbligatorio.
bersaglio	Stringa	Elenco delimitato da virgole di destinazioni da analizzare, ovvero indirizzi IP o nomi host. Obbligatorio.
intervalInHours	Soglia	Intervallo in corrispondenza del quale viene eseguita l'analisi. Obbligatorio.
targetType	Stringa	Tipo di destinazione nel campo di destinazione. I tipi possibili sono "Indirizzo IP" o "Nome Host". Il valore predefinito è Indirizzo IP. Obbligatorio.
scannerAgent	Oggetto	ID computer. Obbligatorio.
scanAuthenticationParams	Oggetto	Oggetto che rappresenta i parametri di autenticazione, vedere Proprietà dell'oggetto Parametri di autenticazione per i campi previsti. Questa proprietà è obbligatoria quando si crea una nuova analisi ed è facoltativa durante l'aggiornamento di un'analisi.

Risposta

In caso di esito positivo, questo metodo restituisce il codice di risposta 200 - OK e la definizione di analisi nuova o aggiornata nel corpo della risposta.

Richiesta di esempio per aggiungere una nuova analisi

Ecco un esempio di richiesta che aggiunge una nuova analisi.

POST https://api.securitycenter.microsoft.com/api/DeviceAuthenticatedScanDefinitions

 {
"scanType": "Windows", 
"scanName": "Test Windows scan", 
"isActive": true, 
"target": "127.0.0.1", 
"intervalInHours": 1, 
"targetType": "Ip",
"scannerAgent": {
    "machineId": "eb663a27ae9d032f61bc268a79eedf14c4b90f77",
},
"scanAuthenticationParams": { 
    "@odata.type": "#microsoft.windowsDefenderATP.api.WindowsAuthParams", 
    "type": "Kerberos", 
    "username": "username", 
    "domain": "password",
    "isGmsaUser": true
    }
}

Risposta di esempio

Ecco un esempio della risposta.

 {
"@odata.context": "https://api.securitycenter.microsoft.com/api/$metadata#DeviceAuthenticatedScanDefinitions/$entity",
    "id": "289224fb-1686-472c-9751-5555960854ca",
    "scanType": "Windows",
    "scanName": "Test Windows scan",
    "isActive": true,
    "target": "127.0.0.1",
    "orgId": "0335a792-18d2-424b-aeed-559567054570",
    "intervalInHours": 1,
    "createdBy": "username@test.com",
    "targetType": "Ip",
    "scanAuthenticationParams": null,
    "scannerAgent": {
        "id": "0335a792-18d2-424b-aeed-559567054570_ eb663a27ae9d032f61bc268a79eedf14c4b90f77",
        "machineId": "eb663a27ae9d032f61bc268a79eedf14c4b90f77",
        "machineName": "DESKTOP-TEST",
        "lastSeen": "2023-01-04T09:40:03.2787058Z",
        "assignedApplicationId": "ae4a5cde-b4a1-4b76-8635-458b2cf15752",
        "scannerSoftwareVersion": "7.6.0.0",
        "lastCommandExecutionTimestamp": "2023-01-04T09:33:16Z",
        "mdeClientVersion": "10.8295.22621.1010"
    },
    "latestScan": {
        "status": null,
        "failureReason": null,
        "executionDateTime": null
    }

}

Richiesta di esempio per aggiornare un'analisi

Ecco un esempio di richiesta che aggiorna un'analisi.

PATCH  https://api.securitycenter.microsoft.com/api/DeviceAuthenticatedScanDefinitions/289224fb-1686-472c-9751-5555960854ca

{
"scanName": "Test Update Windows scan", 
"isActive": false, 
"target": "127.0.0.2,127.0.0.3", 
"intervalInHours": 1, 
"targetType": "Ip",
"scanAuthenticationParams": { 
    "@odata.type": "#microsoft.windowsDefenderATP.api.WindowsAuthParams", 
    "type": "Kerberos", 
    "username": "username", 
    "domain": "password",
    "isGmsaUser": true
    }
 }

Esempio di risposta