Microsoft Sentinel Network Session normalization schema reference (Public preview)
The Network Session normalization schema is used to describe an IP network activity. This includes network connections and network sessions. Such events are reported, for example, by operating systems, routers, firewalls, intrusion prevention systems and web security gateways.
For more information about normalization in Microsoft Sentinel, see Normalization and the Advanced SIEM Information Model (ASIM).
Important
This article describes version 0.2.x of the network normalization schema, where version 0.1 was released before ASIM was available and does not align with ASIM in several places. For more information, see Differences between network normalization schema versions.
Important
The Network normalization schema is currently in PREVIEW. This feature is provided without a service level agreement, and is not recommended for production workloads.
The Azure 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.
Schema overview
The network normalization schema can represent any type of an IP network session, but is specifically designed to provide support for common source types, such as Netflow, Firewalls, and Intrusion prevention systems.
Parsers
Source-agnostic parsers
To use the source-agnostic 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 |
|---|---|---|
| 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 function, but without parameter support, and therefore does not 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 is 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 do not support parameters. |
- Add a source-specific parser for a source when there is 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. |
Deploy ASIM parsers from the Microsoft Sentinel GitHub repository.
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 - Regular: ASimNetworkSessionMicrosoft365Defender |
| Microsoft Defender for IoT - Endpoint (MD4IoT) | - Parametrized: vimNetworkSessionMD4IoT - Regular: ASimNetworkSessionMD4IoT |
| Microsoft Sysmon for Linux | - Parametrized: vimNetworkSessionSysmonLinux - Regular: ASimNetworkSessionSysmonLinux |
| Windows Events Firewall | Windows firewall activity as collected using Windows Events 515x, collected using either the Log Analytics Agent or the Azure Monitor Agent into either the Event or the WindowsEvent table. - Parametrized: vimNetworkSessionMicrosoftWindowsEventFirewall - Regular: ASimNetworkSessionMicrosoftWindowsEventFirewall |
Add your own normalized parsers
When implementing custom parsers for the Network Session information model, name your KQL functions using the following syntax:
vimNetworkSession<vendor><Product>for parametrized parsersASimNetworkSession<vendor><Product>for regular parsers
Then, add the new parser to imNetworkSession or ASimNetworkSession respectively.
Filtering parser parameters
The im and vim* parsers support filtering parameters. While these parsers are optional, they can improve your query performance.
The following filtering parameters are available:
| Name | Type | Description |
|---|---|---|
| starttime | datetime | Filter only network sessions that started at or after this time. |
| endtime | datetime | Filter only network sessions that started running at or before this time. |
| srcipaddr_has_any_prefix | dynamic | Filter only network sessions for which the source IP address field prefix is in one of the listed values. |
| dstipaddr_has_any_prefix | dynamic | Filter only network sessions for which the destination IP address field prefix is in one of the listed values. |
| dstportnum | int | Filter only network sessions with the specified destination port number. |
| hostname_has_any | dynamic | Filter only the network sessions for which the destination hostname field has any of the values listed. |
| dvcaction | dynamic | Filter only the network sessions for which the Device Action field is any of the values listed. |
| eventresult | string | Filter only network sessions with a specific EventResult value. |
For example, to filter only Web sessions for a specified list of domain names, use:
let torProxies=dynamic(["tor2web.org", "tor2web.com", "torlink.co",...]);
imNetworkSession (hostname_has_any = torProxies)
Schema details
The Network Sessions information model is aligned is the OSSEM Network entity schema.
To conform with industry best practices, the Network Session schema uses the descriptors Src and Dst to identify the network session source and destination devices, without including the token Dvc in the field name.
So, for example, the source device hostname and IP address are named SrcHostname and SrcIpAddr respectively, and not SrcDvcHostname and SrcDvcIpAddr. The prefix Dvc is only used for the reporting or intermediary device, as applicable.
Fields that describe the user and application associated with the source and destination devices also use the Src and Dst descriptors.
Other ASIM schemas typically use Target instead of Dst.
Common fields
Fields common to all schemas are described in the ASIM schema overview. The following fields have specific guidelines for Process Events:
| Field | Class | Type | Description |
|---|---|---|---|
| EventCount | Mandatory | Integer | Netflow sources support aggregation, and the EventCount field should be set to the value of the Netflow FLOWS field. For other sources, the value is typically set to 1. |
| EventType | Mandatory | Enumerated | Describes the operation reported by the record. For Network Sessions records, supported values include: - NetworkConnection- NetworkSession |
| EventSubType | Optional | String | Additional description of the event type, if applicable. For Network Sessions records, supported values include: - Start- End |
| EventSchema | Mandatory | String | The name of the schema documented here is NetworkSession. |
| EventSchemaVersion | Mandatory | String | The version of the schema. The version of the schema documented here is 0.2.1 |
| DvcAction | Optional | Enumerated | The action taken on the network session. Supported values are: - Allow- Deny- Drop- Drop ICMP- Reset- Reset Source- Reset Destination- Encrypt- Decrypt- VPNrouteNote: The value may be provided in the source record using different terms, which should be normalized to these values. The original value should be stored in the DvcOriginalAction field. Example: drop |
| Dvc fields | For Network Session Events, device fields refer to the system reporting the Network Session event. | ||
Network session fields
The following fields are common to all network session activity logging:
| Field | Class | Type | Description |
|---|---|---|---|
| Dst | Recommended | String | A unique identifier of the server receiving the DNS request. This field may alias the DstDvcId, DstHostname, or DstIpAddr fields. Example: 192.168.12.1 |
| DstIpAddr | Recommended | IP address | The IP address of the connection or session destination. Example: 2001:db8::ff00:42:8329Note: This value is mandatory if DstHostname is specified. |
| DstPortNumber | Optional | Integer | The destination IP port. Example: 443 |
| DstHostname | Recommended | String | The destination device hostname, excluding domain information. If no device name is available, store the relevant IP address in this field. Example: DESKTOP-1282V4DNote: This value is mandatory if DstIpAddr is specified. |
| Hostname | Alias | Alias to DstHostname | |
| DstDomain | Recommended | String | The domain of the destination device. Example: Contoso |
| DstDomainType | Recommended | Enumerated | The type of DstDomain, if known. Possible values include: - Windows (contoso\mypc)- FQDN (docs.microsoft.com)Required if DstDomain is used. |
| DstFQDN | Optional | String | The destination device hostname, including domain information when available. Example: Contoso\DESKTOP-1282V4D Note: This field supports both traditional FQDN format and Windows domain\hostname format. The DstDomainType reflects the format used. |
| DstDvcId | Optional | String | The ID of the destination device as reported in the record. Example: ac7e9755-8eae-4ffc-8a02-50ed7a2216c3 |
| DstDvcIdType | Optional | Enumerated | The type of DstDvcId, if known. Possible values include: - AzureResourceId- MDEidIfIf multiple IDs are available, use the first one from the list above, and store the others in the DstDvcAzureResourceId or DstDvcMDEid fields, respectively. Required if DstDeviceId is used. |
| DstDeviceType | Optional | Enumerated | The type of the destination device. Possible values include: - Computer- Mobile Device- IOT Device- Other |
| DstUserId | Optional | String | A machine-readable, alphanumeric, unique representation of the destination user. Supported formats and types include: - SID (Windows): S-1-5-21-1377283216-344919071-3415362939-500- UID (Linux): 4578- AADID (Azure Active Directory): 9267d02c-5f76-40a9-a9eb-b686f3ca47aa- OktaId: 00urjk4znu3BcncfY0h7- AWSId: 72643944673Store the ID type in the DstUserIdType field. If other IDs are available, we recommend that you normalize the field names to DstUserSid, DstUserUid, DstUserAADID, DstUserOktaId and UserAwsId, respectively. For more information, see The User entity. Example: S-1-12 |
| DstUserIdType | Optional | Enumerated | The type of the ID stored in the DstUserId field. Supported values are: SID, UIS, AADID, OktaId, and AWSId. |
| DstUsername | Optional | String | The Destination username, including domain information when available. Use one of the following formats and in the following order of priority: - Upn/Email: johndow@contoso.com- Windows: Contoso\johndow- DN: CN=Jeff Smith,OU=Sales,DC=Fabrikam,DC=COM- Simple: johndow. Use the Simple form only if domain information is not available.Store the Username type in the DstUsernameType field. If other IDs are available, we recommend that you normalize the field names to DstUserUpn, DstUserWindows and DstUserDn.For more information, see The User entity. Example: AlbertE |
| User | Alias | Alias to DstUsername | |
| DstUsernameType | Optional | Enumerated | Specifies the type of the username stored in the DstUsername field. Supported values include: UPN, Windows, DN, and Simple. For more information, see The User entity.Example: Windows |
| DstUserType | Optional | Enumerated | The type of Actor. Supported values include: - Regular- Machine- Admin- System- Application- Service Principal- OtherNote: The value may be provided in the source record using different terms, which should be normalized to these values. Store the original value in the DstOriginalUserType field. |
| DstOriginalUserType | Optional | String | The original destination user type, if provided by the source. |
| DstUserDomain | Optional | String | This field is kept for backward compatibility only. ASIM requires domain information, if available, to be part of the DstUsername field. |
| DstAppName | Optional | String | The name of the destination application. Example: Facebook |
| DstAppId | Optional | String | The ID of the destination application, as reported by the reporting device. Example: 124 |
| DstAppType | Optional | String | The type of the application authorizing on behalf of the Actor. Supported values include: - Process- Service- Resource- URL- SaaS application- OtherThis field is mandatory if DstAppName or DstAppId are used. |
| DstZone | Optional | String | The network zone of the destination, as defined by the reporting device. Example: Dmz |
| DstInterfaceName | Optional | String | The network interface used for the connection or session by the destination device. Example: Microsoft Hyper-V Network Adapter |
| DstInterfaceGuid | Optional | String | The GUID of the network interface used on the destination device. Example: 46ad544b-eaf0-47ef-827c-266030f545a6 |
| DstMacAddr | Optional | String | The MAC address of the network interface at used for the connection or session by the destination device. Example: 06:10:9f:eb:8f:14 |
| DstVlanId | Optional | String | The VLAN ID related to the destination device. Examples: 130 |
| OuterVlanId | Optional | Alias | Alias to DstVlanId. In many cases the VLAN can not be determined as a source or a destination but are characterized as inner or outer. This alias to signifies that DstVlanId should be used when the VLAN is characterized as outer. |
| DstGeoCountry | Optional | Country | The country associated with the destination IP address. For more information, see Logical types. Example: USA |
| DstGeoRegion | Optional | Region | The region, or state, within a country associated with the destination IP address. For more information, see Logical types. Example: Vermont |
| DstGeoCity | Optional | City | The city associated with the destination IP address. For more information, see Logical types. Example: Burlington |
| DstGeoLatitude | Optional | Latitude | The latitude of the geographical coordinate associated with the destination IP address. For more information, see Logical types. Example: 44.475833 |
| DstGeoLongitude | Optional | Longitude | The longitude of the geographical coordinate associated with the destination IP address. For more information, see Logical types. Example: 73.211944 |
| Src | Recommended | String | A unique identifier of the source device. This field may alias the SrcDvcId, SrcHostname, or SrcIpAddr fields. Example: 192.168.12.1 |
| SrcIpAddr | Recommended | IP address | The IP address from which the connection or session originated. This value is mandatory if SrcHostname is specified. Example: 77.138.103.108 |
| IpAddr | Alias | Alias to SrcIpAddr | |
| SrcPortNumber | Optional | Integer | The IP port from which the connection originated. May not be relevant for a session comprising multiple connections. Example: 2335 |
| SrcHostname | Recommended | String | The source device hostname, excluding domain information. If no device name is available, store the relevant IP address in this field.This value is mandatory if SrcIpAddr is specified. Example: DESKTOP-1282V4D |
| SrcDomain | Recommended | String | The domain of the source device. Example: Contoso |
| SrcDomainType | Recommended | Enumerated | The type of SrcDomain, if known. Possible values include: - Windows (such as: contoso)- FQDN (such as: microsoft.com)Required if SrcDomain is used. |
| SrcFQDN | Optional | String | The source device hostname, including domain information when available. Note: This field supports both traditional FQDN format and Windows domain\hostname format. The SrcDomainType field reflects the format used. Example: Contoso\DESKTOP-1282V4D |
| SrcDvcId | Optional | String | The ID of the source device as reported in the record. For example: ac7e9755-8eae-4ffc-8a02-50ed7a2216c3 |
| SrcDvcIdType | Optional | Enumerated | The type of SrcDvcId, if known. Possible values include: - AzureResourceId- MDEidIf multiple IDs are available, use the first one from the list above, and store the others in the SrcDvcAzureResourceId and SrcDvcMDEid, respectively. Note: This field is required if SrcDvcId is used. |
| SrcDeviceType | Optional | Enumerated | The type of the source device. Possible values include: - Computer- Mobile Device- IOT Device- Other |
| SrcUserId | Optional | String | A machine-readable, alphanumeric, unique representation of the source user. Format and supported types include: - SID (Windows): S-1-5-21-1377283216-344919071-3415362939-500- UID (Linux): 4578- AADID (Azure Active Directory): 9267d02c-5f76-40a9-a9eb-b686f3ca47aa- OktaId: 00urjk4znu3BcncfY0h7- AWSId: 72643944673Store the ID type in the SrcUserIdType field. 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. Example: S-1-12 |
| SrcUserIdType | Optional | Enumerated | The type of the ID stored in the SrcUserId field. Supported values include: SID, UIS, AADID, OktaId, and AWSId. |
| SrcUsername | Optional | String | The Source username, including domain information when available. Use one of the following formats and in the following order of priority: - Upn/Email: johndow@contoso.com- Windows: Contoso\johndow- DN: CN=Jeff Smith,OU=Sales,DC=Fabrikam,DC=COM- Simple: johndow. Use the Simple form only if domain information is not available.Store the Username type in the SrcUsernameType field. If other IDs are available, we recommend that you normalize the field names to SrcUserUpn, SrcUserWindows and SrcUserDn. For more information, see The User entity. Example: AlbertE |
| SrcUsernameType | Optional | Enumerated | Specifies the type of the username stored in the SrcUsername field. Supported values are: UPN, Windows, DN, and Simple. For more information, see The User entity.Example: Windows |
| SrcUserType | Optional | Enumerated | The type of Actor. Allowed values are: - Regular- Machine- Admin- System- Application- Service Principal- OtherNote: The value may be provided in the source record using different terms, which should be normalized to these values. Store the original value in the SrcOriginalUserType field. |
| SrcOriginalUserType | The original source user type, if provided by the source. | ||
| SrcUserDomain | Optional | String | This field is kept for backward compatibility only. ASIM requires domain information, if available, to be part of the SrcUsername field. |
| SrcAppName | Optional | String | The name of the source application. Example: filezilla.exe |
| SrcAppId | Optional | String | The ID of the destination application, as reported by the reporting device. Example: 124 |
| SrcAppType | Optional | String | The type of the source application. Supported values include: - Process- Service- Resource- OtherThis field is mandatory if SrcAppName or SrcAppId are used. |
| SrcZone | Optional | String | The network zone of the source, as defined by the reporting device. Example: Internet |
| SrcIntefaceName | Optional | String | The network interface used for the connection or session by the source device. Example: eth01 |
| SrcInterfaceGuid | Optional | String | The GUID of the network interface used on the source device. Example: 46ad544b-eaf0-47ef-827c-266030f545a6 |
| SrcMacAddr | Optional | String | The MAC address of the network interface from which the connection or session originated. Example: 06:10:9f:eb:8f:14 |
| SrcVlanId | Optional | String | The VLAN ID related to the source device. Examples: 130 |
| InnerVlanId | Optional | Alias | Alias to SrcVlanId. In many cases the VLAN can not be determined as a source or a destination but are characterized as inner or outer. This alias to signifies that SrcVlanId should be used when the VLAN is characterized as inner. |
| SrcGeoCountry | Optional | Country | The country associated with the source IP address. Example: USA |
| SrcGeoRegion | Optional | Region | The region within a country associated with the source IP address. Example: Vermont |
| SrcGeoCity | Optional | City | The city associated with the source IP address. Example: Burlington |
| SrcGeoLatitude | Optional | Latitude | The latitude of the geographical coordinate associated with the source IP address. Example: 44.475833 |
| SrcGeoLongitude | Optional | Longitude | The longitude of the geographical coordinate associated with the source IP address. Example: 73.211944 |
| NetworkApplicationProtocol | Optional | String | The application layer protocol used by the connection or session. If the DstPortNumber value is provided, we recommend that you include NetworkApplicationProtocol too. If the value is not available from the source, derive the value from the DstPortNumber value. Example: FTP |
| NetworkProtocol | Optional | Enumerated | The IP protocol used by the connection or session as listed in IANA protocol assignment. Typically, TCP, UDP or ICMP.Example: TCP |
| NetworkDirection | Optional | Enumerated | The direction of the connection or session, into or out of the organization. Supported values include: Inbound, Outbound, Listen. Listen indicates that a device has started accepting network connections, but is not actually, necessarily, connected. |
| NetworkDuration | Optional | Integer | The amount of time, in milliseconds, for the completion of the network session or connection. Example: 1500 |
| Duration | Alias | Alias to NetworkDuration | |
| NetworkIcmpCode | Optional | Integer | For an ICMP message, the ICMP message type numeric value as described in RFC 2780 for IPv4 network connections, or in RFC 4443 for IPv6 network connections. If a NetworkIcmpType value is provided, this field is mandatory. If the value is not available from the source, derive the value from the NetworkIcmpType field instead. Example: 34 |
| NetworkIcmpType | Optional | String | For an ICMP message, the ICMP message type text representation, as described in RFC 2780 for IPv4 network connections, or in RFC 4443 for IPv6 network connections. Example: Destination Unreachable |
| NetworkConnectionHistory | Optional | String | TCP Flags and other potential IP header information. |
| DstBytes | Recommended | Integer | The number of bytes sent from the destination to the source for the connection or session. If the event is aggregated, DstBytes should be the sum over all aggregated sessions. Example: 32455 |
| SrcBytes | Recommended | Integer | The number of bytes sent from the source to the destination for the connection or session. If the event is aggregated, SrcBytes should be the sum over all aggregated sessions. Example: 46536 |
| NetworkBytes | Optional | Integer | Number of bytes sent in both directions. If both BytesReceived and BytesSent exist, BytesTotal should equal their sum. If the event is aggregated, NetworkBytes should be the sum over all aggregated sessions. Example: 78991 |
| DstPackets | Optional | Integer | The number of packets sent from the destination to the source for the connection or session. The meaning of a packet is defined by the reporting device.If the event is aggregated, DstPackets should be the sum over all aggregated sessions. Example: 446 |
| SrcPackets | Optional | Integer | The number of packets sent from the source to the destination for the connection or session. The meaning of a packet is defined by the reporting device. If the event is aggregated, SrcPackets should be the sum over all aggregated sessions. Example: 6478 |
| NetworkPackets | Optional | Integer | The number of packets sent in both directions. If both PacketsReceived and PacketsSent exist, BytesTotal should equal their sum. The meaning of a packet is defined by the reporting device. If the event is aggregated, NetworkPackets should be the sum over all aggregated sessions. Example: 6924 |
| NetworkSessionId | Optional | string | The session identifier as reported by the reporting device. Example: 172\_12\_53\_32\_4322\_\_123\_64\_207\_1\_80 |
| SessionId | Alias | String | Alias to NetworkSessionId |
Intermediary device fields
The following fields are useful if the record includes information about an intermediary device, such as a Firewall or a Proxy, which relays the network session.
| Field | Class | Type | Description |
|---|---|---|---|
| DstNatIpAddr | Optional | IP address | If reported by an intermediary NAT device, the IP address used by the NAT device for communication with the source. Example: 2::1 |
| DstNatPortNumber | Optional | Integer | If reported by an intermediary NAT device, the port used by the NAT device for communication with the source. Example: 443 |
| SrcNatIpAddr | Optional | IP address | If reported by an intermediary NAT device, the IP address used by the NAT device for communication with the destination. Example: 4.3.2.1 |
| SrcNatPortNumber | Optional | Integer | If reported by an intermediary NAT device, the port used by the NAT device for communication with the destination. Example: 345 |
| DvcInboundInterface | Optional | String | If reported by an intermediary device, the network interface used by the NAT device for the connection to the source device. Example: eth0 |
| DvcOutboundInterface | Optional | String | If reported by an intermediary device, the network interface used by the NAT device for the connection to the destination device. Example: Ethernet adapter Ethernet 4e |
Inspection fields
The following fields are used to represent that inspection which a security device such as a firewall, an IPS or a Web Security Gateway performed:
| Field | Class | Type | Description |
|---|---|---|---|
| NetworkRuleName | Optional | String | The name or ID of the rule by which DvcAction was decided upon. Example: AnyAnyDrop |
| NetworkRuleNumber | Optional | Integer | The number of the rule by which DvcAction was decided upon. Example: 23 |
| Rule | Mandatory | String | Either NetworkRuleName or NetworkRuleNumber |
| ThreatId | Optional | String | The ID of the threat or malware identified in the network session. Example: Tr.124 |
| ThreatName | Optional | String | The name of the threat or malware identified in the network session. Example: EICAR Test File |
| ThreatCategory | Optional | String | The category of the threat or malware identified in the network session. Example: Trojan |
| ThreatRiskLevel | Optional | Integer | The risk level associated with the Session. The level should be a number between 0 and a 100. Note: The value may be provided in the source record using a different scale, which should be normalized to this scale. The original value should be stored in ThreatRiskLevelOriginal. |
| ThreatRiskLevelOriginal | Optional | String | The risk level as reported by the reporting device. |
Other fields
If the event is reported by one of the endpoints of the network session, it may include information about the process that initiated or terminated the session. In such cases, the ASIM Process Event schema to normalize this information.
Schema updates
These are the changes in version 0.2.1 of the schema:
- Added
SrcandDstas aliases to a leading identifier for the source and destination systems. - Added the fields
NetworkConnectionHistory,SrcVlanId,DstVlanId,InnerVlanId, andOuterVlanId
Next steps
For more information, see: