Actualización de la API de incidentes

  • Artículo

Se aplica a:

Nota:

Pruebe nuestras nuevas API mediante la API de seguridad de MS Graph. Obtenga más información en: Uso de la API de seguridad de Microsoft Graph: Microsoft Graph | Microsoft Learn. Para obtener información sobre la nueva API de incidentes de actualización mediante la API de seguridad de MS Graph, consulte Actualizar incidente.

Importante

Parte de la información se refiere a productos preliminares que pueden ser modificados sustancialmente antes de su lanzamiento comercial. Microsoft no otorga garantías, expresas o implícitas, con respecto a la información que aquí se proporciona.

Descripción de la API

Novedades propiedades del incidente existente. Las propiedades actualizables son: status, determination, classification, assignedTo, tagsy comments.

Cuotas, asignación de recursos y otras restricciones

  1. Puede realizar hasta 50 llamadas por minuto o 1500 llamadas por hora antes de alcanzar el umbral de limitación.
  2. Solo puede establecer la determination propiedad si classification está establecida en TruePositive.

Si la solicitud está limitada, devuelve un código de 429 respuesta. El cuerpo de la respuesta indica la hora en que puede empezar a realizar nuevas llamadas.

Permisos

Se requiere uno de los siguientes permisos para llamar a esta API. Para más información, incluido cómo elegir permisos, consulte Acceso a las API de Microsoft Defender XDR.

Tipo de permiso Permiso Nombre para mostrar del permiso
Aplicación Incident.ReadWrite.All Leer y escribir todos los incidentes
Delegado (cuenta profesional o educativa) Incident.ReadWrite Incidentes de lectura y escritura

Nota:

Al obtener un token con credenciales de usuario, el usuario debe tener permiso para actualizar el incidente en el portal.

Solicitud HTTP

PATCH /api/incidents/{id}

Encabezados de solicitud

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

Cuerpo de la solicitud

En el cuerpo de la solicitud, proporcione los valores de los campos que se deben actualizar. Las propiedades existentes que no se incluyen en el cuerpo de la solicitud mantienen sus valores, a menos que tengan que volver a calcularse debido a cambios en los valores relacionados. Para obtener el mejor rendimiento, debe omitir los valores existentes que no cambiaron.

Propiedad Tipo Descripción
status Enum Especifica el estado actual del incidente. Los valores posibles son Active, Resolved, InProgress y Redirected
assignedTo string Propietario del incidente.
classification Enum Especificación del incidente. Los valores posibles son: TruePositive (True positive), InformationalExpectedActivity (Informational, expected activity) y FalsePositive (False Positive).
Determinación Enum Especifica la determinación del incidente.

Los valores de determinación posibles para cada clasificación son:

  • Verdadero positivo: MultiStagedAttack (ataque con varias fases), MaliciousUserActivity (actividad de usuario malintencionada), CompromisedAccount (cuenta en peligro): considere la posibilidad de cambiar el nombre de la enumeración en la API pública en consecuencia, Malware (Malware), Phishing (Phishing), UnwantedSoftware (software no deseado) y Other (Otros).
  • Actividad informativa y esperada:SecurityTesting (Prueba de seguridad), LineOfBusinessApplication (aplicación de línea de negocio), ConfirmedActivity (actividad confirmada): considere la posibilidad de cambiar el nombre de la enumeración en la API pública en consecuencia y Other (Otros).
  • Falso positivo:Clean (No malintencionado): considere la posibilidad de cambiar el nombre de la enumeración en la API pública en consecuencia, NoEnoughDataToValidate (No hay suficientes datos para validar) y Other (Otros).
    		•
    tags lista de cadenas Lista de etiquetas de incidentes.
    comment string Comentario que se va a agregar al incidente.

    Nota:

    Alrededor del 29 de agosto de 2022, los valores de determinación de alertas admitidos anteriormente ("Apt" y "SecurityPersonnel") estarán en desuso y ya no estarán disponibles a través de la API.

    Respuesta

    Si se ejecuta correctamente, este método devuelve 200 OK. El cuerpo de la respuesta contiene la entidad de incidente con propiedades actualizadas. Si no se encontró un incidente con el identificador especificado, el método devuelve 404 Not Found.

    Ejemplo

    Ejemplo de solicitud

    Este es un ejemplo de la solicitud.

     PATCH https://api.security.microsoft.com/api/incidents/{id}

    Ejemplo de datos de solicitud

    {
    "status": "Resolved",
    "assignedTo": "secop2@contoso.com",
    "classification": "TruePositive",
    "determination": "Malware",
    "tags": ["Yossi's playground", "Don't mess with the Zohan"],
    "comments": [
          {
              "comment": "pen testing",
              "createdBy": "secop2@contoso.com",
              "createdTime": "2021-05-02T09:34:21.5519738Z"
          },
          {
              "comment": "valid incident",
              "createdBy": "secop2@contoso.comt",
              "createdTime": "2021-05-02T09:36:27.6652581Z"
          }
      ]
}

    Sugerencia

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