> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Microsoft Defender for Endpoint

This guide walks you through connecting Microsoft Defender for Endpoint to TruU TOTAL for persona generation and threat detection.

***

## Overview

TOTAL ingests endpoint security events from Microsoft Defender for Endpoint via the Microsoft Defender XDR Advanced Hunting API. We poll the advanced hunting tables on a configurable interval to collect, normalize, and correlate device events, process executions, network connections, logon events, file operations, and security alerts across your managed endpoints.

**Connector Type:** Polling

***

## Prerequisites

* **Microsoft Entra ID** (Azure AD) access with **Application Administrator** or **Global Administrator** role
* **Microsoft Defender for Endpoint Plan 2** or **Microsoft 365 E5 Security** license
* **Devices onboarded** to Defender for Endpoint with active telemetry
* Approximately **20 minutes** to complete setup

***

## Step 1: Register an Application in Entra ID

1. Sign in to the [Azure Portal](https://portal.azure.com)
2. Navigate to **Microsoft Entra ID** → **App registrations**
3. Click **New registration**
4. Enter:
   * **Name**: `TruU TOTAL - Defender for Endpoint`
   * **Supported account types**: *Accounts in this organizational directory only*
   * **Redirect URI**: Leave blank
5. Click **Register**
6. On the app's **Overview** page, copy:
   * **Application (client) ID**
   * **Directory (tenant) ID**
7. Paste the Client ID and Tenant ID into the TruU Portal

***

## Step 2: Create a Client Secret

1. In your App Registration, go to **Certificates & secrets**
2. Click **New client secret**
3. Enter:
   * **Description**: `TOTAL Defender integration`
   * **Expires**: Choose your organization's preferred expiry
4. Click **Add**
5. Immediately copy the secret **Value** — it will only be shown once
6. Paste the Client Secret value into the TruU Portal

***

## Step 3: Grant API Permissions

1. In the App Registration, click **API permissions**
2. Click **Add a permission** → **APIs my organization uses** → search for **Microsoft Threat Protection**
3. Select **Application permissions** and add:
   * `AdvancedHunting.Read.All` — Run advanced hunting queries
4. Additionally, add **WindowsDefenderATP** → **Application permissions**:
   * `Alert.Read.All` — Read alerts
   * `Machine.Read.All` — Read device information
5. Add **Microsoft Graph** → **Application permissions**:
   * `User.Read.All` — Read user profiles for identity resolution
6. Click **Add permissions**
7. Click **Grant admin consent for \[Your Organization]**
8. Click **Yes** to confirm

> All permissions are **read-only**. TOTAL cannot isolate machines, run scans, or modify any Defender configuration.

***

## Step 4: Verify Connectivity

Once credentials are entered in the TruU Portal:

1. Click **Test Connection** — TOTAL will run a test advanced hunting query to confirm access
2. If successful, you'll see a confirmation with the number of devices and recent events detected
3. If configured, TOTAL will run a historical data pull (up to 30 days) to seed user personas

***

## Security & Privacy

### What We Access

* **Read-only access** to Defender for Endpoint advanced hunting tables via the Microsoft 365 Defender API
* Device events, process events, network events, logon events, and file events
* Security alerts and alert evidence
* All queries use `Timestamp` filtering — we only fetch new events since the last poll

### What We Don't Have Access To

* Ability to isolate, scan, or remediate devices
* Access to response actions or live response sessions
* Write access to Defender configuration, policies, or rules
* Access to file contents or memory dumps

***

## Updating or Rotating Credentials

### Rotate Client Secret (Recommended: Before expiry)

1. In Azure Portal, go to **Entra ID** → **App registrations** → `TruU TOTAL - Defender for Endpoint`
2. Go to **Certificates & secrets**
3. Click **New client secret** (create the new one before deleting the old one)
4. Copy the new secret value and paste it in the TruU Portal
5. After TOTAL confirms the new secret is active, delete the old secret

### Revoke Access

To immediately remove TOTAL's access:

1. **Option A** — Disable in the TruU Portal
2. **Option B** — Remove the App Registration's API permissions in Entra ID
3. **Option C** — Delete the App Registration entirely

***

## Rate Limiting & Scalability

### Defender XDR Advanced Hunting API Rate Limits

| Parameter                      | Limit                         |
| ------------------------------ | ----------------------------- |
| **Advanced Hunting API calls** | 45 req/min, 1,500/hour        |
| **CPU execution time**         | 10 min/hour, 4 hours/day      |
| **Max rows per query**         | 100,000                       |
| **Query data range**           | Last 30 days                  |
| **Throttle response**          | HTTP 429 with retry timeframe |

### Ingestion Capacity

The Advanced Hunting API is the most rate-constrained of the Microsoft APIs. The CPU execution budget (10 min/hour) is the binding constraint, not request count. TOTAL optimizes for this with efficient KQL queries using tight timestamp filters, minimal column projection, and distributed queries across tables.

A large enterprise with 100K+ endpoints generates 20M–80M raw endpoint events/day, but after filtering to human-attributable events only, the TOTAL-relevant subset is **2M–10M events/day**. TOTAL prioritizes high-value tables (DeviceLogonEvents, AlertInfo) and adjusts polling frequency per table based on volume. The CPU budget share is configurable — by default TOTAL consumes up to 50% of the hourly budget, leaving the rest available for SOC analysts.

### Event Freshness

Events appear in Advanced Hunting tables 5–30 minutes after occurrence (Microsoft's ingestion pipeline). TOTAL polls on a configurable interval per table (default: 5 minutes). End-to-end latency is typically **10–35 minutes**.

### Resilience

TOTAL uses cursor-based ingestion with at-least-once delivery, maintaining a separate cursor per table. The cursor only advances after events are successfully collected, normalized, and published. If any step fails, the cursor stays put and the next poll replays from the last known-good position. No events are lost.

Transient failures (429s, 5xx, timeouts) are retried automatically with exponential backoff. If the CPU budget is exhausted, remaining queries are deferred to the next hour. After 5 consecutive failures, the connector self-pauses and can be re-enabled from the TruU Portal. Advanced Hunting retains 30 days of data, so any outage shorter than that results in zero data loss.

### Connector Design

Each connector polls on an independent, configurable interval per table. High-value tables are polled first via a configurable priority order. Events are batched and published in per-user order to preserve sequence integrity for persona building. Connector workers are stateless and scale horizontally. All polling intervals, table priorities, CPU budget share, and batching parameters are tunable from the TruU Portal.

***

# Part 2: Event Types & Data Schema

## Signal Classification

| Signal Class      | TOTAL Category                                        |
| ----------------- | ----------------------------------------------------- |
| Endpoint Security | Endpoint, Authentication, Network, Data Access, Alert |

## Event Types We Ingest

TOTAL queries the following Defender XDR Advanced Hunting tables. Every event ingested is filtered to those attributable to a human user identity via `AccountName`, `InitiatingProcessAccountName`, or `LoggedOnUsers`. System-only and service-account events are excluded.

### Device Logon Events (`DeviceLogonEvents`)

| Field              | Type     | Description                                                            |
| ------------------ | -------- | ---------------------------------------------------------------------- |
| `Timestamp`        | datetime | Event timestamp                                                        |
| `DeviceId`         | string   | Unique device identifier                                               |
| `DeviceName`       | string   | FQDN of the device                                                     |
| `ActionType`       | string   | Logon action (LogonSuccess, LogonFailed, LogonAttempted)               |
| `LogonType`        | string   | Interactive, RemoteInteractive, Network (filtered to human users only) |
| `AccountDomain`    | string   | Domain of the account                                                  |
| `AccountName`      | string   | Username                                                               |
| `AccountSid`       | string   | Security identifier                                                    |
| `IsLocalAdmin`     | boolean  | Whether the user is a local admin                                      |
| `RemoteDeviceName` | string   | Source device for remote logons                                        |
| `RemoteIP`         | string   | Source IP address                                                      |
| `RemoteIPType`     | string   | Public, Private, etc.                                                  |
| `Protocol`         | string   | Authentication protocol used                                           |
| `FailureReason`    | string   | Reason for logon failure                                               |

**TOTAL Classification:** Authentication

### Device Process Events (`DeviceProcessEvents`)

| Field                          | Type     | Description                             |
| ------------------------------ | -------- | --------------------------------------- |
| `Timestamp`                    | datetime | Event timestamp                         |
| `DeviceId`                     | string   | Unique device identifier                |
| `DeviceName`                   | string   | FQDN of the device                      |
| `ActionType`                   | string   | ProcessCreated, ProcessTerminated       |
| `FileName`                     | string   | Process executable name                 |
| `FolderPath`                   | string   | Full path to the executable             |
| `SHA256`                       | string   | File hash                               |
| `ProcessCommandLine`           | string   | Command line used to launch the process |
| `AccountDomain`                | string   | Domain of the account                   |
| `AccountName`                  | string   | Username that launched the process      |
| `ProcessTokenElevation`        | string   | Token elevation type                    |
| `InitiatingProcessFileName`    | string   | Parent process name                     |
| `InitiatingProcessCommandLine` | string   | Parent process command line             |

**TOTAL Classification:** Endpoint

### Device Network Events (`DeviceNetworkEvents`)

| Field                          | Type     | Description                                                    |
| ------------------------------ | -------- | -------------------------------------------------------------- |
| `Timestamp`                    | datetime | Event timestamp                                                |
| `DeviceId`                     | string   | Unique device identifier                                       |
| `DeviceName`                   | string   | FQDN of the device                                             |
| `ActionType`                   | string   | ConnectionSuccess, ConnectionFailed, InboundConnectionAccepted |
| `RemoteIP`                     | string   | Destination IP address                                         |
| `RemotePort`                   | int      | Destination port                                               |
| `RemoteUrl`                    | string   | Destination URL or hostname                                    |
| `LocalIP`                      | string   | Source IP address                                              |
| `LocalPort`                    | int      | Source port                                                    |
| `Protocol`                     | string   | TCP, UDP, etc.                                                 |
| `InitiatingProcessFileName`    | string   | Process that initiated the connection                          |
| `InitiatingProcessCommandLine` | string   | Command line of initiating process                             |
| `InitiatingProcessAccountName` | string   | User account of initiating process                             |

**TOTAL Classification:** Network

### Device File Events (`DeviceFileEvents`)

| Field                          | Type     | Description                                         |
| ------------------------------ | -------- | --------------------------------------------------- |
| `Timestamp`                    | datetime | Event timestamp                                     |
| `DeviceId`                     | string   | Unique device identifier                            |
| `DeviceName`                   | string   | FQDN of the device                                  |
| `ActionType`                   | string   | FileCreated, FileModified, FileDeleted, FileRenamed |
| `FileName`                     | string   | Name of the file                                    |
| `FolderPath`                   | string   | Full path to the file                               |
| `SHA256`                       | string   | File hash                                           |
| `FileSize`                     | long     | File size in bytes                                  |
| `InitiatingProcessFileName`    | string   | Process that performed the file operation           |
| `InitiatingProcessAccountName` | string   | User account                                        |
| `SensitivityLabel`             | string   | Sensitivity label applied to the file               |
| `IsAzureInfoProtectionApplied` | boolean  | Whether AIP protection is applied                   |

**TOTAL Classification:** Data Access

### Device Events (`DeviceEvents`)

| Field              | Type     | Description                     |
| ------------------ | -------- | ------------------------------- |
| `Timestamp`        | datetime | Event timestamp                 |
| `DeviceId`         | string   | Unique device identifier        |
| `DeviceName`       | string   | FQDN of the device              |
| `ActionType`       | string   | Event action type               |
| `AccountDomain`    | string   | Domain of the account           |
| `AccountName`      | string   | Username                        |
| `RemoteUrl`        | string   | URL or IP connected to          |
| `AdditionalFields` | string   | Additional event context (JSON) |

Common user-attributable `ActionType` values: `UsbDriveMounted`, `UsbDriveUnmounted`, `SmartScreenUrlWarning`, `SmartScreenAppWarning`, `BrowserLaunchedToOpenUrl`, `PowerShellCommand`, `ScheduledTaskCreated`

**TOTAL Classification:** Endpoint

### Device Registry Events (`DeviceRegistryEvents`)

| Field                          | Type     | Description                                              |
| ------------------------------ | -------- | -------------------------------------------------------- |
| `Timestamp`                    | datetime | Event timestamp                                          |
| `DeviceId`                     | string   | Unique device identifier                                 |
| `ActionType`                   | string   | RegistryKeyCreated, RegistryValueSet, RegistryKeyDeleted |
| `RegistryKey`                  | string   | Registry key path                                        |
| `RegistryValueName`            | string   | Value name                                               |
| `RegistryValueData`            | string   | Value data                                               |
| `InitiatingProcessFileName`    | string   | Process that modified the registry                       |
| `InitiatingProcessAccountName` | string   | User account                                             |

**TOTAL Classification:** Endpoint

### Alert Events (`AlertInfo` + `AlertEvidence`)

| Field              | Type   | Description                                            |
| ------------------ | ------ | ------------------------------------------------------ |
| `AlertId`          | string | Unique alert identifier                                |
| `Title`            | string | Alert title                                            |
| `Severity`         | string | Informational, Low, Medium, High                       |
| `Category`         | string | MITRE ATT\&CK category                                 |
| `DetectionSource`  | string | Detection technology                                   |
| `AttackTechniques` | string | MITRE techniques                                       |
| `ServiceSource`    | string | Source service                                         |
| `EntityType`       | string | Evidence entity type (User, Device, IP, File, Process) |
| `EvidenceRole`     | string | Role of the evidence in the alert                      |
| `AccountName`      | string | Associated user account                                |
| `DeviceId`         | string | Associated device                                      |
| `RemoteIP`         | string | Associated remote IP                                   |
| `FileName`         | string | Associated file                                        |
| `SHA256`           | string | Associated file hash                                   |

**TOTAL Classification:** Alert

***

## Sample Source Event (Advanced Hunting — DeviceLogonEvents)

```json theme={null}
{
  "Timestamp": "2026-03-15T08:45:12.000Z",
  "DeviceId": "device-id-001",
  "DeviceName": "ACME-WS-001.acme.local",
  "ActionType": "LogonSuccess",
  "LogonType": "RemoteInteractive",
  "AccountDomain": "ACME",
  "AccountName": "jane.doe",
  "AccountSid": "S-1-5-21-1234567890-1234567890-1234567890-1001",
  "IsLocalAdmin": false,
  "RemoteDeviceName": "ACME-JUMP-001",
  "RemoteIP": "10.0.5.22",
  "RemoteIPType": "Private",
  "RemotePort": 3389,
  "Protocol": "RDP",
  "FailureReason": "",
  "InitiatingProcessAccountDomain": "ACME",
  "InitiatingProcessAccountName": "jane.doe",
  "InitiatingProcessAccountSid": "S-1-5-21-1234567890-1234567890-1234567890-1001",
  "InitiatingProcessAccountUpn": "jane.doe@acme.com",
  "InitiatingProcessAccountObjectId": "user-aad-id-001",
  "LogonId": 12345678,
  "ReportId": 98765432
}
```

## TOTAL Normalized Event

```json theme={null}
{
  "event_id": "f6a7b8c9-d0e1-2345-fghi-678901234567",
  "event_type": "AUTH",
  "source": "DEFENDER_ENDPOINT",
  "signal_type": "ENDPOINT",
  "domain_id": "customer-domain-001",
  "tuid": "tuid-jane-doe-001",
  "timestamp": "2026-03-15T08:45:12.000Z",
  "payload": {
    "user": "jane.doe@acme.com",
    "action": "LogonSuccess",
    "logon_type": "RemoteInteractive",
    "device": "ACME-WS-001.acme.local",
    "remote_device": "ACME-JUMP-001",
    "remote_ip": "10.0.5.22",
    "protocol": "RDP",
    "is_local_admin": false
  },
  "raw_metadata": {
    "platform_event_id": "98765432",
    "action_type": "LogonSuccess",
    "logon_type": "RemoteInteractive",
    "device_id": "device-id-001",
    "device_name": "ACME-WS-001.acme.local",
    "account_domain": "ACME",
    "account_name": "jane.doe",
    "account_sid": "S-1-5-21-1234567890-1234567890-1234567890-1001",
    "is_local_admin": false,
    "remote_device_name": "ACME-JUMP-001",
    "remote_ip": "10.0.5.22",
    "remote_ip_type": "Private",
    "remote_port": 3389,
    "protocol": "RDP",
    "logon_id": 12345678,
    "created_at": "2026-03-15T08:45:12.000Z",
    "source_platform": "defender_endpoint"
  },
  "platform_event_id": "98765432",
  "platform_event_source": "DEFENDER_XDR_ADVANCED_HUNTING_API"
}
```

***

## How This Feeds TOTAL

### Persona Building

Defender for Endpoint events define a user's **endpoint behavior profile** — which devices they log into, what processes they run, what network connections originate from their workstation, and what files they interact with locally. This forms the endpoint layer of each persona, establishing what "normal" looks like at the device level.

### Anomaly Detection

TOTAL's behavioral engine uses Defender for Endpoint events to detect:

* **Lateral movement** — RDP or network logons to devices outside a user's normal scope, especially from jump servers or administrative workstations
* **Credential misuse** — logon failures followed by success on different devices, indicating credential stuffing or pass-the-hash attacks
* **Suspicious process execution** — processes launched from unusual paths, with elevated tokens, or matching known attack tooling patterns
* **USB exfiltration** — USB drive mount events correlated with file copy activity on devices handling sensitive data
* **Network anomalies** — outbound connections to unusual IPs or ports from a user's device, especially when correlated with process events
* **Registry persistence** — registry modifications associated with persistence mechanisms (run keys, scheduled tasks, services)

### Breach Lifecycle Coverage

Defender for Endpoint events provide primary coverage across **Privilege Escalation**, **Siphon Data**, and **Siege** stages. This is high-fidelity signal that emerges later in the attack chain and validates earlier persona-based risk signals from identity and communication layers. When correlated with upstream signals, endpoint events provide the confirmation needed to escalate from behavioral anomaly to confirmed threat.