> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://docs.brainframe.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Microsoft Defender Integration

# 🛡️ **Microsoft Defender Integration**

> **"Bring endpoint security, vulnerabilities and incidents into your GRC workspace — live from Microsoft Defender, ready to link to risks, assets and controls."**
> *See your security posture at a glance, sort through what matters, and import Defender records as governed Brainframe documents without leaving your compliance workflow.*

The Microsoft Defender integration connects Brainframe to **Microsoft Defender for Endpoint** and **Microsoft 365 Defender** through the same **Microsoft Entra ID app registration** you use for directory integration. Once configured, you get a live security dashboard, browsable device and threat data, and the ability to **import Defender objects as Brainframe documents** — with **fresh data every time you open an imported record**.

For CISOs and compliance professionals, this closes the gap between **operational security tooling** and **GRC evidence**: you can pull a critical CVE, an active incident, or a misconfiguration recommendation directly into a risk register, audit folder, or remediation tracker — and keep that record current as Defender updates.

---

## 1️⃣ Before You Begin

To use the integration you will need:

* 🛠 A **Brainframe workspace administrator** (to configure Microsoft Entra ID credentials and grant Azure permissions).
* 🔐 An existing **Microsoft Entra ID integration** in the same workspace — Defender **reuses those credentials**; no separate secret is stored for Defender.
* 🪪 **Microsoft Defender for Endpoint** licensing for the modules you want (see [License requirements](#-license-requirements) below).
* 📂 **Read-only API permissions** consented in Azure for both the **Defender for Endpoint API** and **Microsoft Graph** security APIs.

|| ⚠️ Configure **Microsoft Entra ID first**. If Entra is not set up, the Defender configuration screen directs you to the Entra credentials page before you can proceed.

> 💡 Defender and Entra share one app registration. You add **extra application permissions** for Defender on the **same** Entra app — you do not create a second registration.

---

## 2️⃣ Configure the Integration

Microsoft Defender does **not** use a separate username/password screen. Configuration is about extending your existing Entra app with the right permissions and verifying that each Defender module is available.

Go to **Workspace Settings → Integrations → Microsoft Defender → Configure** (`/integrations/microsoft-defender/config`).

### Step 1 — Confirm Entra credentials

The configuration page shows whether **Microsoft credentials are detected** (Tenant ID and Client ID from your Entra integration).

* If Entra is missing, click **Configure Microsoft Entra ID credentials** and complete that setup first.
* If Entra is already configured, continue to add Defender permissions in Azure.

### Step 2 — Add permissions in Azure

Open your app registration in the **Microsoft Entra admin center → App registrations → API permissions**.

**A. Defender for Endpoint API** (`WindowsDefenderATP`)

Add **Application permissions**:

| Permission | Used in Brainframe for |
| ---- |
| `Machine.Read.All` | **Devices** tab — onboarded endpoints |
| `Vulnerability.Read.All` | **Vulnerabilities** tab — CVEs and exposure |
| `SecurityRecommendation.Read.All` | **Misconfigurations** tab — secure configuration recommendations |
| `Score.Read.All` | **Exposure Score** and **Secure Score for Devices** KPI cards |
| `RemediationTasks.Read.All` | **Remediation Tasks** tab |

**B. Microsoft Graph**

Add **Application permissions**:

| Permission | Used in Brainframe for |
| ---- |
| `SecurityIncident.Read.All` | **Incidents** sub-tab |
| `SecurityAlert.Read.All` | **Alerts** sub-tab |

Then click **Grant admin consent for your tenant** on the API permissions page. Admin consent is **required** — adding permissions alone is not enough.

### Step 3 — Test the connection

Back in Brainframe, click **Re-test connection**. The **Module capability status** table shows which Defender modules are available:

| Status | Meaning |
| ---- |
| 🟢 **Enabled** | Permission consented and the module returns data. |
| 🟢 **Enabled (propagating…)** | Consent granted; permissions may take 5–15 minutes to appear in tokens. Re-test shortly. |
| 🟢 **Enabled (missing license)** | Permission is consented, but your tenant needs an additional Defender license (e.g. Plan 2 or Vulnerability Management). |
| 🟠 **Enabled (not provisioned)** | Permission is OK, but Defender has not been initialised in the tenant yet. Open the [Defender portal](https://security.microsoft.com) once, then re-test. |
| 🟠 **Enabled (unavailable)** | Permission consented, but the API probe failed (often licensing or provisioning). |
| 🔴 **Disabled** | Permission not consented — add it in Azure and grant admin consent. |

When credentials and at least one module are available, open **Microsoft Defender** from the configuration screen to start browsing.

> 📌 Brainframe only **reads** from Defender. It does not remediate endpoints, change incident status, or modify Defender configuration on your behalf.

### 🪪 License requirements

| Feature area | Typical Microsoft requirement |
| ---- |
| **Devices** (onboarded endpoints) | Microsoft Defender for Endpoint (Plan 1 or Plan 2) |
| **Vulnerabilities** (TVM / CVE exposure) | Defender for Endpoint **Plan 2** or **Defender Vulnerability Management** add-on |
| **Misconfigurations & recommendations** | Defender for Endpoint with TVM / secure score features |
| **Exposure Score & Secure Score for Devices** | Defender for Endpoint TVM |
| **Incidents & alerts** | Microsoft 365 Defender / Defender XDR (often included in E5 or Defender suite bundles) |
| **Remediation tasks** | Defender TVM remediation workflow enabled in tenant |
| **Microsoft Secure Score** (tenant-wide KPI) | Microsoft Secure Score enabled for the organisation |

> 💡 If a tab shows a yellow **missing license** or **not provisioned** banner, other tabs may still work. Brainframe surfaces the limitation clearly rather than failing silently.

### Government and sovereign clouds

Brainframe automatically detects whether your tenant uses **commercial**, **GCC**, **GCC High**, or **DoD** cloud regions and opens the correct Defender portal links (`security.microsoft.com` vs `security.microsoft.us`). No extra configuration is required beyond standard Entra setup for that cloud.

---

## 3️⃣ Using the Microsoft Defender Integration Page

Open **Workspace Settings → Integrations → Microsoft Defender** (or the **Integrations** item in the sidebar when Defender is enabled for your workspace).

The page header includes **Configure** (gear) and **Refresh**. Use Refresh after large changes in Defender or after granting new permissions in Azure.

### 📊 Top KPI cards (security posture at a glance)

Seven cards summarise tenant-level posture. Several are **clickable** — they switch to the relevant tab and apply a matching filter.

| Card | What it shows | Click action |
| ---- |
| **Microsoft Secure Score** | Organisation-wide secure score (% and points) | Informational |
| **Exposure Score** | Aggregate exposure from vulnerable devices (lower is better) | Informational |
| **Secure Score for Devices** | Configuration score across onboarded devices | Informational |
| **Devices onboarded** | Count of endpoints reporting to Defender | Opens **Devices** tab |
| **Devices at risk** | Endpoints with **High** or **Medium** risk score | Opens **Devices** tab, at-risk filter |
| **Active incidents** | Open security incidents | Opens **Incidents & Alerts**, active filter |
| **Outstanding recommendations** | Open misconfiguration / hardening recommendations | Opens **Misconfigurations** tab |

Colour cues help triage: green for healthy counts, amber/orange for attention needed, red for elevated risk.

> 📌 For board reporting or ISO/SOC evidence, screenshot or export these KPIs alongside imported records in your compliance folders.

---

## 4️⃣ Tabs, Filters and Tables

Five main tabs organise Defender data. Each tab has **search**, **filters**, **sortable columns**, **pagination**, an **Open Defender dashboard** link (context-aware for the active tab), and **Import** actions.

### 🖥 Devices

Your onboarded endpoints — the operational asset inventory security teams care about.

**Filters:** Risk, Exposure, Health, OS platform, RBAC group, Device value, Entra-joined (Yes/No), Internet-facing.

**Key columns:** Device name, OS, Health, Risk, Exposure, Device value, Last seen, First seen, IP, Entra-joined, Group, Tags.

**Typical CISO use:** Identify unmanaged or high-risk workstations linked to critical business assets; import key servers or privileged admin devices into an asset register.

---

### ⚠️ Vulnerabilities

CVE-level vulnerability intelligence from Defender TVM.

**Filters:** Severity (Critical / High / Medium / Low), Public exploit, Exploit verified, In exploit kit.

**Key columns:** CVE, Severity, CVSS, exploit flags, Exposed devices, Published/Updated dates, Fixing KB, Description.

**Typical compliance use:** Import Critical/High CVEs with public exploits into a **Vulnerability** document type; link to risk treatments and patch-management controls (e.g. ISO 27001 A.8, NIS2 technical measures).

---

### 🔧 Misconfigurations

Secure configuration recommendations (misconfigurations and hardening gaps).

**Filters:** Category, Remediation type, Status (Active / Exception), Has active alert, Has public exploit.

**Key columns:** Recommendation name, Category, Severity impact, Secure Score impact, Exposure impact, Exposed devices, Status, Related component.

**Default view:** **Active** recommendations only.

**Typical compliance use:** Track configuration drift against CIS benchmarks or internal hardening baselines; import top recommendations into a **Misconfiguration** register tied to control testing.

---

### 🚨 Incidents & Alerts

Two sub-views under one tab:

| Sub-tab | Content |
| ---- |
| **Incidents** | Correlated security incidents (active, in progress, resolved) |
| **Alerts** | Individual alerts from Defender and broader XDR sources |

**Filters:** Severity, Status, Classification (True positive / False positive / etc.), Date range, **MDE only** vs **All XDR sources**.

**Incident columns:** Name, Severity, Status, Classification, Determination, Assigned to, Created, Priority score, Alert count.

**Alert columns:** Title, Severity, Status, Service source, Detection source, Category, MITRE techniques, Classification, Activity timestamps.

**Typical compliance use:** Import active incidents into an **Incident** folder for breach notification workflows, post-incident review, or SOC handover documentation.

---

### ✅ Remediation Tasks

Tracked remediation work items from Defender TVM (patching, configuration fixes).

**Filters:** Status (Active, Completed, Cancelled, Pending).

**Key columns:** Task title, Related recommendation, Status, Due date, Created, Target devices.

**Typical compliance use:** Import open remediation tasks as **Action** documents in a remediation programme folder; align with audit findings or penetration-test follow-ups.

---

## 5️⃣ Browse, Import and Live Documents

### Browsing and opening in Defender

* **Click a table row** to open that record in the **Microsoft Defender portal** in a new tab.
* Use the **↗ Open in Defender** button on a row for the same action without selecting the row.
* **Open Defender dashboard** (top right of the filter bar) jumps to the matching section in the Defender portal for the tab you are on.

### Importing into Brainframe

Import turns a Defender record into a **native Brainframe document** in a folder you choose.

| Action | How |
| ---- |
| **Import one record** | Click **Import** on a table row |
| **Bulk import** | Select checkboxes on multiple rows → **Import selected** |
| **Choose document type** | A folder picker opens; the default type depends on what you import (see table below) |

**Default document types on import**

| Defender record | Suggested Brainframe type |
| ---- |
| Device | Workstation |
| Vulnerability (CVE) | Vulnerability |
| Misconfiguration / recommendation | Misconfiguration |
| Incident | Incident |
| Alert | Incident |
| Remediation task | Action |

When importing from a **table view**, Brainframe pre-selects that table’s document type in the import dialog.

### Live data on imported documents

Unlike a one-time export, imported Defender documents stay **connected to the source**:

* Each time you **open** the document, Brainframe fetches the **latest data** from Microsoft Defender.
* Severity, status, exposure counts, MITRE techniques, and other fields refresh automatically.
* Use **Open in Defender** from the inline viewer to jump to the canonical record in the portal.

This is ideal for **evidence that must stay current** — e.g. a vulnerability linked to a risk treatment, or an incident referenced in a management review.

> 📌 Imported documents remain in your workspace if you later change Entra permissions. They simply show the most recent data Defender still allows you to read.

---

## 6️⃣ Adding Defender Records from Folders and Table Views

You do not need to open the full integration page for every import.

### Folder **NEW** menu

1. Open any folder → **NEW** → **Add from integrations**.
2. Select **Microsoft Defender** from the catalog (filter by **Vulnerabilities**, **Incidents**, **Assets**, or **Misconfigurations** if helpful).
3. Browse the same tabs, filters, and KPI cards as the main integration page.
4. Import one or many records into the chosen folder.

### Table view **cloud** button

In a document-type table, click the **cloud** icon (**Add from integrations**). The same Defender browser opens, with the **current table’s document type** pre-selected for import.

**Typical workflows**

| Role | Workflow |
| ---- |
| **CISO / security lead** | Weekly review of KPI cards → filter Critical CVEs → bulk-import into a “Security posture” folder |
| **Compliance manager** | Import active misconfigurations into a control-evidence folder mapped to ISO 27001 Annex A |
| **Risk owner** | Import a specific device at High risk and link it to an existing asset risk |
| **Incident response** | Import active incidents during an event; use live refresh for status updates in steering meetings |
| **Auditor (internal)** | Sample remediation tasks with due dates as evidence of corrective action tracking |

---

## 7️⃣ Sidebar Integrations Menu

When Defender is **configured and enabled** in your workspace menu settings, **Microsoft Defender** appears under **Integrations** in the left sidebar.

* Greyed-out entries mean the integration is visible in menu configuration but **not enabled** or **not accessible** for your user — ask an administrator to enable it under **Workspace Settings → Menu interface**.

Configuration always remains under **Integrations → Microsoft Defender → Configure**.

---

## 8️⃣ How CISOs and Compliance Teams Typically Use Defender in Brainframe

### Connect security operations to GRC

| GRC artefact | Defender source | Why it helps |
| ---- |
| **Asset register** | Devices at risk, internet-facing endpoints | Tie technical exposure to business-critical assets |
| **Risk register** | Critical CVEs with public exploits | Quantify likelihood with real exposure counts |
| **Control evidence** | Misconfiguration recommendations | Demonstrate secure configuration monitoring |
| **Incident / breach log** | Active incidents and alerts | Single source for IR documentation and regulatory timelines |
| **Remediation / CAPA tracker** | Remediation tasks | Close the loop from finding → assigned action → verification |
| **Management review pack** | KPI cards + imported top issues | Executive summary without manual spreadsheet exports |

### ISO 27001 / SOC 2 / NIS2 alignment (examples)

* **Vulnerability management (A.8 / CC7)** — Import Critical/High CVEs; link to patch SLAs and risk acceptance records.
* **Secure configuration (A.8)** — Import misconfiguration recommendations; map to hardening standards.
* **Incident management (A.5 / CC7)** — Import incidents; maintain timeline evidence for audits.
* **Asset inventory (A.5)** — Import representative devices; cross-reference with Entra-joined status from the Devices tab.
* **Continuous monitoring** — Live refresh on imported records supports “point-in-time plus ongoing” audit narratives.

### Pair with Microsoft Entra ID

Many organisations use **both** integrations on the same app registration:

* **Entra ID** — identities, directory devices, conditional access, identity risk.
* **Microsoft Defender** — endpoint health, CVEs, incidents, remediation.

Together they give a fuller **identity + endpoint** picture inside Brainframe without duplicate credential management.

---

## 9️⃣ Permissions Summary

| Action | Who |
| ---- |
| Configure Entra credentials (prerequisite) | Workspace administrator |
| Add Azure API permissions & admin consent | Azure/Global administrator |
| Browse Defender data | Any user with workspace access and a working Entra/Defender connection |
| Import records | User with permission to create documents in the target folder |
| View imported live records | Users with read access to those documents |
| Sidebar menu item | Integration enabled in menu config + user/group access |

Credentials are **encrypted at rest** and never shown in the browser after save (via the shared Entra integration).

---

## 🔟 Troubleshooting

| Symptom | Likely cause | What to do |
| ---- |
| Redirected to **Configure Microsoft Defender** | No Entra credentials | Complete **Microsoft Entra ID** configuration first. |
| All modules **Disabled** | Permissions not consented | Add Defender + Graph permissions; **Grant admin consent** in Azure. |
| **Enabled (propagating…)** persists | Azure token delay | Wait 5–15 minutes; click **Re-test connection**. |
| **Missing license** on Vulnerabilities | No TVM / Plan 2 | Enable Defender Vulnerability Management or Plan 2 in Microsoft licensing. |
| **Not provisioned** | Defender never opened in tenant | Visit [security.microsoft.com](https://security.microsoft.com); complete setup; re-test. |
| Empty **Devices** tab | No onboarded machines | Onboard endpoints in Defender for Endpoint. |
| Empty **Incidents** tab | No M365 Defender / XDR | Confirm licensing; try **All XDR sources** on Alerts. |
| Yellow banner on a tab only | Module-specific license or consent gap | Read the banner hint; fix the listed permission or license. |
| Import dialog wrong document type | Table context | When importing from a table view, the table type is pre-selected — adjust in the folder picker if needed. |
| Imported doc shows stale snapshot | Live fetch failed | Check permissions; use **Open in Defender**; refresh the document view. |

---

## Related integrations

| Integration | Complementary use |
| ---- |
| **Microsoft Entra ID** | Shared credentials; identities, directory devices, conditional access, identity risk |
| **Aikido.dev** | Application-layer vulnerabilities (SAST/SCA) alongside endpoint CVEs |
| **JIRA / task integrations** | Track remediation tasks imported from Defender alongside project work items |

For Entra directory setup and permission details, see the **Microsoft Entra ID integration** guide. For application security findings, see the **Aikido** integration guide.