Microsoft Defender XDR Trigger
Certified
Trigger on new or updated Microsoft Defender XDR alerts or incidents
Microsoft Defender XDR Trigger
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.
type: io.kestra.plugin.microsoft365.defender.TriggerExamples
Start a flow on every new or updated high-severity incident
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
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
allowConcurrent boolean
falseSpecifies whether a trigger is allowed to start a new execution even if a previous run is still in progress.
clientId string
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.
clientSecret string
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.
filter string
OData filter
Raw OData $filter expression added to the lastUpdateDateTime filter with and, e.g. serviceSource eq 'microsoftDefenderForEndpoint'.
interval string
PT1MdurationPolling interval
ISO-8601 duration between two polls. Default PT1M.
lookback string
PT5MLookback
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.
on string
CREATE_OR_UPDATECREATEUPDATECREATE_OR_UPDATETrigger 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.
pemCertificate string
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.
resource string
ALERTSALERTSINCIDENTSResource to watch
ALERTS (default) or INCIDENTS.
severity string
INFORMATIONALLOWMEDIUMHIGHSeverity
Only fire for items with this severity. Allowed values: INFORMATIONAL, LOW, MEDIUM, HIGH.
stateKey string
State key
Key of the trigger state in the namespace KV store. Defaults to <namespace>_<flowId>_<triggerId>.
stateTtl string
PT168HState 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.
stopAfter array
CREATEDSUBMITTEDRUNNINGPAUSEDRESTARTEDKILLINGSUCCESSWARNINGFAILEDKILLEDCANCELLEDQUEUEDRETRYINGRETRIEDSKIPPEDBREAKPOINTRESUBMITTEDList of execution states after which a trigger should be stopped (a.k.a. disabled).
tenantId string
Tenant ID
when string
trueA 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.
Outputs
count integer
0Number of items
uri string
uriURI of the ION file with the new or updated alerts or incidents
Objects with the Microsoft Graph field names, one per line.