Microsoft Defender for Clouds Connector

Microsoft Defender for Cloud (MDC) provides a robust, cloud-native solution for Cloud security, offering enhanced visibility and AI-driven protection against cyber threats across your devices. 

What is the Microsoft Defender for Cloud (MDC) API Connector?

The MDC API Connector creates a secure bridge between your Microsoft Defender for Cloud platform and Qualys ETM. The API-based connector facilitates regular data retrieval, enabling quicker, data-driven remediation. When configured, it automatically transfers asset inventory and security findings through scheduled API calls. Qualys ETM then processes this data by:

  • Deduplicating redundant entries
  • Normalizing data formats
  • Enriching findings with additional context
  • Calculating risk scores using TruRisk
Category  Supported Asset Type Supported Finding Type
API Connector Host Asset Misconfiguration

Prerequisites

These are the required configurations you need to successfully create a MDC connection for Qualys ETM.

User Roles and Permissions

You need the following MDC API Access information to configure the connection:

  • Subscription
  • Tenant ID
  • Client ID 
  • Client Secret

For quick reference on how to obtain the required values, follow the steps below.

Authentication URL

Just provide the value - https://login.microsoftonline.com/

Client ID and Tenant ID
  1. Log on to your Microsoft Azure console and click Azure Active Directory in the left navigation pane. 
  2. Navigate to  App registrations > New Registration section from your Azure portal. Let's register an application.
  3. Provide a name for the application and select the required supported account types.
  4. You can also provide a Redirect URI. This step is optional, you can leave it blank and proceed if it does not apply.
  5. Click Register once you have provided these inputs. The newly created application is displayed with its properties. 
  6. Go to Overview > Essentials to view your Client (Application) ID and Tenant (Directory) ID. Store these values securely for later use.
  7. Click Add a certificate or secret to create the Client Secret.
Client Secrets
  1. Click New client secret to create a new client secret for this connection.
  2. Provide a value of your choice in the Description field.  You can set the Expires field to its recommended setting. Click Add.
  3. Once the secret is created, copy the Value of your Client Secret and store it securely for later use.
Required Permissions 

Steps to add the required permissions.

  1. API Permissions: After application registration, navigate to the API Permissions section of your app.
  2. Add a permission:
    • Click on Add a permission.
    • Select Microsoft Graph.
  3. Select permissions:
    • Delegated permissions: Choose permissions if the app needs to access the API as the signed-in user.
    • Application permissions: Choose permissions if the app needs to access the API as a background service or daemon without a signed-in user.
  4. Grant admin consent: If necessary, click on Grant admin consent for [Your Organization] to grant the permissions to all users in the organization.

Minimum permission required is "Reader Role (or higher)"

Connector Configuration

Let's create our first MDC connection. Follow the steps below to get started.

Create a New API Connector

Basic DetailsBasic Details

  1. Provide the Connector's Name and Description.
  2. Select the type of findings you want to import or export - currently, we support Misconfiguration.
  3. Select the Asset Type - currently we support Host Asset.
    The following screenshot displays the Basic Details fields.

  4. Next, provide the API authentication details of the MDC environment. You need to provide the following.

    1. Subscription
    2. Tenant ID
    3. Client ID
    4. Client Secret

These values can be obtained by following the steps laid out in the User Roles and Permissions section.

Data ModelData Model

The MDC API Connector offers an out-of-box data model mapping for you to map with Qualys ETM schema. You can view the schema to understand the attributes in the data model.

Transform MapsTransform Maps

Map the fields from Defender to the corresponding fields in your target system. Transform Maps ensure the data is transformed correctly during the import or export process.

The MDC Connector offers an out-of-box transform map for you to proceed without further configuration. View the map to understand the data transformation or clone the map to edit its configurations.

Click Create New for a new Transform Map.

Perform the following steps to configure a Transform Model:

  1. Transform Map Name: Enter a unique name for the Transform Map. This name helps identify the specific transformation configuration within this connector.
  2. Source Data Model: Select the data model that serves as the input for the transformation. This is the model from which data will be extracted.
  3. Target Data Model: Choose the data model that receives the transformed data. This model defines how the data will be structured after the transformation. 

To learn more about the data mapping from MDC to Qualys ETM, refer to Data Model Mapping.

Fields Mapping

The Fields Mapping section maps fields from the Source Data Model to the Target Data Model.

  1. Source Field: Specify the field in the Source Data Model containing the transformed data.
  2. Data Type: Indicate the data type of the Source Field (e.g., string, integer, date).
  3. Target Field: Designate the corresponding field where the transformed data will be placed in the Target Data Model.

Click Add to create and display the mapping for the Source Field, Data Type, and Target Field below the section. This visual helps ensure that all necessary fields are mapped correctly and allows easy verification and adjustments.

ProfileProfile

Create a profile for your connector. A profile decides the connector status, execution schedule and transform map to choose. The connector follows the configurations of this profile for all future executions.

Click the "+" to create a new profile.

In the Add Profile screen, provide the necessary inputs for your new profile.

Provide a Name and Description.

Select the required Transform Map for the data mapping.

The Detection of DataTypes determine which findings to select for the profile. The Asset Types determine the required resource whose findings should be ingested by Qualys ETM.

The Status field determines whether the connector should be in Active or Inactive state after creation. 

Lastly, the Schedule section lets you either create a Single Occurrence schedule or a Recurring schedule. Provide the exact date and time for the Single Occurence execution and provide the Start and End date/time for the Recurring schedule.

ScoringScoring

The Scoring screen lets you map non-CVE vulnerability scores from your vendors to Qualys Detection Score (QDS) system.

Score mapping screen.

You have two columns with 5 input fields in each of them. These fields correspond to a specific severity starting from the least severe (1), to the most severe (5).

Fill out all 5 rows to create a comprehensive score mapping. This allows for translation between various vendor scoring systems and Qualys' Detection Score.

The specifics of the mapping is explained below.

Expected Source Values - Enter the vendor's original score or rating for non-CVE vulnerabilities.
This can be alphanumeric values. (e.g., "High", "Critical", "A", "3", etc.).

Severity - This column is pre-populated with severity levels from 1-5. These represent the severity levels in Qualys. The Source Value must be mapped such that it utilizes these 5 severity levels.

QDS - Enter the corresponding Qualys Detection Score. Use values from 0-100, where higher numbers indicate higher severity.

Default Severity

Below the scoring map, find the 'Default Severity' dropdown menu.

Select a default severity level from 1-5, this is applied when a vendor's score for a non-CVE vulnerability doesn't match any 'Expected Source Value' in your mapping table.

Select Identification RulesSelect Identification Rules

The Identification Rules are a set of out-of-the-box precedence rules set by Qualys CSAM. The connector discovers findings based on the order set by the selected Identification Rules.

You can proceed to the next step without making any changes to this screen.

If you don't want to choose a specific rule, turn off the toggle next to it. But, ensure that at least one rule is selected.

To learn more about the different rules and options present in this screen, refer to the CSAM Online Help.

Once you are done with all the configuration, review the configurations provided in the previous steps. Ensure all details are correct and complete. Confirm the setup to finalize the configuration of the API connector.

Save and run the connector to process the data accordingly, transforming and importing it as per the configurations set.

How Does a Connection Work?

The MDC connector functions through configured profiles that determine what data gets synchronized and when.

A Connection usually involves creating a profile that defines which misconfigurations to import based on detection data types and asset types. The connector then automatically executes according to the schedule (or on-demand), pulling vulnerability data from Microsoft Defender for Enpoint into Qualys ETM where it can be viewed alongside other security findings.

With the MDC API Connector successfully configured, you are almost ready to view all the assets and findings from MDC.

In the Connector screen, you can find your newly configured connector listed and marked in the Processed state.

Connector States

A successfully configured connector goes through 4 states.

  1. Registered - The connector is successfully created and registered to fetch data from the vendor.
  2. Scheduled - The connector is scheduled to execute a connection with the vendor.
  3. Processing - A connection is executed and the connector is fetching the asset and findings data.
  4. Processed - The connector has successfully fetched the assets, it may still be under process of fetching the findings. Wait for some more time for the connector to fetch the findings completely.

The Processed state indicates that the Connector is successfully configured but it is under the process of importing all your assets and findings. This process (specifically for findings) may take some time.

This entire process may take up to 2 hours for completion. Once it is done, you can find the imported data in Enterprise TruRisk Management (ETM).

View Assets and Findings in ETM

Navigate to Enterprise TruRisk Management to get started with analyzing your Connector's vulnerability findings.

You can view the assets imported from the MDC connection by navigating to Inventory tab of ETM.

Go to Assets > Host to find all of your imported assets.

Use the token, inventory: (source: `Defender for Cloud`) to view all the imported MDC assets.

Here, you can learn about the criticality of your assets and their Risk Scores. Click any of the asset to find more details about them.

Next, you can navigate to the Risk Management tab to view your vulnerability findings.

Go to Findings > Misconfigurations to view all the discovered vulnerabilities.

Use the token, finding.vendorProductName: `Defender for Cloud` to view all the discovered Defender vulnerabilities.

To know more about how the MDC API Connector leverages the findings, refer to the Qualys ETM Documentation.

Additional Resources

Additional Information related to MDC Connector.

API Reference

Here are the APIs executed for the MDC connection.

Name

Filters

 Description

Auth API

 N/A https://login.microsoftonline.com/

Fetch Asset

https://management.azure.com/providers/
Microsoft.ResourceGraph/resources?api-version=2021-03-01

Sample Asset fetch query

query": "Resources | where type =~ '\''microsoft.compute/virtualmachines'\'' | where properties.timeCreated >= datetime(2024-10-16T07:25:23.1360003Z)

Fetch Resources and assessments

 

https://management.azure.com/providers/
Microsoft.ResourceGraph/resources?api-version=2021-03-01

Sample Resource and assessments fetch query

securityresources | where type == \"microsoft.security/assessments\" | extend resourceId = parse_json(properties[\"resourceDetails\"][\"Id\"]) | where resourceId == \"${resourceId}\"

Fetch Network Interfaces

https://management.azure.com/providers/
Microsoft.ResourceGraph/resources?api-version=2021-03-01

Sample network-interface-query

Resources | where type == \"microsoft.compute/virtualmachines\" and id == \"${resourceId}\" | extend nics = properties.networkProfile.networkInterfaces | mv-expand nic = nics | extend nicId = tostring(nic.id) | join kind=leftouter (Resources | where type == \"microsoft.network/networkinterfaces\" | project nicId = id, nicName = name, nicGuid = properties.resourceGuid, macAddress = properties.macAddress, ipConfigs = properties.ipConfigurations, fqdn = properties.dnsSettings.internalDomainNameSuffix | mv-expand ipConfig = ipConfigs | extend privateIP = tostring(ipConfig.properties.privateIPAddress), publicIPRef = ipConfig.properties.publicIPAddress, publicIPId = tostring(ipConfig.properties.publicIPAddress.id) | where isnotempty(publicIPId)) on nicId | join kind=leftouter (Resources | where type =~ \"microsoft.network/publicipaddresses\" | project publicIPId = id, publicIPName = name, publicIP = properties.ipAddress) on publicIPId | project vmName = name, resourceGroup, nicName, nicGuid, macAddress, privateIP, publicIPName, publicIP, fqdn

Data Model Map

This section explains the attribute mappings of the values from Microsoft Defender for Cloud and Qualys ETM.

MDC Vulnerability Transformation Mapping

Defender Attribute Key Qualys Attribute Label

vmId

externalAssetId

assessments_name

findingName

assessments_id

externalFindingId

assessments[].properties.metadata.severity

findingSeverity

name

assetName

imageReference_offer

operatingSystemName

networkInterfaces_macAddress

macAddress

networkInterfaces_publicIP

ipAddress

imageReference_version

operatingSystemVersion

assessments_firstEvaluationDate

findingFirstFoundOn

assessments_displayName

findingDescription

assessments_recommendationCategory

recommendation

assessments_links_azurePortal

policyFindingUrl

assessments_userImpact

impact

assessments_type

findingSubType

assessments_metadata_displayName

policyTitle

assessments_severity

Informational | Low | Medium | High

findingSeverity

0 1 | 2 |3 | 4

findingStatus

 | open | resolved | active| closed

assessments_status_code

PASS | FAIL | PASS | FAIL | PASS

assessments_metadata_description

policyDescription

assessments_managedBy

createdBy

assessments_managedBy

updatedBy

assessments_policyDefinitionId

policyId

assessments_remediationDescription

remediationStrategy

ResourceType

productVendor

assessments_statusChangeDate

updatedOn

assessments_assessmentType

policyType

ResourceProvider

productName

 

© Qualys , Inc. All rights reserved. Privacy Policy.