Microsoft Defender XDR Trigger

Microsoft Defender XDR Trigger

Certified

Trigger on new or updated Microsoft Defender XDR alerts or incidents

Polls /security/alerts_v2 or /security/incidents for items whose lastUpdateDateTime (createdDateTime with on: CREATE) is at or after the last one seen minus lookback, and starts one execution with the items not fired yet, stored as an ION file in internal storage. Seen items are kept in the trigger state by id and lastUpdateDateTime, so items sharing a timestamp or indexed late are not missed and are not fired twice. On the first poll no execution is started, so existing items are not replayed. Requires the Microsoft Graph application permission SecurityAlert.Read.All or SecurityIncident.Read.All.

yaml
type: io.kestra.plugin.microsoft365.defender.Trigger

Start a flow on every new or updated high-severity incident

yaml
id: defender_on_new_incident
namespace: company.security

triggers:
  - id: on_incident
    type: io.kestra.plugin.microsoft365.defender.Trigger
    interval: PT1M
    resource: INCIDENTS
    tenantId: "{{ secret('AZURE_TENANT_ID') }}"
    clientId: "{{ secret('AZURE_CLIENT_ID') }}"
    clientSecret: "{{ secret('AZURE_CLIENT_SECRET') }}"
    severity: HIGH

tasks:
  - id: each_incident
    type: io.kestra.plugin.core.flow.ForEachItem
    items: "{{ trigger.uri }}"
    batch:
      rows: 1
    namespace: company.security
    flowId: triage_incident
    inputs:
      incident_file: "{{ taskrun.items }}"

Start a flow on new Defender for Endpoint alerts only

yaml
id: defender_on_endpoint_alert
namespace: company.security

triggers:
  - id: on_alert
    type: io.kestra.plugin.microsoft365.defender.Trigger
    interval: PT5M
    on: CREATE
    tenantId: "{{ secret('AZURE_TENANT_ID') }}"
    clientId: "{{ secret('AZURE_CLIENT_ID') }}"
    clientSecret: "{{ secret('AZURE_CLIENT_SECRET') }}"
    filter: "serviceSource eq 'microsoftDefenderForEndpoint'"

tasks:
  - id: log
    type: io.kestra.plugin.core.log.Log
    message: "{{ trigger.count }} new alerts stored in {{ trigger.uri }}"
Installation

Our standard Docker images already include this plugin. If you use a -slim image or another setup, install it with the following command:

kestractl plugins get io.kestra.plugin:plugin-microsoft365 --compatible-for $KESTRA_VERSION

For kestractl, use your Kestra version with --compatible-for, or specify an exact plugin version.

Properties
Defaultfalse

Specifies whether a trigger is allowed to start a new execution even if a previous run is still in progress.

Client ID

Client ID of the Azure service principal. If you don't have a service principal, refer to create a service principal with Azure CLI.

Client Secret

Service principal client secret. Use this for Client Secret authentication. Provide clientId, tenantId, and clientSecret. Either clientSecret OR pemCertificate must be provided, not both.

OData filter

Raw OData $filter expression added to the lastUpdateDateTime filter with and, e.g. serviceSource eq 'microsoftDefenderForEndpoint'.

DefaultPT1M
Formatduration

Polling interval

ISO-8601 duration between two polls. Default PT1M.

DefaultPT5M

Lookback

How far before the latest timestamp seen each poll reads again, to catch items indexed late. Default PT5M. Must be zero or positive and shorter than stateTtl. Items already fired are skipped using the trigger state.

DefaultCREATE_OR_UPDATE
Possible Values
CREATEUPDATECREATE_OR_UPDATE

Trigger event type

CREATE fires for items not seen before and polls on createdDateTime, so an item forgotten after stateTtl does not fire again when it changes. UPDATE fires only for items the trigger has already seen, with a new lastUpdateDateTime, so changes to items that existed before the first poll or were forgotten after stateTtl do not fire. CREATE_OR_UPDATE (default) fires for both.

PEM Certificate

Alternative authentication method using certificate-based authentication.
Use this for Client Certificate authentication. Provide clientId, tenantId, and pemCertificate.
Either clientSecret OR pemCertificate must be provided, not both.

DefaultALERTS
Possible Values
ALERTSINCIDENTS

Resource to watch

ALERTS (default) or INCIDENTS.

Possible Values
INFORMATIONALLOWMEDIUMHIGH

Severity

Only fire for items with this severity. Allowed values: INFORMATIONAL, LOW, MEDIUM, HIGH.

State key

Key of the trigger state in the namespace KV store. Defaults to <namespace>_<flowId>_<triggerId>.

DefaultPT168H

State TTL

How long a seen item is remembered after it was last read. Default P7D. Must be positive and longer than lookback. Items still in the lookback window are kept and refreshed on every poll. An item that changes after it was forgotten is seen as new, so with UPDATE that change does not fire. CREATE and CREATE_OR_UPDATE are not affected.

SubTypestring
Possible Values
CREATEDSUBMITTEDRUNNINGPAUSEDRESTARTEDKILLINGSUCCESSWARNINGFAILEDKILLEDCANCELLEDQUEUEDRETRYINGRETRIEDSKIPPEDBREAKPOINTRESUBMITTED

List of execution states after which a trigger should be stopped (a.k.a. disabled).

Tenant ID

Defaulttrue

A condition that determines whether the trigger should run.

A Pebble expression evaluated at trigger time. The trigger fires only when the expression evaluates to a truthy value (true, a non-empty string, a non-zero number). Use this to gate trigger execution on dynamic runtime values such as execution labels, flow variables, or environment conditions.

Default0

Number of items

Formaturi

URI of the ION file with the new or updated alerts or incidents

Objects with the Microsoft Graph field names, one per line.