Microsoft Graph Update

Security

Synopsis

Updates existing alerts or incidents in Microsoft Defender for Endpoint and Microsoft Sentinel using the Microsoft Graph Security API, enabling automated incident response workflows and security orchestration through programmatic status changes, assignments, and metadata updates.

Schema

- msgraph_update:
    id: <string>
    tenant_id: <string>
    client_id: <string>
    client_secret: <string>
    type: <string>
    status: <string>
    classification: <string>
    determination: <string>
    assigned_to: <string>
    custom_details: <map>
    custom_tags: <array>
    display_name: <string>
    incident_description: <string>
    severity: <string>
    resolving_comment: <string>
    summary: <string>
    description: <text>
    if: <script>
    disabled: <boolean>
    ignore_failure: <boolean>
    ignore_missing: <boolean>
    on_failure: <processor[]>
    on_success: <processor[]>
    tag: <string>

Configuration

Field	Required	Default	Description
`id`	Y		Alert or incident ID to update
`tenant_id`	N	`${GRAPH_TENANT_ID}`	Azure AD tenant ID
`client_id`	N	`${GRAPH_CLIENT_ID}`	Application (client) ID from Azure AD app registration
`client_secret`	N	`${GRAPH_CLIENT_SECRET}`	Client secret for authentication
`type`	N	`alert`	Resource type to update: `alert` or `incident`
`status`	N		Alert status (`new`, `inProgress`, `resolved`) or incident status (`active`, `resolved`, `redirected`)
`classification`	N		Classification: `unknown`, `falsePositive`, `truePositive`, `informationalExpectedActivity`
`determination`	N		Alert determination: `malware`, `phishing`, `unwantedSoftware`, `multiStagedAttack`, etc.
`assigned_to`	N		User principal name to assign the alert or incident (e.g., `analyst@contoso.com`)
`custom_details`	N		Custom key-value pairs for alerts (investigator notes, ticket numbers, etc.)
`custom_tags`	N		Custom tags array for incidents (department, priority, category)
`display_name`	N		Incident display name (incidents only)
`incident_description`	N		Detailed incident description (incidents only)
`severity`	N		Incident severity: `unknown`, `informational`, `low`, `medium`, `high` (incidents only)
`resolving_comment`	N		Comment added when resolving incident (incidents only)
`summary`	N		Incident summary (incidents only)
`description`	N		Explanatory note
`if`	N		Condition to run
`disabled`	N	`false`	Disable this processor
`ignore_failure`	N	`false`	See Handling Failures
`ignore_missing`	N	`false`	Continue if resource does not exist
`on_failure`	N		See Handling Failures
`on_success`	N		See Handling Success
`tag`	N		Identifier

Details

The msgraph_update processor updates existing security alerts and incidents in Microsoft Defender for Endpoint and Microsoft Sentinel through the Microsoft Graph Security API, enabling automated incident response workflows and security orchestration.

Authentication: Uses OAuth 2.0 client credentials flow with Azure AD. The processor automatically obtains and caches access tokens for performance. Ensure your Azure AD application has SecurityIncident.ReadWrite.All API permissions for Microsoft Graph.

Resource Types: The processor supports two resource types controlled by the type field:

alert: Updates alerts in Microsoft Defender for Endpoint via /security/alerts_v2/{id}
incident: Updates incidents in Microsoft Sentinel via /security/incidents/{id}

Alert Updates: For alerts, you can update status, classification, determination, assignments, and custom details. Custom details accept arbitrary key-value pairs for investigation notes, ticket numbers, escalation levels, or other metadata.

Incident Updates: For incidents, you can update status, classification, determination, assignments, severity, display name, description, custom tags, resolving comments, and summary. Custom tags enable categorization by department, priority level, or incident type.

Status Values:

Alert statuses: new, inProgress, resolved
Incident statuses: active, resolved, redirected

Classification Values: Both alerts and incidents support: unknown, falsePositive, truePositive, informationalExpectedActivity

Determination Values: Common values include malware, phishing, unwantedSoftware, multiStagedAttack, securityTesting, lineOfBusinessApplication, confirmedUserActivity

Template Support: All string fields support Go template syntax with event field interpolation using {{{field_name}}} notation. This enables dynamic updates based on pipeline data.

Token Caching: Access tokens are cached to minimize authentication overhead in high-volume processing scenarios. Token refresh is handled automatically.

Error Handling: Use ignore_missing to continue processing when the specified alert or incident ID does not exist. Use ignore_failure to continue on authentication or API errors.

For integration patterns with automated alert creation, see the defender processor documentation.

Examples

Update Alert Status

Updating alert status to in progress and assigning to analyst...

{
  "alert_id": "da637551227677560813_-961444813",
  "analyst_email": "secadmin@contoso.com"
}

- msgraph_update:
    tenant_id: "${GRAPH_TENANT_ID}"
    client_id: "${GRAPH_CLIENT_ID}"
    client_secret: "${GRAPH_CLIENT_SECRET}"
    type: "alert"
    id: "{{{alert_id}}}"
    status: "inProgress"
    assigned_to: "{{{analyst_email}}}"

Alert updated with new status and assignment in Defender portal...

Classify Alert as True Positive

Classifying alert as true positive malware and resolving...

{
  "alert_id": "da637551227677560813_-961444813"
}

- msgraph_update:
    tenant_id: "${GRAPH_TENANT_ID}"
    client_id: "${GRAPH_CLIENT_ID}"
    client_secret: "${GRAPH_CLIENT_SECRET}"
    type: "alert"
    id: "{{{alert_id}}}"
    status: "resolved"
    classification: "truePositive"
    determination: "malware"

Alert marked as resolved with malware classification...

Update Alert with Custom Details

Adding investigation metadata to alert...

{
  "alert_id": "da637551227677560813_-961444813"
}

- msgraph_update:
    tenant_id: "${GRAPH_TENANT_ID}"
    client_id: "${GRAPH_CLIENT_ID}"
    client_secret: "${GRAPH_CLIENT_SECRET}"
    type: "alert"
    id: "{{{alert_id}}}"
    status: "inProgress"
    custom_details:
      investigator: "John Doe"
      ticketNumber: "INC-12345"
      escalationLevel: "2"

Alert updated with custom investigation tracking details...

Resolve Incident with Comment

Resolving incident with classification and resolving comment...

{
  "incident_id": "2972395"
}

- msgraph_update:
    tenant_id: "${GRAPH_TENANT_ID}"
    client_id: "${GRAPH_CLIENT_ID}"
    client_secret: "${GRAPH_CLIENT_SECRET}"
    type: "incident"
    id: "{{{incident_id}}}"
    status: "resolved"
    classification: "truePositive"
    determination: "multiStagedAttack"
    resolving_comment: "Incident investigated and confirmed as false positive. No further action required."

Incident closed with resolution details in Sentinel...

Update Incident Severity and Assignment

Escalating incident severity and reassigning to senior analyst...

{
  "incident_id": "2972395",
  "senior_analyst": "admin@contoso.com"
}

- msgraph_update:
    tenant_id: "${GRAPH_TENANT_ID}"
    client_id: "${GRAPH_CLIENT_ID}"
    client_secret: "${GRAPH_CLIENT_SECRET}"
    type: "incident"
    id: "{{{incident_id}}}"
    severity: "high"
    assigned_to: "{{{senior_analyst}}}"

Incident severity raised to high and ownership transferred...

Update Incident with Custom Tags

Adding departmental and priority tags to incident...

{
  "incident_id": "2972395"
}

- msgraph_update:
    tenant_id: "${GRAPH_TENANT_ID}"
    client_id: "${GRAPH_CLIENT_ID}"
    client_secret: "${GRAPH_CLIENT_SECRET}"
    type: "incident"
    id: "{{{incident_id}}}"
    custom_tags:
      - "Critical"
      - "Finance Department"
      - "Ransomware"
      - "Q4-2024"

Incident tagged for reporting and filtering in Sentinel portal...

Comprehensive Incident Update

Updating all incident fields with detailed information...

{
  "incident_id": "2972395"
}

- msgraph_update:
    tenant_id: "${GRAPH_TENANT_ID}"
    client_id: "${GRAPH_CLIENT_ID}"
    client_secret: "${GRAPH_CLIENT_SECRET}"
    type: "incident"
    id: "{{{incident_id}}}"
    status: "resolved"
    classification: "truePositive"
    determination: "malware"
    assigned_to: "analyst@contoso.com"
    custom_tags:
      - "High Priority"
      - "Ransomware"
      - "Finance"
    display_name: "Updated Incident Title"
    incident_description: "Detailed description of the incident"
    severity: "high"
    resolving_comment: "Incident resolved after investigation"
    summary: "Malware infection contained and removed"

Incident fully updated with complete investigation details...

Dynamic Template Processing

Using templates to populate update fields from event data...

{
  "resource_type": "alert",
  "resource_id": "da637551227677560813_-961444813",
  "new_status": "resolved",
  "analyst_email": "analyst@contoso.com",
  "alert_class": "truePositive",
  "alert_determine": "malware"
}

- msgraph_update:
    tenant_id: "${GRAPH_TENANT_ID}"
    client_id: "${GRAPH_CLIENT_ID}"
    client_secret: "${GRAPH_CLIENT_SECRET}"
    type: "{{{resource_type}}}"
    id: "{{{resource_id}}}"
    status: "{{{new_status}}}"
    assigned_to: "{{{analyst_email}}}"
    classification: "{{{alert_class}}}"
    determination: "{{{alert_determine}}}"

All update fields dynamically populated from pipeline data...

Ignore Missing Resources

Continuing processing when alert does not exist...

{
  "alert_id": "nonexistent_alert_id"
}

- msgraph_update:
    tenant_id: "${GRAPH_TENANT_ID}"
    client_id: "${GRAPH_CLIENT_ID}"
    client_secret: "${GRAPH_CLIENT_SECRET}"
    type: "alert"
    id: "{{{alert_id}}}"
    status: "resolved"
    ignore_missing: true

Processor continues without error when alert ID not found...

Azure AD App Registration

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

Register Application:
- Navigate to Azure Portal > Microsoft Entra ID > App registrations > New registration
- Choose a name and select supported account types
- Register the application
Create Client Secret:
- Go to Certificates & secrets > New client secret
- Add description and expiration
- Copy the secret value (shown only once)
Assign API Permissions:
- Go to API Permissions > Add permission
- Select "Microsoft Graph" > Application permissions
- Add SecurityIncident.ReadWrite.All
- Grant admin consent

Configure Environment Variables:

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

Obtain Resource IDs:
- Alert IDs can be retrieved from Defender for Endpoint alerts API
- Incident IDs can be retrieved from Microsoft Sentinel incidents API
- IDs are also visible in the Azure portal URLs

For detailed setup instructions, see Microsoft Graph Security API Documentation.

Synopsis​

Schema​

Configuration​

Details​

Examples​

Update Alert Status​

Classify Alert as True Positive​

Update Alert with Custom Details​

Resolve Incident with Comment​

Update Incident Severity and Assignment​

Update Incident with Custom Tags​

Comprehensive Incident Update​

Dynamic Template Processing​

Ignore Missing Resources​

Azure AD App Registration​