Skip to main content

Microsoft Defender Update

Security

Synopsis​

Updates existing alerts in Microsoft Defender for Endpoint using the Alerts API, enabling automated alert management including status changes, assignment, classification, determination, and comment updates for centralized incident response workflows.

Schema​

- msdefender_update:
    tenant_id: <string>
    client_id: <string>
    client_secret: <string>
    alert_id: <string>
    status: <string>
    assigned_to: <string>
    classification: <string>
    determination: <string>
    comment: <string>
    description: <text>
    if: <script>
    disabled: <boolean>
    ignore_failure: <boolean>
    ignore_missing: <boolean>
    on_failure: <processor[]>
    on_success: <processor[]>
    tag: <string>

Configuration​

FieldRequiredDefaultDescription
tenant_idN${GRAPH_TENANT_ID}Azure AD tenant ID
client_idN${GRAPH_CLIENT_ID}Application (client) ID from Azure AD app registration
client_secretN${GRAPH_CLIENT_SECRET}Client secret for authentication
alert_idYAlert identifier to update in Defender for Endpoint
statusNAlert status: New, InProgress, or Resolved (case-insensitive)
assigned_toNEmail address of user to assign the alert to
classificationNAlert classification: TruePositive, InformationalExpectedActivity, or FalsePositive
determinationNAlert determination (see valid values below)
commentNComment to add to the alert
descriptionNExplanatory note
ifNCondition to run
disabledNfalseDisable this processor
ignore_failureNfalseSee Handling Failures
ignore_missingNfalseContinue if alert does not exist
on_failureNSee Handling Failures
on_successNSee Handling Success
tagNIdentifier

Details​

The msdefender_update processor modifies existing alerts in Microsoft Defender for Endpoint, enabling automated alert lifecycle management and incident response workflows through the Microsoft Defender API.

Authentication: Uses OAuth 2.0 client credentials flow with Azure AD. The processor automatically obtains and caches access tokens. Ensure your Azure AD application has the necessary API permissions (Alert.ReadWrite.All) for Defender for Endpoint.

Alert ID: The unique identifier of the alert to update. Alert IDs can be obtained from Defender alert creation responses, alert query APIs, or event data from Defender integrations. The processor supports template syntax for dynamic alert ID resolution from event fields.

Status Values: Valid status values are case-insensitive and normalized to proper case:

  • New: Alert is newly created and not yet investigated
  • InProgress: Alert is currently under investigation
  • Resolved: Alert investigation is complete

Classification Values: Alert classification determines the final verdict of investigation:

  • TruePositive: Confirmed security threat requiring action
  • InformationalExpectedActivity: Known benign activity
  • FalsePositive: Incorrectly flagged as a threat

Determination Values: Provides specific categorization of the alert outcome:

True Positive Determinations:

  • MultiStagedAttack: Complex attack with multiple stages
  • MaliciousUserActivity: Malicious actions by user account
  • CompromisedUser: User account compromise detected
  • Malware: Malicious software detection
  • Phishing: Phishing attempt or credential harvesting
  • UnwantedSoftware: Potentially unwanted programs

Informational/Expected Activity Determinations:

  • SecurityTesting: Authorized security testing activity
  • LineOfBusinessApplication: Legitimate business application behavior
  • ConfirmedActivity: Known and approved activity

False Positive Determinations:

  • NotMalicious: Confirmed benign activity
  • InsufficientData: Not enough information to determine

Common Determination:

  • Other: Does not fit predefined categories

Field Requirements: At least one update field (status, assigned_to, classification, determination, or comment) must be provided. The processor will return an error if called with no fields to update.

Token Caching: Access tokens are cached for the duration of their validity period, reducing authentication overhead for multiple alert updates. The processor automatically handles token expiration and renewal.

Template Support: All string fields support Go template syntax with event field interpolation using {{{field_name}}} notation.

For integration patterns with Defender alert workflows, see Microsoft Sentinel.

Examples​

Update Alert Status​

Changing alert status to InProgress...

{
  "alert_id": "121688558380765161_2136280442",
  "new_status": "InProgress"
}
- msdefender_update:
    tenant_id: "${GRAPH_TENANT_ID}"
    client_id: "${GRAPH_CLIENT_ID}"
    client_secret: "${GRAPH_CLIENT_SECRET}"
    alert_id: "{{{alert_id}}}"
    status: "{{{new_status}}}"

Alert status updated in Defender portal...

Assign Alert to Analyst​

Assigning alert to security analyst...

{
  "alert_id": "121688558380765161_2136280442",
  "analyst": "secadmin@contoso.com"
}
- msdefender_update:
    tenant_id: "${GRAPH_TENANT_ID}"
    client_id: "${GRAPH_CLIENT_ID}"
    client_secret: "${GRAPH_CLIENT_SECRET}"
    alert_id: "{{{alert_id}}}"
    assigned_to: "{{{analyst}}}"

Alert assigned to specified analyst account...

Resolve as True Positive​

Resolving alert with classification and determination...

{
  "alert_id": "121688558380765161_2136280442"
}
- msdefender_update:
    tenant_id: "${GRAPH_TENANT_ID}"
    client_id: "${GRAPH_CLIENT_ID}"
    client_secret: "${GRAPH_CLIENT_SECRET}"
    alert_id: "{{{alert_id}}}"
    status: "Resolved"
    classification: "TruePositive"
    determination: "Malware"
    comment: "Investigated and confirmed as malware"

Alert resolved with malware classification...

Resolve as False Positive​

Closing alert as false positive...

{
  "alert_id": "121688558380765161_2136280442"
}
- msdefender_update:
    tenant_id: "${GRAPH_TENANT_ID}"
    client_id: "${GRAPH_CLIENT_ID}"
    client_secret: "${GRAPH_CLIENT_SECRET}"
    alert_id: "{{{alert_id}}}"
    status: "Resolved"
    classification: "FalsePositive"
    determination: "NotMalicious"
    comment: "False positive - legitimate application behavior"

Alert closed with false positive verdict...

Complete Investigation Workflow​

Updating alert with full investigation results...

{
  "alert_id": "121688558380765161_2136280442",
  "new_status": "Resolved",
  "analyst": "secadmin@contoso.com",
  "alert_class": "TruePositive",
  "alert_determ": "CompromisedUser",
  "note": "User account compromised, credentials reset"
}
- msdefender_update:
    tenant_id: "${GRAPH_TENANT_ID}"
    client_id: "${GRAPH_CLIENT_ID}"
    client_secret: "${GRAPH_CLIENT_SECRET}"
    alert_id: "{{{alert_id}}}"
    status: "{{{new_status}}}"
    assigned_to: "{{{analyst}}}"
    classification: "{{{alert_class}}}"
    determination: "{{{alert_determ}}}"
    comment: "{{{note}}}"

Alert fully updated with investigation findings...

Add Investigation Comment​

Adding investigative notes to alert...

{
  "alert_id": "121688558380765161_2136280442",
  "comment": "Escalated to incident response team for further analysis"
}
- msdefender_update:
    tenant_id: "${GRAPH_TENANT_ID}"
    client_id: "${GRAPH_CLIENT_ID}"
    client_secret: "${GRAPH_CLIENT_SECRET}"
    alert_id: "{{{alert_id}}}"
    comment: "{{{comment}}}"

Comment added to alert timeline...

Case-Insensitive Status Update​

Using lowercase status value (automatically normalized)...

{
  "alert_id": "121688558380765161_2136280442",
  "status": "resolved"
}
- msdefender_update:
    tenant_id: "${GRAPH_TENANT_ID}"
    client_id: "${GRAPH_CLIENT_ID}"
    client_secret: "${GRAPH_CLIENT_SECRET}"
    alert_id: "{{{alert_id}}}"
    status: "{{{status}}}"

Status normalized to "Resolved" automatically...

With Error Handling​

Ignoring failures for non-existent alerts...

{
  "alert_id": "nonexistent_alert_id"
}
- msdefender_update:
    tenant_id: "${GRAPH_TENANT_ID}"
    client_id: "${GRAPH_CLIENT_ID}"
    client_secret: "${GRAPH_CLIENT_SECRET}"
    alert_id: "{{{alert_id}}}"
    status: "Resolved"
    ignore_missing: true

Processing continues even if alert doesn't exist...

Azure AD App Registration​

To use the msdefender_update processor, you must register an application in Azure AD with appropriate permissions:

  1. Register Application:

    • Navigate to Azure Portal > Microsoft Entra ID > App registrations > New registration
    • Choose a name and select supported account types
    • Register the application

  2. Create Client Secret:

    • Go to Certificates & secrets > New client secret
    • Add description and expiration
    • Copy the secret value (shown only once)

  3. Assign API Permissions:

    • Go to API Permissions > Add permission
    • Select "APIs my organization uses" > Search for "WindowsDefenderATP"
    • Choose Application permissions > Alert.ReadWrite.All
    • Grant admin consent

  4. Configure Environment Variables:

    export GRAPH_TENANT_ID="your-tenant-id"
    export GRAPH_CLIENT_ID="your-client-id"
    export GRAPH_CLIENT_SECRET="your-client-secret"

  5. Obtain Alert IDs:

    • Alert IDs are returned when creating alerts via the defender processor
    • Or retrieved via the Alerts API query endpoints
    • Available in Defender event data from integrated systems

For detailed setup instructions, see Microsoft Defender for Endpoint API Documentation.