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).
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.
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.
For more information about ASIM parsers, see the ASIM parsers overview.
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
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 parsers
ASimWebSession<vendor><Product>for regular parsers
Filtering parser parameters
vim* parsers support filtering parameters. While these parsers are optional, they can improve your query performance.
The following filtering parameters are available:
|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
|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
The field ASimMatchingIpAddr is set with the one of the values
|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:
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)
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
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:
|EventType||Mandatory||Enumerated||Describes the operation reported by the record. Allowed values are:
|EventResult||Mandatory||Enumerated||Describes the event result, normalized to one of the following values:
For an HTTP session,
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
|EventSchemaVersion||Mandatory||String||The version of the schema. The version of the schema documented here is
|Dvc fields||For Web Session events, device fields refer to the system reporting the Web Session event. This is typically an intermediary device for
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.
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
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:
|Url||Mandatory||String||The HTTP request URL, including parameters. For
|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.
|HttpRequestMethod||Recommended||Enumerated||The HTTP Method. The values are as defined in RFC 7231 and RFC 5789, and include
|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.
|HttpContentFormat||Optional||String||The content format part of the HttpContentType
|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.
|HttpUserAgent||Optional||String||The HTTP user agent header.
|UserAgent||Alias||Alias to HttpUserAgent|
|HttpRequestXff||Optional||IP Address||The HTTP X-Forwarded-For header.
|HttpRequestTime||Optional||Integer||The amount of time, in milliseconds, it took to send the request to the server, if applicable.
|HttpResponseTime||Optional||Integer||The amount of time, in milliseconds, it took to receive a response in the server, if applicable.
|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.
|FileSHA1||Optional||SHA1||For HTTP uploads, the SHA1 hash of the uploaded file.
|FileSHA256||Optional||SHA256||For HTTP uploads, the SHA256 hash of the uploaded file.
|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:
|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.|
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.
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
The following are the changes in version 0.2.6 of the schema:
- The type of FileSize was changed from Integer to Long.
For more information, see: