The CloudRadial AutomationAI Microsoft Defender for Endpoint extension lets a workflow or agent take part in endpoint detection and response: triage alerts, isolate or contain a machine, run antivirus scans and other response actions, review a device's vulnerabilities and installed software, and manage custom threat indicators. This article covers what the extension can do, the app registration and secrets it needs, which tools require approval, and the skills that ship with it. It is for workspace users who build automations (Admin or Owner Role).
- What the Extension Covers
- Creating the App Registration
- Providing the Credentials to Your Runner
- Reads and Approval-Gated Changes
- How Response Actions Complete
- Skills
- Tips for Working With Defender Data
What the Extension Covers
The extension calls the Microsoft Defender for Endpoint API and provides 18 tools across these areas:
| Area | What you can automate |
| Machines | List machines, filtered for example by DNS name or health status, and read one machine's details |
| Alerts | List alerts filtered by status, severity, or machine, read one alert, and update an alert's status, assignee, classification, or determination |
| Response actions | Isolate a machine from the network and release it, run a quick or full antivirus scan, restrict app execution to Microsoft-signed code and remove the restriction, and collect a forensic investigation package |
| Action tracking and investigations | List response actions and their status, and list automated investigations |
| Vulnerabilities and software | List the vulnerabilities (CVEs) and installed software on one device, and list the organization-wide software inventory with exposure counts |
| Threat indicators | List your custom threat indicators, and add or update a file hash, IP address, domain, URL, or certificate indicator |
Install it from Extensions like any other catalog extension. See Browsing and installing extensions for the general install flow.
Creating the App Registration
The extension signs in with an app-only (client-credentials) token for a Microsoft Entra ID app registration. For the general steps of creating an app registration and a client secret, see Creating a Microsoft 365 app registration for the Microsoft 365 extension. This extension does not use Microsoft Graph permissions. Instead, under the app's API permissions, add Application permissions for WindowsDefenderATP and grant admin consent. The extension uses these permissions:
| Permission | Used for |
Machine.Read.All and Machine.ReadWrite.All |
Reading machines, vulnerabilities, software, and response actions |
Machine.Isolate |
Isolating and releasing a machine |
Machine.Scan |
Running an antivirus scan |
Machine.RestrictExecution |
Restricting and unrestricting app execution |
Machine.CollectForensics |
Collecting an investigation package |
Alert.Read.All and Alert.ReadWrite.All |
Reading and updating alerts |
Ti.ReadWrite.All |
Listing and creating threat indicators |
Providing the Credentials to Your Runner
Store four secrets in your runner's Key Vault with these exact names:
| Secret | Value |
Defender-ApiUrl |
The API base URL, https://api.securitycenter.microsoft.com/api. It is the same for all commercial tenants. US Government tenants use a different host; see Microsoft's documentation. |
Defender-TenantID |
Your Microsoft Entra (directory) tenant ID GUID |
Defender-ClientID |
The Application (client) ID GUID of the app registration that holds the WindowsDefenderATP permissions |
Defender-ClientSecret |
The client secret value from the app registration's Certificates & secrets |
The runner reads these secrets itself and the agent never asks you for them. For how to add secrets, see Accessing and updating your runner's Key Vault. If you manage a separate tenant for each client, see Managing companies and per-company credentials.
Reads and Approval-Gated Changes
Of the 18 tools, 10 are read-only and run without interruption. The other 8 act on a machine, an alert, or your indicator list, and every one of them is approval-gated: the run pauses and the request appears as an Action Required item in the Inbox until someone approves it. See Handling Action Required items in the Inbox.
| Tool behavior | Tools |
| Approval-gated | Isolate a machine; release a machine from isolation; run an antivirus scan; restrict app execution; remove the app-execution restriction; collect an investigation package; update an alert; add or update a threat indicator |
| Read-only | List machines; read a machine; list a machine's vulnerabilities; list a machine's software; list response actions; list the software inventory; list alerts; read an alert; list threat indicators; list automated investigations |
Isolating a machine cuts it off from the network, and restricting app execution stops anything but Microsoft-signed code from running, so confirm the machine before you approve.
How Response Actions Complete
Response actions run asynchronously. When you approve one, Defender accepts the request and creates a response action whose status moves from pending, to in progress, to succeeded or failed. The change is not in place the moment the request is accepted. The skills check the action's status with the response-action list before reporting that it is done.
Every response action needs a comment, and the agent includes one with each request. Tell the agent the reason you want recorded.
Collecting an investigation package returns a response action, not the package itself. The extension has no tool that downloads the package.
Skills
The extension ships five skills that guide an agent through common Defender tasks:
| Skill | Use it to |
| Investigate Alerts | Triage alerts: list new or high-severity ones, read one in detail, pivot to the affected device's software and vulnerabilities, and set its status or classification. Updating an alert is approval-gated. |
| Isolate / Contain a Machine | Isolate a potentially compromised endpoint from the network, and later release it. Both steps are approval-gated. |
| Run Response Actions | Run an antivirus scan, restrict or unrestrict app execution, or collect an investigation package on a device. Every action is approval-gated. |
| Manage Threat Indicators | Review your custom indicator list, or add a file, IP, domain, or URL indicator with an alert or block action. Adding an indicator is approval-gated. |
| Review Vulnerabilities | Review the CVEs and installed software on a device, or browse the organization-wide software inventory. Read-only. |
To give an agent these skills, see Creating custom agents and using them in workflows.
Tips for Working With Defender Data
- Refer to a machine by its DNS name. Defender's machine ids are long hexadecimal values, not names, so the agent looks up the id first and then acts on it.
- List tools return the complete result in one call, so you do not page through results. Ask for a filter, such as alert status or severity, rather than reading the whole tenant.
- Only an alert's status, assignee, classification, and determination can be changed
- An alert's status is New, InProgress, or Resolved. Its classification is TruePositive, InformationalExpectedActivity, or FalsePositive.
- A threat indicator needs a value, a type, a title, a description, and an action. IP ranges in CIDR notation are not supported, and a tenant can hold 15,000 active indicators.
- If one kind of action fails while reads work, check that the app holds the permission for that action, for example
Machine.Isolatefor isolation
If you are still having trouble, we’re here to help! Submit a ticket here for assistance, and don’t forget to check our status page to ensure there are no outages in your area.
Comments
0 comments
Please sign in to leave a comment.