Microsoft Defender

Microsoft Defender Machines API

Manage devices (machines) that have communicated with Microsoft Defender for Endpoint. Retrieve device information, health status, risk scores, and exposure levels.

GitHub OpenAPI

Documentation

📖
Documentation
https://learn.microsoft.com/en-us/defender-endpoint/api/apis-intro
📖
Authentication
https://learn.microsoft.com/en-us/defender-endpoint/api/exposed-apis-create-app-webapp
📖
APIReference
https://learn.microsoft.com/en-us/defender-endpoint/api/exposed-apis-list
📖
Documentation
https://learn.microsoft.com/en-us/graph/api/resources/security-api-overview

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/microsoft-defender/refs/heads/main/openapi/microsoft-defender-machines-api-openapi.yml

Schemas & Data

📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/microsoft-defender/refs/heads/main/json-schema/microsoft-defender-alert-schema.json

Other Resources

🔗
JSONLD
https://raw.githubusercontent.com/api-evangelist/microsoft-defender/refs/heads/main/json-ld/microsoft-defender-context.jsonld
🔗
Pricing
https://www.microsoft.com/en-us/security/business/endpoint-security/microsoft-defender-endpoint-pricing
🔗
ReleaseNotes
https://learn.microsoft.com/en-us/defender-endpoint/api/api-release-notes
🔗
Management APIs
https://learn.microsoft.com/en-us/defender-endpoint/api/management-apis
🔗
Alerts API
https://learn.microsoft.com/en-us/defender-endpoint/api/get-alerts
🔗
Vulnerabilities API
https://learn.microsoft.com/en-us/defender-endpoint/api/get-all-vulnerabilities
🔗
Security Recommendations API
https://learn.microsoft.com/en-us/defender-endpoint/api/get-security-recommendations
🔗
SDKs
https://learn.microsoft.com/en-us/graph/sdks/sdks-overview
🔗
Code Samples
https://learn.microsoft.com/en-us/graph/api/resources/security-api-overview#common-use-cases

OpenAPI Specification

microsoft-defender-machines-api-openapi.yml Raw ↑ 
openapi: 3.1.0
info:
  title: Microsoft Defender for Endpoint Alerts Machines API
  description: API for endpoint detection and response, threat and vulnerability management, and automated investigation and remediation. Provides programmatic access to alerts, machines, and vulnerabilities managed by Microsoft Defender for Endpoint.
  version: 1.0.0
  contact:
    name: Microsoft Defender for Endpoint
    url: https://learn.microsoft.com/en-us/defender-endpoint/api/apis-intro
  license:
    name: Microsoft API Terms of Use
    url: https://www.microsoft.com/en-us/legal/terms-of-use
  x-api-id: microsoft-defender-for-endpoint
servers:
- url: https://api.security.microsoft.com/api
  description: Global production endpoint
- url: https://us.api.security.microsoft.com/api
  description: United States regional endpoint
- url: https://eu.api.security.microsoft.com/api
  description: Europe regional endpoint
- url: https://uk.api.security.microsoft.com/api
  description: United Kingdom regional endpoint
- url: https://au.api.security.microsoft.com/api
  description: Australia regional endpoint
security:
- oauth2: []
tags:
- name: Machines
  description: Manage devices (machines) that have communicated with Microsoft Defender for Endpoint. Retrieve device information, health status, risk scores, and exposure levels.
  externalDocs:
    description: Machines API documentation
    url: https://learn.microsoft.com/en-us/defender-endpoint/api/machine
paths:
  /machines:
    get:
      operationId: listMachines
      summary: Microsoft Defender List machines
      description: Retrieves a collection of machines that have communicated with Microsoft Defender for Endpoint. Supports OData V4 query parameters including $filter, $top (max 10,000), and $skip. Rate limited to 100 calls per minute and 1,500 calls per hour.
      tags:
      - Machines
      parameters:
      - name: $filter
        in: query
        description: OData filter expression. Filterable properties include computerDnsName, id, version, deviceValue, aadDeviceId, machineTags, lastSeen, exposureLevel, onboardingStatus, lastIpAddress, healthStatus, osPlatform, riskScore, and rbacGroupId.
        required: false
        schema:
          type: string
        example: healthStatus eq 'Active' and riskScore eq 'High'
      - name: $top
        in: query
        description: Maximum number of results to return (max 10,000).
        required: false
        schema:
          type: integer
          maximum: 10000
        example: 50
      - name: $skip
        in: query
        description: Number of results to skip for pagination.
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: A collection of machine objects.
          content:
            application/json:
              schema:
                type: object
                properties:
                  '@odata.context':
                    type: string
                    description: OData context URL.
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/Machine'
        '401':
          description: Unauthorized. Invalid or missing authentication token.
        '403':
          description: Forbidden. Insufficient permissions.
        '404':
          description: No recent machines found.
        '429':
          description: Too many requests. Rate limit exceeded.
  /machines/{machineId}:
    get:
      operationId: getMachine
      summary: Microsoft Defender Get machine by ID
      description: Retrieves a specific machine by its device ID or computer name.
      tags:
      - Machines
      parameters:
      - name: machineId
        in: path
        description: The device ID or computer name of the machine.
        required: true
        schema:
          type: string
        example: 1e5bc9d7e413ddd7902c2932e418702b84d0cc07
      responses:
        '200':
          description: The machine object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Machine'
        '401':
          description: Unauthorized. Invalid or missing authentication token.
        '403':
          description: Forbidden. Insufficient permissions.
        '404':
          description: Machine with the specified ID was not found.
  /machines/{machineId}/alerts:
    get:
      operationId: listMachineAlerts
      summary: Microsoft Defender List alerts for a machine
      description: Retrieves a collection of alerts related to a specific machine.
      tags:
      - Machines
      parameters:
      - name: machineId
        in: path
        description: The device ID of the machine.
        required: true
        schema:
          type: string
        example: 1e5bc9d7e413ddd7902c2932e418702b84d0cc07
      responses:
        '200':
          description: A collection of alert objects for the specified machine.
          content:
            application/json:
              schema:
                type: object
                properties:
                  '@odata.context':
                    type: string
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/Alert'
        '401':
          description: Unauthorized.
        '403':
          description: Forbidden.
        '404':
          description: Machine not found.
  /machines/{machineId}/vulnerabilities:
    get:
      operationId: listMachineVulnerabilities
      summary: Microsoft Defender List vulnerabilities for a machine
      description: Retrieves a collection of discovered vulnerabilities related to a specific machine.
      tags:
      - Machines
      parameters:
      - name: machineId
        in: path
        description: The device ID of the machine.
        required: true
        schema:
          type: string
        example: 1e5bc9d7e413ddd7902c2932e418702b84d0cc07
      responses:
        '200':
          description: A collection of vulnerability objects for the machine.
          content:
            application/json:
              schema:
                type: object
                properties:
                  '@odata.context':
                    type: string
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/Vulnerability'
        '401':
          description: Unauthorized.
        '403':
          description: Forbidden.
        '404':
          description: Machine not found.
  /vulnerabilities/{vulnerabilityId}/machineReferences:
    get:
      operationId: listVulnerabilityMachineReferences
      summary: Microsoft Defender List machines affected by a vulnerability
      description: Retrieves a list of machines affected by a specific vulnerability.
      tags:
      - Machines
      parameters:
      - name: vulnerabilityId
        in: path
        description: The CVE identifier of the vulnerability.
        required: true
        schema:
          type: string
        example: CVE-2024-7256
      responses:
        '200':
          description: A collection of machine references for the vulnerability.
          content:
            application/json:
              schema:
                type: object
                properties:
                  '@odata.context':
                    type: string
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/MachineReference'
        '401':
          description: Unauthorized.
        '403':
          description: Forbidden.
        '404':
          description: Vulnerability not found.
components:
  schemas:
    IpAddress:
      type: object
      description: An IP address associated with a machine.
      properties:
        ipAddress:
          type: string
          description: The IP address.
        macAddress:
          type: string
          description: The MAC address.
        type:
          type: string
          description: The type of IP address.
        operationalStatus:
          type: string
          description: The operational status of the network adapter.
    RelatedUser:
      type: object
      description: Details of a user related to an alert.
      properties:
        userName:
          type: string
          description: The user name.
        domainName:
          type: string
          description: The domain name.
    Machine:
      type: object
      description: Represents a device (machine) that has communicated with Microsoft Defender for Endpoint, including its health status, risk assessment, and configuration details.
      properties:
        id:
          type: string
          description: The unique machine identity.
          examples:
          - 1e5bc9d7e413ddd7902c2932e418702b84d0cc07
        computerDnsName:
          type: string
          description: The fully qualified domain name of the machine.
          examples:
          - mymachine1.contoso.com
        firstSeen:
          type: string
          format: date-time
          description: The first date and time where the machine was observed by Microsoft Defender for Endpoint.
        lastSeen:
          type: string
          format: date-time
          description: The time and date of the last received full device report. A device typically sends a full report every 24 hours.
        osPlatform:
          type: string
          description: The operating system platform.
          examples:
          - Windows10
          - Windows11
          - Linux
        onboardingStatus:
          type: string
          description: The onboarding status of the machine.
          enum:
          - Onboarded
          - CanBeOnboarded
          - Unsupported
          - InsufficientInfo
        osProcessor:
          type: string
          description: The operating system processor. Deprecated in favor of osArchitecture.
          deprecated: true
        version:
          type:
          - string
          - 'null'
          description: The operating system version.
        osBuild:
          type:
          - integer
          - 'null'
          format: int64
          description: The operating system build number.
        lastIpAddress:
          type:
          - string
          - 'null'
          description: The last IP address on the local NIC of the machine.
        lastExternalIpAddress:
          type:
          - string
          - 'null'
          description: The last IP address through which the machine accessed the internet.
        healthStatus:
          type: string
          description: The machine health status.
          enum:
          - Active
          - Inactive
          - ImpairedCommunication
          - NoSensorData
          - NoSensorDataImpairedCommunication
          - Unknown
        rbacGroupName:
          type:
          - string
          - 'null'
          description: The machine group name.
        rbacGroupId:
          type:
          - integer
          - 'null'
          description: The machine group ID.
        riskScore:
          type:
          - string
          - 'null'
          description: The risk score as evaluated by Microsoft Defender for Endpoint.
          enum:
          - None
          - Informational
          - Low
          - Medium
          - High
          - null
        aadDeviceId:
          type:
          - string
          - 'null'
          format: uuid
          description: The Microsoft Entra Device ID (when the machine is Microsoft Entra joined).
        machineTags:
          type: array
          items:
            type: string
          description: Set of machine tags.
        exposureLevel:
          type:
          - string
          - 'null'
          description: The exposure level as evaluated by Microsoft Defender for Endpoint.
          enum:
          - None
          - Low
          - Medium
          - High
          - null
        deviceValue:
          type:
          - string
          - 'null'
          description: The value of the device.
          enum:
          - Normal
          - Low
          - High
          - null
        ipAddresses:
          type: array
          items:
            $ref: '#/components/schemas/IpAddress'
          description: Set of IP address objects associated with the machine.
        osArchitecture:
          type:
          - string
          - 'null'
          description: The operating system architecture.
          enum:
          - 32-bit
          - 64-bit
          - null
    AlertEvidence:
      type: object
      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 process command line.
        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.
        detectionStatus:
          type:
          - string
          - 'null'
          description: The detection status of the evidence.
          enum:
          - Detected
          - Blocked
          - Prevented
          - null
    Alert:
      type: object
      description: Represents a security alert generated by Microsoft Defender for Endpoint, indicating a detected threat, suspicious activity, or security event on an endpoint.
      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 and its context.
        alertCreationTime:
          type:
          - string
          - 'null'
          format: date-time
          description: The date and time (in UTC) 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'
          format: int64
          description: The incident ID associated with the alert.
        investigationId:
          type:
          - integer
          - 'null'
          format: int64
          description: The investigation ID related to the alert.
        investigationState:
          type:
          - string
          - 'null'
          description: The current state of the 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.
        rbacGroupName:
          type:
          - string
          - 'null'
          description: The role-based access control device group name.
        mitreTechniques:
          type: array
          items:
            type: string
          description: MITRE ATT&CK Enterprise technique IDs associated with the alert.
          examples:
          - - T1064
            - T1085
            - T1220
        relatedUser:
          $ref: '#/components/schemas/RelatedUser'
        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.
          enum:
          - TruePositive
          - InformationalExpectedActivity
          - FalsePositive
          - null
        determination:
          type:
          - string
          - 'null'
          description: The determination of the alert.
          enum:
          - MultiStagedAttack
          - MaliciousUserActivity
          - CompromisedUser
          - Malware
          - Phishing
          - UnwantedSoftware
          - SecurityTesting
          - LineOfBusinessApplication
          - ConfirmedActivity
          - NotMalicious
          - InsufficientData
          - Other
          - null
        category:
          type:
          - string
          - 'null'
          description: The category of the alert.
          examples:
          - Execution
          - SuspiciousActivity
        detectionSource:
          type:
          - string
          - 'null'
          description: The source that detected the alert.
          examples:
          - WindowsDefenderAtp
          - WindowsDefenderAv
        threatFamilyName:
          type:
          - string
          - 'null'
          description: The threat family name associated with the alert.
        threatName:
          type:
          - string
          - 'null'
          description: The specific threat name.
        machineId:
          type:
          - string
          - 'null'
          description: The ID of the machine entity associated with the alert.
        computerDnsName:
          type:
          - string
          - 'null'
          description: The fully qualified domain name of the machine.
        aadTenantId:
          type:
          - string
          - 'null'
          description: The Microsoft Entra tenant ID.
        detectorId:
          type:
          - string
          - 'null'
          description: The ID of the detector that triggered the alert.
        comments:
          type: array
          items:
            $ref: '#/components/schemas/AlertComment'
          description: Comments associated with the alert.
        evidence:
          type: array
          items:
            $ref: '#/components/schemas/AlertEvidence'
          description: Evidence related to the alert.
    MachineReference:
      type: object
      description: A reference to a machine affected by a vulnerability.
      properties:
        id:
          type: string
          description: The machine ID.
        computerDnsName:
          type: string
          description: The fully qualified domain name of the machine.
        osPlatform:
          type: string
          description: The operating system platform.
        rbacGroupName:
          type:
          - string
          - 'null'
          description: The RBAC group name.
    Vulnerability:
      type: object
      description: Represents a known vulnerability (CVE) detected by Microsoft Defender Vulnerability Management, including severity, CVSS scoring, exploit information, and exposure metrics.
      properties:
        id:
          type: string
          description: The vulnerability ID (CVE identifier).
          examples:
          - CVE-2024-7256
        name:
          type: string
          description: The vulnerability title.
        description:
          type: string
          description: A detailed description of the vulnerability.
        severity:
          type: string
          description: The severity of the vulnerability.
          enum:
          - Low
          - Medium
          - High
          - Critical
        cvssV3:
          type:
          - number
          - 'null'
          format: double
          description: The CVSS v3 score.
        cvssVector:
          type:
          - string
          - 'null'
          description: A compressed textual representation that reflects the values used to derive the CVSS score.
          examples:
          - CVSS:3.0/AV:N/AC:L/PR:N/UI:R/S:U/C:H/I:H/A:H/E:U/RL:O/RC:C
        exposedMachines:
          type: integer
          format: int64
          description: The number of exposed devices.
        publishedOn:
          type: string
          format: date-time
          description: The date when the vulnerability was published.
        updatedOn:
          type: string
          format: date-time
          description: The date when the vulnerability was last updated.
        publicExploit:
          type: boolean
          description: Whether a public exploit exists.
        exploitVerified:
          type: boolean
          description: Whether the exploit has been verified to work.
        exploitInKit:
          type: boolean
          description: Whether the exploit is part of an exploit kit.
        exploitTypes:
          type: array
          items:
            type: string
          description: The types of exploit effects.
          examples:
          - - Local privilege escalation
            - Denial of service
            - Local
        exploitUris:
          type: array
          items:
            type: string
            format: uri
          description: Exploit source URLs.
        cveSupportability:
          type: string
          description: The CVE supportability status.
          enum:
          - Supported
          - NotSupported
          - SupportedInPremium
        epss:
          type:
          - number
          - 'null'
          description: The Exploit Prediction Scoring System (EPSS) probability that the vulnerability will be exploited, expressed as a value between 0 and 1.
          minimum: 0
          maximum: 1
        status:
          type:
          - string
          - 'null'
          description: The remediation status of the vulnerability.
          enum:
          - RemediationRequired
          - NoActionRequired
          - UnderException
          - PartialException
          - null
    AlertComment:
      type: object
      description: A comment associated with an alert.
      properties:
        comment:
          type: string
          description: The comment text.
        createdBy:
          type: string
          description: The user who created the comment.
        createdTime:
          type: string
          format: date-time
          description: The date and time the comment was created.
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 authentication using Microsoft Entra ID (Azure AD). Supports both application-level and delegated permissions.
      flows:
        clientCredentials:
          tokenUrl: https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token
          scopes:
            https://api.security.microsoft.com/.default: Default scope for application permissions
        authorizationCode:
          authorizationUrl: https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/authorize
          tokenUrl: https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token
          scopes:
            https://api.security.microsoft.com/.default: Default scope for delegated permissions
externalDocs:
  description: Microsoft Defender for Endpoint API documentation
  url: https://learn.microsoft.com/en-us/defender-endpoint/api/apis-intro