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`). Sent to Microsoft Graph as written — see the note below
`classification`	N		Classification: `unknown`, `falsePositive`, `truePositive`, `informationalExpectedActivity`. Sent as written
`determination`	N		Alert determination: `malware`, `phishing`, `unwantedSoftware`, `multiStagedAttack`, and the other values Graph accepts. Sent as written
`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

warning

This processor runs on the Director only. The Agent binary is built without it, so an Agent-side pipeline that configures it fails at runtime with a not supported error rather than skipping the step. Put it in a pipeline the Director runs — a route pipeline or a target postprocessing pipeline — not in an Agent's preprocessing chain.

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: Eleven fields are template-expanded — type, id, status, classification, determination, assigned_to, display_name, incident_description, severity, resolving_comment and summary. Use {{field_name}} for the escaped value and {{{field_name}}} for the raw one. No other field is expanded.

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.

note

Only type is validated locally. It has to be alert or incident, matched case-insensitively, and anything else fails before a request is made.

status, classification and determination are not checked against the value lists above — they are resolved as templates and sent to Microsoft Graph verbatim. A typo therefore surfaces as an API error from Graph, not as a pipeline validation error, so read the failure text rather than assuming the value was rejected locally.

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​