Skip to content

Commit 470ccce

Browse files
v-albemiv-albemi
authored
Merge pull request #101929 from memildin/asc-melvyn-alertsschema
First draft of the schema page
2 parents 41652fa + 53b882f commit 470ccce

File tree

6 files changed

+320
-3
lines changed

6 files changed

+320
-3
lines changed

‎articles/security-center/TOC.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,8 @@
6666
href: security-center-alerts-overview.md
6767
- name: Reference list of alerts
6868
href: alerts-reference.md
69+
- name: Alerts schemas
70+
href: alerts-schemas.md
6971
- name: Manage security alerts
7072
href: security-center-managing-and-responding-alerts.md
7173
- name: Manage security incidents

‎articles/security-center/alerts-schemas.md

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
---
2+
title: Schemas for the Azure Security Center alerts
3+
description: This article describes the different schemas used by Azure Security Center for security alerts.
4+
services: security-center
5+
documentationcenter: na
6+
author: memildin
7+
manager: rkarlin
8+
ms.service: security-center
9+
ms.devlang: na
10+
ms.topic: conceptual
11+
ms.tgt_pltfrm: na
12+
ms.workload: na
13+
ms.date: 03/10/2020
14+
ms.author: memildin
15+
16+
---
17+
18+
# Security alerts schemas
19+
20+
Azure Security Center's advanced threat protection mechanisms generate security alerts when they detect threats to your resources.
21+
22+
These alerts are only available to users of the standard tier.
23+
24+
Security alerts can be seen in Azure Security Center's Threat Protection pages. They can also be accessed from:
25+
26+
- [Azure Sentinel](https://docs.microsoft.com/azure/sentinel/)
27+
28+
- [Azure Event Hubs](https://docs.microsoft.com/azure/event-hubs/) using Security Center's [continuous export feature](continuous-export.md) for integrations with third-party SIEMs
29+
30+
- [The REST API](https://docs.microsoft.com/rest/api/securitycenter/) - If you're using the REST API to access alerts, see the [online Alerts API documentation](https://docs.microsoft.com/rest/api/securitycenter/alerts)
31+
32+
- [Log Analytics workspaces](https://docs.microsoft.com/azure/azure-monitor/learn/quick-create-workspace)
33+
34+
If you're using any programmatic methods to consume the alerts, you'll need the correct schema to find the fields that are relevant to you. In addition, when exporting to an Event Hub or when triggering Workflow Automation with generic HTTP connectors, you could use the schemas to properly parse the JSON objects.
35+
36+
>[!IMPORTANT]
37+
> The schema is slightly different for each of these scenarios, so make sure you select the relevant tab below.
38+
39+
40+
## The schemas
41+
42+
43+
### [Workflow automation and continuous export to Event Hub](#tab/schema-continuousexport)
44+
45+
### Sample JSON for alerts sent to Logic Apps, Event Hub, and third-party SIEMs
46+
47+
This is the schema of the alert events passed to:
48+
49+
- Azure Logic App instances that were configured in Security Center's workflow automation
50+
- Azure Event Hub using Security Center's continuous export feature
51+
52+
For more information about the workflow automation feature see [Automate responses to alerts and recommendations](workflow-automation.md).
53+
For more information about continuous export, see [Export alerts and recommendations](continuous-export.md).
54+
55+
[!INCLUDE [Workflow schema](../../includes/security-center-alerts-schema-workflow-automation.md)]
56+
57+
58+
59+
60+
### [Azure Sentinel and Log Analytics workspaces](#tab/schema-sentinel)
61+
62+
The Sentinel Connector gets alerts from Azure Security Center and sends them to the Log Analytics Workspace for Azure Sentinel.
63+
64+
To create a Sentinel case or incident using Security Center alerts, you'll need the schema for those alerts shown below.
65+
66+
For more information about Azure Sentinel, see [the documentation](https://docs.microsoft.com/azure/sentinel/).
67+
68+
[!INCLUDE [Sentinel and workspace schema](../../includes/security-center-alerts-schema-log-analytics-workspace.md)]
69+
70+
71+
72+
73+
### [Azure Activity Log](#tab/schema-activitylog)
74+
75+
Azure Security Center audits generated Security alerts as events in Azure Activity Log.
76+
77+
You can view the security alerts events in Activity Log by searching for the Activate Alert event as shown:
78+
79+
[![Searching the Activity log for the Activate Alert event](media/alerts-schemas/sample-activity-log-alert.png)](media/alerts-schemas/sample-activity-log-alert.png#lightbox)
80+
81+
82+
### Sample JSON for alerts sent to Azure Activity Log
83+
84+
```json
85+
{
86+
"channels": "Operation",
87+
"correlationId": "2518250008431989649_e7313e05-edf4-466d-adfd-35974921aeff",
88+
"description": "PREVIEW - Role binding to the cluster-admin role detected. Kubernetes audit log analysis detected a new binding to the cluster-admin role which gives administrator privileges.\r\nUnnecessary administrator privileges might cause privilege escalation in the cluster.",
89+
"eventDataId": "2518250008431989649_e7313e05-edf4-466d-adfd-35974921aeff",
90+
"eventName": {
91+
"value": "PREVIEW - Role binding to the cluster-admin role detected",
92+
"localizedValue": "PREVIEW - Role binding to the cluster-admin role detected"
93+
},
94+
"category": {
95+
"value": "Security",
96+
"localizedValue": "Security"
97+
},
98+
"eventTimestamp": "2019-12-25T18:52:36.801035Z",
99+
"id": "/subscriptions/SUBSCRIPTION_ID/resourceGroups/RESOURCE_GROUP_NAME/providers/Microsoft.Security/locations/centralus/alerts/2518250008431989649_e7313e05-edf4-466d-adfd-35974921aeff/events/2518250008431989649_e7313e05-edf4-466d-adfd-35974921aeff/ticks/637128967568010350",
100+
"level": "Informational",
101+
"operationId": "2518250008431989649_e7313e05-edf4-466d-adfd-35974921aeff",
102+
"operationName": {
103+
"value": "Microsoft.Security/locations/alerts/activate/action",
104+
"localizedValue": "Activate Alert"
105+
},
106+
"resourceGroupName": "RESOURCE_GROUP_NAME",
107+
"resourceProviderName": {
108+
"value": "Microsoft.Security",
109+
"localizedValue": "Microsoft.Security"
110+
},
111+
"resourceType": {
112+
"value": "Microsoft.Security/locations/alerts",
113+
"localizedValue": "Microsoft.Security/locations/alerts"
114+
},
115+
"resourceId": "/subscriptions/SUBSCRIPTION_ID/resourceGroups/RESOURCE_GROUP_NAME/providers/Microsoft.Security/locations/centralus/alerts/2518250008431989649_e7313e05-edf4-466d-adfd-35974921aeff",
116+
"status": {
117+
"value": "Active",
118+
"localizedValue": "Active"
119+
},
120+
"subStatus": {
121+
"value": "",
122+
"localizedValue": ""
123+
},
124+
"submissionTimestamp": "2019-12-25T19:14:03.5507487Z",
125+
"subscriptionId": "SUBSCRIPTION_ID",
126+
"properties": {
127+
"clusterRoleBindingName": "cluster-admin-binding",
128+
"subjectName": "for-binding-test",
129+
"subjectKind": "ServiceAccount",
130+
"username": "masterclient",
131+
"actionTaken": "Detected",
132+
"resourceType": "Kubernetes Service",
133+
"severity": "Low",
134+
"intent": "[\"Persistence\"]",
135+
"compromisedEntity": "ASC-IGNITE-DEMO",
136+
"remediationSteps": "[\"Review the user in the alert details. If cluster-admin is unnecessary for this user, consider granting lower privileges to the user.\"]",
137+
"attackedResourceType": "Kubernetes Service"
138+
},
139+
"relatedEvents": []
140+
}
141+
```
142+
143+
### The data model of the schema
144+
145+
|Field|Description|
146+
|----|----|
147+
|**channels**|Constant, "Operation"|
148+
|**correlationId**|The Azure Security Center alert ID|
149+
|**description**|Description of the alert|
150+
|**eventDataId**|See correlationId|
151+
|**eventName**|The value and localizedValue sub-fields contain the alert display name|
152+
|**category**|The value and localizedValue sub-fields are constant - "Security"|
153+
|**eventTimestamp**|UTC timestamp for when the alert was generated|
154+
|**id**|The fully qualified alert ID|
155+
|**level**|Constant, "Informational"|
156+
|**operationId**|See correlationId|
157+
|**operationName**|The value field is constant - "Microsoft.Security/locations/alerts/activate/action", and the localized value will be "Activate Alert" (can potentially be localized par the user locale)|
158+
|**resourceGroupName**|Will include the resource group name|
159+
|**resourceProviderName**|The value and localizedValue sub-fields are constant - "Microsoft.Security"|
160+
|**resourceType**|The value and localizedValue sub-fields are constant - "Microsoft.Security/locations/alerts"|
161+
|**resourceId**|The fully qualified Azure resource ID|
162+
|**status**|The value and localizedValue sub-fields are constant - "Active"|
163+
|**subStatus**|The value and localizedValue sub-fields are empty|
164+
|**submissionTimestamp**|The UTC timestamp of event submission to Activity Log|
165+
|**subscriptionId**|The subscription ID of the compromised resource|
166+
|**properties**|A JSON bag of additional properties pertaining to the alert. These can change from one alert to the other, however, the following fields will appear in all alerts:<br>- severity: The severity of the attack<br>- compromisedEntity: The name of the compromised resource<br>- remediationSteps: Array of remediation steps to be taken<br>- intent: The kill-chain intent of the alert. Possible intents are documented in the [Intentions table](alerts-reference.md#intentions)|
167+
|**relatedEvents**|Constant - empty array|
168+
|||
169+
170+
171+
172+
173+
174+
### [MS Graph API](#tab/schema-graphapi)
175+
176+
Microsoft Graph is the gateway to data and intelligence in Microsoft 365. It provides a unified programmability model that you can use to access the tremendous amount of data in Office 365, Windows 10, and Enterprise Mobility + Security. Use the wealth of data in Microsoft Graph to build apps for organizations and consumers that interact with millions of users.
177+
178+
The schema and a JSON representation for security alerts sent to MS Graph, are available in [the Microsoft Graph documentation](https://docs.microsoft.com/graph/api/resources/alert?view=graph-rest-1.0).
179+
180+
---
181+
182+
183+
## Next steps
184+
185+
This article described the schemas that Azure Security Center's threat protection tools use when sending security alert information.
186+
187+
For more information on the ways to access security alerts from outside Security Center, see the following:
188+
189+
- [Azure Sentinel](https://docs.microsoft.com/azure/sentinel/) - Microsoft's cloud-native SIEM
190+
- [Azure Event Hubs](https://docs.microsoft.com/azure/event-hubs/) - Microsoft's fully managed, real-time data ingestion service
191+
- Security Center's [continuous export feature](continuous-export.md)
192+
193+
- [Log Analytics workspaces](https://docs.microsoft.com/azure/azure-monitor/learn/quick-create-workspace) - Azure Monitor stores log data in a Log Analytics workspace, a container that includes data and configuration information

‎articles/security-center/media/alerts-schemas/sample-activity-log-alert.png

67.9 KB
Loading

‎articles/security-center/threat-protection.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -18,11 +18,11 @@ When Security Center detects a threat in any area of your environment, it genera
1818

1919
Azure Security Center's threat protection provides comprehensive defenses for your environment:
2020

21-
* **Threat protection for compute resources**: Windows machines, Linux machines, Azure App Service, and Azure containers
21+
* **Threat protection for Azure compute resources**: Windows machines, Linux machines, Azure App Service, and Azure containers
2222

23-
* **Threat protection for data resources**: SQL Database and SQL Data Warehouse, Azure Storage, and Azure Cosmos DB
23+
* **Threat protection for Azure data resources**: SQL Database and SQL Data Warehouse, Azure Storage, and Azure Cosmos DB
2424

25-
* **Threat protection for the service layer**: Azure network layer, Azure management layer (Azure Resource Manager) (Preview), and Azure Key Vault (Preview)
25+
* **Threat protection for Azure service layers**: Azure network layer, Azure management layer (Azure Resource Manager) (Preview), and Azure Key Vault (Preview)
2626

2727
Whether an alert is generated by Security Center, or received by Security Center from a different security product, you can export it. To export your alerts to Azure Sentinel (or a third-party SIEM) or any other external tool, follow the instructions in [Exporting alerts to a SIEM](continuous-export.md).
2828

‎includes/security-center-alerts-schema-log-analytics-workspace.md

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
---
2+
title: include file
3+
description: include file
4+
services: data-factory
5+
author: memildin
6+
ms.service: data-factory
7+
ms.topic: include
8+
ms.date: 03/17/2020
9+
ms.author: memildin
10+
ms.custom: include file
11+
---
12+
### The data model of the schema
13+
14+
|Field|Description|
15+
|----|----|
16+
|**AlertName**|Alert display name|
17+
|**AlertType**|unique alert identifier|
18+
|**ConfidenceLevel**|(Optional) The confidence level of this alert (High/Low)|
19+
|**ConfidenceScore**|(Optional) Numeric confidence indicator of the security alert|
20+
|**Description**|Description text for the alert|
21+
|**DisplayName**|The alert's display name|
22+
|**EndTime**|The impact end time of the alert (the time of the last event contributing to the alert)|
23+
|**Entities**|A list of entities related to the alert. This list can hold a mixture of entities of diverse types|
24+
|**ExtendedLinks**|(Optional) A bag for all links related to the alert. This bag can hold a mixture of links for diverse types|
25+
|**ExtendedProperties**|A bag of additional fields which are relevant to the alert|
26+
|**IsIncident**|Determines if the alert is an incident or a regular alert. An incident is a security alert that aggregates multiple alerts into one security incident|
27+
|**ProcessingEndTime**|UTC timestamp in which the alert was created|
28+
|**ProductComponentName**|(Optional) The name of a component inside the product which generated the alert.|
29+
|**ProductName**|constant ('Azure Security Center')|
30+
|**ProviderName**|unused|
31+
|**RemediationSteps**|Manual action items to take to remediate the security threat|
32+
|**ResourceId**|Full identifier of the affected resource|
33+
|**Severity**|The alert severity (High/Medium/Low/Informational)|
34+
|**SourceComputerId**|a unique GUID for the affected server (if the alert is generated on the server)|
35+
|**SourceSystem**|unused|
36+
|**StartTime**|The impact start time of the alert (the time of the first event contributing to the alert)|
37+
|**SystemAlertId**|Unique identifier of this security alert instance|
38+
|**TenantId**|the identifier of the parent Azure Active directory tenant of the subscription under which the scanned resource resides|
39+
|**TimeGenerated**|UTC timestamp on which the assessment took place (Security Center's scan time) (identical to DiscoveredTimeUTC)|
40+
|**Type**|constant ('SecurityAlert')|
41+
|**VendorName**|The name of the vendor that provided the alert (e.g. 'Microsoft')|
42+
|**VendorOriginalId**|unused|
43+
|**WorkspaceResourceGroup**|in case the alert is generated on a VM, Server, Virtual Machine Scale Set or App Service instance that reports to a workspace, contains that workspace resource group name|
44+
|**WorkspaceSubscriptionId**|in case the alert is generated on a VM, Server, Virtual Machine Scale Set or App Service instance that reports to a workspace, contains that workspace subscriptionId|
45+
|||

‎includes/security-center-alerts-schema-workflow-automation.md

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
---
2+
title: include file
3+
description: include file
4+
services: data-factory
5+
author: memildin
6+
ms.service: data-factory
7+
ms.topic: include
8+
ms.date: 03/10/2020
9+
ms.author: memildin
10+
ms.custom: include file
11+
---
12+
13+
```json
14+
{
15+
"VendorName": "Microsoft",
16+
"AlertType": "SUSPECT_SVCHOST",
17+
"StartTimeUtc": "2016-12-20T13:38:00.000Z",
18+
"EndTimeUtc": "2019-12-20T13:40:01.733Z",
19+
"ProcessingEndTime": "2019-09-16T12:10:19.5673533Z",
20+
"TimeGenerated": "2016-12-20T13:38:03.000Z",
21+
"IsIncident": false,
22+
"Severity": "High",
23+
"Status": "New",
24+
"ProductName": "Azure Security Center",
25+
"SystemAlertId": "2342409243234234_F2BFED55-5997-4FEA-95BD-BB7C6DDCD061",
26+
"CompromisedEntity": "WebSrv1",
27+
"Intent": "Execution",
28+
"AlertDisplayName": "Suspicious process detected",
29+
"Description": "Suspicious process named 'SVCHOST.EXE' was running from path: %{Process Path}",
30+
"RemediationSteps": ["contact your security information team"],
31+
"ExtendedProperties": {
32+
"Process Path": "c:\\temp\\svchost.exe",
33+
"Account": "Contoso\\administrator",
34+
"PID": 944,
35+
"ActionTaken": "Detected"
36+
},
37+
"Entities": [],
38+
"ResourceIdentifiers": [
39+
{
40+
Type: "AzureResource",
41+
AzureResourceId: "/subscriptions/86057C9F-3CDD-484E-83B1-7BF1C17A9FF8/resourceGroups/backend-srv/providers/Microsoft.Compute/WebSrv1"
42+
},
43+
{
44+
Type: "LogAnalytics",
45+
WorkspaceId: "077BA6B7-8759-4F41-9F97-017EB7D3E0A8",
46+
WorkspaceSubscriptionId: "86057C9F-3CDD-484E-83B1-7BF1C17A9FF8",
47+
WorkspaceResourceGroup: "omsrg",
48+
AgentId: "5A651129-98E6-4E6C-B2CE-AB89BD815616",
49+
}
50+
]
51+
}
52+
```
53+
54+
### The data model of the schema
55+
56+
|Field|Data type|Description|
57+
|----|----|----|
58+
|**AlertDisplayName**|String|The display name of the alert.|
59+
|**AlertType**|String|The type of alert. Alerts of the same type should have the same value. This field is a keyed string representing the type of alert and not of an alert instance. All alert instances from the same detection logic/analytic should have the same value for alert type.|
60+
|**CompromisedEntity**|String|The display name of the resource most related to this alert.|
61+
|**Description**|String|Description of the alert.|
62+
|**EndTimeUtc**|DateTime|The time of the last event or activity included in the alert. The field should be a string that conforms to the ISO8601 format, including UTC timezone information.|
63+
|**Entities**|IEnumerable (IEntity)|A list of entities related to the alert. This list can hold a mixture of entities of diverse types. The entities type can be any of the types defined in the Entities section. Entities that are not in the list below can also be sent, however it is not guaranteed that they will be processed (the alert will not fail validation with new types of entities).|
64+
|**ExtendedProperties**|Dictionary (String,String)|Providers might (optionally) include custom fields here.|
65+
|**Intent**|Enum|The kill chain related intent behind the alert. For list of supported values, and explanations of Azure Security Center's supported kill chain intents, see [Intentions](/articles/security-center/alerts-reference.md#intentions).<br/>This field might have multiple values (separated by comma).|
66+
|**IsIncident**|Bool|This field determines whether the alert is an incident (a compound grouping of several alerts) or a single alert. Default value for the field is 'false' (meaning it's a single alert).|
67+
|**ProcessingEndTime**|DateTime|The time the alert was accessible to the end user in the original product holding the alert.|
68+
|**ProductName**|String|The name of the product that published this alert (Azure Security Center, Azure ATP, Microsoft Defender ATP, O365 ATP, MCAS, and so on).|
69+
|**RemediationSteps**|List<String>|Manual action items to take to remediate the alert.|
70+
|**ResourceIdentifiers**|List (Resource Identifiers)|The resource identifiers for this alert that can be used to direct the alert to the right product exposure group (tenant, workspace, subscription etc.). There can be multiple identifiers of different type per alert.|
71+
|**Severity**|Enum|The severity of the alert as reported by the provider. Possible Values: Informational, Low, Medium, and High.|
72+
|**StartTimeUtc**|DateTime|The time of the first event or activity included in the alert. The field should be a string that conforms to the ISO8601 format, including UTC timezone information.|
73+
|**Status**|Enum|The life-cycle status of the alert.<br/>Supported statuses are: New, Resolved, Dismissed, Unknown.<br/>An alert that specifies a value other than the supported options is assigned the status 'Unknown'.<br/>An alert that doesn't specify a value is assigned the status 'New'.|
74+
|**SystemAlertId**|String|The alert identifier.|
75+
|**TimeGenerated**|DateTime|The time the alert was generated by the alert provider. If not reported by internal alert providers, a product can choose to assign the time it was received for processing by the product. The field should be a string that conforms to the ISO8601 format, including UTC timezone information.|
76+
|**VendorName**|String|The name of the vendor that raises the alert.|
77+
|||

0 commit comments

Comments
 (0)