Incidents - Create Or Update

Reference

Service:: Sentinel

API Version:: 2023-11-01

Creates or updates an incident.

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.OperationalInsights/workspaces/{workspaceName}/providers/Microsoft.SecurityInsights/incidents/{incidentId}?api-version=2023-11-01

URI Parameters

Name	In	Required	Type	Description
incidentId	path	True	string	Incident ID
resourceGroupName	path	True	string	The name of the resource group. The name is case insensitive.
subscriptionId	path	True	string	The ID of the target subscription.
workspaceName	path	True	string	The name of the workspace. Regex pattern: `^[A-Za-z0-9][A-Za-z0-9-]+[A-Za-z0-9]$`
api-version	query	True	string	The API version to use for this operation.

Request Body

Name	Required	Type	Description
properties.severity	True	IncidentSeverity	The severity of the incident
properties.status	True	IncidentStatus	The status of the incident
properties.title	True	string	The title of the incident
etag		string	Etag of the azure resource
properties.classification		IncidentClassification	The reason the incident was closed
properties.classificationComment		string	Describes the reason the incident was closed
properties.classificationReason		IncidentClassificationReason	The classification reason the incident was closed with
properties.description		string	The description of the incident
properties.firstActivityTimeUtc		string	The time of the first activity in the incident
properties.labels		IncidentLabel[]	List of labels relevant to this incident
properties.lastActivityTimeUtc		string	The time of the last activity in the incident
properties.owner		IncidentOwnerInfo	Describes a user that the incident is assigned to

Responses

Name	Type	Description
200 OK	Incident	OK, Operation successfully completed
201 Created	Incident	Created
Other Status Codes	CloudError	Error response describing why the operation failed.

Security

azure_auth

Azure Active Directory OAuth2 Flow

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

Name	Description
user_impersonation	impersonate your user account

Examples

Creates or updates an incident.

Sample request

HTTP

PUT https://management.azure.com/subscriptions/d0cfe6b2-9ac0-4464-9919-dccaee2e48c0/resourceGroups/myRg/providers/Microsoft.OperationalInsights/workspaces/myWorkspace/providers/Microsoft.SecurityInsights/incidents/73e01a99-5cd7-4139-a149-9f2736ff2ab5?api-version=2023-11-01

{
  "etag": "\"0300bf09-0000-0000-0000-5c37296e0000\"",
  "properties": {
    "lastActivityTimeUtc": "2019-01-01T13:05:30Z",
    "firstActivityTimeUtc": "2019-01-01T13:00:30Z",
    "description": "This is a demo incident",
    "title": "My incident",
    "owner": {
      "objectId": "2046feea-040d-4a46-9e2b-91c2941bfa70"
    },
    "severity": "High",
    "classification": "FalsePositive",
    "classificationComment": "Not a malicious activity",
    "classificationReason": "IncorrectAlertLogic",
    "status": "Closed"
  }
}

Sample response

Status code:: 200

{
  "id": "/subscriptions/d0cfe6b2-9ac0-4464-9919-dccaee2e48c0/resourceGroups/myRg/providers/Microsoft.OperationalInsights/workspaces/myWorkspace/providers/Microsoft.SecurityInsights/incidents/73e01a99-5cd7-4139-a149-9f2736ff2ab5",
  "name": "73e01a99-5cd7-4139-a149-9f2736ff2ab5",
  "type": "Microsoft.SecurityInsights/incidents",
  "etag": "\"0300bf09-0000-0000-0000-5c37296e0001\"",
  "properties": {
    "lastModifiedTimeUtc": "2019-01-01T13:15:30Z",
    "createdTimeUtc": "2019-01-01T13:15:30Z",
    "lastActivityTimeUtc": "2019-01-01T13:05:30Z",
    "firstActivityTimeUtc": "2019-01-01T13:00:30Z",
    "description": "This is a demo incident",
    "title": "My incident",
    "owner": {
      "objectId": "2046feea-040d-4a46-9e2b-91c2941bfa70",
      "email": "john.doe@contoso.com",
      "userPrincipalName": "john@contoso.com",
      "assignedTo": "john doe"
    },
    "severity": "High",
    "classification": "FalsePositive",
    "classificationComment": "Not a malicious activity",
    "classificationReason": "IncorrectAlertLogic",
    "status": "Closed",
    "incidentUrl": "https://portal.azure.com/#asset/Microsoft_Azure_Security_Insights/Incident/subscriptions/d0cfe6b2-9ac0-4464-9919-dccaee2e48c0/resourceGroups/myRg/providers/Microsoft.OperationalInsights/workspaces/myWorkspace/providers/Microsoft.SecurityInsights/incidents/73e01a99-5cd7-4139-a149-9f2736ff2ab5",
    "incidentNumber": 3177,
    "labels": [],
    "providerName": "Azure Sentinel",
    "providerIncidentId": "3177",
    "relatedAnalyticRuleIds": [],
    "additionalData": {
      "alertsCount": 0,
      "bookmarksCount": 0,
      "commentsCount": 3,
      "alertProductNames": [],
      "tactics": []
    }
  }
}

Status code:: 201

{
  "id": "/subscriptions/d0cfe6b2-9ac0-4464-9919-dccaee2e48c0/resourceGroups/myRg/providers/Microsoft.OperationalInsights/workspaces/myWorkspace/providers/Microsoft.SecurityInsights/incidents/73e01a99-5cd7-4139-a149-9f2736ff2ab5",
  "name": "73e01a99-5cd7-4139-a149-9f2736ff2ab5",
  "type": "Microsoft.SecurityInsights/incidents",
  "etag": "\"0300bf09-0000-0000-0000-5c37296e0001\"",
  "properties": {
    "lastModifiedTimeUtc": "2019-01-01T13:15:30Z",
    "createdTimeUtc": "2019-01-01T13:15:30Z",
    "lastActivityTimeUtc": "2019-01-01T13:05:30Z",
    "firstActivityTimeUtc": "2019-01-01T13:00:30Z",
    "description": "This is a demo incident",
    "title": "My incident",
    "owner": {
      "objectId": "2046feea-040d-4a46-9e2b-91c2941bfa70",
      "email": "john.doe@contoso.com",
      "userPrincipalName": "john@contoso.com",
      "assignedTo": "john doe"
    },
    "severity": "High",
    "classification": "FalsePositive",
    "classificationComment": "Not a malicious activity",
    "classificationReason": "IncorrectAlertLogic",
    "status": "Closed",
    "incidentUrl": "https://portal.azure.com/#asset/Microsoft_Azure_Security_Insights/Incident/subscriptions/d0cfe6b2-9ac0-4464-9919-dccaee2e48c0/resourceGroups/myRg/providers/Microsoft.OperationalInsights/workspaces/myWorkspace/providers/Microsoft.SecurityInsights/incidents/73e01a99-5cd7-4139-a149-9f2736ff2ab5",
    "incidentNumber": 3177,
    "labels": [],
    "providerName": "Azure Sentinel",
    "providerIncidentId": "3177",
    "relatedAnalyticRuleIds": [],
    "additionalData": {
      "alertsCount": 0,
      "bookmarksCount": 0,
      "commentsCount": 3,
      "alertProductNames": [],
      "tactics": []
    }
  }
}

Definitions

Name	Description
AttackTactic	The severity for alerts created by this alert rule.
CloudError	Error response structure.
CloudErrorBody	Error details.
createdByType	The type of identity that created the resource.
Incident	Represents an incident in Azure Security Insights.
IncidentAdditionalData	Incident additional data property bag.
IncidentClassification	The reason the incident was closed
IncidentClassificationReason	The classification reason the incident was closed with
IncidentLabel	Represents an incident label
IncidentLabelType	The type of the label
IncidentOwnerInfo	Information on the user an incident is assigned to
IncidentSeverity	The severity of the incident
IncidentStatus	The status of the incident
OwnerType	The type of the owner the incident is assigned to.
systemData	Metadata pertaining to creation and last modification of the resource.

AttackTactic

The severity for alerts created by this alert rule.

Name	Type	Description
Collection	string
CommandAndControl	string
CredentialAccess	string
DefenseEvasion	string
Discovery	string
Execution	string
Exfiltration	string
Impact	string
ImpairProcessControl	string
InhibitResponseFunction	string
InitialAccess	string
LateralMovement	string
Persistence	string
PreAttack	string
PrivilegeEscalation	string
Reconnaissance	string
ResourceDevelopment	string

CloudError

Error response structure.

Name	Type	Description
error	CloudErrorBody	Error data

CloudErrorBody

Error details.

Name	Type	Description
code	string	An identifier for the error. Codes are invariant and are intended to be consumed programmatically.
message	string	A message describing the error, intended to be suitable for display in a user interface.

createdByType

The type of identity that created the resource.

Name	Type	Description
Application	string
Key	string
ManagedIdentity	string
User	string

Incident

Represents an incident in Azure Security Insights.

Name	Type	Description
etag	string	Etag of the azure resource
id	string	Fully qualified resource ID for the resource. E.g. "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}"
name	string	The name of the resource
properties.additionalData	IncidentAdditionalData	Additional data on the incident
properties.classification	IncidentClassification	The reason the incident was closed
properties.classificationComment	string	Describes the reason the incident was closed
properties.classificationReason	IncidentClassificationReason	The classification reason the incident was closed with
properties.createdTimeUtc	string	The time the incident was created
properties.description	string	The description of the incident
properties.firstActivityTimeUtc	string	The time of the first activity in the incident
properties.incidentNumber	integer	A sequential number
properties.incidentUrl	string	The deep-link url to the incident in Azure portal
properties.labels	IncidentLabel[]	List of labels relevant to this incident
properties.lastActivityTimeUtc	string	The time of the last activity in the incident
properties.lastModifiedTimeUtc	string	The last time the incident was updated
properties.owner	IncidentOwnerInfo	Describes a user that the incident is assigned to
properties.providerIncidentId	string	The incident ID assigned by the incident provider
properties.providerName	string	The name of the source provider that generated the incident
properties.relatedAnalyticRuleIds	string[]	List of resource ids of Analytic rules related to the incident
properties.severity	IncidentSeverity	The severity of the incident
properties.status	IncidentStatus	The status of the incident
properties.title	string	The title of the incident
systemData	systemData	Azure Resource Manager metadata containing createdBy and modifiedBy information.
type	string	The type of the resource. E.g. "Microsoft.Compute/virtualMachines" or "Microsoft.Storage/storageAccounts"

IncidentAdditionalData

Incident additional data property bag.

Name	Type	Description
alertProductNames	string[]	List of product names of alerts in the incident
alertsCount	integer	The number of alerts in the incident
bookmarksCount	integer	The number of bookmarks in the incident
commentsCount	integer	The number of comments in the incident
providerIncidentUrl	string	The provider incident url to the incident in Microsoft 365 Defender portal
tactics	AttackTactic[]	The tactics associated with incident

IncidentClassification

The reason the incident was closed

Name	Type	Description
BenignPositive	string	Incident was benign positive
FalsePositive	string	Incident was false positive
TruePositive	string	Incident was true positive
Undetermined	string	Incident classification was undetermined

IncidentClassificationReason

The classification reason the incident was closed with

Name	Type	Description
InaccurateData	string	Classification reason was inaccurate data
IncorrectAlertLogic	string	Classification reason was incorrect alert logic
SuspiciousActivity	string	Classification reason was suspicious activity
SuspiciousButExpected	string	Classification reason was suspicious but expected

IncidentLabel

Represents an incident label

Name	Type	Description
labelName	string	The name of the label
labelType	IncidentLabelType	The type of the label

IncidentLabelType

The type of the label

Name	Type	Description
AutoAssigned	string	Label automatically created by the system
User	string	Label manually created by a user

IncidentOwnerInfo

Information on the user an incident is assigned to

Name	Type	Description
assignedTo	string	The name of the user the incident is assigned to.
email	string	The email of the user the incident is assigned to.
objectId	string	The object id of the user the incident is assigned to.
ownerType	OwnerType	The type of the owner the incident is assigned to.
userPrincipalName	string	The user principal name of the user the incident is assigned to.

IncidentSeverity

The severity of the incident

Name	Type	Description
High	string	High severity
Informational	string	Informational severity
Low	string	Low severity
Medium	string	Medium severity

IncidentStatus

The status of the incident

Name	Type	Description
Active	string	An active incident which is being handled
Closed	string	A non-active incident
New	string	An active incident which isn't being handled currently

OwnerType

The type of the owner the incident is assigned to.

Name	Type	Description
Group	string	The incident owner type is an AAD group
Unknown	string	The incident owner type is unknown
User	string	The incident owner type is an AAD user

systemData

Metadata pertaining to creation and last modification of the resource.

Name	Type	Description
createdAt	string	The timestamp of resource creation (UTC).
createdBy	string	The identity that created the resource.
createdByType	createdByType	The type of identity that created the resource.
lastModifiedAt	string	The timestamp of resource last modification (UTC)
lastModifiedBy	string	The identity that last modified the resource.
lastModifiedByType	createdByType	The type of identity that last modified the resource.

Share via

Incidents - Create Or Update

URI Parameters

Request Body

Responses

Security

azure_auth

Scopes

Examples

Creates or updates an incident.

Sample request

Sample response

Definitions

AttackTactic

CloudError

CloudErrorBody

createdByType

Incident

IncidentAdditionalData

IncidentClassification

IncidentClassificationReason

IncidentLabel

IncidentLabelType

IncidentOwnerInfo

IncidentSeverity

IncidentStatus

OwnerType

systemData

Additional resources