Microsoft Cloud — Security Tools

The 52 security tools cover Microsoft Defender XDR alerts and incidents, Conditional Access, named locations, Identity Protection (risky users and risk detections), sign-in logs with server-side aggregation, directory audit logs, the Microsoft 365 Unified Audit Log, Defender for Office 365 analyzed emails and attack simulation training, Defender for Identity sensor posture, Defender for Endpoint, Defender Vulnerability Management, the Security Exposure Management attack graph, Defender Advanced Hunting (typed table queries plus arbitrary KQL against the XDR data lake), BitLocker recovery keys, LAPS credentials, and Secure Score.

All tools accept an optional connection_id. Omit it to use the default Entra connection. See entra_connection_list for multi-tenant scenarios.

WARNING

BitLocker recovery keys, LAPS passwords, and Secure Score profile content are sensitive. Confirm caller intent before retrieving them, and avoid logging the actual key/password values into insights or artifacts.

Defender Alerts

mscloud_security_list_alerts

Lists unified security alerts (alerts_v2) from Microsoft 365 Defender. Covers endpoint, identity, email, and cloud app alerts. Filter by severity (high, medium, low, informational) or status (new, inProgress, resolved).

Parameter	Type	Required	Description
connection_id	string	—	Target Entra tenant.
filter	string	—	OData $filter, e.g. severity eq 'high'.
orderby	string	—	OData $orderby.
select	string	—	Comma-separated property list.
top	number	—	Page size, max 100.
skiptoken	string	—	From the previous response.

Example prompt.

"List all high-severity Defender alerts that are still new."

mscloud_security_get_alert

Returns a single alert by ID — full details including evidence, affected entities, and recommended actions. Evidence is deduplicated and capped at 10 entries by default — duplicate command lines or file hashes collapse to compact references. Raise or lower the cap with evidence_limit, or pass omit_evidence to drop the evidence array entirely and return only metadata plus an evidenceCount.

Parameter	Type	Required	Description
alert_id	string	✓	Security alert ID.
connection_id	string	—	Target Entra tenant.
evidence_limit	number	—	Maximum evidence items to keep. Default 10.
omit_evidence	boolean	—	Drop the evidence array, keep metadata plus evidenceCount. Default false.
select	string	—	Comma-separated property list.

Example prompt.

"Show me everything about alert <id>, including affected entities and evidence."

Defender XDR Incidents

Incidents are the containers Defender XDR builds by correlating related alerts into a single multi-stage attack view. They are the natural entry point when investigating a suspected compromise; use mscloud_security_list_alerts instead when you do not need correlation.

mscloud_security_list_incidents

Lists Defender XDR incidents, most recently updated first (matching the Defender portal). Graph supports filtering only on assignedTo, classification, createdDateTime, determination, lastUpdateDateTime, severity, and status, and enum values are lowercase — severity eq 'high', unlike the alerts list which accepts 'High'.

By default the related alerts are not inlined: incidents can correlate 50 or more alerts with full evidence each, so pivoting per alert via mscloud_security_get_alert is usually cheaper. Pass expand_alerts as true only when you really want everything in one response; each inlined alert's evidence is then deduplicated and capped at 10 entries, the same as mscloud_security_get_alert.

Parameter	Type	Required	Description
connection_id	string	—	Target Entra tenant.
filter	string	—	OData $filter on the supported fields, lowercase enums.
orderby	string	—	OData $orderby. Defaults to lastUpdateDateTime desc.
select	string	—	Comma-separated property list.
expand_alerts	boolean	—	Inline related alerts. Default false.
top	number	—	Page size, max 100.
skiptoken	string	—	From the previous response.

Example prompt.

"List all active high-severity Defender incidents."

mscloud_security_get_incident

Returns a single incident by its numeric ID — severity, status, classification, determination, assignee, comments, and (by default) the related alerts inline. Each expanded alert's evidence is deduplicated and capped at 10 entries (tune with evidence_limit). For a triage view that lists the alerts without their evidence arrays — 60–80 % smaller on alert-heavy incidents — pass omit_alert_evidence as true.

Parameter	Type	Required	Description
incident_id	string	✓	Numeric incident ID, e.g. 2972395.
connection_id	string	—	Target Entra tenant.
expand_alerts	boolean	—	Inline related alerts. Default true.
omit_alert_evidence	boolean	—	Keep alert metadata but drop evidence arrays.
evidence_limit	number	—	Per-alert evidence cap. Default 10.
select	string	—	Comma-separated property list.

Example prompt.

"Walk me through incident 2972395 — which alerts and entities are involved?"

Conditional Access & Named Locations

mscloud_security_list_ca_policies

Lists all Conditional Access policies. Critical for security posture assessment — review policy state (enabled, disabled, enabledForReportingButNotEnforced), conditions, and grant controls. Compose with mscloud_security_list_named_locations and mscloud_security_get_ca_policy. By default the response is stripped of nested @odata.* metadata and null-valued fields, which typically halves the bytes; pass include_odata_metadata or include_nulls to retain them.

Parameter	Type	Required	Description
connection_id	string	—	Target Entra tenant.
filter	string	—	OData $filter.
select	string	—	Comma-separated property list.
include_nulls	boolean	—	Retain fields whose value is null. Default false.
include_odata_metadata	boolean	—	Retain nested @odata.* metadata fields. Default false.
top	number	—	Page size, max 100.

Example prompt.

"List all Conditional Access policies — flag any that are still in report-only mode."

mscloud_security_get_ca_policy

Returns a single Conditional Access policy by ID — full configuration including user/group inclusions and exclusions, app conditions, location conditions, and grant/session controls.

Parameter	Type	Required	Description
policy_id	string	✓	Policy ID (GUID).
connection_id	string	—	Target Entra tenant.

Example prompt.

"Show me the full configuration of the 'Require MFA for admins' Conditional Access policy."

mscloud_security_list_named_locations

Lists named locations used in Conditional Access. Includes IP-based and country-based locations. Review to ensure trusted locations match corporate network boundaries. Takes only an optional connection_id.

Example prompt.

"List all named locations and flag any marked as trusted."

mscloud_security_get_named_location

Returns a single named location by location_id — location type (IP ranges or countries) and trust configuration.

Example prompt.

"What IP ranges are in the 'Corporate HQ' named location?"

Identity Protection

mscloud_security_list_risky_users

Lists users flagged as risky by Identity Protection. Filter by riskLevel (high, medium, low) and riskState (atRisk, confirmedCompromised, dismissed). Cross-reference with mscloud_identity_list_directory_role_members to flag any privileged users at risk.

Parameter	Type	Required	Description
connection_id	string	—	Target Entra tenant.
filter	string	—	OData $filter, e.g. riskLevel eq 'high'.
orderby	string	—	OData $orderby.
select	string	—	Comma-separated property list.
top	number	—	Page size, max 100.
skiptoken	string	—	From the previous response.

Example prompt.

"List all users currently flagged as high risk."

mscloud_security_get_risky_user

Returns a single risky user by ID — risk details, risk history, and current risk state.

Parameter	Type	Required	Description
user_id	string	✓	User ID.
connection_id	string	—	Target Entra tenant.
select	string	—	Comma-separated property list.

Example prompt.

"Show me the risk history for this user."

mscloud_security_list_risk_detections

Lists risk detection events from Identity Protection. Each event describes a specific risk signal — anonymized IP, impossible travel, leaked credentials, and so on. Filter by riskType or riskLevel to focus on critical detections.

Parameter	Type	Required	Description
connection_id	string	—	Target Entra tenant.
filter	string	—	OData $filter, e.g. riskType eq 'anonymizedIPAddress'.
orderby	string	—	OData $orderby.
select	string	—	Comma-separated property list.
top	number	—	Page size, max 100.
skiptoken	string	—	From the previous response.

Example prompt.

"List all impossible-travel risk detections from the last 30 days."

Sign-In & Audit Logs

mscloud_security_aggregate_sign_ins

Aggregates Entra ID sign-in logs server-side into compact facets — counts, failure counts, and distinct users per source IP — for password-spray hunting, brute-force detection, and Conditional Access effectiveness analysis. Prefer it over paginating mscloud_security_list_sign_ins whenever the question is statistical (top source IPs, spray patterns, failure-code distribution): it pages and aggregates on the server and returns only the roll-up.

Pass preset as spray_hunt for a one-call spray triage — top source IPs by distinct user count, top accounts by failure count, failure-code distribution, and success-after-failure accounts. Otherwise pick one to three group_by dimensions from upn, ip, country, error_code, app, client_app, ca_status, is_interactive, device_os, and asn.

When a response is truncated, truncated_reason tells you why: time_budget (narrow time_range or add filters) or record_cap (raise max_records, or narrow the window). The warnings array carries the same tokens.

Parameter	Type	Required	Description
time_range	string	—	Look-back window ending now, e.g. 24h, 7d, 30d. Required unless from/to is given.
from / to	string	—	RFC3339 range as an alternative to time_range.
group_by	array	—	1–3 facet dimensions (see above). Required unless preset is set.
preset	string	—	spray_hunt. Overrides group_by.
filter_upn	string	—	Restrict to one user principal name.
filter_ip	string	—	Restrict to one source IP.
filter_app_id	string	—	Restrict to one application ID.
filter_status	string	—	success, failure, or all (default). Not allowed with the preset.
include_non_interactive	boolean	—	Include non-interactive sign-ins. Default false.
max_records	number	—	Cap on records scanned. Default 25000, max 100000.
top	number	—	Top-N entries per facet. Default 15, max 50.
connection_id	string	—	Target Entra tenant.

Example prompt.

"Hunt for password spray over the last 7 days — top source IPs by distinct users targeted."

mscloud_security_list_sign_ins

Lists sign-in logs (interactive and non-interactive). Essential for record-level authentication analysis — inspecting the sign-ins of an entity you have already identified, checking MFA details, or spotting legacy auth usage. For statistical questions across many sign-ins, use mscloud_security_aggregate_sign_ins instead.

Parameter	Type	Required	Description
connection_id	string	—	Target Entra tenant.
filter	string	—	OData $filter.
orderby	string	—	OData $orderby.
select	string	—	Comma-separated property list.
top	number	—	Page size, max 100.
skiptoken	string	—	From the previous response.

Example prompt.

"Show me the last 50 sign-ins for stefan.hayduk@example.com."

mscloud_security_get_sign_in

Returns a single sign-in log entry by ID — full details including authentication methods, Conditional Access results, device info, and location.

Parameter	Type	Required	Description
sign_in_id	string	✓	Sign-in log entry ID.
connection_id	string	—	Target Entra tenant.
select	string	—	Comma-separated property list.

Example prompt.

"Show me the full details of sign-in <id> — auth method, location, and CA result."

mscloud_security_list_directory_audits

Lists directory audit logs (user, group, app changes, and so on). Tracks configuration changes for compliance — who added a user to Global Admins, when Conditional Access policies were modified, who consented to an app.

Parameter	Type	Required	Description
connection_id	string	—	Target Entra tenant.
filter	string	—	OData $filter, e.g. activityDisplayName eq 'Add user'.
orderby	string	—	OData $orderby, e.g. activityDateTime desc.
select	string	—	Comma-separated property list.
top	number	—	Page size, max 100.
skiptoken	string	—	From the previous response.

Example prompt.

"Show every change to a Conditional Access policy in the last 30 days."

mscloud_security_get_directory_audit

Returns a single directory audit log entry by ID — full audit details including initiator, target resources, and modified properties.

Parameter	Type	Required	Description
audit_id	string	✓	Directory audit log entry ID.
connection_id	string	—	Target Entra tenant.
select	string	—	Comma-separated property list.

Example prompt.

"Show me the full audit detail for log entry <id>."

Microsoft 365 Unified Audit Log

The sign-in and directory audit logs above answer "who signed in" and "who changed the directory". The Unified Audit Log answers "who touched which mailbox, file, or Team" — it is the data-plane activity log across Exchange, SharePoint, OneDrive, Teams, and other Microsoft 365 workloads, the same data PowerShell's Search-UnifiedAuditLog reads.

Searches are asynchronous: mscloud_security_create_audit_log_query (or one of the three investigation shortcuts) returns a query_id; check mscloud_security_get_audit_log_query until the status is succeeded — each check waits server-side for the search to progress — then page through the results with mscloud_security_list_audit_log_records. Lookback is bounded by retention: 180 days with Purview Audit Standard, one year with E5.

Plan for a wait. Duration scales with the time window and how tightly the search is filtered: a scoped search — a few days, narrowed by record type, operation, or actor — typically takes 5 to 30 minutes, while a wide or unfiltered search over months can run for hours. Filter as hard as the investigation allows, and treat a search as something you start and come back to rather than something you sit and watch. A search that is still running is not a search that is lost: check back later with the same query_id instead of creating a duplicate.

INFO

These tools require the AuditLogsQuery.Read.All application permission. The current onboarding script grants it; tenants provisioned before it was added must re-run the script or consent manually — see Connecting Entra ID.

WARNING

The permission is only one of two gates. Microsoft Purview Audit must also be enabled for the tenant. If a query reaches succeeded but returns no records, confirm audit logging is turned on rather than assuming a permission failure — an empty result on a succeeded query is not a permission error.

mscloud_security_create_audit_log_query

Creates a Unified Audit Log search. Narrow it with record_types (the workload — for example exchangeItem for mailbox access, sharePointFileOperation for file access, sharePointSharingOperation for external sharing), operations (activity names such as MailItemsAccessed, New-InboxRule, FileDownloaded, AnonymousLinkCreated), user_principal_names (the actor), object_ids (the target file path or mailbox), ip_addresses, a free-text keyword, and a start_time/end_time range (default: the last 24 hours). Omit record_types for a cross-workload search.

Parameter	Type	Required	Description
connection_id	string	—	Target Entra tenant.
start_time	string	—	RFC3339 start of the range. Default: end_time minus 24 hours.
end_time	string	—	RFC3339 end of the range. Default: now (UTC).
record_types	array	—	Workload selectors (e.g. exchangeItem, sharePointFileOperation). Omit for a cross-workload search.
operations	array	—	Activity names (e.g. MailItemsAccessed, New-InboxRule).
user_principal_names	array	—	Actor UPNs to scope to.
object_ids	array	—	Target object IDs — a SharePoint/OneDrive file path, a mailbox, or an admin-cmdlet target. Always a list, even for a single value.
ip_addresses	array	—	Source IP addresses at the time of activity.
service	string	—	Single-workload filter (e.g. Exchange, SharePoint, AzureActiveDirectory). Prefer record_types for most filtering; use this only to scope a search to one service.
keyword	string	—	Free-text search of non-indexed audit-log fields.

Pass object IDs as a list, never a comma-joined string

File paths legitimately contain commas — Q3 Report, Final.docx is a perfectly ordinary document name. Send object_ids as a list of values (["/sites/finance/Shared Documents/Q3 Report, Final.docx"]), not as one string with the values joined by commas, or the path is read as two filters that match nothing. A bare comma-joined string now fails with an explicit error rather than silently returning an empty result — an empty result on a security search reads like a finding, which is the worst possible way to be wrong.

Example prompt.

"Search the audit log for every file download from SharePoint by jane@example.com last week."

mscloud_security_get_audit_log_query

Checks a search created by mscloud_security_create_audit_log_query or a shortcut. Returns the status: notStarted, running, succeeded, failed, or cancelled. The call waits server-side — up to about 25 seconds, checking every few seconds — and returns as soon as the search reaches a final state, so you no longer need to poll rapidly. If the search is still running after the wait, the response includes a note telling you to stop polling and check back later. Fetch records on succeeded; a failed or cancelled query has no results and needs to be recreated. Pass the query_id.

mscloud_security_list_audit_log_queries

Lists previously created audit log searches for the tenant, most recent first, each with its query_id, status, and the filters it was created with. Use it to recover a lost query_id or to check what searches are already in flight before creating another. Page with next_link; set the page size with top (default 50, max 150), which is ignored once a next_link is supplied.

mscloud_security_list_audit_log_records

Fetches one page of records from a succeeded search. Each record carries the timestamp, record type, operation, actor, client IP, target object, service, and the workload-specific auditData payload. Pass the query_id; page with next_link, and set the page size with top (default 50, max 150), which is ignored once a next_link is supplied.

Investigation Shortcuts

Three pre-scoped searches cover the most common incident-response questions. They follow the same asynchronous flow — each returns a query_id to poll and fetch. All three accept user_principal_names and a start_time/end_time range (default: the last 24 hours).

mscloud_security_audit_external_sharing

Finds external and anonymous file-sharing events (AnonymousLinkCreated, SharingInvitationCreated, AddedToSecureLink, SharingSet) — a data-exfiltration indicator for SharePoint and OneDrive. Additionally scopes by object_ids (file paths), which follows the same list rule as mscloud_security_create_audit_log_query.

"Who created anonymous sharing links in the last 24 hours?"

mscloud_security_audit_inbox_rules

Finds inbox-rule creation and mailbox-forwarding changes (New-InboxRule, Set-InboxRule, Set-Mailbox) — the classic Business Email Compromise persistence indicator.

"Check whether any forwarding rules were created on executive mailboxes this week."

mscloud_security_audit_mailbox_access

Finds non-owner mailbox access (MailItemsAccessed) — a key account-compromise indicator. Additionally scopes by mailbox (the target). Note that MailItemsAccessed is only emitted for mailboxes covered by Purview Audit (Premium) / E5; on Audit Standard this search returns no rows.

"Did anyone other than the owner read mail in stefan.hayduk@example.com's mailbox yesterday?"

Defender for Office 365 — Analyzed Emails

Analyzed emails are the per-message detection and delivery records behind the Defender for Office 365 Threat Explorer — verdicts, delivery action and location, transport-rule matches, attachments, and URLs for every message copy Defender analyzed. Use them for false-positive triage ("why was this newsletter quarantined?") and email threat hunting ("which mailboxes received this campaign?"). Both tools are read-only and require a time window.

INFO

These tools require the SecurityAnalyzedMessage.Read.All application permission and Defender for Office 365 Plan 2 licensing. The current onboarding script grants the permission; tenants provisioned earlier must re-run the script or consent manually.

mscloud_security_list_analyzed_emails

Lists analyzed emails for a required time window. List rows are kept compact: attachments, URLs, and timeline events are summarized as counts, while transport-rule matches and the latest delivery verdict and location are included in full. Pivot into mscloud_security_get_analyzed_email for the complete record.

Parameter	Type	Required	Description
start_time	string	✓	RFC3339 start of the window.
end_time	string	✓	RFC3339 end of the window.
connection_id	string	—	Target Entra tenant.
filter	string	—	OData $filter on the network message ID or recipient email address.
top	number	—	Page size.
skiptoken	string	—	From the previous response.

Example prompt.

"List every email Defender analyzed for jane@example.com in the last 24 hours — what were the verdicts?"

mscloud_security_get_analyzed_email

Returns the full detail for one analyzed email — complete attachments, URLs, timeline events, and the delivery record. Identify the message by network_message_id plus the time window it falls in; pass recipient_email_address when the message went to several recipients and you need one specific copy.

Parameter	Type	Required	Description
network_message_id	string	✓	The message's network message ID, from the list call or a message trace.
start_time	string	✓	RFC3339 start of the window containing the message.
end_time	string	✓	RFC3339 end of the window.
recipient_email_address	string	—	Disambiguates multi-recipient copies.
connection_id	string	—	Target Entra tenant.

Example prompt.

"Show me the full analysis for network message ID <id> — why was it quarantined?"

Attack Simulation Training

Phishing simulations tell you something no configuration review can: how your people actually behave when a credible lure lands in their inbox. Three tools read the Defender for Office 365 attack-simulation data — the campaigns you have run, what each person did, and who has never been tested at all.

INFO

These tools require Defender for Office 365 Plan 2 and the AttackSimulation.Read.All application permission, and they work against the Global cloud only. Tenants provisioned before this release must re-run the onboarding script to consent to the new permission.

mscloud_security_list_attack_simulations

Lists your simulation campaigns with the technique each one used (credential harvesting, malware attachment, drive-by URL, link in attachment, link to a malware file, or OAuth consent grant), its status, when it launched and completed, whether it was automated, and its training settings. Start here to get the campaign IDs the other two tools take.

Parameter	Type	Required	Description
connection_id	string	—	Target Entra tenant.
filter	string	—	OData $filter. Graph supports attackTechnique, attackType, completionDateTime, displayName, isAutomated, launchDateTime, and status only.
orderby	string	—	OData $orderby, limited to the same property set.
select	string	—	Comma-separated property list.
top	number	—	Page size, max 100.
skiptoken	string	—	From the previous response.

Example prompt.

"Which phishing simulations have we run this year, and what techniques did they use?"

mscloud_security_get_attack_simulation_users

Returns per-user outcomes for a single campaign: who was compromised and when, who reported the message as phishing, the individual events behind each outcome (clicks, source IPs, browser), and how much assigned training each person completed. This is the view that turns a campaign's headline compromise rate into a list of names to follow up with.

Parameter	Type	Required	Description
simulation_id	string	✓	Campaign ID from mscloud_security_list_attack_simulations.
connection_id	string	—	Target Entra tenant.
top	number	—	Page size.
skiptoken	string	—	From the previous response.

Example prompt.

"For the March credential-harvesting simulation, who clicked and who reported it?"

mscloud_security_get_attack_simulation_coverage

Reads the tenant-wide coverage reports rather than one campaign. Pick a report_type: simulation_user_coverage gives per-user simulation, click, and compromise counts — which is how you find the people who have never been included in any simulation at all; training_user_coverage gives assigned trainings and completion status; repeat_offenders gives the users compromised across multiple campaigns.

Parameter	Type	Required	Description
report_type	string	✓	One of simulation_user_coverage, training_user_coverage, or repeat_offenders.
connection_id	string	—	Target Entra tenant.
skiptoken	string	—	From the previous response.

Example prompt.

"Who has never been included in a phishing simulation, and who has been compromised more than once?"

Count fields come back null for users with no data, which is meaningfully different from zero — a null means the person was never in a campaign, while a zero means they were and did not fall for it.

Defender for Identity — Sensor Posture

Defender for Identity only sees what its sensors watch, so an unsensored domain controller is a blind spot rather than a clean result. Two tools give you the sensor inventory and the health issues behind it, which together answer the coverage question directly.

INFO

These tools require a deployed Defender for Identity workspace (M365 E5-tier licensing) and the SecurityIdentitiesHealth.Read.All and SecurityIdentitiesSensors.Read.All application permissions. Re-run the onboarding script if your tenant was provisioned before this release.

mscloud_security_list_identity_sensors

Lists the Defender for Identity sensor inventory across domain controllers, AD FS and AD CS servers, and Entra Connect hosts. Each row carries deployment status (up to date, outdated, updating), health status, service status, version, sensor type, and a count of open health issues.

The core check this enables is a comparison, not a read: pull this list, pull your domain controllers from inventory_list_hosts or your own asset register, and look for the controllers that appear in one and not the other. Those are the hosts where identity attacks would go unseen.

Parameter	Type	Required	Description
connection_id	string	—	Target Entra tenant.
filter	string	—	OData $filter.
top / skip	number	—	Page size and offset — this endpoint pages by offset, not a token.

Example prompt.

"List our Defender for Identity sensors and flag any that are outdated or unhealthy."

mscloud_security_list_identity_health_issues

Lists the open misconfigurations, outages, and degradations across your hybrid-identity monitoring: unreachable or outdated sensors, disabled auditing, certificate problems, connectivity failures. Each issue arrives with its recommendations and, where Microsoft supplies them, ordered PowerShell remediation steps — so a finding comes with a fix rather than just a label.

Parameter	Type	Required	Description
connection_id	string	—	Target Entra tenant.
filter	string	—	OData $filter, e.g. status eq 'open', severity eq 'high', healthIssueType eq 'sensor'.
select	string	—	Comma-separated property list.
top / skip	number	—	Page size and offset.

Example prompt.

"What Defender for Identity health issues are open at high severity, and how do we fix them?"

Defender for Endpoint

The Defender tools live in their own mscloud_defender_* namespace. The machine tools below use the Defender for Endpoint API and require the WindowsDefenderATP permissions; the Advanced Hunting tools run through Microsoft Graph and require the ThreatHunting.Read.All Graph permission. See Connecting Entra ID for the full list.

mscloud_defender_list_machines

Lists machines onboarded to Microsoft Defender for Endpoint. Filter by OS platform, health status, or machine name. Compose with mscloud_defender_get_machine_recommendations and mscloud_defender_get_machine_logon_users. By default only the last IP (lastIpAddress) is kept per machine; pass include_all_ips to retain the full per-interface ipAddresses array.

Parameter	Type	Required	Description
connection_id	string	—	Target Entra tenant.
os_platform	string	—	Comma-separated platforms (e.g. Windows10,Windows11,WindowsServer2022).
machine_name	string	—	Filter computerDnsName starting with this value.
active_only	boolean	—	Only healthStatus = Active machines.
include_all_ips	boolean	—	Retain the full per-interface ipAddresses array. Default false (only lastIpAddress is kept).
filter	string	—	Custom OData $filter (overrides the simpler params).
select	string	—	Comma-separated property list.
top	number	—	Page size, max 100.
skiptoken	string	—	From the previous response.

Example prompt.

"List all active Windows 11 machines onboarded to Defender."

mscloud_defender_get_machine_recommendations

Returns security recommendations for a specific machine — software vulnerabilities and configuration weaknesses. Filter by remediation_type to separate software patches from configuration changes. Each recommendation's associated-threats list is capped at five entries by default, with associatedThreatCount carrying the original length; set include_all_threats to true for the complete list.

Parameter	Type	Required	Description
machine_id	string	✓	Defender machine ID — 40-character lowercase hex, same format as the hunting tables' DeviceId.
connection_id	string	—	Target Entra tenant.
remediation_type	string	—	Software (Update/Upgrade/Uninstall combined) or Configuration, or any raw value (Update, Upgrade, Uninstall, ConfigurationChange).
include_all_threats	boolean	—	Return the full associated-threats list per recommendation. Default false.
select	string	—	Comma-separated property list.

Example prompt.

"Show me all software-update recommendations for machine <id>."

mscloud_defender_get_machine_logon_users

Returns logon users for a specific machine — useful for identifying shared workstations and mapping attack surfaces.

Parameter	Type	Required	Description
machine_id	string	✓	Defender machine ID — 40-character lowercase hex, same format as the hunting tables' DeviceId (not the Entra device GUID).
connection_id	string	—	Target Entra tenant.

Example prompt.

"Which users have logged onto machine <id> recently?"

Defender Advanced Hunting

These tools query the Microsoft 365 Defender XDR data lake through Microsoft Graph — the same tables you can hunt against in the Defender portal. Six typed tools cover the most common pivots; a seventh accepts arbitrary KQL for joins, summaries, and tables not exposed via the typed shapes.

Responses are wrapped in an envelope with rowCount, totalRowCount, truncated, columns, and rows. Up to 200 rows are returned per call — narrow your time window or add filters when truncated is true. Throttled responses surface a clear "Retry after N seconds" hint so InfraScout can pace follow-up calls; Graph allows roughly 45 hunting calls per minute per tenant.

The five device-event tools share a common shape. Each accepts device_id (the Defender DeviceId — 40-character lowercase hex, not the Entra device GUID) or device_name, a time_range of 15m, 1h, 24h, or 7d (default 1h), a limit (default 100, max 200), and a columns projection: default for the curated hunt columns, forensic to add hashes and the deeper initiating-process parent chain, or all for the full table schema.

WARNING

Advanced Hunting accesses raw telemetry — process command lines, alert evidence, and entity links. Treat results like any other security data: avoid persisting command-line strings or evidence payloads beyond the assessment they were collected for.

mscloud_defender_query_device_process_events

Process creation events (DeviceProcessEvents) — the most common security pivot. Filter by process_name (such as powershell.exe) or command_line_contains (substring against the command line).

Example prompt.

"Show me PowerShell processes started on device <id> in the last 24 hours where the command line contains -EncodedCommand."

mscloud_defender_query_device_file_events

File creation, modification, and rename events (DeviceFileEvents), including path, hashes, and the initiating process. Filter by file_name or sha256. The forensic projection adds SHA1/MD5 hashes and file-origin details.

Example prompt.

"Was the file invoice.exe written anywhere on this device in the last 7 days?"

mscloud_defender_query_device_network_events

Network connection events (DeviceNetworkEvents), including remote IP, port, URL, protocol, and the initiating process. Filter by remote_ip, remote_url (FQDN), remote_port, or protocol (Tcp, Udp, Icmp).

Example prompt.

"Which processes on this device connected to evil.example.com in the last 24 hours?"

mscloud_defender_query_device_registry_events

Registry create, modify, and delete events (DeviceRegistryEvents) — useful for hunting persistence and configuration tampering. Filter by registry_key_contains (substring, such as \Run for autostart keys) or action_type (such as RegistryValueSet).

Example prompt.

"Show registry changes to autostart keys on this device in the last 24 hours."

mscloud_defender_query_device_image_load_events

DLL and module load events (DeviceImageLoadEvents) — useful for hunting DLL side-loading and modules loaded from suspicious paths. Filter by file_name (the DLL) or folder_path_contains (such as \Temp\). For signed/unsigned analysis, join DeviceFileCertificateInfo via the generic KQL tool.

Example prompt.

"Which processes loaded DLLs from a Temp directory on this device today?"

mscloud_defender_query_alert_evidence

Maps Defender alerts to the entities they reference — files, processes, users, IPs, URLs, mailboxes, and registry keys — from the AlertEvidence table. Supply at least one of alert_id or entity_type (File, Process, User, Ip, Url, MailMessage, Registry); pass both to narrow further. The default time_range is 24h.

Duplicate evidence rows are collapsed by default (dedupe), and the bulky raw AdditionalFields payload is dropped — with the device ID and verdict fields lifted to top-level columns so you can still pivot from user evidence to a device. Set include_additional_fields to true to retain the raw payload.

Example prompt.

"List every entity Defender linked to alert <id> — users, devices, files, IPs."

mscloud_defender_advanced_hunting_query

Generic KQL passthrough for joins, summarize, and any table the typed tools do not expose (DeviceLogonEvents, DeviceEvents, Email, Identity, and CloudApp tables, plus cross-product correlations). Write the query the same way you would in the Defender portal hunting console, and always include a | limit N clause — results are also capped server-side at 200 rows.

Parameter	Type	Required	Description
query	string	✓	KQL statement, including a limit N clause.
connection_id	string	—	Target Entra tenant.
timeout_seconds	integer	—	Per-query timeout for slow joins. Default 120, max 180.

Example prompt.

"Run this hunting query: DeviceLogonEvents | where Timestamp > ago(1h) | summarize count() by AccountName | limit 50."

Defender Vulnerability Management

The per-machine recommendation tool above answers "what is wrong with this host". These four answer the organizational version: what is worth fixing first across the whole estate, how exposed you are today, whether anyone is actually doing the remediation, and which software is dragging the score down.

INFO

All four require Defender for Endpoint Plan 2 (or Microsoft 365 E5) — no Defender Vulnerability Management add-on is needed. They use the Score.Read.All, RemediationTasks.Read.All, Software.Read.All, and Vulnerability.Read.All permissions alongside the existing SecurityRecommendation.Read.All. Re-run the onboarding script if your tenant predates this release.

mscloud_defender_list_recommendations

Returns the org-wide, risk-prioritized recommendation list that sits behind the Vulnerability Management dashboard. Each row carries a severity score, how many machines are exposed out of the total, whether a public exploit exists, whether there is an active alert tied to it, the remediation type, and what fixing it would do to your exposure and secure scores. Those last fields are what let the AI rank work by payoff rather than by severity label alone.

Associated threats are capped at five per recommendation by default, with the original count preserved alongside; a single recommendation can carry hundreds, so ask for the full list only when you need it.

Parameter	Type	Required	Description
connection_id	string	—	Target Entra tenant.
filter	string	—	OData $filter on id, productName, vendor, recommendedVersion, recommendationCategory, subCategory, severityScore, or remediationType.
include_all_threats	boolean	—	Return the full associated-threats array. Default false.
top / skip	number	—	Page size (max 100, default 50) and offset.

Example prompt.

"What are our top ten security recommendations by exposure impact, and which of them have public exploits?"

mscloud_defender_get_exposure_score

Returns both organizational scores in one call: the exposure score (0–100, where lower is better — it weights unremediated weaknesses by exploit likelihood and device value) and the Microsoft Secure Score for Devices, which is an absolute point total from configuration posture. Two different scales pointing the same direction, so read them together rather than mistaking one for the other. Set by_machine_group to break exposure down per RBAC machine group instead, which is how you find the one business unit dragging the tenant number down.

Parameter	Type	Required	Description
connection_id	string	—	Target Entra tenant.
by_machine_group	boolean	—	Break the exposure score down per RBAC machine group instead of returning the org-level pair.

Example prompt.

"What's our exposure score, and which machine group is worst?"

mscloud_defender_list_remediation_activities

Lists the remediation tasks created from recommendations, with status, priority, target versus fixed device counts, due date, and who requested them. This is the follow-through check — recommendations tell you what should happen, and this tells you whether it did.

An empty list is a normal answer, not an error: it means your tenant has never created remediation tasks, which is itself worth reporting.

Parameter	Type	Required	Description
connection_id	string	—	Target Entra tenant.
filter	string	—	OData $filter — this endpoint supports createdOn and status (Active, Completed) only.
top / skip	number	—	Page size (max 100, default 50) and offset.

Example prompt.

"Are there any active remediation tasks, and how far along are they?"

mscloud_defender_list_software

Two views in one tool. Called plainly, it returns the org software inventory as the "top vulnerable software" list: per product, the number of discovered weaknesses, public-exploit and active-alert flags, exposed machine count, and impact score. Pass a software_id from that inventory and it pivots to the CVE list for that product instead — severity, CVSS v3 score, exposed machines, and exploit status per vulnerability.

Advisory descriptions on the CVE pivot are truncated to 300 characters by default, which is usually enough to identify the vulnerability; include_full_descriptions returns them whole when you need to quote one.

Parameter	Type	Required	Description
connection_id	string	—	Target Entra tenant.
software_id	string	—	Inventory ID in vendor-_-product form, e.g. microsoft-_-edge. Set it to get that product's CVEs instead of the inventory.
filter	string	—	OData $filter on id, name, or vendor only. Ignored on the CVE pivot.
include_full_descriptions	boolean	—	CVE pivot only — return full advisory text instead of the 300-character truncation.
top / skip	number	—	Page size (max 100, default 50) and offset.

Example prompt.

"Which software in our estate has the most vulnerabilities, then show me the CVEs for the worst one."

For per-device install detail beyond these views, drop down to mscloud_defender_advanced_hunting_query against the DeviceTvm* tables.

Security Exposure Management — Attack Paths

A vulnerability list tells you what is weak. An attack path tells you what that weakness reaches. These two tools read the Microsoft Security Exposure Management graph — the same asset-and-relationship model behind the attack-path view in the Defender portal — and hand back paths and neighborhoods as plain readable structures rather than graph query results.

Both hide the graph's schema, its query language, and its inverted criticality scale (where 0 means most critical) behind decoded labels, so a path arrives as a sequence you can read aloud: this identity, can authenticate to this host, which has a role on this critical asset.

INFO

These tools require Microsoft Security Exposure Management onboarding. Without it the exposure graph is unavailable and the call returns an error saying so. Both are read-only and need no agent on any host.

mscloud_defender_find_attack_paths

Walks the exposure graph backward from a target — starting at what you care about protecting and finding what can reach it, which is the direction that matters for defense. The target is either a pinned node (by ID or exact name) or your critical-asset set, selected with target_criticality.

One detail worth internalizing: a call returns paths of exactly max_hops length, not every path up to that length. Searching at depth 3 will not surface a one-hop direct edge. To cover the short paths too, call again with a smaller max_hops — start at 1 and work outward, since the direct routes are usually the ones to fix first.

Narrow the result with entry_point_category when you only care about a class of starting point (identities, say, rather than devices), or with edge_label to trace one relationship type through the graph.

Parameter	Type	Required	Description
target_criticality	string	—	Target set when no node is pinned: critical or high (critical plus high). Default critical.
target_node_id	string	—	Pin the target to one graph node. Overrides target_criticality.
target_node_name	string	—	Pin the target by exact display name. May match several nodes.
max_target_nodes	number	—	Cap the target nodes walked when targeting by criticality or name. Default 10, max 25.
entry_point_category	string	—	Keep only paths whose starting node is in this category, e.g. identity, device.
edge_label	string	—	Restrict traversal to one relationship type, e.g. can authenticate to. Exact match.
max_hops	number	—	Exact hop count per returned path. Default 2, range 1–3.
limit	number	—	Maximum paths returned. Default 25, max 200.
connection_id	string	—	Target Entra tenant.
timeout_seconds	number	—	Per-query timeout. Default 120, max 180.

Example prompt.

"What identities can reach our critical assets in two hops or fewer?"

Truncation is always signaled rather than silent: when more target nodes or paths existed than were returned, the response says so, so a partial graph walk is never read as an exhaustive one.

mscloud_defender_get_exposure_node

Pivots into a single asset and its one-hop neighborhood — the node's label, categories, and decoded criticality, plus the relationships pointing at it, leading from it, or both. Use it after a path search to understand an asset a path named: what else touches this host, and what does it in turn touch.

Parameter	Type	Required	Description
node_id	string	—	Exact graph node ID, from a path's entry or target. Provide this or node_name.
node_name	string	—	Exact node display name. Provide this or node_id.
edge_direction	string	—	in, out, or both (default).
edge_limit	number	—	Neighbor edges per direction. Default 50, max 99.
connection_id	string	—	Target Entra tenant.

Example prompt.

"Tell me about the asset that path went through — what else connects to it?"

BitLocker Keys

mscloud_security_list_bitlocker_keys

Lists BitLocker recovery keys stored in Entra ID. Returns key metadata (device ID, creation date, volume type) but not the actual recovery key. Use mscloud_security_get_bitlocker_key to retrieve the key value.

Parameter	Type	Required	Description
connection_id	string	—	Target Entra tenant.
filter	string	—	OData $filter, e.g. deviceId eq 'device-guid'.
select	string	—	Comma-separated property list.
top	number	—	Page size, max 100.
skiptoken	string	—	From the previous response.

Example prompt.

"List BitLocker recovery keys stored for device <device-id>."

mscloud_security_get_bitlocker_key

Returns a single BitLocker recovery key by ID. By default returns metadata only — include key in select to retrieve the actual recovery key value. Requires BitlockerKey.Read.All permission.

Parameter	Type	Required	Description
key_id	string	✓	BitLocker recovery key ID (GUID).
connection_id	string	—	Target Entra tenant.
select	string	—	Use key to include the actual recovery key.

WARNING

Including key in select returns the actual BitLocker recovery key. Confirm caller intent and avoid persisting the value beyond the immediate response.

Example prompt.

"Retrieve the BitLocker recovery key for ID <id> — I need to unlock the drive."

LAPS Credentials

mscloud_security_list_laps_credentials

Lists device local credentials (LAPS) for Entra ID-joined devices. Returns metadata about which devices have LAPS passwords managed by Entra. Use mscloud_security_get_laps_credential to retrieve the actual password.

Parameter	Type	Required	Description
connection_id	string	—	Target Entra tenant.
filter	string	—	OData $filter, e.g. deviceName eq 'DESKTOP-ABC123'.
orderby	string	—	OData $orderby.
select	string	—	Comma-separated property list.
top	number	—	Page size, max 100.
skiptoken	string	—	From the previous response.

Example prompt.

"Find the LAPS entry for DESKTOP-ABC123."

mscloud_security_get_laps_credential

Returns LAPS credential details for a specific device. Use the id field from mscloud_security_list_laps_credentials as device_id — it is the Entra device object ID. Requires DeviceLocalCredential.Read.All permission.

Parameter	Type	Required	Description
device_id	string	✓	Entra device object ID (the id from the list call).
connection_id	string	—	Target Entra tenant.
select	string	—	Use credentials to include the actual password.

WARNING

Including credentials in select returns the actual LAPS password. Confirm caller intent and avoid logging the value.

Example prompt.

"Get the LAPS password for device <device-id> — I need to log on locally."

Secure Score

mscloud_security_get_secure_scores

Returns the tenant's Microsoft Secure Score history — point-in-time snapshots of current vs. max score. Use this when the user asks "what is our current score" or "show score trend". For improvement actions or roadmap, call mscloud_security_list_secure_score_profiles instead. The per-control breakdown is stripped from each snapshot by default; pass include_control_breakdown only when you genuinely need it (the breakdown is the proper job of mscloud_security_list_secure_score_profiles).

Parameter	Type	Required	Description
connection_id	string	—	Target Entra tenant.
include_control_breakdown	boolean	—	Include the per-control controlScores array on each snapshot. Default false.
orderby	string	—	OData $orderby, e.g. createdDateTime desc.
top	number	—	Number of snapshots to return.

Example prompt.

"What's our current Secure Score and how has it changed over the last 30 days?"

mscloud_security_list_secure_score_profiles

Lists secure score control profiles — the per-control improvement actions that raise the tenant's score. Use whenever the user asks for a roadmap, improvement plan, recommendations, or "what should we do to improve our Secure Score".

Parameter	Type	Required	Description
connection_id	string	—	Target Entra tenant.
filter	string	—	OData $filter.
select	string	—	Comma-separated property list.
top	number	—	Page size, max 100.
skiptoken	string	—	From the previous response.

Example prompt.

"What improvements would raise our Secure Score the most?"

See Also

For users, groups, directory roles, and PIM, see Microsoft Cloud — Identity. For app registrations, GDAP, and Azure platform inventory, see Microsoft Cloud — Platform. For Intune managed devices and configuration, see Microsoft Cloud — Intune. For Teams, SharePoint, Exchange Online, and licensing, see Microsoft Cloud — Services.