> ## Documentation Index > Fetch the complete documentation index at: https://docs.forge.ai/llms.txt > Use this file to discover all available pages before exploring further. # Microsoft Defender for Endpoint > Connect Defender-managed devices to Forge for endpoint inventory and approved remote operations. The Microsoft Defender for Endpoint connection lets Forge identify an exact Defender device, read supported endpoint inventory, and run approved typed endpoint actions. Forge never exposes a free-form shell or script input. ## Before you start You need: * A Microsoft Defender for Endpoint tenant in the commercial cloud. * A Microsoft Entra administrator who can create an app registration and grant tenant admin consent. * One or more Defender-onboarded pilot devices that are safe for testing. * The Microsoft tenant ID, application client ID, and client secret. ## Optional remote execution Forge's inventory reads work without Live Response. Remote endpoint actions, helper-backed inventory, and AI-session backfill need these Defender settings. In the [Microsoft Defender portal](https://security.microsoft.com), open **Settings → Endpoints → Advanced features**, turn on each setting below, and select **Save preferences**: * **Live Response** * **Live Response for Servers**, if any pilot device is a server For Windows helper-backed actions, choose one of these script trust options: * **Trusted signed runner:** deploy the Forge runner's matching publisher certificate to `LocalMachine\TrustedPublisher` on each pilot device. Keep **Live Response unsigned script execution** off. Signing alone is not enough: the endpoint must trust the exact publisher certificate paired with that Forge release. * **Unsigned script execution:** enable **Live Response unsigned script execution** in the same Defender settings page. This permits unsigned library scripts for users with Live Response **Advanced** permissions on devices in scope; review those roles and device groups before enabling it. ### Why the Windows trust package exists Defender's API executes a **script from its Live Response library**. Forge uploads both a fixed PowerShell runner and the native helper that runner invokes. A signature on the helper executable alone does not authorize the PowerShell runner. The runner checks the helper's SHA-256 before executing its typed plan. The pinned `TrustedPublisher` package is Forge's deployment choice for its runner certificate, not a Microsoft requirement to install a persistent Forge agent first. If that exact publisher is already trusted on the endpoint, no additional trust installation is needed. Otherwise an administrator must deploy the matching trust package, or explicitly allow unsigned Live Response scripts. Uploading a signed file does not itself enroll its publisher as trusted. A publicly trusted certificate chain and an approved PowerShell publisher are different checks: Microsoft's [PowerShell signing guidance](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_signing) describes the prompt for a signed script whose publisher has not been trusted. The Live Response documentation does not promise that a public CA signature alone suppresses every endpoint trust-policy requirement. Validate the signed runner on a pilot while retaining your tenant's signed-script policy. ### Linux and macOS execution Microsoft supports Linux Live Response starting with Defender agent version `101.45.13`. Its [Live Response prerequisites](https://learn.microsoft.com/en-us/defender-endpoint/live-response#other-requirements) state that script signature verification applies only to PowerShell scripts. Do not deploy the Windows certificate package to Linux or macOS. Forge uploads one fixed shell runner containing both release-pinned Linux helpers. The runner selects `x86_64` or `arm64` from the endpoint's `uname -m`, verifies that helper's SHA-256, executes only the compiled typed operation plan, and removes its private temporary directory. It does not infer CPU ISA from Defender's ambiguous `64-bit` machine property or depend on a `putfile` working-directory path. No persistent helper predeployment is required. Linux requires `sh`, `uname`, `sha256sum`, `base64`, `mktemp`, and an executable `/tmp` filesystem. The complete encoded runner is checked against Microsoft's 20 MB library upload limit before submission. Forge does not offer arbitrary shell input or disable host execution restrictions. Microsoft's [Linux analyzer example](https://learn.microsoft.com/en-us/defender-endpoint/run-analyzer-linux#use-live-response-in-defender-for-endpoint-to-collect-support-logs) also uses a library script to invoke a native binary; a binary cannot replace that API script step. Complete a read-only pilot execution before enabling scheduled helper-backed collection on a Linux fleet. ### Deploy the Windows trust package Request the Windows runner trust package for your deployed Forge release from Forge before using the trusted signed runner option. The package includes `publisher.cer`, `trust-runner.ps1`, `detect-trust.ps1`, and `remove-trust.ps1`. Deploy it through Intune as a Windows app running as `SYSTEM`, using these commands: | Action | Command | | - | - | | Install | `powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\trust-runner.ps1` | | Detect | `powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\detect-trust.ps1` | | Uninstall | `powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\remove-trust.ps1` | The package adds only its pinned publisher certificate, not a root CA, and does not change the device's PowerShell execution policy. Deploy the matching trust package before disabling unsigned scripts or changing the runner release. Microsoft describes the settings in [Live Response prerequisites](https://learn.microsoft.com/en-us/defender-endpoint/live-response#other-requirements). Each device must apply these settings itself, and the change may not take effect until the device restarts. After changing them, restart each pilot device before running the pilot workflow. If script trust is not ready, Defender can report the Forge script as completed without running it. Forge detects the missing result and reports that the runner did not execute. Create a dedicated, single-tenant Entra app registration for Forge. Do not reuse a broad automation app shared with other products. Microsoft documents the app-only setup flow in [Create an app to access Microsoft Defender for Endpoint without a user](https://learn.microsoft.com/en-us/defender-endpoint/api/exposed-apis-create-app-webapp). ## Create credentials 1. In the Microsoft Entra admin center, open **Entra ID → App registrations** and select **New registration**. 2. Give the app a recognizable name, such as `Forge Endpoint Integration`, select **Accounts in this organizational directory only**, and register it. 3. Open **API permissions → Add a permission → APIs my organization uses**. 4. Search for `WindowsDefenderATP`. Microsoft notes that this resource may not appear until its name is typed into the search box. 5. Select **Application permissions** and add the permissions in the table below. Do not choose delegated permissions. 6. If hunting-backed features are approved, add the separate Microsoft Graph application permission shown below. 7. Select **Grant admin consent for \** and verify that every added permission shows as granted. Application permissions require admin consent. 8. Open **Certificates & secrets → New client secret**. Set an expiry that fits your credential-rotation policy and copy the secret **value** immediately; Microsoft does not show it again. 9. From the app's **Overview**, copy the **Directory (tenant) ID** and **Application (client) ID**. Microsoft's [app registration guide](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app) and [application-permission guidance](https://learn.microsoft.com/en-us/entra/identity-platform/consent-types-developer#admin-consent-for-application-permissions) describe the Entra steps and consent model. ## Minimum effective permissions Add only the application permissions required for the Forge features you plan to enable. | API resource | Application permission | Why Forge needs it | Requirement | | - | - | - | - | | WindowsDefenderATP | `Machine.ReadWrite.All` | Discover and resolve exact machine records, poll actions, and retrieve Live Response results | Required | | WindowsDefenderATP | `Machine.LiveResponse` | Submit and cancel approved Live Response actions | Required for remote endpoint actions | | WindowsDefenderATP | `Library.Manage` | Temporarily upload and remove Forge-owned Live Response helpers | Required for helper-backed actions and AI-session backfill | | WindowsDefenderATP | `Software.Read.All` | Read installed software and browser-extension inventory | Required for software and extension inventory | | WindowsDefenderATP | `User.Read.All` | Read users observed on an exact machine | Required for user inventory | | Microsoft Graph | `ThreatHunting.Read.All` | Run fixed historical hunting queries for features that explicitly use historical evidence | Optional; omit when hunting-backed features are disabled | Do not add `Machine.Read.All` when `Machine.ReadWrite.All` is granted. The latter already permits machine reads and is required by Microsoft's app-only [Live Response result API](https://learn.microsoft.com/en-us/defender-endpoint/api/get-live-response-result). The permission resource and token audience use Microsoft's legacy Defender identifier. Forge requests the Defender token with `https://api.securitycenter.microsoft.com/.default`, even though it sends API requests to `https://api.security.microsoft.com`. Microsoft warns that using a different audience can return `403 Forbidden`; its current [app-only access guide](https://learn.microsoft.com/en-us/defender-endpoint/api/exposed-apis-create-app-webapp#get-an-access-token) shows the required scope. Forge obtains this token automatically. Customers only provide the tenant ID, client ID, and client secret. Microsoft Graph hunting uses a separate Graph token. These permissions do not grant Forge Defender policy administration. The initial integration does not isolate or offboard devices, run antivirus scans, quarantine files, change Defender policy, mutate Defender tags, or manage alerts and incidents. ## Credential reach and pilot safety These are app-only permissions. They authorize the service principal without a signed-in user and can apply across the tenant. A pilot tag entered in Forge is a Forge discovery and selection guardrail; it does not narrow the Microsoft permission grant. An exact Forge device binding also controls what Forge selects, but it does not change the credential's authority in Microsoft. For a production-tenant pilot: 1. Choose disposable or otherwise low-risk devices that are already onboarded to Defender. 2. Add a distinct Defender machine tag, such as `Forge-Pilot`, to those devices. 3. Record each device's Defender machine ID, hostname, operating system, and a time when it will be online. 4. Enter the same tag as **Pilot device tag** in Forge. Forge shows matching devices for selection, then binds each selected endpoint by its exact Defender machine ID rather than by hostname. 5. Keep the pilot set small and do not select ordinary employee devices for mutation testing. 6. Remove the app registration or revoke its admin consent if the integration is abandoned. Rotate the client secret on your normal schedule. Microsoft's machine API returns machine tags and the immutable machine ID used for this binding. See [List machines](https://learn.microsoft.com/en-us/defender-endpoint/api/get-machines). ## Connect Forge 1. In Forge, open **Settings → Integrations → Microsoft Defender for Endpoint**. 2. Enter a connection name, **Microsoft tenant ID**, **Application client ID**, **Application client secret**, and **Pilot device tag**. 3. Save the connection and run **Test connection**. 4. Review each capability result separately. The connection test combines non-mutating provider reads with inspection of the app's granted roles. A successful token request does not prove that an endpoint can complete a Live Response action; the guarded pilot workflow provides that proof. 5. Discover the pilot devices, compare hostname and platform with your pilot record, and bind only the intended exact machine IDs. Open **Device import** to select devices and assign their owners. Import enables scheduled inventory, including collections that can run a Live Response helper. Complete the pilot's execution and script-trust approval before importing it. Connection setup and **Test connection** do not perform a Live Response execution test. For a configuration-only edit, leave both the application client ID and **Application client secret** empty to retain the saved credential. To rotate credentials, enter both values and run **Test connection** again. See [Endpoint operations](/integrations/endpoint-operations) for the shared import and inventory workflow. Share the client secret through your normal secure-secret channel. Do not send it in email, tickets, chat, screenshots, or test reports. ## Capabilities and coverage limits The available endpoint actions depend on the device's operating system. Helper-backed actions also require Live Response and the script trust setup described above. | Forge capability | Provider path | macOS | Windows | Linux | | - | - | - | - | - | | Host discovery and details | Defender machine APIs | Available | Available | Available | | Logged-on user inventory | Per-machine logon-user API | Available | Available | Available | | Installed application inventory | Per-machine installed-software API | Available | Available | Available | | Browser-extension inventory | Tenant snapshot partitioned by exact machine ID | Available | Available | Available | | Historical hunting evidence | Fixed Microsoft Graph query with optional permission | Used by inventory; no separate action | Used by inventory; no separate action | Available | | Current process list | Fixed typed Live Response helper | Available | Available | Available | | Guarded process termination | Fixed typed Live Response helper | Available | Available | Available | | Directory and filesystem inspection | Fixed typed Live Response helper | Available | Available | Available | | Network and local-runtime inventory | Fixed typed Live Response helper | Available | Available | Available | | MCP, skills, and selected-file inventory | Fixed typed Live Response helper | Available | Available | Available | | Bounded file retrieval | Live Response `GetFile` | Available | Available | Available | | AI-session backfill | Fixed typed Live Response helper | Available | Not enabled | Not enabled | | Deployment and managed configuration | Signed-material product workflow | Available | Not enabled | Not enabled | | Finite policy remediation | Registered product workflow | Available | Not enabled | Not enabled | | File delivery (`file.push`) | No approved product byte source | Not enabled | Not enabled | Not enabled | | Defender policy administration | No supported provider operation | Unsupported | Unsupported | Unsupported | Windows profile scans require an exact directory-user target. If the source has no verified home, Forge first collects a bounded profile catalog through Live Response. It compares the SID and local path reported by [Win32\_UserProfile](https://learn.microsoft.com/en-us/previous-versions/windows/desktop/legacy/ee886409\(v=vs.85\)) with the Windows ProfileList registry entry and rejects redirected directories. Only one matching source-native SID resolved to the requested directory user can authorize the next inventory wave. Missing identity, multiple matching SIDs, partial discovery, or a changed device/source binding produce partial coverage; Forge never constructs a profile path from an email or logged-on-user label. The verified path is retained for that inventory run, not as a general device home override. A configured target user still needs authoritative SID resolution; discovering a directory named after that user is not sufficient. An empty browser-extension snapshot does not prove that a particular device has no extensions. Historical hunting observations also do not represent a current process snapshot. Process termination is never a PID-only action. Forge first binds the request to a process observation and requires the PID, observed start time, and executable digest to still match before termination. A reused PID fails safely. `file.push` is not a supported operation. Forge does not yet have an approved product path that resolves authorized object bytes into this connector, and it will not substitute a caller-supplied local path, script, or command. The deployment and managed-configuration workflows are currently available only for macOS devices. ## Validate the connection 1. Run **Test connection** and inspect each permission result. 2. Confirm the exact machine ID, platform, architecture, and fresh Defender last-seen time. 3. Run a read-only host/software inventory first; these API reads do not prove remote execution. 4. On an approved online pilot, run a bounded directory or process inventory. Require a typed Forge result, not merely Defender reporting the script completed. 5. Confirm the operation reaches a terminal state and its temporary library files are removed. Linux typed execution has automated command/architecture/cleanup coverage; a customer Linux Defender pilot is still required to verify its tenant and host execution environment. Backfill, deployment, and managed configuration remain macOS-only for this connector. ## Temporary data and cleanup Helper-backed operations use attempt-scoped, content-addressed library names. Forge removes its helper and runner files from the Live Response library after success, confirmed cancellation, and other terminal paths. The macOS live suite also checks that its disposable process fixture and endpoint file are gone. File packages, signed download links, transcripts, stdout, stderr, and file bytes remain transient; durable results retain typed inventory or operation state plus safe action references, byte counts, and hashes. For a `GetFile` or script result, Forge consumes the signed result link immediately. If the first download returns 401, 403, or 404, Forge requests one fresh link and retries once. It does not loop or refresh unrelated failures. ## Microsoft service limits Forge separates these provider budgets so a busy inventory route does not consume Live Response capacity. Microsoft can also return `429 Too Many Requests`; Forge honors the provider's retry delay. | Provider route | Microsoft-published limit or behavior | | - | - | | Machine list and exact machine read | 100 calls/minute and 1,500 calls/hour; list page size up to 10,000 | | Logged-on users | 100 calls/minute and 1,500 calls/hour | | Installed software for a machine | The current endpoint-specific Microsoft page does not publish a numeric route limit; Forge applies a separate conservative budget and provider backoff | | Browser-extension JSON snapshot | 30 calls/minute and 1,000 calls/hour; maximum page size 200,000; the response is an organization-wide current snapshot | | Live Response submission | 10 calls/minute; at most 50 concurrent sessions; one active session per machine | | Offline Live Response | Microsoft may queue an unavailable machine for up to two hours; Forge still honors the shorter deadline of the requested operation | | `RunScript` through the Live Response API | 10-minute command timeout | | Live Response result retrieval | 100 calls/minute and 1,500 calls/hour; result links last 30 minutes; Forge performs at most one refresh after an expired-link response | | Live Response library list, upload, and delete | 100 calls/minute and 1,500 calls/hour; upload size is limited to 20 MB | | Machine-action cancellation | 100 calls/minute and 1,500 calls/hour | | Microsoft Graph hunting | The operation page does not publish a fixed call count; Forge uses a separate conservative budget and responds to provider throttling and execution diagnostics | See Microsoft's documentation for [machine limits](https://learn.microsoft.com/en-us/defender-endpoint/api/get-machines), [logged-on users](https://learn.microsoft.com/en-us/defender-endpoint/api/get-machine-log-on-users), [installed software](https://learn.microsoft.com/en-us/defender-endpoint/api/get-installed-software), [browser-extension export](https://learn.microsoft.com/en-us/defender-endpoint/api/get-assessment-browser-extensions), [Live Response](https://learn.microsoft.com/en-us/defender-endpoint/api/run-live-response), [result retrieval](https://learn.microsoft.com/en-us/defender-endpoint/api/get-live-response-result), [library upload](https://learn.microsoft.com/en-us/defender-endpoint/api/upload-library), [library deletion](https://learn.microsoft.com/en-us/defender-endpoint/api/delete-library), [action cancellation](https://learn.microsoft.com/en-us/defender-endpoint/api/cancel-machine-action), and [Microsoft Graph hunting](https://learn.microsoft.com/en-us/graph/api/security-security-runhuntingquery?view=graph-rest-1.0). ## Troubleshooting * **The WindowsDefenderATP API is missing:** type its full name under **APIs my organization uses**; Microsoft says it may not appear in the initial list. * **Authentication works but a capability fails:** verify that the exact application permission was added and that admin consent shows as granted. * **Defender requests return `403` despite granted roles:** verify the access token audience is `https://api.securitycenter.microsoft.com`. Forge uses that legacy audience for requests sent to `https://api.security.microsoft.com`, as required by Microsoft's current app-only guidance. * **A pilot device is absent:** confirm it is onboarded, recently seen by Defender, and has the exact tag entered in Forge. * **Live Response is rejected:** confirm the device and operating system meet Microsoft's Live Response prerequisites. Microsoft also requires a minimum remediation level for some Defender device-group configurations. * **Forge reports that Defender did not run the Forge script:** verify either that the Windows endpoint trusts the exact publisher certificate paired with the Forge runner release, or that **Live Response unsigned script execution** is on under **Settings → Endpoints → Advanced features** and has applied to the device. After changing Defender settings, restart the device and rerun the action. A tamper-protected Defender service cannot be restarted on its own; restart the device instead. * **A Live Response request is already active:** Microsoft permits only one active session per machine. Wait for the existing action to finish or cancel it through the owning workflow. * **Requests are throttled:** wait for Forge's displayed retry time. Do not add permissions or create a second app registration to work around a quota. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.