This article explains how to set up and use the Microsoft Defender for Endpoint response integration in Logsign USO (Unified SecOps Platform), lists the available commands with their inputs and outputs, and flags two commands that are currently non-functional in the shipped manifest.
Overview
The Microsoft Defender for Endpoint integration (formerly Microsoft Defender ATP) is called from playbook action blocks and makes REST calls to Microsoft's https://api.securitycenter.windows.com API.
It provides two groups of commands:
- Analysis commands: read-only lookups for alerts, machines, files, IP addresses, and vulnerabilities, used inside playbooks for enrichment.
- Containment / Eradication commands: the actual response actions. These add a file hash, IP address, domain, URL, or certificate to Defender as a custom indicator (block, allow or alert), and remove that indicator again.
Authentication
Add a Microsoft Defender for Endpoint asset from the Integrations / Assets screen. It has a single configuration field:
| Field | Required | Description |
|---|---|---|
| Token | Yes | Bearer access token used to call the Microsoft Defender for Endpoint API (stored encrypted) |
Unlike the log-collection (poller) integration for Microsoft Defender, this asset does not take a Client ID, Client Secret, or Tenant ID. It expects a ready-made access token that you generate on the Azure AD (Entra ID) side and paste in.
Generating the Token
- In Microsoft Entra ID, create an App Registration (or reuse an existing one).
Under API Permissions, add Application permissions for WindowsDefenderATP (may appear as "Microsoft Threat Protection" in some tenants). Depending on which commands you plan to use, add at least:
Alert.Read.Allfor alert lookup commandsMachine.Read.Allfor machine, logon user and discovered vulnerability commandsTi.ReadWrite(orTi.ReadWrite.All) for submit-or-update-indicator and delete-indicator, the actual response actionsFile.Read.Allfor file information commandsIp.Read.Allfor IP statistics and alert commandsVulnerability.Read.Allfor vulnerability commands
Grant admin consent after adding the permissions.
- Create a client secret and use the Client Credentials grant against the
https://api.securitycenter.windows.com/.defaultscope to obtain an access token. - Paste the resulting access token, as-is, into the Token field on the asset.
Token Lifetime
This asset stores a static token only. It does not refresh automatically using a client ID and secret: the token is decrypted directly from the stored config on every call, and there is no refresh-token or client-credentials logic in the code. Standard Azure AD access tokens expire after roughly one hour. Plan on generating a new token and updating the asset configuration periodically, otherwise every command starts failing with authorization errors.
Testing the Connection
The connection test only validates that the configuration is well-formed JSON. It does not call Microsoft's API, so a successful test does not confirm the token is valid or authorized. To check that the token actually works, run list-alerts from a playbook after saving the asset.
Known Issue: Two Commands Do Not Work
Two commands appear as selectable options when configuring a playbook action, but fail every time they are executed. This was confirmed by tracing the dispatch path in the integration engine: the command you select is matched against the method names declared in the asset's manifest, then that exact name is looked up in the Go handler map registered for this integration. For these two commands, the name declared in the manifest has no matching entry in the handler map, so the lookup fails and the call returns an invalid method error before any request reaches Microsoft.
| Command (as shown in the UI) | Why it fails |
|---|---|
get-machine-related-alerts | The manifest declares this name, but the integration only registers a handler under the key get-machine-related-events. No handler is found for get-machine-related-alerts. |
create-user | The manifest declares this name with an argument (query) and result shape that match the Advanced Hunting (KQL) feature, but no handler named create-user is registered at all. |
Do not select these two commands in a playbook until Engineering corrects the manifest and handler name mismatch. If you need machine-related alerts or advanced hunting today, there is no working path to them through this asset's exposed commands.
Commands
The commands below are the ones that are actually reachable and functional (the two commands from the previous section are excluded on purpose). Field names and types come directly from the manifest's declared result schema, which mirrors Microsoft's own Defender for Endpoint API field names.
submit-or-update-indicator
Category: Containment. Adds or updates a custom indicator in Defender. Managed devices generate an alert and/or are blocked based on this indicator. This is the primary blocking action of this integration.
Input
| Argument | Required | Description |
|---|---|---|
indicatorValue | Yes | The value to block or monitor (hash, IP, domain, URL, certificate thumbprint) |
indicatorType | Yes | Type of the value. Per Microsoft's public API: FileSha1, FileSha256, IpAddress, DomainName, Url, Certificate (verify the current list in Microsoft's own documentation) |
action | Yes | Action to apply. Per Microsoft's public API: Alert, AlertAndBlock, Block, BlockAndRemediate, Allowed, Warn (supported values vary by indicator type) |
title | No | Indicator title |
application | No | Application associated with the indicator |
expirationTime | No | When the indicator expires |
severity | No | Severity of the indicator |
description | No | Free-text description |
recommendedActions | No | Free-text recommended actions |
rbacGroupNames | No | Array of RBAC device group names this indicator applies to |
Output
| Field | Description |
|---|---|
id | Defender-assigned indicator ID. Save this to remove the indicator later with delete-indicator |
indicatorValue, indicatorType, action | Echo of the submitted values |
source, sourceType, createdBy | Who or what created the indicator |
severity, title, description, recommendedActions | Echo of the submitted metadata |
creationTimeDateTimeUtc, expirationTime, lastUpdateTime, lastUpdatedBy | Lifecycle timestamps |
rbacGroupNames[] | RBAC groups the indicator applies to |
Verified example, from the integration's own test suite:
{
"indicatorValue": "220e7d15b011d7fac48f2bd61114db1022197f7f",
"indicatorType": "FileSha1",
"action": "AlertAndBlock"
}delete-indicator
Category: Eradication. Removes an existing indicator via DELETE /api/indicators/{id}.
Input
| Argument | Required | Description |
|---|---|---|
id | Yes | Defender's internal indicator ID, not the original hash/IP/URL value |
Output: empty body on success (HTTP 200/204).
The most common mistake is entering the original indicator value (the hash, IP or URL you blocked) in the id field. The API rejects that. It expects the indicator's Defender-assigned internal ID.
The only reliable way to get that ID today is from the response of the submit-or-update-indicator call that originally created the indicator (its id field). The underlying integration also implements a list-indicators lookup that could otherwise be used to find this ID by matching indicatorValue, but it is not declared in the manifest and is therefore not selectable from the playbook UI, the same gap described in the Known Issue section above. If you did not capture the id from the original submit-or-update-indicator response, there is currently no in-product way to look it up; you would need to check the indicator directly in the Microsoft Defender portal.
list-alerts
Category: Analysis. Lists alerts, with optional OData filtering.
Input
| Argument | Required | Description |
|---|---|---|
filter | No | OData $filter expression |
top | No | OData $top (page size) |
skip | No | OData $skip (pagination offset) |
expand | No | OData $expand, for example expanding related evidence |
Output: value[], an array of alert objects (see get-alert-info-by-id for the alert shape).
get-alert-info-by-id
Category: Analysis. Returns full details for a single alert.
Input: id (required), the Alert ID.
Output
| Field | Description |
|---|---|
id, incidentId, investigationId, investigationState | Alert and related investigation identifiers |
assignedTo, severity, status, classification, determination | Triage state |
detectionSource, category, threatFamilyName, title, description | Alert classification |
alertCreationTime, firstEventTime, lastEventTime, lastUpdateTime, resolvedTime | Timestamps |
machineId | Machine ID this alert was raised on, feed this into get-machine-by-id |
comments[] | Array of {comment, createdBy, createdTime} |
get-alert-related-machine-info
Category: Analysis. Returns the machine (device) associated with an alert. Input: id (required), the Alert ID. Output: same shape as get-machine-by-id below.
get-alert-related-ips-info
Category: Analysis. Returns IP addresses observed on the alert. Input: id (required), the Alert ID. Output: value[], an array of { id } (IP address strings).
get-alert-related-files-info
Category: Analysis. Returns files observed on the alert. Input: id (required), the Alert ID. Output: value[], an array of file objects with sha1, sha256, md5, globalPrevalence, globalFirstObserved, globalLastObserved, size, fileType, isPeFile, filePublisher, fileProductName, signer, issuer, signerHash, isValidCertificate, determinationType, determinationValue.
get-alert-related-domain-info
Category: Analysis. Returns domains observed on the alert. Input: id (required), the Alert ID. Output: value[], an array of { host }.
get-machine-by-id
Category: Analysis. Returns full details for a single machine (device).
Input
| Argument | Required | Description |
|---|---|---|
id | Yes | Machine ID, Defender's device identifier, not a MAC or IP address |
Output
| Field | Description |
|---|---|
id, computerDnsName | Machine identity |
firstSeen, lastSeen | Activity window |
osPlatform, version, osProcessor, osBuild | OS details |
lastIpAddress, lastExternalIpAddress | Networking |
healthStatus, riskScore, exposureLevel | Posture |
rbacGroupId, rbacGroupName | RBAC scoping |
isAadJoined, aadDeviceId | Azure AD join state |
machineTags[] | Tags applied to the device |
get-machine-logon-users
Category: Analysis. Returns users that have logged on to a machine. Input: id (required), the Machine ID. Output: value[], an array of { id, accountName, accountDomain, accountSid, firstSeen, lastSeen, logonTypes, logOnMachinesCount, isDomainAdmin, isOnlyNetworkUser }.
get-discovered-vulnerabilities
Category: Analysis. Returns vulnerabilities discovered on a machine. Input: id (required), the Machine ID. Output: value[], an array of vulnerability objects (same shape as get-vulnerability-by-id below).
get-file-information
Category: Analysis. Returns reputation and metadata for a file.
Input
| Argument | Required | Description |
|---|---|---|
id | Yes | File hash (SHA1 or SHA256) |
Output
| Field | Description |
|---|---|
sha1, sha256 | File hashes |
globalPrevalence, globalFirstObserved, globalLastObserved | Prevalence across the tenant base |
size, fileType, isPeFile | File properties |
filePublisher, fileProductName, signer, issuer, signerHash, isValidCertificate | Signing information |
determinationType, determinationValue | Microsoft's verdict on the file |
get-file-related-alerts
Category: Analysis. Returns alerts related to a file hash. Input: id (required), the file hash. Output: an array of alert objects (same shape as get-alert-info-by-id).
This command name is declared twice in the manifest, once with an incorrect (machine-shaped) result schema and once with the correct (alert-shaped) result schema. Both entries dispatch to the same handler, so whichever one you pick in the UI, the actual response at runtime is always the alert-shaped object described above. The machine-shaped schema is a leftover documentation error in the manifest, not a second reachable behavior.
get-ip-related-alerts
Category: Analysis. Returns alerts related to an IP address. Input: id (required), the IP address. Output: value[], an array of alert objects (same shape as get-alert-info-by-id, plus computerDnsName, rbacGroupName, aadTenantId, relatedUser, evidence[]).
get-ip-statistics
Category: Analysis. Returns prevalence statistics for an IP address. Input: id (required), the IP address. Output: ipAddress, orgPrevalence, orgFirstSeen, orgLastSeen.
get-vulnerability-by-id
Category: Analysis. Returns details for a single CVE.
Input
| Argument | Required | Description |
|---|---|---|
id | Yes | CVE ID, for example CVE-2019-0608 |
Output
| Field | Description |
|---|---|
id, name, description, severity, cvssV3 | Vulnerability identity and scoring |
exposedMachines | Count of machines in the tenant exposed to this CVE |
publishedOn, updatedOn | Timeline |
publicExploit, exploitVerified, exploitInKit | Exploitability flags |
exploitTypes[], exploitUris[] | Known exploit metadata |
list-devices-by-vulnerability
Category: Analysis. Returns devices affected by a given CVE. Input: id (required), the CVE ID. Output: value[], an array of { id, computerDnsName, osPlatform, rbacGroupName }.
Frequently Asked Questions
Do I need to enter a Client ID, Secret, or Tenant ID?
No. This asset only takes a ready-made Bearer token, which you generate in Azure AD using the Client Credentials flow.
The asset's connection test passed. Does that mean the token works?
Not necessarily. The test only checks that the configuration is valid JSON; it does not call Microsoft's API. Run list-alerts from a playbook to confirm the token actually works.
The integration was working and suddenly started failing. Why?
The most likely cause is that the access token expired. Azure AD tokens typically last about one hour, and this integration does not refresh automatically. Generate a new token and update the asset.
I want to remove a blocked file hash. Do I enter the hash in the id field?
No. The id field for delete-indicator expects Defender's internal indicator ID, not the hash. See the delete-indicator section above, and make sure you saved the id returned when you originally submitted the indicator.
Can I enter a device's IP address in the id field for machine commands?
No. These commands expect Defender's Machine ID, not a MAC or IP address. You can get the Machine ID from related alert or vulnerability responses (the machineId / id field on those objects).
Why can't I select "get machine related alerts" or advanced hunting and have it work?
See the Known Issue section above. get-machine-related-alerts and create-user are present in the picker but fail every time due to a manifest/handler naming mismatch. This needs an Engineering fix; it is not a configuration problem on your side.
Common Result Messages
| Message | Meaning |
|---|---|
| 200 OK / 204 No Content | Successful call |
| 404 Not Found | The requested resource was not found (wrong ID, deleted record, etc.) |
| 500 Internal Server Error | A server-side error occurred on Microsoft's end |
| Unknown status code | Any other status code, for example 401/403 when the token is invalid or unauthorized |
| Mandatory argument: id | The id field was left empty on a command that requires it |
| Invalid method | The selected command's manifest name has no matching handler. Currently affects get-machine-related-alerts and create-user only |