Microsoft Defender Assessments API

openapi: 3.2.0
info:
  title: Microsoft Defender for Cloud REST API (Microsoft.Security)…
  version: stable-composite
  description: Composite of the latest stable Microsoft.Security resource-manager swagger files published by Microsoft in Azure/azure-rest-api-specs. Each path keeps its own api-version via x-source.
  x-source-repo: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/security/resource-manager/Microsoft.Security/Security
servers:
- url: https://management.azure.com
security:
- azure_auth:
  - user_impersonation
tags:
- name: Assessments
paths:
  /{scope}/providers/Microsoft.Security/assessments:
    get:
      operationId: Assessments_List
      tags:
      - Assessments
      description: Get security assessments on all your scanned resources inside a scope
      parameters:
      - $ref: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/common-types/resource-management/v5/types.json#/parameters/ApiVersionParameter
      - name: scope
        in: path
        description: The fully qualified Azure Resource manager identifier of the resource.
        required: true
        x-ms-skip-url-encoding: true
        schema:
          type: string
      responses:
        '200':
          description: Azure operation completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecurityAssessmentList'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Common.CloudError'
      x-ms-examples:
        List security assessments:
          $ref: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/security/resource-manager/Microsoft.Security/Security/stable/2025-05-04/examples/Assessments/ListAssessments_example.json
      x-ms-pageable:
        nextLinkName: nextLink
      x-source: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/security/resource-manager/Microsoft.Security/Security/stable/2025-05-04/security-Assessment.json
      summary: Assessments list
      x-summary-source: derived
  /{resourceId}/providers/Microsoft.Security/assessments/{assessmentName}:
    get:
      operationId: Assessments_Get
      tags:
      - Assessments
      description: Get a security assessment on your scanned resource
      parameters:
      - $ref: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/common-types/resource-management/v5/types.json#/parameters/ApiVersionParameter
      - name: resourceId
        in: path
        description: The fully qualified Azure Resource manager identifier of the resource.
        required: true
        x-ms-skip-url-encoding: true
        schema:
          type: string
      - name: assessmentName
        in: path
        description: The Assessment Key - Unique key for the assessment type
        required: true
        schema:
          type: string
      - name: $expand
        in: query
        description: OData expand. Optional.
        required: false
        x-ms-enum:
          name: ExpandEnum
          modelAsString: true
          values:
          - name: links
            value: links
            description: All links associated with an assessment
          - name: metadata
            value: metadata
            description: Assessment metadata
        schema:
          type: string
          enum:
          - links
          - metadata
      responses:
        '200':
          description: Azure operation completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecurityAssessmentResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Common.CloudError'
      x-ms-examples:
        Get security recommendation task from security data location:
          $ref: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/security/resource-manager/Microsoft.Security/Security/stable/2025-05-04/examples/Assessments/GetAssessment_example.json
        Get security recommendation task from security data location with expand parameter:
          $ref: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/security/resource-manager/Microsoft.Security/Security/stable/2025-05-04/examples/Assessments/GetAssessmentWithExpand_example.json
      x-source: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/security/resource-manager/Microsoft.Security/Security/stable/2025-05-04/security-Assessment.json
      summary: Assessments get
      x-summary-source: derived
    put:
      operationId: Assessments_CreateOrUpdate
      tags:
      - Assessments
      description: Create a security assessment on your resource. An assessment metadata that describes this assessment must be predefined with the same name before inserting the assessment result
      parameters:
      - $ref: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/common-types/resource-management/v5/types.json#/parameters/ApiVersionParameter
      - name: resourceId
        in: path
        description: The fully qualified Azure Resource manager identifier of the resource.
        required: true
        x-ms-skip-url-encoding: true
        schema:
          type: string
      - name: assessmentName
        in: path
        description: The Assessment Key - Unique key for the assessment type
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Resource 'SecurityAssessmentResponse' update operation succeeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecurityAssessmentResponse'
        '201':
          description: Resource 'SecurityAssessmentResponse' create operation succeeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecurityAssessmentResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Common.CloudError'
      x-ms-examples:
        Create security recommendation task on a resource:
          $ref: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/security/resource-manager/Microsoft.Security/Security/stable/2025-05-04/examples/Assessments/PutAssessment_example.json
      x-source: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/security/resource-manager/Microsoft.Security/Security/stable/2025-05-04/security-Assessment.json
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SecurityAssessment'
        description: Calculated assessment on a pre-defined assessment metadata
        required: true
      summary: Assessments create or update
      x-summary-source: derived
    delete:
      operationId: Assessments_Delete
      tags:
      - Assessments
      description: Delete a security assessment on your resource. An assessment metadata that describes this assessment must be predefined with the same name before inserting the assessment result
      parameters:
      - $ref: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/common-types/resource-management/v5/types.json#/parameters/ApiVersionParameter
      - name: resourceId
        in: path
        description: The fully qualified Azure Resource manager identifier of the resource.
        required: true
        x-ms-skip-url-encoding: true
        schema:
          type: string
      - name: assessmentName
        in: path
        description: The Assessment Key - Unique key for the assessment type
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Resource deleted successfully.
        '204':
          description: Resource does not exist.
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Common.CloudError'
      x-ms-examples:
        Delete a security recommendation task on a resource:
          $ref: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/security/resource-manager/Microsoft.Security/Security/stable/2025-05-04/examples/Assessments/DeleteAssessment_example.json
      x-source: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/security/resource-manager/Microsoft.Security/Security/stable/2025-05-04/security-Assessment.json
      summary: Assessments delete
      x-summary-source: derived
components:
  schemas:
    AssessmentStatusResponse:
      type: object
      description: The result of the assessment
      properties:
        firstEvaluationDate:
          readOnly: true
          type: string
          format: date-time
          description: The time that the assessment was created and first evaluated. Returned as UTC time in ISO 8601 format
        statusChangeDate:
          readOnly: true
          type: string
          format: date-time
          description: The time that the status of the assessment last changed. Returned as UTC time in ISO 8601 format
      allOf:
      - $ref: '#/components/schemas/AssessmentStatus'
    Common.CloudErrorBody:
      type: object
      description: The error detail.
      properties:
        code:
          type: string
          description: The error code.
          readOnly: true
        message:
          type: string
          description: The error message.
          readOnly: true
        target:
          type: string
          description: The error target.
          readOnly: true
        details:
          type: array
          description: The error details.
          items:
            $ref: '#/components/schemas/Common.CloudErrorBody'
          readOnly: true
          x-ms-identifiers: []
        additionalInfo:
          type: array
          description: The error additional info.
          items:
            $ref: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/common-types/resource-management/v5/types.json#/definitions/ErrorAdditionalInfo
          readOnly: true
          x-ms-identifiers: []
      x-ms-external: true
    SecurityAssessmentPropertiesBase:
      type: object
      description: Describes properties of an assessment.
      properties:
        resourceDetails:
          $ref: ./common/v1/types.json#/definitions/ResourceDetails
        displayName:
          readOnly: true
          type: string
          description: User friendly display name of the assessment
        additionalData:
          type: object
          description: Additional data regarding the assessment
          additionalProperties:
            type: string
        links:
          $ref: '#/components/schemas/AssessmentLinks'
        metadata:
          $ref: ./assessmentMetadata.json#/definitions/SecurityAssessmentMetadataProperties
        partnersData:
          $ref: '#/components/schemas/SecurityAssessmentPartnerData'
      required:
      - resourceDetails
    AssessmentLinks:
      type: object
      description: Links relevant to the assessment
      readOnly: true
      properties:
        azurePortalUri:
          type: string
          description: Link to assessment in Azure Portal
          readOnly: true
    SecurityAssessmentResponse:
      type: object
      description: Security assessment on a resource - response format
      properties:
        properties:
          x-ms-client-flatten: true
          $ref: '#/components/schemas/SecurityAssessmentPropertiesResponse'
      allOf:
      - $ref: ./common/v1/types.json#/definitions/Resource
    SecurityAssessmentList:
      type: object
      description: Page of a security assessments list
      properties:
        value:
          description: Collection of security assessments in this page
          readOnly: true
          type: array
          items:
            $ref: '#/components/schemas/SecurityAssessmentResponse'
        nextLink:
          readOnly: true
          type: string
          description: The URI to fetch the next page.
    SecurityAssessmentPartnerData:
      type: object
      description: Data regarding 3rd party partner integration
      properties:
        partnerName:
          type: string
          description: Name of the company of the partner
        secret:
          type: string
          description: secret to authenticate the partner - write only
          x-ms-secret: true
      required:
      - partnerName
      - secret
    SecurityAssessmentProperties:
      type: object
      description: Describes properties of an assessment.
      properties:
        status:
          $ref: '#/components/schemas/AssessmentStatus'
      allOf:
      - $ref: '#/components/schemas/SecurityAssessmentPropertiesBase'
      required:
      - status
    SecurityAssessmentPropertiesResponse:
      type: object
      description: Describes properties of an assessment.
      properties:
        status:
          $ref: '#/components/schemas/AssessmentStatusResponse'
      allOf:
      - $ref: '#/components/schemas/SecurityAssessmentPropertiesBase'
      required:
      - status
    SecurityAssessment:
      type: object
      description: Security assessment on a resource
      properties:
        properties:
          x-ms-client-flatten: true
          $ref: '#/components/schemas/SecurityAssessmentProperties'
      allOf:
      - $ref: ./common/v1/types.json#/definitions/Resource
    AssessmentStatus:
      type: object
      description: The result of the assessment
      properties:
        code:
          type: string
          description: Programmatic code for the status of the assessment
          enum:
          - Healthy
          - Unhealthy
          - NotApplicable
          x-ms-enum:
            name: AssessmentStatusCode
            modelAsString: true
            values:
            - value: Healthy
              description: The resource is healthy
            - value: Unhealthy
              description: The resource has a security issue that needs to be addressed
            - value: NotApplicable
              description: Assessment for this resource did not happen
        cause:
          type: string
          description: Programmatic code for the cause of the assessment status
        description:
          type: string
          description: Human readable description of the assessment status
      required:
      - code
    Common.CloudError:
      type: object
      description: Common error response for all Azure Resource Manager APIs to return error details for failed operations. (This also follows the OData error response format.).
      properties:
        error:
          $ref: '#/components/schemas/Common.CloudErrorBody'
          description: The error object.
          x-ms-client-flatten: true
      x-ms-external: true
  securitySchemes:
    azure_auth:
      type: oauth2
      flows:
        implicit:
          scopes:
            user_impersonation: impersonate your user account
          authorizationUrl: https://login.microsoftonline.com/common/oauth2/authorize
      description: Azure Active Directory OAuth2 Flow.