Compartir a través de

Adición, actualización o eliminación de una definición de examen

  • Artículo

Se aplica a:

¿Quiere experimentar Microsoft Defender para punto de conexión? Regístrese para obtener una prueba gratuita.

¿Quieres experimentar Administración de vulnerabilidades de Microsoft Defender? Obtenga más información sobre cómo puede registrarse en la versión de prueba de Administración de vulnerabilidades de Microsoft Defender versión preliminar pública.

Importante

Parte de la información contenida en este artículo se refiere a un producto preliminar que puede sufrir modificaciones sustanciales antes de su lanzamiento comercial. Microsoft no otorga garantías, expresas o implícitas, con respecto a la información que aquí se proporciona.

Nota:

Si es cliente del Gobierno de EE. UU., use los URI que aparecen en Microsoft Defender para punto de conexión para los clientes del Gobierno de EE. UU.

Sugerencia

Para mejorar el rendimiento, puede usar el servidor más cercano a la ubicación geográfica:

  • 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

Descripción de la API

API para agregar, actualizar o eliminar un examen autenticado.

Limitaciones

Las limitaciones de velocidad de esta API son 100 llamadas por minuto y 1500 llamadas por hora.

Puede publicar en las máquinas que se vieron por última vez según el período de retención configurado.

Permisos

Se requiere uno de los siguientes permisos para llamar a esta API. Para obtener más información, incluido cómo elegir permisos, consulte Uso de Defender para API de punto de conexión.

Tipo de permiso Permiso Nombre para mostrar del permiso
Aplicación Machine.ReadWrite.All Leer y escribir toda la información del examen.
Delegado (cuenta profesional o educativa) Machine.Read.Write Leer y escribir toda la información del examen.

Nota:

Al obtener un token con credenciales de usuario:

  • Para ver los datos, el usuario debe tener al menos el siguiente permiso de rol: ViewData o TvmViewData (Consulte Create y administrar roles para obtener más información).
  • Para editar datos, el usuario debe tener al menos el siguiente permiso de rol: ManageSecurity (Consulte Create y administrar roles para obtener más información).

Solicitud HTTP

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

Encabezados de solicitud

Nombre Tipo Descripción
Authorization Cadena {token} de portador. Necesario.
Content-Type string application/json. Necesario.

Cuerpo de la solicitud

En el cuerpo de la solicitud, proporcione un objeto JSON con los parámetros siguientes:

Parámetro Tipo Descripción
scanType Enum Tipo de examen. Los valores posibles son: "Windows", "Network". Necesario.
scanName Cadena Nombre del examen. Necesario.
isActive Booleano Estado de si el examen se está ejecutando activamente. Necesario.
target Cadena Lista separada por comas de destinos que se van a examinar, ya sea direcciones IP o nombres de host. Necesario.
intervalInHours Int Intervalo en el que se ejecuta el examen. Necesario.
targetType Cadena Tipo de destino en el campo de destino. Los tipos posibles son "Dirección IP" o "Nombre de host". El valor predeterminado es Dirección IP. Necesario.
scannerAgent Objeto id. de máquina. Obligatorio.
scanAuthenticationParams Objeto Un objeto que representa los parámetros de autenticación, consulte Propiedades del objeto Parámetros de autenticación para los campos esperados. Esta propiedad es obligatoria al crear un nuevo examen y es opcional al actualizar un examen.

Respuesta

Si se ejecuta correctamente, este método devuelve el código de respuesta 200 - Ok y la definición de examen nueva o actualizada en el cuerpo de la respuesta.

Solicitud de ejemplo para agregar un nuevo examen

Este es un ejemplo de una solicitud que agrega un nuevo examen.

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
    }
}

Ejemplo de respuesta

Este es un ejemplo de la respuesta:

 {
"@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
    }

}

Solicitud de ejemplo para actualizar un examen

Este es un ejemplo de una solicitud que actualiza un examen.

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
    }
 }

Ejemplo de respuesta

Este es un ejemplo de la respuesta:

{
    "@odata.context": "https://localhost:1059/api/$metadata#DeviceAuthenticatedScanDefinitions/$entity",
    "id": "289224fb-1686-472c-9751-5555960854ca",
    "scanType": "Windows",
    "scanName": "Test Update Windows scan",
    "isActive": false,
    "target": "127.0.0.2,127.0.0.3",
    "orgId": "0335a792-18d2-424b-aeed-559567054570",
    "intervalInHours": 1,
    "createdBy": "userName@microsoft.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
    }
}

Solicitud de ejemplo para eliminar exámenes

Este es un ejemplo de una solicitud que elimina los exámenes.

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

{
  "ScanDefinitionIds": ["td32f17af-5cc2-4e4e-964a-4c4ef7d216e2", "ab32g20af-5dd2-4a5e-954a-4c4ef7d216e2"],
}

Sugerencia

¿Desea obtener más información? Engage con la comunidad de seguridad de Microsoft en nuestra comunidad tecnológica: Microsoft Defender para punto de conexión Tech Community.