Skip to main content
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, 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 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 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 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: 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. 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.

​
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 <tenant> 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 and application-permission guidance describe the Entra steps and consent model.

​
Minimum effective permissions

Add only the application permissions required for the Forge features you plan to enable. 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. 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 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.

​
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 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. 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 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. See Microsoft’s documentation for machine limits, logged-on users, installed software, browser-extension export, Live Response, result retrieval, library upload, library deletion, action cancellation, and Microsoft Graph hunting.

​
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.