Azure Sentinel File Event normalization schema reference (Public preview)

The File Event normalization schema is used to describe file activity such as creating, modifying, or deleting files or documents. Such events are reported by operating systems, file storage systems such as Azure Files, and document management systems such as Microsoft SharePoint.

For more information about normalization in Azure Sentinel, see Normalization and the Azure Sentinel Information Model (ASIM).

Important

The File Event 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.

Parsers

Azure Sentinel provides the following built-in, product-specific file event parsers:

  • Sysmon file activity events (Events 11, 23, and 26), collected using the Log Analytics Agent or Azure Monitor Agent.
  • Microsoft Office 365 SharePoint and OneDrive events, collected using the Office Activity connector.
  • Microsoft 365 Defender for Endpoints file events
  • Azure Storage, including Blob, File, Queue, and Table Storage.

To use the source-agnostic parser that unifies all of the built-in parsers, and ensure that your analysis runs across all the configured sources, use imFileEvent as the table name in your query.

Deploy the source-agnostic and source-specific parsers from the Azure Sentinel GitHub repository.

Add your own normalized parsers

When implementing custom parsers for the File Event information model, name your KQL functions using the following syntax: imFileEvent<vendor><Product.

Add your KQL function to the imFileEvent source-agnostic parser to ensure that any content using the File Event model also uses your new parser.

Normalized content for file activity data

Support for the File Activity ASIM schema also includes support for the following built-in analytics rules with normalized file activity parsers. While links to the Azure Sentinel GitHub repository are provided below as a reference, you can also find these rules in the Azure Sentinel Analytics rule gallery. Use the linked GitHub pages to copy any relevant hunting queries for the listed rules.

For more information, see Create custom analytics rules to detect threats.

Schema details

The File Event information model is aligned to the OSSEM Process entity schema.

Log Analytics fields

The following fields are generated by Log Analytics for each record, and can be overridden when creating a custom connector.

Field Type Discussion
TimeGenerated datetime The time the event was generated by the reporting device.
_ResourceId guid The Azure Resource ID of the reporting device or service, or the log forwarder resource ID for events forwarded using Syslog, CEF, or WEF.
Type String The original table from which the record was fetched. This field is useful when the same event can be received through multiple channels to different tables, and have the same EventVendor and EventProduct values.

For example, a Sysmon event can be collected either to the Event table or to the WindowsEvent table.

Note

Log Analytics also adds other fields that are less relevant to security use cases. For more information, see Standard columns in Azure Monitor Logs.

Event fields

Event fields are common to all schemas and describe the activity itself and the reporting device.

Field Class Type Description
EventMessage Optional String A general message or description, either included in or generated from the record.
EventCount Mandatory Integer The number of events described by the record.

This value is used when the source supports aggregation, and a single record may represent multiple events.

For other sources, set to 1.
EventStartTime Mandatory Date/time If the source supports aggregation and the record represents multiple events, this field specifies the time that the first event was generated. Otherwise, this field aliases the TimeGenerated field.
EventEndTime Mandatory Alias Alias to the TimeGenerated field.
EventType Mandatory Enumerated Describes the operation reported by the record.

For File records, supported values include:

- FileCreated
- FileModified
- FileDeleted
- FileRenamed
- FileCopied
- FileMoved
- FolderCreated
- FolderDeleted
EventResult Mandatory Enumerated Describes the result of the event, normalized to one of the following supported values:

- Success
- Partial
- Failure
- NA (not applicable)

The source may provide only a value for the EventOriginalResultDetails field, which must be analyzed to get the EventResult value.
EventOriginalResultDetails Optional String Describes the result of the event.

Note: This value is not normalized, and is intended for the original value as provided by the data source. There is currently no related, normalized field, such as EventResultDetails, for the File Event normalization schema.
EventOriginalUid Optional String A unique ID of the original record, if provided by the source.

Example: 69f37748-ddcd-4331-bf0f-b137f1ea83b
EventOriginalType Optional String The original event type or ID, if provided by the source.

Example: 4663
EventProduct Mandatory String The product generating the event.

Example: Sysmon

Note: This field may not be available in the source record. In such cases, this field must be set by the parser.
EventProductVersion Optional String The version of the product generating the event.

Example: 12.1

Note: This field may not be available in the source record. In such cases, this field must be set by the parser.
EventVendor Mandatory String The vendor of the product generating the event.

Example: Microsoft

Note: This field may not be available in the source record. In such cases, this field must be set by the parser.
EventSchemaVersion Mandatory String The version of the schema. The version of the schema documented here is 0.1
EventReportUrl Optional String A URL provided in the event for a resource that provides additional information about the event.
Dvc Alias String A unique identifier of the device on which the event occurred.

For example: ContosoDc.Contoso.Azure

This field may alias the DvcId, DvcHostname, or DvcIpAddr fields. For cloud sources, for which there is no apparent device, use the same value as the EventProduct field.
DvcIpAddr Recommended IP Address The IP Address of the device on which the file event occurred.

Example: 45.21.42.12
DvcHostname Recommended Hostname The hostname of the device on which the file event occurred.

Example: ContosoDc.Contoso.Azure
DvcId Optional String The unique ID of the device on which the file event occurred.

Example: 41502da5-21b7-48ec-81c9-baeea8d7d669
DvcMacAddr Optional MAC The MAC of device on which the file event occurred.

Example: 00:1B:44:11:3A:B7
DvcOs Optional String The operating system running on the device on which the file event occurred.

Example: Windows
DvcOsVersion Optional String The version of the operating system on the device on which the file event occurred.

Example: 10
AdditionalFields Optional Dynamic If your source provides additional information worth preserving, either keep it with the original field names or create the dynamic AdditionalFields field, and add to it the extra information as key/value pairs.

File event specific fields

The fields listed in the table below are specific to File events, but are similar to fields in other schemas and follow similar naming conventions.

The File Event schema references the following entities, which are central to file activities:

  • Actor. The user that initiated the file activity
  • ActingProcess. The process used by the Actor to initiate the file activity
  • TargetFile. The file on which the operation was performed
  • Source File (SrcFile). Stores file information prior to the operation.

The relationship between these entities is best demonstrated as follows: An Actor performs a file operation using an Acting Process, which modifies the Source File to Target File.

For example: JohnDoe (Actor) uses Windows File Explorer (Acting process) to rename new.doc (Source File) to old.doc (Target File).

Field Class Type Description
ActingProcessCommandLine Optional String The command line used to run the acting process.

Example: "choco.exe" -v
ActingProcessGuid Optional String A generated unique identifier (GUID) of the acting process. Enables identifying the process across systems.

Example: EF3BD0BD-2B74-60C5-AF5C-010000001E00
ActingProcessId Mandatory String The process ID (PID) of the acting process.

Example: 48610176

Note: The type is defined as string to support varying systems, but on Windows and Linux this value must be numeric.

If you are using a Windows or Linux machine and used a different type, make sure to convert the values. For example, if you used a hexadecimal value, convert it to a decimal value.
ActingProcessName Optional String The name of the acting process. This name is commonly derived from the image or executable file that's used to define the initial code and data that's mapped into the process' virtual address space.

Example: C:\Windows\explorer.exe
Process Alias Alias to ActingProcessName
ActorUserId Recommended String A unique ID of the Actor. The specific ID depends on the system generating the event. For more information, see The User entity.

Example: S-1-5-18
ActorUserIdType Recommended String The type of the ID stored in the ActorUserId field. For more information, see The User entity.

Example: SID
ActorUsername Mandatory String The user name of the user who initiated the event.

Example: CONTOSO\WIN-GG82ULGC9GO$
ActorUsernameType Mandatory Enumerated Specifies the type of the user name stored in the ActorUsername field. For more information, see The User entity.

Example: Windows
User Alias Alias to the ActorUsername field.

Example: CONTOSO\dadmin
ActorUserType Optional Enumerated The type of Actor. Supported values include:

- Regular
- Machine
- Admin
- System
- Application
- Service Principal
- Other

Note: The source may provide only a value for the ActorOriginalUserType field, which must be analyzed to get the ActorUserType value.
ActorOriginalUserType Optional String The Actor user type, as provided by the reporting device.
HttpUserAgent Optional String When the operation is initiated by a remote system using HTTP or HTTPS, the user agent used.

For example:
Mozilla/5.0 (Windows NT 10.0; Win64; x64)
AppleWebKit/537.36 (KHTML, like Gecko)
Chrome/42.0.2311.135
Safari/537.36 Edge/12.246
NetworkApplicationProtocol Optional String When the operation is initiated by a remote system, this value is the application layer protocol used in the OSI model.

While this field is not enumerated, and any value is accepted, preferable values include: HTTP, HTTPS, SMB,FTP, and SSH

Example: SMB
SrcIpAddr Recommended IP Address When the operation is initiated by a remote system, the IP address of this system.

Example: 185.175.35.214
SrcFileCreationTime Optional Date/Time The time at which the source file was created.
SrcFileDirectory Optional String The source file folder or location. This field should be similar to the SrcFilePath field, without the final element.

Note: A parser can provide this value if the value is available in the log source, and does not need to be extracted from the full path.
SrcFileExtension Optional String The source file extension.

Note: A parser can provide this value the value is available in the log source, and does not need to be extracted from the full path.
SrcFileMimeType Optional Enumerated The Mime or Media type of the source file. Supported values are listed in the IANA Media Types repository.
SrcFileName Optional String The name of the source file, without a path or a location, but with an extension if relevant. This field should be similar to the last element in the SrcFilePath field.

Note: A parser can provide this value if the value available in the log source and does not need to be extracted from the full path.
SrcFilePath Mandatory String The full, normalized path of the source file, including the folder or location, the file name, and the extension.

For more information, see Path structure.

Example: /etc/init.d/networking
SrcFilePathType Mandatory Enumerated The type of SrcFilePath. For more information, see Path structure.
SrcFileMD5 Optional MD5 The MD5 hash of the source file.

Example: 75a599802f1fa166cdadb360960b1dd0
SrcFileSHA1 Optional SHA1 The SHA-1 hash of the source file.

Example:
d55c5a4df19b46db8c54
c801c4665d3338acdab0
SrcFileSHA256 Optional SHA256 The SHA-256 hash of the source file.

Example:
e81bb824c4a09a811af17deae22f22dd
2e1ec8cbb00b22629d2899f7c68da274
SrcFileSHA512 Optional SHA512 The SHA-512 hash of the source file.
SrcFileSize Optional Integer The size of the source file in bytes.
TargetFileCreationTime Optional Date/Time The time at which the target file was created.
TargetFileDirectory Optional String The target file folder or location. This field should be similar to the TargetFilePath field, without the final element.

Note: A parser can provide this value if the value available in the log source and does not need to be extracted from the full path.
TargetFileExtension Optional String The target file extension.

Note: A parser can provide this value if the value available in the log source and does not need to be extracted from the full path.
TargetFileMimeType Optional Enumerated The Mime, or Media, type of the target file. Allowed values are listed in the IANA Media Types repository.
TargetFileName Optional String The name of the target file, without a path or a location, but with an extension if relevant. This field should be similar to the final element in the TargetFilePath field.

Note: A parser can provide this value if the value available in the log source and does not need to be extracted from the full path.
TargetFilePath Mandatory String The full, normalized path of the target file, including the folder or location, the file name, and the extension. For more information, see Path structure.

Note: If the record does not include folder or location information, store the filename only here.

Example: C:\Windows\System32\notepad.exe
TargetFilePathType Mandatory Enumerated The type of TargetFilePath. For more information, see Path structure.
FilePath Alias Alias to the TargetFilePath field.
TargetFileMD5 Optional MD5 The MD5 hash of the target file.

Example: 75a599802f1fa166cdadb360960b1dd0
TargetFileSHA1 Optional SHA1 The SHA-1 hash of the target file.

Example:
d55c5a4df19b46db8c54
c801c4665d3338acdab0
TargetFileSHA256 Optional SHA256 The SHA-256 hash of the target file.

Example:
e81bb824c4a09a811af17deae22f22dd
2e1ec8cbb00b22629d2899f7c68da274
TargetFileSHA512 Optional SHA512 The SHA-512 hash of the source file.
Hash Alias Alias to the best available Target File hash.
TargetFileSize Optional Integer The size of the target file in bytes.
TargetUrl Optional String When the operation is initiated using HTTP or HTTPS, the URL used.

Example: https://onedrive.live.com/?authkey=...

Path structure

The path should be normalized to match one of the following formats. The format the value is normalized to will be reflected in the respective FilePathType field.

Type Example Notes
Windows Local C:\Windows\System32\notepad.exe Since Windows path names are case insensitive, this type implies that the value is case insensitive.
Windows Share \\Documents\My Shapes\Favorites.vssx Since Windows path names are case insensitive, this type implies that the value is case insensitive.
Unix /etc/init.d/networking Since Unix path names are case-sensitive, this type implies that the value is case-sensitive.

- Use this type for AWS S3. Concatenate the bucket and key names to create the path.

- Use this type for Azure Blob storage object keys.
URL https://1drv.ms/p/s!Av04S_*********we Use when the file path is available as a URL. URLs are not limited to http or https, and any value, including an FTP value, is valid.

Next steps

For more information, see: