The Advanced Security Information Model (ASIM) Web Session normalization schema reference (Public preview)
The Web Session normalization schema is used to describe an IP network activity. For example, IP network activities are reported by web servers, web proxies, and web security gateways.
For more information about normalization in Microsoft Sentinel, see Normalization and the Advanced Security Information Model (ASIM).
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 Web Session normalization schema represents any HTTP network session, and is suitable to provide support for common source types, including:
- Web servers
- Web proxies
- Web security gateways
The ASIM Web Session schema represents HTTP and HTTPS protocol activity. Since the schema represents protocol activity, it is governed by RFCs and officially assigned parameter lists, which are referenced in this article when appropriate.
The Web Session schema doesn't represent audit events from source devices. For example, an event modifying a Web Security Gateway policy can't be represented by the Web Session schema.
Since HTTP sessions are application layer sessions that utilize TCP/IP as the underlying network layer session, the Web Session schema is a super set of the ASIM Network Session schema.
The most important fields in a Web Session schema are:
- Url, which reports the url that the client requested from the server.
- The SrcIpAddr (aliased to IpAddr), which represents the IP address from which the request was generated.
- EventResultDetails field, which typically reports the HTTP Status Code.
Web Session events may also include User and Process information for the user and process initiating the request.
Parsers
For more information about ASIM parsers, see the ASIM parsers overview.
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_WebSession filtering parser or the _ASim_WebSession parameter-less parser.
You can also use workspace-deployed ImWebSession and ASimWebSession parsers by deploying them from the Microsoft Sentinel GitHub repository. For more information, see built-in ASIM parsers and workspace-deployed parsers.
Out-of-the-box, source-specific parsers
For the list of the Web Session parsers Microsoft Sentinel provides out-of-the-box refer to the ASIM parsers list
Add your own normalized parsers
When implementing custom parsers for the Web Session information model, name your KQL functions using the following syntax:
vimWebSession<vendor><Product>for parametrized parsersASimWebSession<vendor><Product>for regular parsers
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 Web sessions that started at or after this time. |
| endtime | datetime | Filter only Web sessions that started running at or before this time. |
| srcipaddr_has_any_prefix | dynamic | Filter only Web sessions for which the source IP address field prefix is in one of the listed values. The list of values can include IP addresses and IP address prefixes. Prefixes should end with a ., for example: 10.0.. The length of the list is limited to 10,000 items. |
| ipaddr_has_any_prefix | dynamic | Filter only network sessions for which the destination IP address field or source IP address field prefix is in one of the listed values. Prefixes should end with a ., for example: 10.0.. The length of the list is limited to 10,000 items.The field ASimMatchingIpAddr is set with the one of the values SrcIpAddr, DstIpAddr, or Both to reflect the matching fields or fields. |
| url_has_any | dynamic | Filter only Web sessions for which the URL field has any of the values listed. The parser may ignore the schema of the URL passed as a parameter, if the source does not report it. If specified, and the session is not a web session, no result will be returned. The length of the list is limited to 10,000 items. |
| httpuseragent_has_any | dynamic | Filter only web sessions for which the user agent field has any of the values listed. If specified, and the session is not a web session, no result will be returned. The length of the list is limited to 10,000 items. |
| eventresultdetails_in | dynamic | Filter only web sessions for which the HTTP status code, stored in the EventResultDetails field, is any of the values listed. |
| eventresult | string | Filter only network sessions with a specific EventResult value. |
Some parameter can accept both list of values of type dynamic or a single string value. To pass a literal list to parameters that expect a dynamic value, explicitly use a dynamic literal. For example: dynamic(['192.168.','10.'])
For example, to filter only Web sessions for a specified list of domain names, use:
let torProxies=dynamic(["tor2web.org", "tor2web.com", "torlink.co"]);
_Im_WebSession (url_has_any = torProxies)
Schema details
The Web Session information model is aligned with the OSSEM Network entity schema and the OSSEM HTTP entity schema.
To conform with industry best practices, the Web Session schema uses the descriptors Src and Dst to identify the 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 ASIM fields
Important
Fields common to all schemas are described in detail in the ASIM Common Fields article.
Common fields with specific guidelines
The following list mentions fields that have specific guidelines for Web Session events:
| Field | Class | Type | Description |
|---|---|---|---|
| EventType | Mandatory | Enumerated | Describes the operation reported by the record. Allowed values are: - HTTPsession: Denotes a network session used for HTTP or HTTPS, typically reported by an intermediary device, such as a proxy or a Web security gateway.- WebServerSession: Denotes an HTTP request reported by a web server. Such an event typically has less network related information. The URL reported should not include a schema and a server name, but only the path and parameters part of the URL. - ApiRequest: Denotes an HTTP request reported associated with an API call, typically reported by an application server. Such an event typically has less network related information. When reported by the application server, the URL reported should not include a schema and a server name, but only the path and parameters part of the URL. |
| EventResult | Mandatory | Enumerated | Describes the event result, normalized to one of the following values: - Success - Partial - Failure - NA (not applicable) For an HTTP session, Success is defined as a status code lower than 400, and Failure is defined as a status code higher than 400. For a list of HTTP status codes, refer to W3 Org.The source may provide only a value for the EventResultDetails field, which must be analyzed to get the EventResult value. |
| EventResultDetails | Recommended | String | The HTTP status code. Note: 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 EventOriginalResultDetails field. |
| EventSchema | Mandatory | String | The name of the schema documented here is WebSession. |
| EventSchemaVersion | Mandatory | String | The version of the schema. The version of the schema documented here is 0.2.6 |
| Dvc fields | For Web Session events, device fields refer to the system reporting the Web Session event. This is typically an intermediary device for HTTPSession events, and the destination web or application server for WebServerSession and ApiRequest events. |
All common fields
Fields that appear in the table below are common to all ASIM schemas. Any guideline specified above overrides the general guidelines for the field. For example, a field might be optional in general, but mandatory for a specific schema. For further details on each field, refer to the ASIM Common Fields article.
| Class | Fields |
|---|---|
| Mandatory | - EventCount - EventStartTime - EventEndTime - EventType - EventResult - EventProduct - EventVendor - EventSchema - EventSchemaVersion - Dvc |
| Recommended | - EventResultDetails - EventSeverity - EventUid - DvcIpAddr - DvcHostname - DvcDomain - DvcDomainType - DvcFQDN - DvcId - DvcIdType - DvcAction |
| Optional | - EventMessage - EventSubType - EventOriginalUid - EventOriginalType - EventOriginalSubType - EventOriginalResultDetails - EventOriginalSeverity - EventProductVersion - EventReportUrl - EventOwner - DvcZone - DvcMacAddr - DvcOs - DvcOsVersion - DvcOriginalAction - DvcInterface - AdditionalFields - DvcDescription - DvcScopeId - DvcScope |
Network session fields
HTTP sessions are application layer sessions that utilize TCP/IP as the underlying network layer session. The Web Session schema is a super set of ASIM Network Session schema and all the Network Schema Fields are also included in the Web Session schema.
The following ASIM Network Session schema fields have specific guidelines when used for a Web Session event:
- The alias User should refer to the SrcUsername and not to DstUsername.
- The field EventOriginalResultDetails can hold any result reported by the source in addition to the HTTP status code stored in EventResultDetails.
- For Web Sessions, the primary destination field is the Url Field. The DstDomain is optional rather than recommended. Specifically, if not available, there is no need to extract it from the URL in the parser.
- The fields
NetworkRuleNameandNetworkRuleNumberare renamedRuleNameandRuleNumberrespectively.
Web Session events are commonly reported by intermediate devices that terminate the HTTP connection from the client and initiate a new connection, acting as a proxy, with the server. To represent the intermediate device, use the ASIM Network Session schema Intermediary device fields
HTTP session fields
The following are additional fields that are specific to web sessions:
| Field | Class | Type | Description |
|---|---|---|---|
| Url | Mandatory | String | The HTTP request URL, including parameters. For HTTPSession events, the URL may include the schema and should include the server name. For WebServerSession and for ApiRequest the URL would typically not include the schema and server, which can be found in the NetworkApplicationProtocol and DstFQDN fields respectively. Example: https://contoso.com/fo/?k=v&q=u#f |
| UrlCategory | Optional | String | The defined grouping of a URL or the domain part of the URL. The category is commonly provided by web security gateways and is based on the content of the site the URL points to. Example: search engines, adult, news, advertising, and parked domains. |
| UrlOriginal | Optional | String | The original value of the URL, when the URL was modified by the reporting device and both values are provided. |
| HttpVersion | Optional | String | The HTTP Request Version. Example: 2.0 |
| HttpRequestMethod | Recommended | Enumerated | The HTTP Method. The values are as defined in RFC 7231 and RFC 5789, and include GET, HEAD, POST, PUT, DELETE, CONNECT, OPTIONS, TRACE, and PATCH.Example: GET |
| HttpStatusCode | Alias | The HTTP Status Code. Alias to EventResultDetails. | |
| HttpContentType | Optional | String | The HTTP Response content type header. Note: The HttpContentType field may include both the content format and extra parameters, such as the encoding used to get the actual format. Example: text/html; charset=ISO-8859-4 |
| HttpContentFormat | Optional | String | The content format part of the HttpContentType Example: text/html |
| HttpReferrer | Optional | String | The HTTP referrer header. Note: ASIM, in sync with OSSEM, uses the correct spelling for referrer, and not the original HTTP header spelling. Example: https://developer.mozilla.org/docs |
| HttpUserAgent | Optional | String | The HTTP user agent header. Example: Mozilla/5.0 (Windows NT 10.0; WOW64)AppleWebKit/537.36 (KHTML, like Gecko)Chrome/83.0.4103.97 Safari/537.36 |
| UserAgent | Alias | Alias to HttpUserAgent | |
| HttpRequestXff | Optional | IP Address | The HTTP X-Forwarded-For header. Example: 120.12.41.1 |
| HttpRequestTime | Optional | Integer | The amount of time, in milliseconds, it took to send the request to the server, if applicable. Example: 700 |
| HttpResponseTime | Optional | Integer | The amount of time, in milliseconds, it took to receive a response in the server, if applicable. Example: 800 |
| HttpHost | Optional | String | The virtual web server the HTTP request has targeted. This value is typically based on the HTTP Host header. |
| FileName | Optional | String | For HTTP uploads, the name of the uploaded file. |
| FileMD5 | Optional | MD5 | For HTTP uploads, the MD5 hash of the uploaded file. Example: 75a599802f1fa166cdadb360960b1dd0 |
| FileSHA1 | Optional | SHA1 | For HTTP uploads, the SHA1 hash of the uploaded file. Example: d55c5a4df19b46db8c54c801c4665d3338acdab0 |
| FileSHA256 | Optional | SHA256 | For HTTP uploads, the SHA256 hash of the uploaded file. Example: e81bb824c4a09a811af17deae22f22dd2e1ec8cbb00b22629d2899f7c68da274 |
| FileSHA512 | Optional | SHA512 | For HTTP uploads, the SHA512 hash of the uploaded file. |
| Hash | Alias | Alias to the available Hash field. | |
| FileHashType | Optional | Enumerated | The type of the hash in the Hash field. Possible values include: MD5, SHA1, SHA256, and SHA512. |
| FileSize | Optional | Long | For HTTP uploads, the size in bytes of the uploaded file. |
| FileContentType | Optional | String | For HTTP uploads, the content type of the uploaded file. |
Other fields
If the event is reported by one of the endpoints of the web 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
The Web Session schema relies on the Network Session schema. Therefore, Network Session schema updates apply to the Web Session schema as well.
The following are the changes in version 0.2.5 of the schema:
- Added the field
HttpHost.
The following are the changes in version 0.2.6 of the schema:
- The type of FileSize was changed from Integer to Long.
Next steps
For more information, see: