openapi: 3.1.0
info:
  title: Microsoft Defender for Endpoint Alerts Vulnerabilities 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: Vulnerabilities
  description: Retrieve vulnerability information from Microsoft Defender Vulnerability Management. Access CVE data, severity scores, exploit information, and exposure metrics.
  externalDocs:
    description: Vulnerabilities API documentation
    url: https://learn.microsoft.com/en-us/defender-endpoint/api/vulnerability
paths:
  /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:
      - Vulnerabilities
      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:
    get:
      operationId: listVulnerabilities
      summary: Microsoft Defender List all vulnerabilities
      description: Retrieves a list of all vulnerabilities affecting the organization. Supports OData V4 query parameters including $filter, $top (max 8,000), and $skip.
      tags:
      - Vulnerabilities
      parameters:
      - name: $filter
        in: query
        description: OData filter expression. Filterable properties include id, name, description, cvssV3, publishedOn, severity, and updatedOn.
        required: false
        schema:
          type: string
        example: severity eq 'Critical'
      - name: $top
        in: query
        description: Maximum number of results to return (max 8,000).
        required: false
        schema:
          type: integer
          maximum: 8000
        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 vulnerability objects.
          content:
            application/json:
              schema:
                type: object
                properties:
                  '@odata.context':
                    type: string
                    description: OData context URL.
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/Vulnerability'
        '401':
          description: Unauthorized. Invalid or missing authentication token.
        '403':
          description: Forbidden. Insufficient permissions.
        '429':
          description: Too many requests. Rate limit exceeded.
  /vulnerabilities/{vulnerabilityId}:
    get:
      operationId: getVulnerability
      summary: Microsoft Defender Get vulnerability by ID
      description: Retrieves a specific vulnerability by its CVE ID.
      tags:
      - Vulnerabilities
      parameters:
      - name: vulnerabilityId
        in: path
        description: The CVE identifier of the vulnerability.
        required: true
        schema:
          type: string
        example: CVE-2024-7256
      responses:
        '200':
          description: The vulnerability object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Vulnerability'
        '401':
          description: Unauthorized.
        '403':
          description: Forbidden.
        '404':
          description: Vulnerability 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:
      - Vulnerabilities
      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:
    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
  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