Microsoft Defender for Cloud
Microsoft Defender for Cloud is a cloud environment solution that focuses on threat detection, assessments, and security management across your cloud environments. You can bring alert, alert definition, assessment, assessment metadata, and asset data from Microsoft Defender for Cloud into Brinqa to gain a comprehensive view of your cloud security landscape, thus enhancing your cybersecurity posture.
This document details the information you must provide for the connector to authenticate with Microsoft Defender for Cloud and how to obtain that information from Microsoft. See create a data integration for step-by-step instructions on setting up the integration.
Required connection settings
When setting up a data integration, select Microsoft Defender for Cloud from the Connector drop-down. If you cannot find the connector in the drop-down, make sure that you have installed it first. You must provide the following information to authenticate Microsoft Defender for Cloud with Brinqa:
-
API URL: The Microsoft Defender for Cloud API URL. The default URL is
https://management.azure.com. -
Login URL: The Microsoft Azure authentication URL. The default URL is
https://login.microsoftonline.com. -
Client ID and Client secret: The client ID and client secret associated with the service principal, which must have permissions to log in to the Microsoft Azure Active Directory (Active AD) and return data from the Azure REST API.
-
Tenant ID: The unique identifier for the Active AD tenant associated with the service principal.
-
Subscription ID: The unique identifier for your Microsoft Azure subscription, which represents a billing and resource usage entity within Azure. The Subscription ID is required to grant the Microsoft Defender for Cloud connector access to resources within your specific subscription, such as your assets and cloud environments.
Register a Microsoft Azure application
You must create a new application for the Microsoft Defender for Cloud connector to authenticate with Azure AD and access the Azure REST API. To register an application in your Azure AD tenant, follow these steps:
-
Log in to your Microsoft Azure Portal as an administrator.
-
Navigate to and click Microsoft Entra ID.
-
On the left-hand side of the page, click App registrations, and then click New registration.
-
Give your new application a name, select the supported account types, and provide an optional Redirect URI. If you do not have a redirect URI, you can leave the field as is.
-
Click Register.
For additional details about registering an application in Azure AD and creating a service principal, see Microsoft Azure documentation.
Obtain Microsoft Azure credentials
After you have created your new Microsoft Azure application, your client and tenant ID display. Copy the Application (client) ID and Directory (tenant) ID as shown below:
To obtain your client secret and subscription ID, follow these steps:
-
Click Certificates & secrets and then click New client secret.
-
Provide a description, set an expiry date, and then click Add.
The new client secret displays. You cannot view the client secret again. There is both a Value and Secret ID. The Value field is needed for authentication. Copy the Value field and save it to a secure location.
-
Search for "Subscriptions" in the search box at the top of the page and click Subscriptions.
The subscription ID of your new application displays. Copy this subscription ID. In addition to the Client ID, Tenant ID, and Client secret, the Subscription ID is also needed for authentication.
Assign permissions
After you have created your new Microsoft Azure application and obtained the authentication credentials, you must assign the required permissions for the application to access your data. To do so, follow these steps:
-
Navigate to the applicable Azure subscription.
-
Click Access control (IAM), click Add, and then click Add role assignment from the drop-down.
-
In the Job function roles tab, search for and select the Reader role.
- The Reader role allows you to view all resources, but does not grant permission to modify them.
-
Click Next.
-
In the Members tab, click the User, group, or service principal option.
-
Click Select members, search for and click the application you registered earlier, and then click Select.
-
Navigate to the Review + assign tab and click Review + assign.
If you do not have permissions to assign roles, contact your Azure administrator. For additional information, see Microsoft documentation.
(Optional) Create a management group for multiple subscriptions
If you have multiple Azure subscriptions, you can organize them into a single management group to uniformly set access controls. To do so, follow these steps:
-
Log in to your Microsoft Azure Portal as an administrator.
-
Search for "Management groups" in the search box and click Management groups.
-
Click Create, provide a management group ID and display name, and then click Submit.
-
On the Management groups page, click the name of the new management group.
-
Click Add subscription, select the Azure subscriptions you want to add to the management group, and then click Save.
-
Click Access control (IAM), click Add, and then click Add role assignment from the drop-down.
-
Search for and select the role you want to assign to the management group.
-
Click Next.
-
In the Members tab, click the User, group, or service principal option.
-
Click Select members, search for and click the application you registered earlier, or any relevant members who require this role, and then click Select.
-
Navigate to the Review + assign tab and click Review + assign.
If you do not have permissions to create management groups, contact your Azure administrator. For additional information, see Microsoft documentation.
Additional settings
The Microsoft Defender for Cloud connector contains an additional option for specific configuration:
- Maximum retries: The maximum number of times that the integration attempts to connect to the Azure REST API before giving up and reporting a failure. The default setting is 5.
Types of data to retrieve
The Microsoft Defender for Cloud connector can retrieve the following types of data from the Azure REST API:
Table 1: Data retrieved from Azure REST API
| Connector Object | Required | Maps to Data Model |
|---|---|---|
| Alert | Yes | Alert |
| Alert Definition | Yes | Alert Definition |
| Assessment | Yes | Violation |
| Assessment Metadata | Yes | Violation Definition |
| Asset | Yes | Cloud Resource |
| Host | Yes | Host |
| Subscription | Yes | Cloud Resource |
| Vulnerability | Yes | Vulnerability |
| Vulnerability Definition | Yes | Vulnerability Definition |
The Microsoft Defender for Cloud connector does not currently support operation options for the types of data it retrieves.
For detailed steps on how to view the data retrieved from Microsoft Defender for Cloud in the Brinqa Platform, see How to view your data.
Attribute mappings
Click the tabs below to view the mappings between the source and the Brinqa data model attributes.
- Alert
- Alert Definition
- Assessment
- Assessment Metadata
- Asset
Table 2: Alert attribute mappings
| Source Field Name | Maps to Attribute |
|---|---|
| actionTaken | Local variable |
| additionalData | Local variable |
| associatedResource | targets |
| canBeInvestigated | Local variable |
| compromisedEntity | Local variable |
| confidenceReasons | Local variable |
| description | type |
| endTime | sourceLastModified |
| instanceId | Local variable |
| isIncident | Local variable |
| name | Local variable |
| processingTime | Local variable |
| startTime | sourceCreatedDate |
| state | status, statusCategory |
| subscriptionId | targets |
| sysId | uid |
| title | Local variable |
| workspaceArmId | Local variable |
Table 3: Alert Definition attribute mappings
| Source Field Name | Maps to Attribute |
|---|---|
| actionTaken | Local variable |
| additionalData | Local variable |
| canBeInvestigated | Local variable |
| compromisedEntity | Local variable |
| confidenceReasons | Local variable |
| description | description |
| instanceId | Local variable |
| isIncident | Local variable |
| name | Local variable |
| processingTime | Local variable |
| remediation | remediation |
| reportedSeverity | severity, sourceSeverity |
| title | uid, name |
| vendorName | affected |
| workspaceArmId | Local variable |
Table 4: Assessment attribute mappings
| Source Field Name | Maps to Attribute |
|---|---|
| sysId | uid |
| subscriptionId | Local variable |
| metadataName | Local variable |
| resourceId | targets, Local variable |
| title | name |
| statusCode | status |
| STATUS_CAUSE | Local variable |
| STATUS_DESCRIPTION | Local variable |
| ADDITIONAL_DATE | Local variable |
| TARGET | targets |
Table 5: Assessment Metadata attribute mappings
| Source Field Name | Maps to Attribute |
|---|---|
| ADDITIONAL_DATA | Local variable |
| ASSESSMENT_TYPE | categories |
| CATEGORIES | categories |
| DESCRIPTION | description |
| IMPLEMENTATION_EFFORT | Local variable |
| NAME | name |
| POLICY_ID | Local variable |
| PREVIEW | Local variable |
| REMEDIATION | remediation |
| SEVERITY | severity, sourceSeverity, severityScore |
| SYS_ID | uid |
| THREATS | Local variable |
| TITLE | Local variable |
| USER_IMPACT | Local variable |
Table 6: Asset attribute mappings
| Source Field Name | Maps to Attribute |
|---|---|
| SYS_ID | uid |
| RESOURCE_ID | description, Local variable |
| SUBSCRIPTION_ID | description, Local variable |
| RESOURCE_NAME | description, name |
| RESOURCE_TYPE | categores, Local variable |
| SKU_NAME | Local variable |
| SKU_CAPACITY | Local variable |
| SKU_FAMILY | Local variable |
| SKU_MODEL | Local variable |
| SKU_SIZE | Local variable |
| SKU_TIER | Local variable |
| KIND | Local variable |
| LOCATION | Local variable |
| IDENTITY_PRINCIPAL_ID | Local variable |
| IDENTITY_TENANT_ID | Local variable |
| IDENTITY_TYPE | Local variable |
| PLAN_NAME | Local variable |
| PLAN_PRODUCT | Local variable |
| PLAN_VERSION | Local variable |
| CREATED_TIME | sourceCreatedDate |
| CHANGED_TIME | sourceLastModified |
| PROVISIONING_STATE | status |
| TAGS | tags |
Local variable indicates that the field is processed within a specific context, such as a particular workflow or calculation. Unlike other attributes, local variables aren't mapped to the unified data models. They only exist on the source data model.
APIs
The Microsoft Defender for Cloud connector uses the Azure REST API. Specifically, it uses the following endpoints:
Table 7: Microsoft Defender for Cloud API Endpoints
| Connector Object | API Endpoints |
|---|---|
| Alert | GET https://management.azure.com/subscriptions/{subscriptionID}/providers/Microsoft.Security/alerts |
| Assessment | GET http://management.azure.com/subscriptions/{subscriptionID}/providers/Microsoft.Security/assessments |
| Assessment Metadata | GET https://management.azure.com/providers/Microsoft.Security/assessmentMetadata |
| Asset | GET https://management.azure.com/subscriptions/{subscriptionID}/resources |
Changelog
The Microsoft Defender for Cloud connector has undergone the following changes:
3.1.7
-
Added more connector objects, such as Host, Vulnerability, and Vulnerability Definition.
-
Fixed an issue where the connector was responding with a multi-value attribute when it should be a single attribute.
3.1.6
- Added the source status to the Machine object.
3.1.12
- Mapped the Assessment object to the Violation data model, and the Assessment Metadata object to the Violation Definition data model.
3.1.11
- Initial Integration+ release.