{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://github.com/kinlane/microsoft-defender/json-schema/microsoft-defender-alert-schema.json",
  "title": "Microsoft Defender for Endpoint Alert",
  "description": "JSON Schema for a security alert generated by Microsoft Defender for Endpoint. Represents a detected threat, suspicious activity, or security event on an endpoint, including severity classification, investigation state, MITRE ATT&CK mapping, related user information, evidence, and comments.",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique identifier for the alert.",
      "examples": [
        "da637472900382838869_1364969609"
      ]
    },
    "title": {
      "type": "string",
      "description": "A brief title summarizing the alert.",
      "examples": [
        "Low-reputation arbitrary code executed by signed executable"
      ]
    },
    "description": {
      "type": "string",
      "description": "A detailed description of the alert, providing context about the detected threat or suspicious activity."
    },
    "alertCreationTime": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "The date and time (in UTC) when the alert was created."
    },
    "lastEventTime": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "The last occurrence of the event that triggered the alert on the same device."
    },
    "firstEventTime": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "The first occurrence of the event that triggered the alert on that device."
    },
    "lastUpdateTime": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "The date and time (in UTC) the alert was last updated."
    },
    "resolvedTime": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "The date and time when the status of the alert was changed to Resolved."
    },
    "incidentId": {
      "type": [
        "integer",
        "null"
      ],
      "description": "The incident ID associated with the alert."
    },
    "investigationId": {
      "type": [
        "integer",
        "null"
      ],
      "description": "The investigation ID related to the alert."
    },
    "investigationState": {
      "type": [
        "string",
        "null"
      ],
      "description": "The current state of the automated investigation.",
      "enum": [
        "Unknown",
        "Terminated",
        "SuccessfullyRemediated",
        "Benign",
        "Failed",
        "PartiallyRemediated",
        "Running",
        "PendingApproval",
        "PendingResource",
        "PartiallyInvestigated",
        "TerminatedByUser",
        "TerminatedBySystem",
        "Queued",
        "InnerFailure",
        "PreexistingAlert",
        "UnsupportedOs",
        "UnsupportedAlertType",
        "SuppressedAlert",
        null
      ]
    },
    "assignedTo": {
      "type": [
        "string",
        "null"
      ],
      "description": "The owner (assignee) of the alert.",
      "examples": [
        "secop123@contoso.com"
      ]
    },
    "rbacGroupName": {
      "type": [
        "string",
        "null"
      ],
      "description": "The role-based access control device group name."
    },
    "mitreTechniques": {
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^T[0-9]{4}(\\.[0-9]{3})?$"
      },
      "description": "MITRE ATT&CK Enterprise technique IDs associated with the alert.",
      "examples": [
        [
          "T1064",
          "T1085",
          "T1220"
        ]
      ]
    },
    "relatedUser": {
      "type": [
        "object",
        "null"
      ],
      "description": "Details of the user related to the alert.",
      "properties": {
        "userName": {
          "type": "string",
          "description": "The user name."
        },
        "domainName": {
          "type": "string",
          "description": "The domain name."
        }
      },
      "required": [
        "userName",
        "domainName"
      ]
    },
    "severity": {
      "type": "string",
      "description": "The severity level of the alert.",
      "enum": [
        "UnSpecified",
        "Informational",
        "Low",
        "Medium",
        "High"
      ]
    },
    "status": {
      "type": "string",
      "description": "The current status of the alert.",
      "enum": [
        "Unknown",
        "New",
        "InProgress",
        "Resolved"
      ]
    },
    "classification": {
      "type": [
        "string",
        "null"
      ],
      "description": "The classification of the alert indicating whether it is a true positive, informational expected activity, or false positive.",
      "enum": [
        "TruePositive",
        "InformationalExpectedActivity",
        "FalsePositive",
        null
      ]
    },
    "determination": {
      "type": [
        "string",
        "null"
      ],
      "description": "The determination of the alert, specifying the nature of the detected activity based on the classification.",
      "enum": [
        "MultiStagedAttack",
        "MaliciousUserActivity",
        "CompromisedUser",
        "Malware",
        "Phishing",
        "UnwantedSoftware",
        "SecurityTesting",
        "LineOfBusinessApplication",
        "ConfirmedActivity",
        "NotMalicious",
        "InsufficientData",
        "Other",
        null
      ]
    },
    "category": {
      "type": [
        "string",
        "null"
      ],
      "description": "The alert category describing the type of threat activity.",
      "examples": [
        "Execution",
        "SuspiciousActivity",
        "Malware",
        "Persistence"
      ]
    },
    "detectionSource": {
      "type": [
        "string",
        "null"
      ],
      "description": "The source that detected and generated the alert.",
      "examples": [
        "WindowsDefenderAtp",
        "WindowsDefenderAv",
        "CustomDetection"
      ]
    },
    "threatFamilyName": {
      "type": [
        "string",
        "null"
      ],
      "description": "The threat family name associated with the alert.",
      "examples": [
        "Meterpreter"
      ]
    },
    "threatName": {
      "type": [
        "string",
        "null"
      ],
      "description": "The specific threat name."
    },
    "machineId": {
      "type": [
        "string",
        "null"
      ],
      "description": "The ID of the machine entity associated with the alert.",
      "examples": [
        "111e6dd8c833c8a052ea231ec1b19adaf497b625"
      ]
    },
    "computerDnsName": {
      "type": [
        "string",
        "null"
      ],
      "description": "The fully qualified domain name of the machine.",
      "examples": [
        "temp123.middleeast.corp.microsoft.com"
      ]
    },
    "aadTenantId": {
      "type": [
        "string",
        "null"
      ],
      "description": "The Microsoft Entra (Azure AD) tenant ID.",
      "examples": [
        "a839b112-1253-6432-9bf6-94542403f21c"
      ]
    },
    "detectorId": {
      "type": [
        "string",
        "null"
      ],
      "description": "The ID of the detector that triggered the alert.",
      "examples": [
        "17e10bbc-3a68-474a-8aad-faef14d43952"
      ]
    },
    "comments": {
      "type": "array",
      "description": "Comments associated with the alert.",
      "items": {
        "$ref": "#/$defs/AlertComment"
      }
    },
    "evidence": {
      "type": "array",
      "description": "Evidence related to the alert, including files, processes, users, IPs, and URLs.",
      "items": {
        "$ref": "#/$defs/AlertEvidence"
      }
    }
  },
  "required": [
    "id",
    "severity",
    "status"
  ],
  "$defs": {
    "AlertComment": {
      "type": "object",
      "title": "Alert Comment",
      "description": "A comment associated with a security alert, including the comment text, author, and creation time.",
      "properties": {
        "comment": {
          "type": "string",
          "description": "The comment text."
        },
        "createdBy": {
          "type": "string",
          "description": "The user who created the comment.",
          "examples": [
            "secop123@contoso.com"
          ]
        },
        "createdTime": {
          "type": "string",
          "format": "date-time",
          "description": "The date and time when the comment was created."
        }
      },
      "required": [
        "comment",
        "createdBy",
        "createdTime"
      ]
    },
    "AlertEvidence": {
      "type": "object",
      "title": "Alert Evidence",
      "description": "Evidence associated with an alert. Can represent various entity types including User, Process, File, IP address, and URL.",
      "properties": {
        "entityType": {
          "type": "string",
          "description": "The type of evidence entity.",
          "enum": [
            "User",
            "Process",
            "File",
            "Ip",
            "Url"
          ]
        },
        "evidenceCreationTime": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "The time the evidence was created."
        },
        "sha1": {
          "type": [
            "string",
            "null"
          ],
          "description": "SHA-1 hash of the file."
        },
        "sha256": {
          "type": [
            "string",
            "null"
          ],
          "description": "SHA-256 hash of the file."
        },
        "fileName": {
          "type": [
            "string",
            "null"
          ],
          "description": "The file name."
        },
        "filePath": {
          "type": [
            "string",
            "null"
          ],
          "description": "The file path."
        },
        "processId": {
          "type": [
            "integer",
            "null"
          ],
          "description": "The process ID."
        },
        "processCommandLine": {
          "type": [
            "string",
            "null"
          ],
          "description": "The command line used to start the process."
        },
        "processCreationTime": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "The process creation time."
        },
        "parentProcessId": {
          "type": [
            "integer",
            "null"
          ],
          "description": "The parent process ID."
        },
        "parentProcessCreationTime": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "The parent process creation time."
        },
        "parentProcessFileName": {
          "type": [
            "string",
            "null"
          ],
          "description": "The parent process file name."
        },
        "parentProcessFilePath": {
          "type": [
            "string",
            "null"
          ],
          "description": "The parent process file path."
        },
        "ipAddress": {
          "type": [
            "string",
            "null"
          ],
          "description": "The IP address."
        },
        "url": {
          "type": [
            "string",
            "null"
          ],
          "description": "The URL."
        },
        "registryKey": {
          "type": [
            "string",
            "null"
          ],
          "description": "The registry key."
        },
        "registryHive": {
          "type": [
            "string",
            "null"
          ],
          "description": "The registry hive."
        },
        "registryValueType": {
          "type": [
            "string",
            "null"
          ],
          "description": "The registry value type."
        },
        "registryValue": {
          "type": [
            "string",
            "null"
          ],
          "description": "The registry value."
        },
        "accountName": {
          "type": [
            "string",
            "null"
          ],
          "description": "The account name."
        },
        "domainName": {
          "type": [
            "string",
            "null"
          ],
          "description": "The domain name."
        },
        "userSid": {
          "type": [
            "string",
            "null"
          ],
          "description": "The user security identifier (SID)."
        },
        "aadUserId": {
          "type": [
            "string",
            "null"
          ],
          "description": "The Microsoft Entra user ID."
        },
        "userPrincipalName": {
          "type": [
            "string",
            "null"
          ],
          "description": "The user principal name (UPN)."
        },
        "detectionStatus": {
          "type": [
            "string",
            "null"
          ],
          "description": "The detection status of the evidence.",
          "enum": [
            "Detected",
            "Blocked",
            "Prevented",
            null
          ]
        }
      },
      "required": [
        "entityType"
      ]
    }
  },
  "examples": [
    {
      "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.",
      "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": "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"
        }
      ]
    }
  ]
}