> For the complete documentation index, see [llms.txt](https://docs.adaptiva.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.adaptiva.com/patch/integrations/integrate-defender.md).

# Microsoft Defender

You can configure OneSite Patch to collect vulnerability metadata from Microsoft Defender. You can use this metadata to:

* Configure patch filters in simple strategies.
* Set a trigger to rerun an advanced strategy based on changes to specific metadata.
* Configure patch deployment bots to deploy patches based on the metadata.

For a full list of imported values from Microsoft Defender, please see the [Metadata properties](#metadata-properties) section below.

### Prerequisites

#### Add Microsoft Defender license key

To enable Microsoft Defender integration, you will need a license key. For more information about acquiring these keys, please reach out to your Sales manager.

You can add and view your license keys in the Adaptiva Admin Portal. Please see [License your Adaptiva solution](https://docs.adaptiva.com/platform-guide/license-solution#add-a-license) page for more details.

#### Obtain Entra ID information

Integrating Microsoft Defender requires the following Microsoft Entra ID information:

* **Tenant ID:** The existing Directory ID for the Entra customer.
* **Application ID:** A configured application Client ID for the Entra customer.
* **Client Secret:** A configured authentication for content sharing between OneSite Patch and Entra.

Instructions on how to obtain this information is detailed below.

#### Internet connectivity to the Microsoft Defender API service

You must make sure that the Adaptiva server can access the Microsoft Defender API service. This enables the Adaptiva server to:

* Verify and save your Microsoft Defender access settings.
* Regularly download updates to the vulnerability metadata. The default schedule for this is every 8 hours.

You can see the integration section of [Plan for OneSite platform installation](https://docs.adaptiva.com/platform-install/planning-guides/onesite-platform-planning#integrations) for a list of the URLs you must add to your allowlist.

### Create a Microsoft Entra Application

To integrate Microsoft Defender with OneSite Patch, begin with registering an application with Microsoft Entra ID and creating a service principle.

You can refer to the official documentation on Microsoft Learn at [Register an application in Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app).

1. Sign in to your **entra.microsoft.com** account as an administrator.
2. Browse to **Entra ID > App registrations**, and then select **New registration**.
3. Enter the following details into the form:
   * Enter a **Name** that identifies the Adaptiva integration.
   * Under Supported account types, select "**Single tenant only - <*****your tenant*****>**".
   * Skip **Redirect URI**. If you must enter something for the **Redirect URI**, select **Web**.
4. Select Register to create the application.

### Add Permissions to an Entra Application

After creating the new Entra application, use the following steps to add the `Vulnerability.Read.All` permission from **Add registrations**. Make sure you are logged in as an administrator.

You can refer to the official documentation on Microsoft Learn at [Configure app permissions for a web API](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-configure-app-access-web-apis).

1. Access the **API Permissions** workspace from the **App registrations** page:
   * Select the **Name** of the newly created application on the **App registrations** page. This opens the application and a new list of menu options.
   * Select **API permissions** on the left navigation menu, and then select **Add a Permission**. This opens the **Request API Permissions** workspace.
2. Select **APIs my organization uses**, and then locate **WindowsDefenderATP** in the list.
3. Select **WIndowsDefenderATP**, and then select **Application permissions**.
4. Scroll down to and expand **Vulnerability**, and then select **Vulnerability Read All**.
5. Click the **Add Permissions** button.
6. Check the **Status** of the newly added permission. If the status is **Not granted for <*****your tenant*****>** and you have administrator privileges, click "**Grant admin consent for <*****your tenant*****>**. Otherwise, get your administrator to grant admin consent for your app.

   ![](/files/fNu9ezXqowigzQoWiKuI)

### Create a Shared Secret ID

After creating an application and adding permissions, use the following steps to create a shared secret ID. The secret ID enables authentication between OneSite Patch and Defender for the application you created.

You can refer to the official documentation on Microsoft Learn at [Add and manage application credentials in Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity-platform/how-to-add-credentials?tabs=client-secret).

1. Select **Certificates & secrets** on the **Manage** menu for the open application.
2. Select **Client secrets**.
3. Select **+ New client secret**. This opens the **Add a client secret** dialog:

   a. Enter a **Description** of the secret.

   b. Select an **Expires** timeline.

   c. Select **Add** to save your changes and return to the **Certificates & secrets** workspace.
4. Immediately copy the **Value** field of the new client secret and save it in a secure location. This field is only viewable immediately after creation.

### Locate and Record the Microsoft Entra IDs

1. Sign in to your entra.microsoft.com account as an administrator.
2. From the **Home** page, navigate to **Applications > App Registrations**, and then open the application you created for integration.
3. Select **Overview** on the left navigation of the application workspace and record the following identification information:
   * **Application (client) ID**
   * **Directory (tenant) ID**

### Integrate Defender with OneSite Patch

1. Select **Microsoft Defender** on the left navigation menu of the OneSite Patch dashboard to open the Defender Access Settings workspace.

   ![](/files/1iN5ShXyZyyFwMBSpTyK)
2. Enter the ID information gathered from [Microsoft Entra](#locate-and-record-the-microsoft-entra-ids), making sure to use the client secret **Value**.
3. Click the **More** dropdown and select **Test Settings** to make sure that your settings are valid and that the Adaptiva server can connect with the Microsoft Defender API service. Any connection errors are recorded in the server error logs.
4. Click **Save** on the upper left.

   <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>When you attempt to save your settings, the Adaptiva portal will try to connect to the Microsoft Defender API service with those settings. If the portal cannot successfully authenticate with the entered settings, it will display an error message and will not save the settings. Make sure that you used the <strong>Value</strong> field of the client secret and not the <strong>Secret ID</strong>.</p></div>

### Metadata properties

These metadata properties can be used to filter patches when creating patch strategies.

| Property                         | Description                                                                                                                                                                                      | Values                                                                             |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- |
| Defender.CvssScore               | The Common Vulnerability Scoring System (CVSS) score of a vulnerability. A decimal value between 0.0 and 10.0, indicating the severity of a given vulnerability with 10.0 being the most severe. | Decimal value 0.0 to 10.0, 1 decimal place                                         |
| Defender.ExploitabilityLevel     | The exploitability level of this vulnerability.                                                                                                                                                  | Unknown / No exploit / Exploit is public / Exploit is verified / Exploit is in kit |
| Defender.KnownExploitExists      | True if the vulnerability is public, verified or in a kit                                                                                                                                        | true / false                                                                       |
| Defender.SecurityUpdateAvailable | Indicates whether a security update is available for the software                                                                                                                                | true / false                                                                       |
| Defender.SeverityLevel           | Defender severity level of vulnerability.                                                                                                                                                        | None / Low / Medium / High / Critical                                              |