swagger: "2.0"
schemes:
  - https
host: management.azure.com
info:
  description: API spec for Microsoft.Security (Azure Security Center) resource provider
  title: Security Center
  version: 2020-01-01
  x-apisguru-categories:
    - cloud
  x-logo:
    url: https://api.apis.guru/v2/cache/logo/https_assets.onestore.ms_cdnfiles_onestorerolling-1606-01000_shell_v3_images_logo_microsoft.png
  x-origin:
    - format: swagger
      url: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/master/specification/security/resource-manager/Microsoft.Security/stable/2020-01-01/assessments.json
      version: "2.0"
  x-preferred: true
  x-providerName: azure.com
  x-serviceName: security-assessments
  x-tags:
    - Azure
    - Microsoft
consumes:
  - application/json
produces:
  - application/json
securityDefinitions:
  azure_auth:
    authorizationUrl: https://login.microsoftonline.com/common/oauth2/authorize
    description: Azure Active Directory OAuth2 Flow
    flow: implicit
    scopes:
      user_impersonation: impersonate your user account
    type: oauth2
security:
  - azure_auth:
      - user_impersonation
parameters:
  AssessmentBody:
    description: Calculated assessment on a pre-defined assessment metadata
    in: body
    name: assessment
    required: true
    schema:
      $ref: "#/definitions/SecurityAssessment"
    x-ms-parameter-location: method
  AssessmentName:
    description: The Assessment Key - Unique key for the assessment type
    in: path
    name: assessmentName
    required: true
    type: string
    x-ms-parameter-location: method
  ExpandAssessments:
    description: OData expand. Optional.
    enum:
      - links
      - metadata
    in: query
    name: $expand
    required: false
    type: string
    x-ms-enum:
      modelAsString: true
      name: ExpandEnum
      values:
        - description: All links associated with an assessment
          value: links
        - description: Assessment metadata
          value: metadata
    x-ms-parameter-location: method
paths:
  "/{resourceId}/providers/Microsoft.Security/assessments/{assessmentName}":
    delete:
      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
      operationId: Assessments_Delete
      parameters:
        - description: API version for the operation
          in: query
          name: api-version
          required: true
          type: string
        - description: The identifier of the resource.
          in: path
          name: resourceId
          required: true
          type: string
          x-ms-parameter-location: method
        - $ref: "#/parameters/AssessmentName"
      responses:
        "200":
          description: OK - Assessment was deleted
        "204":
          description: No Content - Assessment does not exist
        default:
          description: Error response describing why the operation failed.
          schema:
            description: Error response structure.
            properties:
              error:
                description: Error details.
                properties:
                  code:
                    description: An identifier for the error. Codes are invariant and are intended to be consumed programmatically.
                    readOnly: true
                    type: string
                  message:
                    description: A message describing the error, intended to be suitable for display in a user interface.
                    readOnly: true
                    type: string
                type: object
                x-ms-external: true
            type: object
            x-ms-external: true
      tags:
        - Assessments
      x-ms-examples:
        Delete a security recommendation task on a resource:
          parameters:
            api-version: 2020-01-01
            assessmentName: 8bb8be0a-6010-4789-812f-e4d661c4ed0e
            resourceId: subscriptions/20ff7fc3-e762-44dd-bd96-b71116dcdc23/resourceGroups/myRg/providers/Microsoft.Compute/virtualMachineScaleSets/vmss2
          responses:
            "200": {}
            "204": {}
    get:
      description: Get a security assessment on your scanned resource
      operationId: Assessments_Get
      parameters:
        - description: API version for the operation
          in: query
          name: api-version
          required: true
          type: string
        - description: The identifier of the resource.
          in: path
          name: resourceId
          required: true
          type: string
          x-ms-parameter-location: method
        - $ref: "#/parameters/AssessmentName"
        - $ref: "#/parameters/ExpandAssessments"
      responses:
        "200":
          description: OK
          schema:
            $ref: "#/definitions/SecurityAssessment"
        default:
          description: Error response describing why the operation failed.
          schema:
            description: Error response structure.
            properties:
              error:
                description: Error details.
                properties:
                  code:
                    description: An identifier for the error. Codes are invariant and are intended to be consumed programmatically.
                    readOnly: true
                    type: string
                  message:
                    description: A message describing the error, intended to be suitable for display in a user interface.
                    readOnly: true
                    type: string
                type: object
                x-ms-external: true
            type: object
            x-ms-external: true
      tags:
        - Assessments
      x-ms-examples:
        Get security recommendation task from security data location:
          parameters:
            api-version: 2020-01-01
            assessmentName: 21300918-b2e3-0346-785f-c77ff57d243b
            resourceId: subscriptions/20ff7fc3-e762-44dd-bd96-b71116dcdc23/resourceGroups/myRg/providers/Microsoft.Compute/virtualMachineScaleSets/vmss2
          responses:
            "200":
              body:
                id: /subscriptions/20ff7fc3-e762-44dd-bd96-b71116dcdc23/resourceGroups/myRg/providers/Microsoft.Compute/virtualMachineScaleSets/vmss2/providers/Microsoft.Security/assessments/21300918-b2e3-0346-785f-c77ff57d243b
                name: 21300918-b2e3-0346-785f-c77ff57d243b
                properties:
                  additionalData:
                    linkedWorkspaceId: /subscriptions/20ff7fc3-e762-44dd-bd96-b71116dcdc23/resourceGroups/myRg/providers/Microsoft.OperationalInsights/workspaces/myLaWorkspace
                  displayName: Install endpoint protection solution on virtual machine scale sets
                  resourceDetails:
                    id: /subscriptions/20ff7fc3-e762-44dd-bd96-b71116dcdc23/resourceGroups/myRg/providers/Microsoft.Compute/virtualMachineScaleSets/vmss2
                    source: Azure
                  status:
                    cause: OffByPolicy
                    code: NotApplicable
                    description: The effective policy for the assessment was evaluated to off - use Microsoft.Authorization/policyAssignments to turn this assessment on
                type: Microsoft.Security/assessments
        Get security recommendation task from security data location with expand parameter:
          parameters:
            $expand: links
            api-version: 2020-01-01
            assessmentName: 21300918-b2e3-0346-785f-c77ff57d243b
            resourceId: subscriptions/20ff7fc3-e762-44dd-bd96-b71116dcdc23/resourceGroups/myRg/providers/Microsoft.Compute/virtualMachineScaleSets/vmss2
          responses:
            "200":
              body:
                id: /subscriptions/20ff7fc3-e762-44dd-bd96-b71116dcdc23/resourceGroups/myRg/providers/Microsoft.Compute/virtualMachineScaleSets/vmss2/providers/Microsoft.Security/assessments/21300918-b2e3-0346-785f-c77ff57d243b
                name: 21300918-b2e3-0346-785f-c77ff57d243b
                properties:
                  additionalData:
                    linkedWorkspaceId: /subscriptions/20ff7fc3-e762-44dd-bd96-b71116dcdc23/resourceGroups/myRg/providers/Microsoft.OperationalInsights/workspaces/myLaWorkspace
                  displayName: Install endpoint protection solution on virtual machine scale sets
                  links:
                    azurePortalUri: https://www.portal.azure.com/?fea#blade/Microsoft_Azure_Security/RecommendationsBlade/assessmentKey/21300918-b2e3-0346-785f-c77ff57d243b
                  resourceDetails:
                    id: /subscriptions/20ff7fc3-e762-44dd-bd96-b71116dcdc23/resourceGroups/myRg/providers/Microsoft.Compute/virtualMachineScaleSets/vmss2
                    source: Azure
                  status:
                    cause: OffByPolicy
                    code: NotApplicable
                    description: The effective policy for the assessment was evaluated to off - use Microsoft.Authorization/policyAssignments to turn this assessment on
                type: Microsoft.Security/assessments
    put:
      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
      operationId: Assessments_CreateOrUpdate
      parameters:
        - description: API version for the operation
          in: query
          name: api-version
          required: true
          type: string
        - description: The identifier of the resource.
          in: path
          name: resourceId
          required: true
          type: string
          x-ms-parameter-location: method
        - $ref: "#/parameters/AssessmentName"
        - $ref: "#/parameters/AssessmentBody"
      responses:
        "200":
          description: OK - Updated
          schema:
            $ref: "#/definitions/SecurityAssessment"
        "201":
          description: Created
          schema:
            $ref: "#/definitions/SecurityAssessment"
        default:
          description: Error response describing why the operation failed.
          schema:
            description: Error response structure.
            properties:
              error:
                description: Error details.
                properties:
                  code:
                    description: An identifier for the error. Codes are invariant and are intended to be consumed programmatically.
                    readOnly: true
                    type: string
                  message:
                    description: A message describing the error, intended to be suitable for display in a user interface.
                    readOnly: true
                    type: string
                type: object
                x-ms-external: true
            type: object
            x-ms-external: true
      tags:
        - Assessments
      x-ms-examples:
        Create security recommendation task on a resource:
          parameters:
            api-version: 2020-01-01
            assessment:
              properties:
                resourceDetails:
                  source: Azure
                status:
                  code: Healthy
            assessmentName: 8bb8be0a-6010-4789-812f-e4d661c4ed0e
            resourceId: subscriptions/20ff7fc3-e762-44dd-bd96-b71116dcdc23/resourceGroups/myRg/providers/Microsoft.Compute/virtualMachineScaleSets/vmss2
          responses:
            "200":
              body:
                id: /subscriptions/20ff7fc3-e762-44dd-bd96-b71116dcdc23/resourceGroups/myRg/providers/Microsoft.Compute/virtualMachineScaleSets/vmss1/providers/Microsoft.Security/assessments/8bb8be0a-6010-4789-812f-e4d661c4ed0e
                name: 8bb8be0a-6010-4789-812f-e4d661c4ed0e
                properties:
                  displayName: Install internal agent on VM
                  resourceDetails:
                    id: /subscriptions/20ff7fc3-e762-44dd-bd96-b71116dcdc23/resourceGroups/myRg/providers/Microsoft.Compute/virtualMachineScaleSets/vmss1/providers/Microsoft.Security/assessments/8bb8be0a-6010-4789-812f-e4d661c4ed0e
                    source: Azure
                  status:
                    code: Healthy
                type: Microsoft.Security/assessments
            "201":
              body:
                id: /subscriptions/20ff7fc3-e762-44dd-bd96-b71116dcdc23/resourceGroups/myRg/providers/Microsoft.Compute/virtualMachineScaleSets/vmss1/providers/Microsoft.Security/assessments/8bb8be0a-6010-4789-812f-e4d661c4ed0e
                name: 8bb8be0a-6010-4789-812f-e4d661c4ed0e
                properties:
                  displayName: Install internal agent on VM
                  resourceDetails:
                    id: /subscriptions/20ff7fc3-e762-44dd-bd96-b71116dcdc23/resourceGroups/myRg/providers/Microsoft.Compute/virtualMachineScaleSets/vmss1/providers/Microsoft.Security/assessments/8bb8be0a-6010-4789-812f-e4d661c4ed0e
                    source: Azure
                  status:
                    code: Healthy
                type: Microsoft.Security/assessments
  "/{scope}/providers/Microsoft.Security/assessments":
    get:
      description: Get security assessments on all your scanned resources inside a scope
      operationId: Assessments_List
      parameters:
        - description: API version for the operation
          in: query
          name: api-version
          required: true
          type: string
        - description: Scope of the query, can be subscription (/subscriptions/0b06d9ea-afe6-4779-bd59-30e5c2d9d13f) or management group (/providers/Microsoft.Management/managementGroups/mgName).
          in: path
          name: scope
          required: true
          type: string
          x-ms-parameter-location: method
      responses:
        "200":
          description: OK
          schema:
            $ref: "#/definitions/SecurityAssessmentList"
        default:
          description: Error response describing why the operation failed.
          schema:
            description: Error response structure.
            properties:
              error:
                description: Error details.
                properties:
                  code:
                    description: An identifier for the error. Codes are invariant and are intended to be consumed programmatically.
                    readOnly: true
                    type: string
                  message:
                    description: A message describing the error, intended to be suitable for display in a user interface.
                    readOnly: true
                    type: string
                type: object
                x-ms-external: true
            type: object
            x-ms-external: true
      tags:
        - Assessments
      x-ms-examples:
        List security assessments:
          parameters:
            api-version: 2020-01-01
            scope: subscriptions/20ff7fc3-e762-44dd-bd96-b71116dcdc23
          responses:
            "200":
              body:
                value:
                  - id: /subscriptions/20ff7fc3-e762-44dd-bd96-b71116dcdc23/resourceGroups/myRg/providers/Microsoft.Compute/virtualMachineScaleSets/vmss1/providers/Microsoft.Security/assessments/21300918-b2e3-0346-785f-c77ff57d243b
                    name: 21300918-b2e3-0346-785f-c77ff57d243b
                    properties:
                      displayName: Install endpoint protection solution on virtual machine scale sets
                      resourceDetails:
                        id: /subscriptions/20ff7fc3-e762-44dd-bd96-b71116dcdc23/resourceGroups/myRg/providers/Microsoft.Compute/virtualMachineScaleSets/vmss1
                        source: Azure
                      status:
                        code: Healthy
                    type: Microsoft.Security/assessments
                  - id: /subscriptions/20ff7fc3-e762-44dd-bd96-b71116dcdc23/resourceGroups/myRg/providers/Microsoft.Compute/virtualMachineScaleSets/vmss2/providers/Microsoft.Security/assessments/21300918-b2e3-0346-785f-c77ff57d243b
                    name: 21300918-b2e3-0346-785f-c77ff57d243b
                    properties:
                      additionalData:
                        linkedWorkspaceId: /subscriptions/20ff7fc3-e762-44dd-bd96-b71116dcdc23/resourceGroups/myRg/providers/Microsoft.OperationalInsights/workspaces/myLaWorkspace
                      displayName: Install endpoint protection solution on virtual machine scale sets
                      resourceDetails:
                        id: /subscriptions/20ff7fc3-e762-44dd-bd96-b71116dcdc23/resourceGroups/myRg/providers/Microsoft.Compute/virtualMachineScaleSets/vmss2
                        source: Azure
                      status:
                        cause: OffByPolicy
                        code: NotApplicable
                        description: The effective policy for the assessment was evaluated to off - use Microsoft.Authorization/policyAssignments to turn this assessment on
                    type: Microsoft.Security/assessments
      x-ms-pageable:
        nextLinkName: nextLink
definitions:
  AssessmentLinks:
    description: Links relevant to the assessment
    properties:
      azurePortalUri:
        description: Link to assessment in Azure Portal
        readOnly: true
        type: string
    readOnly: true
    type: object
  AssessmentStatus:
    description: The result of the assessment
    properties:
      cause:
        description: Programmatic code for the cause of the assessment status
        type: string
      code:
        description: Programmatic code for the status of the assessment
        enum:
          - Healthy
          - Unhealthy
          - NotApplicable
        type: string
        x-ms-enum:
          modelAsString: true
          name: AssessmentStatusCode
          values:
            - description: The resource is healthy
              value: Healthy
            - description: The resource has a security issue that needs to be addressed
              value: Unhealthy
            - description: Assessment for this resource did not happen
              value: NotApplicable
      description:
        description: Human readable description of the assessment status
        type: string
    required:
      - code
    type: object
  SecurityAssessment:
    allOf:
      - description: Describes an Azure resource.
        properties:
          id:
            description: Resource Id
            readOnly: true
            type: string
          name:
            description: Resource name
            readOnly: true
            type: string
          type:
            description: Resource type
            readOnly: true
            type: string
        type: object
        x-ms-azure-resource: true
    description: Security assessment on a resource
    properties:
      properties:
        $ref: "#/definitions/SecurityAssessmentProperties"
        x-ms-client-flatten: true
    type: object
  SecurityAssessmentList:
    description: Page of a security assessments list
    properties:
      nextLink:
        description: The URI to fetch the next page.
        readOnly: true
        type: string
      value:
        description: Collection of security assessments in this page
        items:
          $ref: "#/definitions/SecurityAssessment"
        readOnly: true
        type: array
    type: object
  SecurityAssessmentPartnerData:
    description: Data regarding 3rd party partner integration
    properties:
      secret:
        description: secret to authenticate the partner - write only
        type: string
        x-ms-secret: true
    type: object
  SecurityAssessmentProperties:
    description: Describes properties of an assessment.
    properties:
      additionalData:
        additionalProperties:
          type: string
        description: Additional data regarding the assessment
        type: object
      displayName:
        description: User friendly display name of the assessment
        readOnly: true
        type: string
      links:
        $ref: "#/definitions/AssessmentLinks"
      metadata:
        description: Describes properties of an assessment metadata.
        properties:
          assessmentType:
            description: BuiltIn if the assessment based on built-in Azure Policy definition, Custom if the assessment based on custom Azure Policy definition
            enum:
              - BuiltIn
              - CustomPolicy
              - CustomerManaged
              - VerifiedPartner
            type: string
            x-ms-enum:
              modelAsString: true
              name: assessmentType
              values:
                - description: Azure Security Center managed assessments
                  value: BuiltIn
                - description: User defined policies that are automatically ingested from Azure Policy to Azure Security Center
                  value: CustomPolicy
                - description: User assessments pushed directly by the user or other third party to Azure Security Center
                  value: CustomerManaged
                - description: An assessment that was created by a verified 3rd party if the user connected it to ASC
                  value: VerifiedPartner
          category:
            items:
              description: The category of resource that is at risk when the assessment is unhealthy
              enum:
                - Compute
                - Networking
                - Data
                - IdentityAndAccess
                - IoT
              type: string
              x-ms-enum:
                modelAsString: true
                name: category
                values:
                  - value: Compute
                  - value: Networking
                  - value: Data
                  - value: IdentityAndAccess
                  - value: IoT
            type: array
          description:
            description: Human readable description of the assessment
            type: string
          displayName:
            description: User friendly display name of the assessment
            type: string
          implementationEffort:
            description: The implementation effort required to remediate this assessment
            enum:
              - Low
              - Moderate
              - High
            type: string
            x-ms-enum:
              modelAsString: true
              name: implementationEffort
              values:
                - value: Low
                - value: Moderate
                - value: High
          partnerData:
            description: Describes the partner that created the assessment
            properties:
              partnerName:
                description: Name of the company of the partner
                readOnly: true
                type: string
              productName:
                description: Name of the product of the partner that created the assessment
                type: string
              secret:
                description: Secret to authenticate the partner and verify it created the assessment - write only
                type: string
                x-ms-secret: true
            type: object
          policyDefinitionId:
            description: Azure resource ID of the policy definition that turns this assessment calculation on
            readOnly: true
            type: string
          preview:
            description: True if this assessment is in preview release status
            type: boolean
          remediationDescription:
            description: Human readable description of what you should do to mitigate this security issue
            type: string
          severity:
            description: The severity level of the assessment
            enum:
              - Low
              - Medium
              - High
            type: string
            x-ms-enum:
              modelAsString: true
              name: severity
              values:
                - value: Low
                - value: Medium
                - value: High
          threats:
            items:
              description: Threats impact of the assessment
              enum:
                - accountBreach
                - dataExfiltration
                - dataSpillage
                - maliciousInsider
                - elevationOfPrivilege
                - threatResistance
                - missingCoverage
                - denialOfService
              type: string
              x-ms-enum:
                modelAsString: true
                name: threats
                values:
                  - value: accountBreach
                  - value: dataExfiltration
                  - value: dataSpillage
                  - value: maliciousInsider
                  - value: elevationOfPrivilege
                  - value: threatResistance
                  - value: missingCoverage
                  - value: denialOfService
            type: array
          userImpact:
            description: The user impact of the assessment
            enum:
              - Low
              - Moderate
              - High
            type: string
            x-ms-enum:
              modelAsString: true
              name: userImpact
              values:
                - value: Low
                - value: Moderate
                - value: High
        required:
          - displayName
          - severity
          - assessmentType
        type: object
      partnersData:
        $ref: "#/definitions/SecurityAssessmentPartnerData"
      resourceDetails:
        description: Details of the resource that was assessed
        discriminator: source
        properties:
          source:
            description: The platform where the assessed resource resides
            enum:
              - Azure
              - OnPremise
            type: string
            x-ms-enum:
              modelAsString: true
              name: source
              values:
                - description: Resource is in Azure
                  value: Azure
                - description: Resource in an on premise machine connected to Azure cloud
                  value: OnPremise
        required:
          - source
        type: object
      status:
        $ref: "#/definitions/AssessmentStatus"
    required:
      - resourceDetails
      - status
    type: object
