{ "swagger": "2.0", "info": { "title": "Microsoft Defender for Cloud", "version": "2020-01-01", "description": "API spec for Microsoft.Security (Microsoft Defender for Cloud) resource provider", "x-typespec-generated": [ { "emitter": "@azure-tools/typespec-autorest" } ] }, "schemes": [ "https" ], "host": "management.azure.com", "produces": [ "application/json" ], "consumes": [ "application/json" ], "security": [ { "azure_auth": [ "user_impersonation" ] } ], "securityDefinitions": { "azure_auth": { "type": "oauth2", "description": "Azure Active Directory OAuth2 Flow.", "flow": "implicit", "authorizationUrl": "https://login.microsoftonline.com/common/oauth2/authorize", "scopes": { "user_impersonation": "impersonate your user account" } } }, "tags": [ { "name": "Secure Score" }, { "name": "Secure Score Controls" }, { "name": "Secure Score Control Definitions" } ], "paths": { "/providers/Microsoft.Security/secureScoreControlDefinitions": { "get": { "operationId": "SecureScoreControlDefinitions_List", "tags": [ "Secure Score Control Definitions" ], "description": "List the available security controls, their assessments, and the max score", "parameters": [ { "$ref": "../../../../../../common-types/resource-management/v5/types.json#/parameters/ApiVersionParameter" } ], "responses": { "200": { "description": "The request has succeeded.", "schema": { "$ref": "#/definitions/secureScoreControlDefinitionList" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/Common.CloudError" } } }, "x-ms-examples": { "List security controls definition": { "$ref": "./examples/secureScoreControlDefinitions/ListSecureScoreControlDefinitions_example.json" } }, "x-ms-pageable": { "nextLinkName": "nextLink" } } }, "/subscriptions/{subscriptionId}/providers/Microsoft.Security/secureScoreControlDefinitions": { "get": { "operationId": "SecureScoreControlDefinitions_ListBySubscription", "tags": [ "Secure Score Control Definitions" ], "description": "For a specified subscription, list the available security controls, their assessments, and the max score", "parameters": [ { "$ref": "../../../../../../common-types/resource-management/v5/types.json#/parameters/ApiVersionParameter" }, { "$ref": "../../../../../../common-types/resource-management/v5/types.json#/parameters/SubscriptionIdParameter" } ], "responses": { "200": { "description": "The request has succeeded.", "schema": { "$ref": "#/definitions/secureScoreControlDefinitionList" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/Common.CloudError" } } }, "x-ms-examples": { "List security controls definition by subscription": { "$ref": "./examples/secureScoreControlDefinitions/ListSecureScoreControlDefinitions_subscription_example.json" } }, "x-ms-pageable": { "nextLinkName": "nextLink" } } }, "/subscriptions/{subscriptionId}/providers/Microsoft.Security/secureScoreControls": { "get": { "operationId": "SecureScoreControls_List", "tags": [ "Secure Score Controls" ], "description": "Get all security controls within a scope", "parameters": [ { "$ref": "../../../../../../common-types/resource-management/v5/types.json#/parameters/ApiVersionParameter" }, { "$ref": "../../../../../../common-types/resource-management/v5/types.json#/parameters/SubscriptionIdParameter" }, { "name": "$expand", "in": "query", "description": "OData expand. Optional.", "required": false, "type": "string", "enum": [ "definition" ], "x-ms-enum": { "name": "ExpandControlsEnum", "modelAsString": true, "values": [ { "name": "definition", "value": "definition", "description": "Add definition object for each control" } ] } } ], "responses": { "200": { "description": "The request has succeeded.", "schema": { "$ref": "#/definitions/SecureScoreControlList" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/Common.CloudError" } } }, "x-ms-examples": { "List all secure scores controls": { "$ref": "./examples/secureScores/ListSecureScoreControls_example.json" } }, "x-ms-pageable": { "nextLinkName": "nextLink" } } }, "/subscriptions/{subscriptionId}/providers/Microsoft.Security/secureScores": { "get": { "operationId": "SecureScores_List", "tags": [ "Secure Score" ], "description": "List secure scores for all your Microsoft Defender for Cloud initiatives within your current scope.", "parameters": [ { "$ref": "../../../../../../common-types/resource-management/v5/types.json#/parameters/ApiVersionParameter" }, { "$ref": "../../../../../../common-types/resource-management/v5/types.json#/parameters/SubscriptionIdParameter" } ], "responses": { "200": { "description": "Azure operation completed successfully.", "schema": { "$ref": "#/definitions/SecureScoresList" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/Common.CloudError" } } }, "x-ms-examples": { "List secure scores": { "$ref": "./examples/secureScores/ListSecureScores_example.json" } }, "x-ms-pageable": { "nextLinkName": "nextLink" } } }, "/subscriptions/{subscriptionId}/providers/Microsoft.Security/secureScores/{secureScoreName}": { "get": { "operationId": "SecureScores_Get", "tags": [ "Secure Score" ], "description": "Get secure score for a specific Microsoft Defender for Cloud initiative within your current scope. For the ASC Default initiative, use 'ascScore'.", "parameters": [ { "$ref": "../../../../../../common-types/resource-management/v5/types.json#/parameters/ApiVersionParameter" }, { "$ref": "../../../../../../common-types/resource-management/v5/types.json#/parameters/SubscriptionIdParameter" }, { "name": "secureScoreName", "in": "path", "description": "The initiative name. For the ASC Default initiative, use 'ascScore' as in the sample request below.", "required": true, "type": "string" } ], "responses": { "200": { "description": "Azure operation completed successfully.", "schema": { "$ref": "#/definitions/SecureScoreItem" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/Common.CloudError" } } }, "x-ms-examples": { "Get single secure score": { "$ref": "./examples/secureScores/GetSecureScoresSingle_example.json" } } } }, "/subscriptions/{subscriptionId}/providers/Microsoft.Security/secureScores/{secureScoreName}/secureScoreControls": { "get": { "operationId": "SecureScoreControls_ListBySecureScore", "tags": [ "Secure Score" ], "description": "Get all security controls for a specific initiative within a scope", "parameters": [ { "$ref": "../../../../../../common-types/resource-management/v5/types.json#/parameters/ApiVersionParameter" }, { "$ref": "../../../../../../common-types/resource-management/v5/types.json#/parameters/SubscriptionIdParameter" }, { "name": "secureScoreName", "in": "path", "description": "The initiative name. For the ASC Default initiative, use 'ascScore' as in the sample request below.", "required": true, "type": "string" }, { "name": "$expand", "in": "query", "description": "OData expand. Optional.", "required": false, "type": "string", "enum": [ "definition" ], "x-ms-enum": { "name": "ExpandControlsEnum", "modelAsString": true, "values": [ { "name": "definition", "value": "definition", "description": "Add definition object for each control" } ] } } ], "responses": { "200": { "description": "Azure operation completed successfully.", "schema": { "$ref": "#/definitions/SecureScoreControlList" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/Common.CloudError" } } }, "x-ms-examples": { "Get security controls and their current score for the specified initiative": { "$ref": "./examples/secureScores/ListSecureScoreControlsForName_builtin_example.json" }, "Get security controls and their current score for the specified initiative with the expand parameter": { "$ref": "./examples/secureScores/ListSecureScoreControlsForNameWithExpand_builtin_example.json" } }, "x-ms-pageable": { "nextLinkName": "nextLink" } } } }, "definitions": { "AzureResourceLink": { "type": "object", "description": "Describes an Azure resource with kind", "properties": { "id": { "type": "string", "description": "Azure resource Id", "readOnly": true } } }, "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": "#/definitions/Common.CloudErrorBody", "description": "The error object.", "x-ms-client-flatten": true } }, "x-ms-external": true }, "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": "#/definitions/Common.CloudErrorBody" }, "readOnly": true, "x-ms-identifiers": [] }, "additionalInfo": { "type": "array", "description": "The error additional info.", "items": { "$ref": "../../../../../../common-types/resource-management/v5/types.json#/definitions/ErrorAdditionalInfo" }, "readOnly": true, "x-ms-identifiers": [] } }, "x-ms-external": true }, "ControlType": { "type": "string", "description": "The type of security control (for example, BuiltIn)", "enum": [ "BuiltIn", "Custom" ], "x-ms-enum": { "name": "ControlType", "modelAsString": true, "values": [ { "name": "BuiltIn", "value": "BuiltIn", "description": "Microsoft Defender for Cloud managed assessments" }, { "name": "Custom", "value": "Custom", "description": "Non Microsoft Defender for Cloud managed assessments" } ] } }, "ScoreDetails": { "type": "object", "description": "Calculation result data", "properties": { "max": { "type": "integer", "format": "int32", "description": "Maximum score available", "minimum": 0, "readOnly": true }, "current": { "type": "number", "format": "double", "description": "Current score", "minimum": 0, "readOnly": true }, "percentage": { "type": "number", "format": "double", "description": "Ratio of the current score divided by the maximum. Rounded to 4 digits after the decimal point", "minimum": 0, "maximum": 1, "readOnly": true } } }, "SecureScoreControlDefinitionItem": { "type": "object", "description": "Information about the security control.", "properties": { "properties": { "$ref": "#/definitions/SecureScoreControlDefinitionItemProperties", "description": "Security Control Definition Properties.", "x-ms-client-flatten": true } }, "allOf": [ { "$ref": "../../../../../../common-types/resource-management/v5/types.json#/definitions/Resource" } ] }, "SecureScoreControlDefinitionItemProperties": { "type": "object", "description": "Security Control Definition Properties.", "properties": { "displayName": { "type": "string", "description": "User friendly display name of the control", "readOnly": true }, "description": { "type": "string", "description": "User friendly description of the control", "maxLength": 256, "readOnly": true }, "maxScore": { "type": "integer", "format": "int32", "description": "Maximum control score (0..10)", "minimum": 0, "maximum": 10, "readOnly": true }, "source": { "$ref": "#/definitions/SecureScoreControlDefinitionSource", "description": "Source object from which the control was created", "readOnly": true }, "assessmentDefinitions": { "type": "array", "description": "Array of assessments metadata IDs that are included in this security control", "items": { "$ref": "#/definitions/AzureResourceLink" }, "readOnly": true } } }, "SecureScoreControlDefinitionSource": { "type": "object", "description": "The type of the security control (For example, BuiltIn)", "properties": { "sourceType": { "$ref": "#/definitions/ControlType", "description": "The type of security control (for example, BuiltIn)" } } }, "SecureScoreControlDetails": { "type": "object", "description": "Details of the security control, its score, and the health status of the relevant resources.", "properties": { "properties": { "$ref": "#/definitions/SecureScoreControlScoreDetails", "description": "Calculation result data in control level", "x-ms-client-flatten": true } }, "allOf": [ { "$ref": "../../../../../../common-types/resource-management/v5/types.json#/definitions/Resource" } ] }, "SecureScoreControlList": { "type": "object", "description": "List of security controls", "properties": { "value": { "type": "array", "description": "Collection of security controls in this page", "items": { "$ref": "#/definitions/SecureScoreControlDetails" }, "readOnly": true }, "nextLink": { "type": "string", "description": "The URI to fetch the next page." } } }, "SecureScoreControlScoreDetails": { "type": "object", "description": "Calculation result data in control level", "properties": { "displayName": { "type": "string", "description": "User friendly display name of the control", "readOnly": true }, "score": { "$ref": "#/definitions/ScoreDetails", "description": "Actual score object for the control", "x-ms-client-flatten": true }, "healthyResourceCount": { "type": "integer", "format": "int32", "description": "Number of healthy resources in the control", "readOnly": true }, "unhealthyResourceCount": { "type": "integer", "format": "int32", "description": "Number of unhealthy resources in the control", "readOnly": true }, "notApplicableResourceCount": { "type": "integer", "format": "int32", "description": "Number of not applicable resources in the control", "readOnly": true }, "weight": { "type": "integer", "format": "int64", "description": "The relative weight for this specific control in each of your subscriptions. Used when calculating an aggregated score for this control across all of your subscriptions.", "minimum": 0, "readOnly": true }, "definition": { "$ref": "#/definitions/SecureScoreControlDefinitionItem", "description": "Information about the security control." } } }, "SecureScoreItem": { "type": "object", "description": "Secure score item data model", "properties": { "properties": { "$ref": "#/definitions/SecureScoreItemProperties", "description": "Secure score item", "readOnly": true, "x-ms-client-flatten": true } }, "allOf": [ { "$ref": "../../../../../../common-types/resource-management/v5/types.json#/definitions/ProxyResource" } ] }, "SecureScoreItemProperties": { "type": "object", "description": "Describes properties of a calculated secure score.", "properties": { "displayName": { "type": "string", "description": "The initiative's name", "readOnly": true }, "score": { "$ref": "#/definitions/ScoreDetails", "description": "score object", "readOnly": true, "x-ms-client-flatten": true }, "weight": { "type": "integer", "format": "int64", "description": "The relative weight for each subscription. Used when calculating an aggregated secure score for multiple subscriptions.", "minimum": 0, "readOnly": true } } }, "SecureScoresList": { "type": "object", "description": "List of secure scores", "properties": { "value": { "type": "array", "description": "Collection of secure scores in this page", "items": { "$ref": "#/definitions/SecureScoreItem" }, "readOnly": true }, "nextLink": { "type": "string", "description": "The URI to fetch the next page." } } }, "secureScoreControlDefinitionList": { "type": "object", "description": "List of security controls definition", "properties": { "value": { "type": "array", "description": "Collection of security control definitions.", "items": { "$ref": "#/definitions/SecureScoreControlDefinitionItem" }, "readOnly": true }, "nextLink": { "type": "string", "description": "The URL to get the next page of results." } } } }, "parameters": {} }