Microsoft Defender for Endpoint

Reference for the Tracecat Microsoft Defender for Endpoint integration: registered actions, required secrets, expected inputs, and example workflow usage.

Create machine action

Action ID: tools.microsoft_defender_endpoint.create_machine_action

Submit a machine action (for example, isolate or run an antivirus scan) in Microsoft Defender for Endpoint.

Reference: https://learn.microsoft.com/en-us/defender-endpoint/api/machineaction

Secrets

Optional secrets:

• microsoft_defender_endpoint_oauth: OAuth token MICROSOFT_DEFENDER_ENDPOINT_USER_TOKEN.
• microsoft_defender_endpoint_oauth: OAuth token MICROSOFT_DEFENDER_ENDPOINT_SERVICE_TOKEN.

Input fields

action_type · string · required

Type of machine action to perform.

Allowed values: Isolate, Unisolate, CollectInvestigationPackage, RunAntivirusScan, RestrictCodeExecution, UnrestrictCodeExecution, StopAndQuarantineFile, LiveResponse, Offboard, RequestSample.

comment · string · required

Comment describing why the action is being taken.

machine_id · string · required

Machine ID to target with the action.

base_url · string

Base URL for the Microsoft Defender for Endpoint API.

Default: "https://api.securitycenter.microsoft.com".

Allowed values: https://api.securitycenter.microsoft.com, https://api-gcc.securitycenter.microsoft.us, https://api-gov.securitycenter.microsoft.us.

parameters · object | null

Optional action parameters payload (for example, {“scanType”: “Quick”} for RunAntivirusScan).

Default: null.

Create or update indicator

Action ID: tools.microsoft_defender_endpoint.create_or_update_indicator

Create or update a Microsoft Defender for Endpoint custom indicator of compromise.

Reference: https://learn.microsoft.com/en-us/defender-endpoint/api/post-ti-indicator

Secrets

Optional secrets:

• microsoft_defender_endpoint_oauth: OAuth token MICROSOFT_DEFENDER_ENDPOINT_USER_TOKEN.
• microsoft_defender_endpoint_oauth: OAuth token MICROSOFT_DEFENDER_ENDPOINT_SERVICE_TOKEN.

Input fields

action · string · required

Enforcement action for the indicator.

Allowed values: Alert, Warn, Block, Audit, BlockAndRemediate, AlertAndBlock, Allowed.

description · string · required

Indicator description.

indicator_type · string · required

Indicator type.

Allowed values: FileSha1, FileSha256, FileMd5, CertificateThumbprint, IpAddress, DomainName, Url.

indicator_value · string · required

Indicator value (for example, SHA1 hash, domain, URL, or IP address).

title · string · required

Indicator alert title.

application · string | null

Friendly application name to display in end-user notifications.

Default: null.

base_url · string

Base URL for the Microsoft Defender for Endpoint API.

Default: "https://api.securitycenter.microsoft.com".

Allowed values: https://api.securitycenter.microsoft.com, https://api-gcc.securitycenter.microsoft.us, https://api-gov.securitycenter.microsoft.us.

expiration_time · string | null

Optional ISO 8601 timestamp when the indicator expires (for example, 2025-12-31T00:00:00Z).

Default: null.

generate_alert · boolean | null

Whether Defender should generate an alert when the indicator matches.

Default: null.

rbac_group_names · array[string] | null

Optional list of RBAC device group names that the indicator applies to.

Default: null.

recommended_actions · string | null

Recommended remediation steps to include with the indicator.

Default: null.

severity · string | null

Optional severity to associate with the indicator.

Default: null.

Get alert

Action ID: tools.microsoft_defender_endpoint.get_alert

Retrieve a Microsoft Defender for Endpoint alert by ID.

Reference: https://learn.microsoft.com/en-us/defender-endpoint/api/get-alert-info-by-id

Secrets

Optional secrets:

• microsoft_defender_endpoint_oauth: OAuth token MICROSOFT_DEFENDER_ENDPOINT_USER_TOKEN.
• microsoft_defender_endpoint_oauth: OAuth token MICROSOFT_DEFENDER_ENDPOINT_SERVICE_TOKEN.

Input fields

alert_id · string · required

Alert ID to retrieve.

base_url · string

Base URL for the Microsoft Defender for Endpoint API.

Default: "https://api.securitycenter.microsoft.com".

Allowed values: https://api.securitycenter.microsoft.com, https://api-gcc.securitycenter.microsoft.us, https://api-gov.securitycenter.microsoft.us.

Get file from machine

Action ID: tools.microsoft_defender_endpoint.get_file_from_machine

Request a file from a device using Microsoft Defender Live Response.

Reference: https://learn.microsoft.com/en-us/defender-endpoint/api/run-live-response

Secrets

Optional secrets:

• microsoft_defender_endpoint_oauth: OAuth token MICROSOFT_DEFENDER_ENDPOINT_USER_TOKEN.
• microsoft_defender_endpoint_oauth: OAuth token MICROSOFT_DEFENDER_ENDPOINT_SERVICE_TOKEN.

Input fields

file_path · string · required

Absolute file path on the device (escape backslashes, for example C:\\Windows\\Temp\\sample.txt).

machine_id · string · required

Machine ID to collect the file from.

base_url · string

Base URL for the Microsoft Defender for Endpoint API.

Default: "https://api.securitycenter.microsoft.com".

Allowed values: https://api.securitycenter.microsoft.com, https://api-gcc.securitycenter.microsoft.us, https://api-gov.securitycenter.microsoft.us.

comment · string | null

Comment describing the Live Response action.

Default: null.

Get incident

Action ID: tools.microsoft_defender_endpoint.get_incident

Retrieve a Microsoft Defender for Endpoint incident by ID.

Reference: https://learn.microsoft.com/en-us/defender-endpoint/api/exposed-apis-list

Secrets

Optional secrets:

• microsoft_defender_endpoint_oauth: OAuth token MICROSOFT_DEFENDER_ENDPOINT_USER_TOKEN.
• microsoft_defender_endpoint_oauth: OAuth token MICROSOFT_DEFENDER_ENDPOINT_SERVICE_TOKEN.

Input fields

incident_id · string · required

Incident ID to retrieve.

base_url · string

Base URL for the Microsoft Defender for Endpoint API.

Default: "https://api.securitycenter.microsoft.com".

Allowed values: https://api.securitycenter.microsoft.com, https://api-gcc.securitycenter.microsoft.us, https://api-gov.securitycenter.microsoft.us.

Get machine

Action ID: tools.microsoft_defender_endpoint.get_machine

Retrieve detailed information about a device from Microsoft Defender for Endpoint.

Reference: https://learn.microsoft.com/en-us/defender-endpoint/api/get-machine-by-id

Secrets

Optional secrets:

• microsoft_defender_endpoint_oauth: OAuth token MICROSOFT_DEFENDER_ENDPOINT_USER_TOKEN.
• microsoft_defender_endpoint_oauth: OAuth token MICROSOFT_DEFENDER_ENDPOINT_SERVICE_TOKEN.

Input fields

machine_id · string · required

Machine ID to retrieve, as returned by the alerts or incidents APIs.

base_url · string

Base URL for the Microsoft Defender for Endpoint API.

Default: "https://api.securitycenter.microsoft.com".

Allowed values: https://api.securitycenter.microsoft.com, https://api-gcc.securitycenter.microsoft.us, https://api-gov.securitycenter.microsoft.us.

Isolate machine

Action ID: tools.microsoft_defender_endpoint.isolate_machine

Isolate a device from the network using Microsoft Defender for Endpoint.

Reference: https://learn.microsoft.com/en-us/defender-endpoint/api/isolate-machine

Secrets

Optional secrets:

• microsoft_defender_endpoint_oauth: OAuth token MICROSOFT_DEFENDER_ENDPOINT_USER_TOKEN.
• microsoft_defender_endpoint_oauth: OAuth token MICROSOFT_DEFENDER_ENDPOINT_SERVICE_TOKEN.

Input fields

comment · string · required

Comment describing why the device is being isolated.

machine_id · string · required

Machine ID to isolate.

base_url · string

Base URL for the Microsoft Defender for Endpoint API.

Default: "https://api.securitycenter.microsoft.com".

Allowed values: https://api.securitycenter.microsoft.com, https://api-gcc.securitycenter.microsoft.us, https://api-gov.securitycenter.microsoft.us.

isolation_type · string

Isolation scope to apply.

Default: "Full".

Allowed values: Full, Selective, UnManagedDevice.

List alerts

Action ID: tools.microsoft_defender_endpoint.list_alerts

List Microsoft Defender for Endpoint alerts with optional filtering and time range.

Reference: https://learn.microsoft.com/en-us/defender-endpoint/api/get-alerts

Secrets

Optional secrets:

• microsoft_defender_endpoint_oauth: OAuth token MICROSOFT_DEFENDER_ENDPOINT_USER_TOKEN.
• microsoft_defender_endpoint_oauth: OAuth token MICROSOFT_DEFENDER_ENDPOINT_SERVICE_TOKEN.

Input fields

base_url · string

Base URL for the Microsoft Defender for Endpoint API.

Default: "https://api.securitycenter.microsoft.com".

Allowed values: https://api.securitycenter.microsoft.com, https://api-gcc.securitycenter.microsoft.us, https://api-gov.securitycenter.microsoft.us.

filter · string | null

OData filter expression to apply (for example, status eq ‘Active’ and severity eq ‘High’).

Default: null.

order_by · string | null

OData order by clause (for example, lastUpdateTime desc).

Default: null.

since_time · string | null

ISO 8601 timestamp to restrict alerts updated after this time (convenience filter applied as lastUpdateTime ge).

Default: null.

top · integer | null

Maximum number of alerts to return (maps to $top OData query option).

Default: null.

List incidents

Action ID: tools.microsoft_defender_endpoint.list_incidents

List Microsoft Defender for Endpoint incidents with optional OData filtering.

Reference: https://learn.microsoft.com/en-us/defender-endpoint/api/exposed-apis-list

Secrets

Optional secrets:

• microsoft_defender_endpoint_oauth: OAuth token MICROSOFT_DEFENDER_ENDPOINT_USER_TOKEN.
• microsoft_defender_endpoint_oauth: OAuth token MICROSOFT_DEFENDER_ENDPOINT_SERVICE_TOKEN.

Input fields

base_url · string

Base URL for the Microsoft Defender for Endpoint API.

Default: "https://api.securitycenter.microsoft.com".

Allowed values: https://api.securitycenter.microsoft.com, https://api-gcc.securitycenter.microsoft.us, https://api-gov.securitycenter.microsoft.us.

filter · string | null

OData filter expression to apply (for example, status eq ‘Active’ and severity eq ‘High’).

Default: null.

order_by · string | null

OData order by clause (for example, lastUpdateTime desc).

Default: null.

top · integer | null

Maximum number of incidents to return (maps to $top OData query option).

Default: null.

List indicators

Action ID: tools.microsoft_defender_endpoint.list_indicators

Retrieve Microsoft Defender for Endpoint indicators with optional OData filters.

Reference: https://learn.microsoft.com/en-us/defender-endpoint/api/get-ti-indicators-collection

Secrets

Optional secrets:

• microsoft_defender_endpoint_oauth: OAuth token MICROSOFT_DEFENDER_ENDPOINT_USER_TOKEN.
• microsoft_defender_endpoint_oauth: OAuth token MICROSOFT_DEFENDER_ENDPOINT_SERVICE_TOKEN.

Input fields

base_url · string

Base URL for the Microsoft Defender for Endpoint API.

Default: "https://api.securitycenter.microsoft.com".

Allowed values: https://api.securitycenter.microsoft.com, https://api-gcc.securitycenter.microsoft.us, https://api-gov.securitycenter.microsoft.us.

filter · string | null

OData filter expression to apply (for example, action eq ‘AlertAndBlock’).

Default: null.

order_by · string | null

OData order by clause (for example, creationTimeDateTimeUtc desc).

Default: null.

skip_token · string | null

OData skip token to continue pagination.

Default: null.

top · integer | null

Maximum number of indicators to return (maps to $top).

Default: null.

List machine actions

Action ID: tools.microsoft_defender_endpoint.list_machine_actions

List Microsoft Defender for Endpoint machine actions with optional filters.

Reference: https://learn.microsoft.com/en-us/defender-endpoint/api/get-machineactions-collection

Secrets

Optional secrets:

• microsoft_defender_endpoint_oauth: OAuth token MICROSOFT_DEFENDER_ENDPOINT_USER_TOKEN.
• microsoft_defender_endpoint_oauth: OAuth token MICROSOFT_DEFENDER_ENDPOINT_SERVICE_TOKEN.

Input fields

base_url · string

Base URL for the Microsoft Defender for Endpoint API.

Default: "https://api.securitycenter.microsoft.com".

Allowed values: https://api.securitycenter.microsoft.com, https://api-gcc.securitycenter.microsoft.us, https://api-gov.securitycenter.microsoft.us.

filter · string | null

OData filter expression to apply (for example, machineId eq ‘deviceId’).

Default: null.

order_by · string | null

OData order by clause (for example, creationDateTimeUtc desc).

Default: null.

skip_token · string | null

OData skip token to continue pagination.

Default: null.

top · integer | null

Maximum number of machine actions to return (maps to $top).

Default: null.

List machines

Action ID: tools.microsoft_defender_endpoint.list_machines

List Microsoft Defender for Endpoint machines with optional filters.

Reference: https://learn.microsoft.com/en-us/defender-endpoint/api/get-machines

Secrets

Optional secrets:

• microsoft_defender_endpoint_oauth: OAuth token MICROSOFT_DEFENDER_ENDPOINT_USER_TOKEN.
• microsoft_defender_endpoint_oauth: OAuth token MICROSOFT_DEFENDER_ENDPOINT_SERVICE_TOKEN.

Input fields

base_url · string

Base URL for the Microsoft Defender for Endpoint API.

Default: "https://api.securitycenter.microsoft.com".

Allowed values: https://api.securitycenter.microsoft.com, https://api-gcc.securitycenter.microsoft.us, https://api-gov.securitycenter.microsoft.us.

filter · string | null

OData filter expression to apply (for example, healthStatus eq ‘Active’).

Default: null.

order_by · string | null

OData order by clause (for example, lastSeen desc).

Default: null.

skip_token · string | null

OData skip token to continue pagination.

Default: null.

top · integer | null

Maximum number of machines to return (maps to $top).

Default: null.

Put file on machine

Action ID: tools.microsoft_defender_endpoint.put_file_on_machine

Copy a file from the Live Response library onto a device.

Reference: https://learn.microsoft.com/en-us/defender-endpoint/api/run-live-response

Secrets

Optional secrets:

• microsoft_defender_endpoint_oauth: OAuth token MICROSOFT_DEFENDER_ENDPOINT_USER_TOKEN.
• microsoft_defender_endpoint_oauth: OAuth token MICROSOFT_DEFENDER_ENDPOINT_SERVICE_TOKEN.

Input fields

file_name · string · required

Name of the file in the Live Response library to push to the device.

machine_id · string · required

Machine ID to receive the file.

base_url · string

Base URL for the Microsoft Defender for Endpoint API.

Default: "https://api.securitycenter.microsoft.com".

Allowed values: https://api.securitycenter.microsoft.com, https://api-gcc.securitycenter.microsoft.us, https://api-gov.securitycenter.microsoft.us.

comment · string | null

Comment describing why the file was delivered.

Default: null.

Release machine from isolation

Action ID: tools.microsoft_defender_endpoint.unisolate_machine

Release a device from network isolation in Microsoft Defender for Endpoint.

Reference: https://learn.microsoft.com/en-us/defender-endpoint/api/unisolate-machine

Secrets

Optional secrets:

• microsoft_defender_endpoint_oauth: OAuth token MICROSOFT_DEFENDER_ENDPOINT_USER_TOKEN.
• microsoft_defender_endpoint_oauth: OAuth token MICROSOFT_DEFENDER_ENDPOINT_SERVICE_TOKEN.

Input fields

comment · string · required

Comment describing why the device is being released.

machine_id · string · required

Machine ID to release from isolation.

base_url · string

Base URL for the Microsoft Defender for Endpoint API.

Default: "https://api.securitycenter.microsoft.com".

Allowed values: https://api.securitycenter.microsoft.com, https://api-gcc.securitycenter.microsoft.us, https://api-gov.securitycenter.microsoft.us.

Run advanced hunting query

Action ID: tools.microsoft_defender_endpoint.run_advanced_hunting_query

Execute a Microsoft Defender advanced hunting query across Defender for Endpoint data.

Reference: https://learn.microsoft.com/en-us/defender-endpoint/api/run-advanced-query-api

Secrets

Optional secrets:

• microsoft_defender_endpoint_oauth: OAuth token MICROSOFT_DEFENDER_ENDPOINT_USER_TOKEN.
• microsoft_defender_endpoint_oauth: OAuth token MICROSOFT_DEFENDER_ENDPOINT_SERVICE_TOKEN.

Input fields

query · string · required

Kusto Query Language (KQL) query to run (for example, “DeviceNetworkEvents | take 25”).

advanced_query_run_settings · object | null

Optional AdvancedQueryRunSettings object (for example, {“TimeoutInSeconds”: 120}).

Default: null.

base_url · string

Base URL for the Microsoft Defender for Endpoint API.

Default: "https://api.securitycenter.microsoft.com".

Allowed values: https://api.securitycenter.microsoft.com, https://api-gcc.securitycenter.microsoft.us, https://api-gov.securitycenter.microsoft.us.

Run antivirus scan

Action ID: tools.microsoft_defender_endpoint.run_antivirus_scan

Trigger a Microsoft Defender Antivirus scan on a device.

Reference: https://learn.microsoft.com/en-us/defender-endpoint/api/run-av-scan

Secrets

Optional secrets:

• microsoft_defender_endpoint_oauth: OAuth token MICROSOFT_DEFENDER_ENDPOINT_USER_TOKEN.
• microsoft_defender_endpoint_oauth: OAuth token MICROSOFT_DEFENDER_ENDPOINT_SERVICE_TOKEN.

Input fields

comment · string · required

Comment describing why the scan was requested.

machine_id · string · required

Machine ID to scan.

base_url · string

Base URL for the Microsoft Defender for Endpoint API.

Default: "https://api.securitycenter.microsoft.com".

Allowed values: https://api.securitycenter.microsoft.com, https://api-gcc.securitycenter.microsoft.us, https://api-gov.securitycenter.microsoft.us.

scan_type · string

Type of antivirus scan to perform.

Default: "Quick".

Allowed values: Quick, Full.

Run live response

Action ID: tools.microsoft_defender_endpoint.run_live_response

Run a sequence of Live Response commands on a device in Microsoft Defender for Endpoint.

Reference: https://learn.microsoft.com/en-us/defender-endpoint/api/run-live-response

Secrets

Optional secrets:

• microsoft_defender_endpoint_oauth: OAuth token MICROSOFT_DEFENDER_ENDPOINT_USER_TOKEN.
• microsoft_defender_endpoint_oauth: OAuth token MICROSOFT_DEFENDER_ENDPOINT_SERVICE_TOKEN.

Input fields

commands · array[object] · required

Ordered list of Live Response commands (each object requires at least a ‘type’ key and optional ‘params’ list of key/value objects).

machine_id · string · required

Machine ID to target with Live Response commands.

base_url · string

Base URL for the Microsoft Defender for Endpoint API.

Default: "https://api.securitycenter.microsoft.com".

Allowed values: https://api.securitycenter.microsoft.com, https://api-gcc.securitycenter.microsoft.us, https://api-gov.securitycenter.microsoft.us.

comment · string | null

Comment describing the purpose of the Live Response session.

Default: null.

Run script on machine

Action ID: tools.microsoft_defender_endpoint.run_script_on_machine

Execute a script from the Live Response library on a device.

Reference: https://learn.microsoft.com/en-us/defender-endpoint/api/run-live-response

Secrets

Optional secrets:

• microsoft_defender_endpoint_oauth: OAuth token MICROSOFT_DEFENDER_ENDPOINT_USER_TOKEN.
• microsoft_defender_endpoint_oauth: OAuth token MICROSOFT_DEFENDER_ENDPOINT_SERVICE_TOKEN.

Input fields

machine_id · string · required

Machine ID to target with the script.

script_name · string · required

Name of the uploaded Live Response script to run.

base_url · string

Base URL for the Microsoft Defender for Endpoint API.

Default: "https://api.securitycenter.microsoft.com".

Allowed values: https://api.securitycenter.microsoft.com, https://api-gcc.securitycenter.microsoft.us, https://api-gov.securitycenter.microsoft.us.

comment · string | null

Comment describing the Live Response action.

Default: null.

script_arguments · string | null

Optional arguments passed to the script (quoted as a single string).

Default: null.

Update alert

Action ID: tools.microsoft_defender_endpoint.update_alert

Update status, ownership, or classification details for a Microsoft Defender for Endpoint alert.

Reference: https://learn.microsoft.com/en-us/defender-endpoint/api/update-alert

Secrets

Optional secrets:

• microsoft_defender_endpoint_oauth: OAuth token MICROSOFT_DEFENDER_ENDPOINT_USER_TOKEN.
• microsoft_defender_endpoint_oauth: OAuth token MICROSOFT_DEFENDER_ENDPOINT_SERVICE_TOKEN.

Input fields

alert_id · string · required

Alert ID to update.

assigned_to · string | null

User principal name (UPN) or email address to assign the alert to.

Default: null.

base_url · string

Base URL for the Microsoft Defender for Endpoint API.

Default: "https://api.securitycenter.microsoft.com".

Allowed values: https://api.securitycenter.microsoft.com, https://api-gcc.securitycenter.microsoft.us, https://api-gov.securitycenter.microsoft.us.

classification · string | null

Updated alert classification.

Default: null.

comment · string | null

Comment to append to the alert.

Default: null.

determination · string | null

Determination that provides additional context for the classification (for example, Malware, SecurityTesting, NotMalicious).

Default: null.

status · string | null

Updated alert status.

Default: null.

Update incident

Action ID: tools.microsoft_defender_endpoint.update_incident

Update classification, determination, or assignment details for a Microsoft Defender for Endpoint incident.

Reference: https://learn.microsoft.com/en-us/defender-endpoint/api/exposed-apis-list

Secrets

Optional secrets:

• microsoft_defender_endpoint_oauth: OAuth token MICROSOFT_DEFENDER_ENDPOINT_USER_TOKEN.
• microsoft_defender_endpoint_oauth: OAuth token MICROSOFT_DEFENDER_ENDPOINT_SERVICE_TOKEN.

Input fields

incident_id · string · required

Incident ID to update.

assigned_to · string | null

User principal name (UPN) or email to assign the incident to.

Default: null.

base_url · string

Base URL for the Microsoft Defender for Endpoint API.

Default: "https://api.securitycenter.microsoft.com".

Allowed values: https://api.securitycenter.microsoft.com, https://api-gcc.securitycenter.microsoft.us, https://api-gov.securitycenter.microsoft.us.

classification · string | null

Classification to apply to the incident (for example, Unknown, TruePositive, FalsePositive, InformationalExpectedActivity).

Default: null.

comment · string | null

Comment to add to the incident history.

Default: null.

determination · string | null

Determination that provides additional context for the classification (for example, Unknown, Malware, SecurityTesting).

Default: null.

status · string | null

Incident status (for example, Active, Resolved, InProgress, Redirected).

Default: null.

tags · array[string] | null

Tags to associate with the incident.

Default: null.