Merge pull request #3 from batamig/patch-127

Review 2

Author: oshezaf

articles/sentinel/TOC.yml

@@ -65,7 +65,7 @@
       href: connect-data-sources.md
     - name: Classifying data with entities
       href: entities.md
-  - name: Normalization and the Advanced SIEM Information Model (ASIM)
+  - name: Normalization with ASIM
     items:
     - name: ASIM overview
       href: normalization.md
@@ -184,7 +184,7 @@
       href: monitor-data-connector-health.md
     - name: Integrate Azure Data Explorer
       href: store-logs-in-azure-data-explorer.md
-  - name: Use the Advanced SIEM Information Model (ASIM)
+  - name: Use ASIM to normalize data
     items:
     - name: Develop ASIM parsers
       href: normalization-develop-parsers.md

articles/sentinel/dns-normalization-schema.md

@@ -31,9 +31,14 @@ The most important activity reported by DNS servers is a DNS query, for which th
 The most important fields in a DNS event are:
 
 - [DnsQuery](#query), which reports the domain name for which the query was issued.
+
 - The [SrcIpAddr](#srcipaddr) (aliased to [IpAddr](#ipaddr)), which represents the IP address from which the request was generated. 
+
 - [EventResultDetails](#eventresultdetails), which reports as to whether the request was successful and if not, why.
-- When available, [DnsResponseName](#responsename), which holds the answer provided by the server to the query. ASIM does not require parsing the response, and its format varies between sources. To use this field in source-agnostic content, search the content using the `has` or `contains` operators.
+
+- When available, [DnsResponseName](#responsename), which holds the answer provided by the server to the query. ASIM does not require parsing the response, and its format varies between sources. 
+
+    To use this field in source-agnostic content, search the content using the `has` or `contains` operators.
 
 DNS events collected on client device may also include [User](#user) and [Process](#process) information. 
 
@@ -59,6 +64,8 @@ imDNS | where SrcIpAddr != "127.0.0.1" and EventSubType == "response"
 
 ## Parsers
 
+For more information about ASIM parsers, see the [ASIM parsers overview](normalization-parsers-overview.md) and [Use ASIM parsers](normalization-about-parsers.md).
+
 ### Unifying parsers
 
 To use parsers that unify all ASIM out-of-the-box parsers, and ensure that your analysis runs across all the configured sources, use the `_Im_Dns` filtering parser or the `_ASim_Dns` parameter-less parser.
@@ -82,7 +89,7 @@ Microsoft Sentinel provides the following out-of-the-box, product-specific DNS p
 | **zScaler ZIA** |`_ASim_DnsZscalerZIA` (regular)<br> `_Im_DnsZdcalerZIA` (filtering)  | `AsimDnsZscalerZIA` (regular)<br> `vimDnsSzcalerZIA` (filtering)  |
 | | | |
 
-The parsers can be deployed from the [Microsoft Sentinel GitHub repository](https://aka.ms/azsentinelDNS).
+These parsers can be deployed from the [Microsoft Sentinel GitHub repository](https://aka.ms/azsentinelDNS).
 
 ### Add your own normalized parsers
 
@@ -124,7 +131,7 @@ imDns (domain_has_any = torProxies)
 
 ## Normalized content
 
-For a full list of analytics rules that use normalized DNS events, see the [DNS query security content](normalization-content.md#dns-query-security-content) section.
+For a full list of analytics rules that use normalized DNS events, see [DNS query security content](normalization-content.md#dns-query-security-content).
 
 ## Schema details
 
@@ -171,7 +178,7 @@ The fields below are specific to DNS events, although many are similar to fields
 | <a name="srcdvcid"></a>**SrcDvcId** | Optional | String | The ID of the source device as reported in the record.<br><br>For example: `ac7e9755-8eae-4ffc-8a02-50ed7a2216c3` |
 | **SrcDvcIdType** | Optional | Enumerated | The type of [SrcDvcId](#srcdvcid), if known. Possible values include:<br> - `AzureResourceId`<br>- `MDEid`<br><br>If multiple IDs are available, use the first one from the list above, and store the others in the **SrcDvcAzureResourceId** and **SrcDvcMDEid**, respectively.<br><br>**Note**: This field is required if [SrcDvcId](#srcdvcid) is used. |
 | **SrcDeviceType** | Optional | Enumerated | The type of the source device. Possible values include:<br>- `Computer`<br>- `Mobile Device`<br>- `IOT Device`<br>- `Other` |
-| <a name="srcuserid"></a>**SrcUserId** | Optional | String | A machine-readable, alphanumeric, unique representation of the source user. Format and supported types include:<br>-  **SID**  (Windows): `S-1-5-21-1377283216-344919071-3415362939-500`<br>-  **UID**  (Linux): `4578`<br>-  **AADID**  (Azure Active Directory): `9267d02c-5f76-40a9-a9eb-b686f3ca47aa`<br>-  **OktaId**: `00urjk4znu3BcncfY0h7`<br>-  **AWSId**: `72643944673`<br><br>Store the ID type in the [SrcUserIdType](#srcuseridtype) field. <br><br>If other IDs are available, we recommend that you normalize the field names to **SrcUserSid**, **SrcUserUid**, **SrcUserAadId**, **SrcUserOktaId** and **UserAwsId**, respectively. For more information, see [The User entity](normalization-about-schemas.md#the-user-entity).<br><br>Example: S-1-12 |
+| <a name="srcuserid"></a>**SrcUserId** | Optional | String | A machine-readable, alphanumeric, unique representation of the source user. Format and supported types include:<br>-  **SID**  (Windows): `S-1-5-21-1377283216-344919071-3415362939-500`<br>-  **UID**  (Linux): `4578`<br>-  **AADID**  (Azure Active Directory): `9267d02c-5f76-40a9-a9eb-b686f3ca47aa`<br>-  **OktaId**: `00urjk4znu3BcncfY0h7`<br>-  **AWSId**: `72643944673`<br><br>Store the ID type in the [SrcUserIdType](#srcuseridtype) field. <br><br>If other IDs are available, we recommend that you normalize the field names to **SrcUserSid**, **SrcUserUid**, **SrcUserAadId**, **SrcUserOktaId** and **UserAwsId**, respectively. For more information, see [The User entity](normalization-about-schemas.md#the-user-entity).<br><br>Example: `S-1-12` |
 | <a name="srcuseridtype"></a>**SrcUserIdType** | Optional | Enumerated | The type of the ID stored in the [SrcUserId](#srcuserid) field. Supported values include: `SID`, `UIS`, `AADID`, `OktaId`, and `AWSId`. |
 | <a name="srcusername"></a>**SrcUsername** | Optional | String | The Source username, including domain information when available. Use one of the following formats and in the following order of priority:<br>- **Upn/Email**: `[email protected]`<br>- **Windows**: `Contoso\johndow`<br>- **DN**: `CN=Jeff Smith,OU=Sales,DC=Fabrikam,DC=COM`<br>- **Simple**: `johndow`. Use the Simple form only if domain information is not available.<br><br>Store the Username type in the [SrcUsernameType](#srcusernametype) field. If other IDs are available, we recommend that you normalize the field names to **SrcUserUpn**, **SrcUserWindows** and **SrcUserDn**.<br><br>For more information, see [The User entity](normalization-about-schemas.md#the-user-entity).<br><br>Example: `AlbertE` |
 | <a name="user"></a>**User** | Alias | | Alias to [SrcUsername](#srcusername) |

articles/sentinel/network-normalization-schema.md

@@ -28,32 +28,60 @@ The network normalization schema can represent any type of an IP network session
 
 ## Parsers
 
-This section discusses parsers, how to add parsers, and how to filter parser parameters.
+This section discusses parsers, how to add parsers, and how to filter parser parameters. For more information, see [ASIM parsers](normalization-parsers-overview.md) and [Use ASIM parsers](normalization-about-parsers.md).
 
 ### Unifying parsers
 
-To use the unifying parsers that unify all of the out-of-the-box parsers, and ensure that your analysis runs across all the configured sources, use the following KQL functions as the table name in your query:
-
-| Name | Description | Usage instructions |
-| ---- | --- | --- |
-| <a name="imnetworksession"></a>**imNetworkSession** | Aggregative parser that uses *union* to include normalized events from all *network session* sources. |- Update this parser if you want to add or remove sources from source-agnostic analytics. <br><br>- Use this function in your source-agnostic queries.|
-| **ASimNetworkSession** | Similar to the [imNetworkSession](#imnetworksession) function, but without parameter support, so it doesn't force the **Logs** page time picker to use the `custom` value. |- Update these parsers if you want to add or remove sources from source-agnostic analytics.<br><br>- Use this function in your source-agnostic queries if you don't plan to use parameters.|
-| **vimNetworkSession\<vendor\>\<product\>** | Source-specific parsers implement normalization for a specific source. <br><br>Example: `vimNetworkSessionSysmonLinux` |- Add a source-specific parser for a source when there's no out-of-the-box normalizing parser. Update the `im` aggregative parser to include reference to your new parser. <br><br>- Update a source-specific parser to resolve parsing and normalization issues.<br><br>- Use a source-specific parser for source-specific analytics.|
- **ASimNetworkSession\<vendor\>\<product\>>** | Source-specific parsers implement normalization for a specific source. <br><br>Unlike the `vim*` functions, the `ASim*` functions don't support parameters. |- Add a source-specific parser for a source when there's no out-of-the-box normalizing parser. Update the aggregative `ASim` parser to include reference to your new parser.<br><br>- Update a source-specific parser to resolve parsing and normalization issues.<br><br>- Use an `ASim` source-specific parser for interactive queries when not using parameters.|
-| | | |
+To use the unifying parsers that unify all of the out-of-the-box parsers, and ensure that your analysis runs across all the configured sources, use the following KQL functions as the table name in your query. 
 
 Deploy ASIM parsers from the [Microsoft Sentinel GitHub repository](https://aka.ms/DeployASIM).
 
+#### <a name="imnetworksession"></a>imNetworkSession
+
+Aggregative parser that uses *union* to include normalized events from all *network session* sources.
+
+- Update this parser if you want to add or remove sources from source-agnostic analytics. 
+- Use this function in your source-agnostic queries.
+
+#### ASimNetworkSession
+
+Similar to the [imNetworkSession](#imnetworksession) function, but without parameter support, so it doesn't force the **Logs** page time picker to use the `custom` value. 
+
+- Update these parsers if you want to add or remove sources from source-agnostic analytics.
+- Use this function in your source-agnostic queries if you don't plan to use parameters.
+
+#### vimNetworkSession\<vendor\>\<product\>
+
+Source-specific parsers implement normalization for a specific source.
+
+Example: `vimNetworkSessionSysmonLinux`
+
+- Add a source-specific parser for a source when there's no out-of-the-box normalizing parser. Update the `im` aggregative parser to include reference to your new parser.
+- Update a source-specific parser to resolve parsing and normalization issues.
+- Use a source-specific parser for source-specific analytics.
+
+#### ASimNetworkSession\<vendor\>\<product\>>
+
+Source-specific parsers implement normalization for a specific source.
+
+Unlike the `vim*` functions, the `ASim*` functions don't support parameters.
+
+- Add a source-specific parser for a source when there's no out-of-the-box normalizing parser. Update the aggregative `ASim` parser to include reference to your new parser.
+- Update a source-specific parser to resolve parsing and normalization issues.
+- Use an `ASim` source-specific parser for interactive queries when not using parameters.
+
+
+
 ### Out-of-the-box, source-specific parsers
 
 Microsoft Sentinel provides the following built-in, product-specific Network Session parsers:
 
 | **Name** | **Description** |
 | --- | --- |
-| **Microsoft 365 Defender for Endpoint** | - Parametrized: vimNetworkSessionMicrosoft365Defender <br> - Regular: ASimNetworkSessionMicrosoft365Defender | 
-| **Microsoft Defender for IoT - Endpoint (MD4IoT)** | - Parametrized: vimNetworkSessionMD4IoT <br> - Regular: ASimNetworkSessionMD4IoT  |
-| **Microsoft Sysmon for Linux** | - Parametrized: vimNetworkSessionSysmonLinux<br> - Regular: ASimNetworkSessionSysmonLinux  |
-| **Windows Events Firewall** | Windows firewall activity as represented by using Windows Events 515x, collected by using either the Log Analytics Agent or the Azure Monitor Agent into either the `Event` table or the `WindowsEvent` table.<br><br> - Parametrized: vimNetworkSessionMicrosoftWindowsEventFirewall <br> -  Regular: ASimNetworkSessionMicrosoftWindowsEventFirewall
+| **Microsoft 365 Defender for Endpoint** | - Parametrized: `vimNetworkSessionMicrosoft365Defender` <br> - Regular: `ASimNetworkSessionMicrosoft365Defender` | 
+| **Microsoft Defender for IoT - Endpoint (MD4IoT)** | - Parametrized: `vimNetworkSessionMD4IoT` <br> - Regular: `ASimNetworkSessionMD4IoT`  |
+| **Microsoft Sysmon for Linux** | - Parametrized: `vimNetworkSessionSysmonLinux`<br> - Regular: `ASimNetworkSessionSysmonLinux`  |
+| **Windows Events Firewall** | Windows firewall activity as represented by using Windows Events 515x, collected by using either the Log Analytics Agent or the Azure Monitor Agent into either the `Event` table or the `WindowsEvent` table.<br><br> - Parametrized: `vimNetworkSessionMicrosoftWindowsEventFirewall` <br> -  Regular: `ASimNetworkSessionMicrosoftWindowsEventFirewall`
 | | |
 
 ### Add your own normalized parsers

articles/sentinel/normalization-develop-parsers.md

@@ -13,8 +13,6 @@ ms.author: ofshezaf
 
 Advanced SIEM Information Model (ASIM) users use *unifying parsers* instead of table names in their queries, to view data in a normalized format and to include all data relevant to the schema in the query. Unifying parsers, in turn, use *source-specific parsers* to handle the specific details of each source. 
 
-To understand how parsers fit within the ASIM architecture, refer to the [ASIM architecture diagram](normalization.md#asim-components).
-
 Microsoft Sentinel provides built-in, source-specific parsers for many data sources. You may want to modify, or *develop*, these source-specific parsers in the following situations:
 
 - When your device provides events that fit an ASIM schema, but a source-specific parser for your device and the relevant schema is not available in Microsoft Sentinel.
@@ -27,7 +25,13 @@ Microsoft Sentinel provides built-in, source-specific parsers for many data sour
 
   - The events might be collected, modified, and forwarded by an intermediary system.
 
-## The ASIM custom parser development process
+To understand how parsers fit within the ASIM architecture, refer to the [ASIM architecture diagram](normalization.md#asim-components).
+
+> [!IMPORTANT]
+> ASIM is currently in PREVIEW. The [Azure Preview Supplemental Terms](https://azure.microsoft.com/support/legal/preview-supplemental-terms/) include additional legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability.
+
+
+## Custom parser development process
 
 The following workflow describe the high level steps in developing a custom ASIM, source-specific parser:
 
@@ -47,9 +51,6 @@ This article guides you through the process's development, testing, and deployme
 > Also watch the [Deep Dive Webinar on Microsoft Sentinel Normalizing Parsers and Normalized Content](https://www.youtube.com/watch?v=zaqblyjQW6k) or review the related [slide deck](https://1drv.ms/b/s!AnEPjr8tHcNmjGtoRPQ2XYe3wQDz?e=R3dWeM). For more information, see [Next steps](#next-steps).
 >
 
-> [!IMPORTANT]
-> ASIM is currently in PREVIEW. The [Azure Preview Supplemental Terms](https://azure.microsoft.com/support/legal/preview-supplemental-terms/) include additional legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability.
->
 
 ## Developing parsers
 

articles/sentinel/normalization-modify-content.md

@@ -1,5 +1,5 @@
 ---
-title: Modify content to us the Advanced SIEM Information Model (ASIM) | Microsoft Docs
+title: Modify content to use the Microsoft Sentinel Advanced SIEM Information Model (ASIM) | Microsoft Docs
 description: This article explains how to convert Microsoft Sentinel content to use the the Advanced SIEM Information Model (ASIM).
 author: oshezaf
 ms.topic: conceptual
@@ -8,15 +8,15 @@ ms.author: ofshezaf
 ms.custom: ignite-fall-2021
 ---
 
-# Modify content to us the Advanced SIEM Information Model (ASIM) (Public preview)
+# Modify content to use the Advanced SIEM Information Model (ASIM) (Public preview)
 
 [!INCLUDE [Banner for top of topics](./includes/banner.md)]
 
 Normalized security content in Microsoft Sentinel includes analytics rules, hunting queries, and workbooks that work with unifying normalization parsers.
 
-<a name="builtin"></a>You can find normalized, built-in content in Microsoft Sentinel galleries and [solutions](sentinel-solutions-catalog.md), create your own normalized content, or modify existing content to use normalized data.
+<a name="builtin"></a>You can find normalized, out-of-the-box content in Microsoft Sentinel galleries and [solutions](sentinel-solutions-catalog.md), create your own normalized content, or modify existing, custom content to use normalized data.
 
-This article explains how to convert Microsoft Sentinel analytic rules to use the the Advanced SIEM Information Model (ASIM).
+This article explains how to convert existing Microsoft Sentinel analytics rules to use [normalizated data](normalization.md) with the Advanced SIEM Information Model (ASIM).
 
 To understand how normalized content fits within the ASIM architecture, refer to the [ASIM architecture diagram](normalization.md#asim-components).
 
@@ -28,12 +28,18 @@ To understand how normalized content fits within the ASIM architecture, refer to
 > ASIM is currently in PREVIEW. The [Azure Preview Supplemental Terms](https://azure.microsoft.com/support/legal/preview-supplemental-terms/) include additional legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability.
 >
 
-To enable your custom content to use normalization:
+## Modify custom content to use normalization
+
+To enable your custom Microsoft Sentinel content to use normalization:
+
+- Modify your queries to use any [unifying parsers](normalization-about-parsers.md) relevant to the query.
+
+- Modify field names in your query to use the [normalized schema](normalization-about-schemas.md) field names.
 
-- Modify your queries to use the unifying parsers relevant to the query.
-- Modify field names in your query to use the normalized schema field names.
 - When applicable, change conditions to use the normalized values of the fields in your query.
 
+## Sample normalization for analytics rules
+
 For example, consider the **Rare client observed with high reverse DNS lookup count** DNS analytic rule, which works on DNS events send by Infoblox DNS servers:
 
 ```kusto
@@ -62,15 +68,14 @@ _Im_Dns(responsecodename='NXDOMAIN')
 | extend timestamp = TimeGenerated, IPCustomEntity = SrcIpAddr```
 ```
 
-To use workspace deployed ASIM parsers, replace the first line with the following code:
+To use workspace-deployed ASIM parsers, replace the first line with the following code:
 
 ```kusto
 imDns(responsecodename='NXDOMAIN')
 ```
+### Differences between built-in and workspace-deployed parsers
 
-The two options are functionally identical.
-
-The normalized, source-agnostic version has the following differences:
+The two options in the example [above](#sample-normalization-for-analytics-rules) are functionally identical. The normalized, source-agnostic version has the following differences:
 
 - The `_In_Dns` or `imDns`normalized parsers are used instead of the Infoblox Parser.
 
@@ -81,9 +86,11 @@ The normalized, source-agnostic version has the following differences:
 - Parser parameter filtering is used for ResponseCodeName, eliminating the need for an explicit `where` clauses.
 
 
-Apart from supporting any normalized DNS source, the normalized version is shorter and easier to understand. 
+>[!NOTE]
+> Apart from supporting any normalized DNS source, the normalized version is shorter and easier to understand. 
+>
 
-If the schema or parsers do not support filtering parameters, the changes are similar, excluding the last one. Instead the filtering conditions are kept from the original query as seen below:
+If the schema or parsers do not support filtering parameters, the changes are similar, except that the filtering conditions are kept from the original query. For example:
 
 ```kusto
 let threshold = 200;