## Tool catalog

### Read tools (38)

| Area | Tool | Content |
|---|---|---|
| Overview | `get_security_overview` | Open incidents (active, in progress, awaiting action) by severity and status, alerts by product and severity with the most frequent titles, device onboarding and sensor health, Secure Score, open MDI health issues; also a connection test |
| Incidents and alerts | `list_incidents` | Incident queue: filter by status, severity, period, owner (including `me`), unassigned only, tag, classification, determination (e.g. malware, phishing), part of the name; optionally with the alerts per incident (title, severity, MITRE, entities) in one call |
| | `get_incident` | Details with alerts, affected entities, comments |
| | `list_alerts`, `get_alert` | all products (alerts_v2), filter also by product; details with full evidence (processes, files, IPs, URLs, mails, accounts) |
| | `get_incident_statistics` | SOC report for a period (shift handover, week): created per day, by severity and status, resolved by classification/determination, time to resolve (median, P90), open and unassigned, top assignees |
| Investigation | `investigate_user` | one user account across everything, with an assessment (`assessment`: level, verdict, reasons): account status, Entra ID Protection risk and risk detections, identity (department, roles, MDI tags), alerts with incident IDs, sign-ins (failures, countries, risky, single-factor), devices used, email threats and Safe Links clicks, cloud app activity; from the Sentinel/ISOC workspace UEBA (investigation priority, insights) and anomalies |
| | `analyze_indicator` | Verdict on a URL, domain, IP or hash (malicious, suspicious …) with reasons: Microsoft Threat Intelligence, own threat intelligence (`ThreatIntelIndicators`) and watchlists of the workspace, file reputation, alerts and occurrences in the organization |
| | `get_identity_risks` | Entra ID Protection for the whole tenant: risky users (at risk or confirmed compromised), risk detections of the last days (type, level, IP, location; summarized by type, level and user) or risky service principals, highest risk first |
| | `find_identities` | Identity inventory as in the portal under Assets > Identities: accounts from Entra ID, Active Directory and other providers (e.g. Okta) with type, status, department, privileged roles (assigned and eligible), MDI tags, MFA methods, criticality and Defender risk; filters such as privileged, guests, without MFA |
| | `hunt_ioc` | an IP, domain, URL or hash (SHA256/SHA1/MD5) across devices, identities, cloud apps, email and alert evidence: hits per source with the number of affected entities, affected devices, related alerts (not for MD5), timeline; for SHA1/SHA256 also the file profile (global prevalence, signature, detection name). A SHA256 is also searched via the SHA1 from the file profile, because many tables only fill the SHA1; IPv4 addresses also in the form `::ffff:a.b.c.d` |
| | `get_threat_intelligence` | Microsoft Threat Intelligence: reputation of an IP, domain or URL, information about a CVE (active exploitation, exploits, priority), search in threat articles and actor profiles |
| Advanced Hunting | `run_hunting_query` | own KQL query, read-only, row limit and time limit; Defender tables and tables of the Sentinel/ISOC workspace (`workspace`, period up to 180 days) |
| | `get_hunting_schema` | all tables of the Advanced Hunting schema (as of Learn 10/2026, a test checks the list) by product including Sentinel/ISOC tables, keyword search also over the tables that receive data in the workspace (with volume and plan, including custom `_CL` tables), columns of up to five tables |
| | `list_sentinel_workspaces` | reachable Sentinel/ISOC workspaces: primary workspace and configured ones, each with workspace ID, tables with data and last ingestion |
| | `run_custom_hunt` | the team's own saved queries from a catalog with validated parameters; without a name: show the catalog (see [Custom hunts](#custom-hunts-run_custom_hunt)) |
| Exposure graph | `find_exposure_nodes` | Context of the exposure graph (node types, relationship types, categories) or nodes by name, type, category, criticality, internet exposure |
| AI agents | `find_ai_agents` | AI agent inventory as in the portal under Assets > AI agents: Copilot Studio, Microsoft Foundry, Microsoft 365 and other platforms (e.g. AWS Bedrock, GCP Vertex AI) plus local agents on devices (e.g. coding assistants); filter by name, platform, device, account/owner, MCP server, risky configuration (acts without approval, untrusted host process); summary |
| | `get_ai_agent` | one agent in full: description, instructions (system prompt), model, owners and sharing, authentication and permissions, tools, MCP servers, data sources, connected agents, triggers, guardrails, endpoints; relationships in the exposure graph (runs on, uses, is used by) as the starting point for the blast radius |
| | `explore_exposure_graph` | Attack paths: neighbors of a node, blast radius (what is reachable from a compromised node, default: critical assets), perimeter (who reaches an asset, internet-exposed first), paths between two nodes |
| Predefined hunts | `hunt_endpoint_threats` | suspicious PowerShell, LOLBin downloads, new services, scheduled tasks, AV detections, ASR events, tampering attempts, new local administrators |
| | `hunt_identity_threats` | failed sign-ins, password spray, LDAP reconnaissance, lateral movement (accounts with network/RDP logons on many devices), AD group changes, identity alerts |
| | `hunt_email_threats` | daily overview, phishing, malware, malicious attachments, Safe Links clicks, spoofing, message trace, post-delivery actions (ZAP, manual remediation), campaigns (recipients, delivered, still in the inbox), Teams messages with threats, malicious files in SharePoint, OneDrive and Teams |
| | `hunt_cloud_app_activity` | activities per app, activities of an account, OAuth consents, mass downloads, admin activities, impossible travel alerts, OAuth app inventory from App Governance (permission level, risk, verified publisher, admin consent, unused apps) |
| Devices | `find_defender_devices` | Search by name, operating system, onboarding, sensor health, exposure, risk level, internet exposure, "not seen since", device group, tag; summary. Also: which device had an internal IP address at a point in time (`ip_address`, `seen_at`) |
| | `get_defender_device` | Details (OS, sensor, exposure, risk level and health, device group, tags, IPs) with alerts, vulnerabilities and the signed-in users of the last 30 days (count, local admin logons) |
| | `get_device_activity` | Timeline: processes, network, logons, files, registry, events or alerts; last days or a time window around a point in time (e.g. ±30 min. around an alert) |
| | `get_device_exposure` | Vulnerabilities (minimum severity selectable), software, security configuration, security baselines (CIS, STIG with current and expected value), browser extensions with risk or certificates (expiry, weak keys) of the device; vulnerabilities and software also for one product (`software`) |
| | `get_antivirus_health` | Health of Microsoft Defender Antivirus: mode (active, passive, EDR block), currency of signatures, engine and platform, signature age, scan results; devices with a specific problem or the details of one device |
| Vulnerabilities | `get_vulnerability_overview` | Top CVEs, vulnerable software, exposed devices (each with minimum severity and "only with exploit"), missing security updates, unsupported software, misconfigurations, security baselines (compliance per profile and the most frequently failed checks), browser extensions by risk, expired, soon-to-expire or weak certificates; CVE views can be restricted to one product (`software`, e.g. "chrome" or "Google Chrome": every word must occur in vendor or product) |
| | `get_cve_exposure` | one CVE: CVSS, exploit, affected software and devices |
| | `get_remediation_tasks` | Remediation tasks from Defender Vulnerability Management: status, priority, due date, progress (remediated/affected devices), overdue first; details with the devices still affected |
| Posture | `get_secure_score` | current value, history, comparison, improvement actions |
| | `list_attack_simulations` | attack simulations (Defender for Office 365) with report |
| Defender for Identity | `get_identity_health` | health issues (open, closed, suppressed) or sensor inventory with health, service status, version and update status |
| Defender for Cloud Apps | `get_cloud_app_discovery` | Evaluation of the Cloud Discovery report for 7, 30 or 90 days: summary (apps by risk, tag and category, traffic, unsanctioned apps still in use, untagged risky apps awaiting a decision, AI and MCP apps, top apps by users and upload), filtered and sorted app lists, one app in detail (security, compliance and GDPR attributes, users, IP addresses, devices) and the data sources. Default is the Defender for Endpoint stream |
| Custom detections | `list_detection_rules`, `get_detection_rule` | Rules with status, frequency, alert title and severity, MITRE tactics, last change; details with KQL and alert template |

### Admin tools (12)

| Tool | Action | Execution |
|---|---|---|
| `update_incident` | Status, classification, determination, owner (including `me`), severity, tags, closing comment | two steps |
| `update_alert` | Status, classification, determination, owner | two steps |
| `add_comment` | Comment on an incident or alert | immediate |
| `create_detection_rule` | Custom detection from KQL (e.g. the `kql` of a hunt), frequency, alert template, MITRE tactic, entities. The preview runs the query once and reports missing required columns | two steps |
| `manage_detection_rule` | Enable, disable, change or delete a rule | two steps |
| `update_identity_health_issue` | Close, suppress or reopen a health issue | two steps |
| `run_device_response` | Isolate / release, restrict / unrestrict app execution, collect investigation package, stop and quarantine file (SHA1), start automated investigation, add / remove device tag. The preview shows the device, impact, existing tags and running actions | two steps; antivirus scan (quick/full) immediate |
| `get_response_actions` | Status of response actions (of a device or an action), of automated investigations (AIR: running, pending approval, by device or status, details of an investigation) or of automatic attack disruption (blocked sign-ins of contained users, terminated sessions, applied policies) | immediate, read-only |
| `sanction_cloud_apps` | Tag discovered apps as Sanctioned or Unsanctioned (up to 10 per call): preview with current tag, risk, users and impact, then verification of the new tag through Graph. **Undocumented API** (the call the Defender portal makes), requires `MDCA_API_URL`; see "Sanctioning apps" | two steps |
| `manage_submissions` | Submissions to Microsoft (Actions & submissions > Submissions): list email, URL and file submissions including user-reported messages with Microsoft's verdict; submit a URL as phishing, malware or spam or as wrongly blocked (notJunk) | listing immediate, submitting two steps |
| `manage_indicator` | List, create (Block, Warn, Audit, Allow …, with expiry date) or delete indicators (IP, domain, URL, hash, certificate) | listing immediate, otherwise two steps |
| `contain_user` | Contain a compromised account: revoke all sessions, disable / enable the Entra account, confirm compromised or dismiss risk in Entra ID Protection; disable, enable or force a password reset for the **on-premises Active Directory account** (also synchronized ones) through Defender for Identity (input UPN or SID). Your own account is protected | two steps |

`get_response_actions` is an admin tool because it needs a Defender for Endpoint API permission that is only granted
with `-GrantWritePermissions`.

### Deliberately not included or not possible through the API

| Task | Reason | Alternative |
|---|---|---|
| Remove emails from mailboxes (soft/hard delete, junk, move back to inbox) | The Graph API `analyzedEmails/remediate` supports **no delegated permissions**, only an application permission. It would contradict the "on behalf of the user only" principle | Defender portal (Explorer, "Take action" in Advanced Hunting) or your own automation with an application permission and approval |
| Approve pending actions in the Action center, control automated investigations | no public API (the status can be read with `get_response_actions`) | Defender portal (Action center) |
| Release quarantined mails, Tenant Allow/Block List, Defender for Office 365 policies | no Graph API (Exchange Online PowerShell) | Defender portal / PowerShell |
| AV, ASR and EDR policies, exclusions | managed through Intune or Security Settings Management, not through the Defender API | Intune / Defender portal |
| Alert suppression, device groups, roles, automation levels | no public API | Defender portal (Settings) |
| Live Response, offboarding, downloading investigation packages | deliberately left out (script execution or forensic data in the chat) | Defender portal |
| Report an email to Microsoft | The submission needs the message itself (Graph message URL of the mailbox or .eml content), which the agent does not have; `manage_submissions` submits URLs | Defender portal (Submissions), report button in Outlook |
| Search the Purview audit log | asynchronous API with run times above the Copilot Studio tool time limit; `hunt_cloud_app_activity` (CloudAppEvents) returns the Microsoft 365 activities of the last 30 days | Purview portal (Audit) |
| Other Defender for Cloud Apps actions (suspend user, tag Monitored, custom app tags, remove tag), App Governance policies | no documented API; `sanction_cloud_apps` sets Sanctioned and Unsanctioned through an undocumented endpoint | Defender portal (Cloud apps) |

**Example requests to the agent**
- "Show me my open incidents and all unassigned ones with high severity." → `list_incidents`
- "What do we know about max@contoso.com? Is the account compromised?" → `investigate_user`
- "What happened on PC-0815 15 minutes before and after the alert?" → `get_alert`, then `get_device_activity(around=…)`
- "Is the domain evil.example known to be malicious, and does it show up in our environment?" → `get_threat_intelligence`, `hunt_ioc`
- "Which devices have outdated antivirus signatures?" → `get_antivirus_health(issue="outdated_signatures")`
- "Which security updates would close the most critical CVEs?" → `get_vulnerability_overview(view="missing_updates")`
- "Isolate PC-0815 and disable max@contoso.com." → `run_device_response`, `contain_user` (each preview, then execution)
- "How did the week go in the SOC?" → `get_incident_statistics(days=7)`
- "Which device had the IP 10.20.4.17 yesterday at 2:10 pm?" → `find_defender_devices(ip_address=…, seen_at=…)`
- "Which remediation tasks are overdue?" → `get_remediation_tasks`
- "Which automated investigations are pending approval?" → `get_response_actions(kind="investigations", state="PendingApproval")`
- "Which custom hunts are there?" → `run_custom_hunt()`
- "Is https://login-contoso.example/ malicious, and who clicked on it?" → `analyze_indicator`
- "Is alice@contoso.com compromised?" → `investigate_user` (assessment with UEBA)
- "Which users are currently risky, and which risk detections were there today?" → `get_identity_risks`, `get_identity_risks(view="detections", days=1)`
- "Which privileged accounts have no MFA?" → `find_identities(privileged_only=True, without_mfa=True)`
- "Disable the AD account of max@contoso.com." → `contain_user(action="disable_ad_account")` (preview, then execution)
- "Which mails did ZAP remove today, and which campaigns are running?" → `hunt_email_threats(hunt="post_delivery")`, `hunt_email_threats(hunt="campaigns")`
- "What did users report as phishing?" → `manage_submissions(operation="list", source="user")`
- "What did automatic attack disruption block?" → `get_response_actions(kind="attack_disruption")`
- "Which OAuth apps have high privileges and are not used?" → `hunt_cloud_app_activity(hunt="oauth_apps")`
- "How well do our devices meet the CIS baseline? Which certificates are expiring?" → `get_vulnerability_overview(view="security_baselines" / "certificates")`
- "Which AI agents do we have, and which of them use MCP servers?" → `find_ai_agents`
- "Evaluate the Cloud Discovery report of the last 30 days." → `get_cloud_app_discovery()`
- "Which AI apps and MCP servers do our employees use?" → `get_cloud_app_discovery(view="apps", category="ai")`
- "Who uses Dropbox, and how secure is the app?" → `get_cloud_app_discovery(view="app", app_id="11627")`
- "Mark Dropbox as Unsanctioned." → `sanction_cloud_apps(app_ids=["11627"], status="Unsanctioned")` (preview, then execution)
- "Which local AI agents act without approval?" → `find_ai_agents(platform="local", risky_only=True)`
- "What is the HR Helpdesk agent allowed to do, and what can it reach?" → `get_ai_agent`, then `explore_exposure_graph(view="blast_radius", source=<agentNodeId>)`
- "What can an attacker reach from PC-0815?" → `explore_exposure_graph(view="blast_radius", source="PC-0815")`
- "Who can reach our critical SQL servers?" → `find_exposure_nodes`, then `explore_exposure_graph(view="perimeter", target=...)`
- "Show the failed sign-ins of the last 90 days from SigninLogs." → `get_hunting_schema(search=...)`, `run_hunting_query(..., timespan_days=90)`

## Custom hunts (`run_custom_hunt`)

The team's proven KQL queries can be provided as **custom hunts**, comparable to the "custom tools" of the Sentinel
MCP Server. The agent calls them through a single tool with a name and parameters; `run_custom_hunt()` without a
name shows the catalog with purpose and parameters. If a custom hunt fits, the agent uses it instead of writing KQL
itself.

The catalog is the file `src/defender_mcp/custom_hunts.json` (two examples are included):

```json
[
  {
    "name": "process_runs_on_device",
    "description": "Every start of one program on one device with command line, account and parent process.",
    "query": "DeviceProcessEvents\n| where Timestamp > ago({{days}}d)\n| where DeviceId =~ {{device}} or DeviceName =~ {{device}}\n| where FileName =~ {{file_name}}",
    "parameters": {
      "device": {"type": "device", "required": true, "description": "Device name or Defender device ID."},
      "file_name": {"type": "string", "required": true, "description": "Program file name, e.g. powershell.exe."},
      "days": {"type": "days", "default": 3, "description": "Look-back window in days (1-30)."}
    }
  }
]