Skip to main content

Who is this article for?

Incydr Professional, Enterprise, Horizon, and Gov F2
Incydr Basic, Advanced, and Gov F1

Find your product plan in the Code42 console on the Account menu.

Instructor, no.

Incydr Professional, Enterprise, Horizon, and Gov F2, yes.

Incydr Basic, Advanced, and Gov F1, yes.

CrashPlan Cloud, no.

CrashPlan for Small Business, no.

HOME
GETTING STARTED
RELEASE NOTES
FAQs
APIs
SYSTEM STATUS
Code42 Support

File event metadata changes June 2022

Overview

This article describes data model changes to Incydr file event metadata introduced on June 13, 2022. Most changes are minor and do not require you to take any action.

Changes include:

  • Reorganized file event details display order to better highlight insider risk indicators.
  • Addition of several new fields to better focus on details of a specific event.
  • Removal of outdated, duplicate, and ambiguous/extraneous fields.
  • A new /v2/file-events Code42 API endpoint, which uses a hierarchical structure with parent objects for each field.
  • Improved clarity on source and destination fields.

See below for the complete list of changes.

Summary of changes

  • Introduced several new fields. Some provide metadata not captured previously (such as Event ID and Operating system), and some contain values previously included in other fields. See the Additions section below for complete details.
  • Removed and consolidated fields. A number of fields were removed or consolidated to streamline and improve clarity of the file event metadata. See the Removals section below for complete details.
  • All fields are now grouped under parent categories. This results in improved organization of the Forensic Search filter options and the file event metadata details throughout the Code42 console. See the File event metadata reference for complete details.
Code42 API changes
  • The file-events endpoint incremented from /v1/file-events to /v2/file-events
    • The /v1/file-events endpoint did not change and will continue to return the same data. However, new feature development and other improvements will be focused on the /v2/file-events endpoint. 
    • No immediate changes are required if you use the /v1/file-events endpoint in scripts or integrations. However, it will eventually be deprecated in a future release.
  • The new data model groups all fields under parent categories. The /v2/file-events endpoint field names reflect this new structure. For example, removableMediaName is now destination.removableMedia.name. See the field mapping details below for a complete list of changes.
Other considerations
  • Most Saved searches were automatically updated to use the new search filters and values. However, you should double-check your saved searches to make sure they are still returning expected results. Some searches that used the Exposure type filter may require you to manually adjust the search criteria to return the expected results.
  • If you used a web browser to bookmark a search in Forensic Search, the bookmarked link no longer works. You can recreate the search and make a new bookmark, or create a  saved search for future searches you plan to use regularly.

Additions

The following fields and search filters were added to the Code42 console and the /v2/file-events API endpoint.

Code42 console user interface JSON/Code42 API field name Description
Event action event.action Contains values previously included in the Exposure Type and Event Type fields.
Event ID event.id Provides a unique identifier for the event. Event ID is now visible in Forensic Search and file event details in the Code42 console. Previously, it was only accessible via the Code42 API.
Operating System source.operatingSystem
destination.operatingSystem
Indicates the operating system of the device associated with the file event. The new field was added to both the Source and Destination categories.
Share type event.shareType Indicates the sharing permissions for an event. This replaces/consolidates values previously included in the File exposure change to and Exposure Type fields.
Source Name source.name Contains values previously included in the Hostname (endpoint events) and Source name (download events) fields.

Removals

The following fields and search filters were removed from the Code42 console and the /v2/file-events API endpoint.

Code42 console user interface JSON/Code42 API field name Notes
Actor actor Consolidated into Username (user.email).
Event type eventType Consolidated into Event Action (event.action).
Exposure Type exposure

Removed the Exposure Type field and search filter. All Exposure Type values still exist, but they have been moved to new filters. See the Exposure Type alternatives section below for details about the new equivalents.

MD5 hash
SHA256 hash
Error reasons appeared in these fields in place of the actual hash value
fieldErrors Replaced by error fields specific to where the error applies. For example: file.hash.md5Error, file.hash.sha256Error, destination.tabs.urlError
Remote Activity remoteActivity This true/false field has been replaced by the Risk indicator value Remote activity.
Risk Indicators - Off hours outsideActiveHours This true/false field has been replaced by the Risk indicator value Off hours.
Shared shared

Removed the Shared field and search filter because it returned a static attribute of the file, which did not always apply to the file activity that generated a specific event. As such, it was not an accurate risk indicator for individual events.

 

Use the new Event > Share type filter instead (event.shareType). Share type improves the accuracy of file event details and simplifies search results because it returns sharing attributes based on the event, not the file.

Shared With Users sharedWith

Removed the Shared With Users field and search filter because it returned a static list of all users the file had ever been shared with, which did not always apply to the file activity that generated a specific event. As such, it was not an accurate risk indicator for individual events.

 

Use the Destination > User filter instead, which lists the users the file is shared with for each specific event.

Suspicious File Type Mismatch mimeTypeMismatch This true/false field has been replaced by the Risk indicator value File mismatch.
Sync destination syncDestination Consolidated into Destination > Name (destination.name).
Email DLP Policy Names emailDlpPolicyNames

No longer in use. Deprecated September 2021.

API only. Not visible in the Code42 console. windowTitle

Deprecated February 2021 and replaced by tabTitles in the /v1/file-events endpoint.

 

In the /v2/file-events endpoint, use destination.tabs.title instead.

API only. Not visible in the Code42 console. tabURL Deprecated February 2021 and replaced by tabURLs

 in the /v1/file-events endpoint.

 

In the /v2/file-events endpoint, use destination.tabs.URL instead.

API only. Not visible in the Code42 console. fileType Indicated if the event was for a file or a folder (directory). Incydr only reports events for files (not folders), so this field was not necessary.
API only. Not visible in the Code42 console. detectionSourceAlias

Indicated the name you provided when the cloud data connection was initially configured in the Code42 console. Use event.observer instead to identify the source of cloud events.

Exposure Type alternatives

The Exposure Type filter was removed and has been replaced with more specific insider risk indicator options.

Exposure Type value (removed) New equivalent
Synced to cloud service Risk indicator = [cloud storage name] upload. For example: Dropbox upload
Activity on removable media Risk indicator = Removable media
Read by browser or other app Event action = Browser or app read
Public via direct link Share type = Anyone with the link
Share with corporate domain Share type = Anyone in your organization
Outside trusted domain Share type = Shared with specific people

Complete field mapping details

This table lists every file event metadata field and shows how it was affected by the data model changes.

  • All JSON/API field names changed to reflect the parent category data structure.
  • Most Code42 console labels remain the same.
  • Some fields included in the Code42 API are not included in the Code42 console interface. Those fields are marked with -- below.
Old Code42 console label New Code42 console label Old JSON/Code42 API field name New JSON/Code42 API field name Notes
Date observed Date observed eventTimestamp @timestamp  
-- Event ID eventId event.id  
-- -- insertionTimestamp event.inserted  
Exposure type
Event type
Event Action exposure, eventType event.action New field.
Consolidates values previously included in the Exposure type (exposure) and Event type (eventType) fields.
-- Share type -- event.shareType New field.
Consolidates values previously included in the Exposure type (exposure) and File exposure changed to (sharingTypeAdded) fields.
Event observer Event observer source event.observer  
Username Username deviceUserName, actor user.email  
-- User ID userUid user.id  
-- -- deviceUid user.deviceUid  
File name File name fileName file.name  
File path File path filePath file.directory  
File category File category fileCategory file.category  
-- -- mimeTypeByBytes file.mimeTypeByBytes  
-- -- fileCategoryByBytes file.categoryByBytes  
-- -- mimeTypeByExtension file.mimeTypeByExtension  
-- -- fileCategoryByExtension file.categoryByExtension  
File size File size fileSize file.sizeInBytes  
File owner File owner fileOwner file.owner  
File created File created createTimestamp file.created  
File modified File modified modifyTimestamp file.modified  
MD5 hash MD5 hash md5Checksum file.hash.md5  
SHA256 hash SHA256 hash sha256Checksum file.hash.sha256  
-- -- fileId file.id  
-- -- url file.url  
Directory ID Directory ID directoryId file.directoryId  
-- -- cloudDriveId file.cloudDriveId  
File classification File classification fileClassifications file.classifications  
Report ID Report ID reportId report.id  
Report name Report name reportName report.name  
Report description Report description reportDescription report.description  
Report column headers Report column headers reportColumnHeaders report.headers  
Number of rows Number of rows reportRecordCount report.count  
Report type Report type reportType report.type  
Source Category Source Category sourceCategory source.category  

Source Name

Hostname

Source Name

sourceName

osHostName

source.name New field combining the previous Hostname /osHostName (for endpoint events) and Source Name / sourceName of the original location of a file download (for cloud events).
Fully qualified domain name Domain domainName source.domain Renamed to more clearly distinguish between source and destination values.
IP address (public) IP address (public) publicIpAddress source.ip Renamed to more clearly distinguish between source and destination values.
IP address (private) IP address (private) privateIpAddresses source.privateIp Renamed to more clearly distinguish between source and destination values.
-- Operating System -- source.operatingSystem New field.
Indicates the operating system of the device associated with the file event. 
Sender Email sender emailSender source.email.sender  
From Email from emailFrom source.email.from  
Vendor name Removable media vendor name removableMediaVendor source.removableMedia.vendor

Renamed to more clearly distinguish between source and destination values.

Device name Removable media device name removableMediaName source.removableMedia.name Renamed to more clearly distinguish between source and destination values.
Serial number Removable media serial number removableMediaSerialNumber source.removableMedia.serialNumber Renamed to more clearly distinguish between source and destination values.
Capacity Removable media capacity removableMediaCapacity source.removableMedia.capacity Renamed to more clearly distinguish between source and destination values.
Bus type Removable media bus type removableMediaBusType source.removableMedia.busType Renamed to more clearly distinguish between source and destination values.
Device media name Removable media device media name removableMediaMediaName source.removableMedia.mediaName Renamed to more clearly distinguish between source and destination values.
Device volume name Removable media device volume name removableMediaVolumeName source.removableMedia.volumeName Renamed to more clearly distinguish between source and destination values.
Device partition ID Removable media device partition ID removableMediaPartitionId source.removableMedia.partitionId Renamed to more clearly distinguish between source and destination values.
Active tab titles and URLs Active tab titles and URLs tabs.title source.tabs.title  
Error reason Error reason tabs.titleError source.tabs.titleError  
Active tab titles and URLs Active tab titles and URLs tabs.url source.tabs.url  
Error reason Error reason tabs.urlError source.tabs.urlError  
Destination category Destination category destinationCategory destination.category  
Destination name Destination name destinationName destination.name  
Sync username, Shared with users User operatingSystemUser,
syncDestinationUser
destination.user.email New field.
Consolidates values previously included in the Sync username (operatingSystemUser) and Shared with users (syncDestinationUser) fields.
IP address (public) IP address (public) publicIpAddress destination.ip Renamed to more clearly distinguish between source and destination values.
IP address (private) IP address (private) privateIpAddresses destination.privateIp Renamed to more clearly distinguish between source and destination values.
-- Operating System -- destination.operatingSystem New field.
Indicates the operating system of the device associated with the file event. 
Print job name Print job name printJobName destination.printJobName  
Printer name Printer name printerName destination.printerName  
-- -- printedFilesBackupPath destination.printedFilesBackupPath  
Vendor name Removable media vendor name removableMediaVendor destination.removableMedia.vendor Renamed to more clearly distinguish between source and destination values.
Device name Removable media device name removableMediaName destination.removableMedia.name Renamed to more clearly distinguish between source and destination values.
Serial number Removable media serial number removableMediaSerialNumber destination.removableMedia.serialNumber Renamed to more clearly distinguish between source and destination values.
Capacity Removable media capacity removableMediaCapacity destination.removableMedia.capacity Renamed to more clearly distinguish between source and destination values.
Bus type Removable media bus type removableMediaBusType destination.removableMedia.busType Renamed to more clearly distinguish between source and destination values.
Device media name Removable media device media name removableMediaMediaName destination.removableMedia.mediaName Renamed to more clearly distinguish between source and destination values.
Device volume name Removable media device volume name removableMediaVolumeName destination.removableMedia.volumeName Renamed to more clearly distinguish between source and destination values.
Device partition ID Removable media device partition ID removableMediaPartitionId destination.removableMedia.partitionId Renamed to more clearly distinguish between source and destination values.
Recipients Email recipients emailRecipients destination.email.recipients  
Subject Email subject emailSubject destination.email.subject  
Active tab titles and URLs Active tab titles and URLs tabs.title destination.tabs.title  
Error reason Error reason tabs.titleError destination.tabs.titleError  
Active tab titles and URLs Active tab titles and URLs tabs.url destination.tabs.url  
Error reason Error reason tabs.urlError destination.tabs.urlError  
Executable name Executable name processName process.executable  
Process user Process user processOwner process.owner  
Risk score Risk score riskScore risk.score  
Risk severity Risk severity riskSeverity risk.severity  
Risk indicator Risk indicator riskIndicators.name     risk.indicators.name  
Risk indicator Risk indicator riskIndicators.weight risk.indicators.weight  
Trusted activity Trusted activity trusted risk.trusted  
Trusted activity Trusted activity trustReason risk.trustReason  
-- -- windowTitle --

Removed.
This field is no longer in use. This data is now included in destination.tabs.title and source.tabs.title.

-- -- tabURL -- Removed.
This field is no longer in use. This data is now included in destination.tabs.url and source.tabs.url.
Exposure Type -- exposure --

Removed.
Data now appears in risk.indicator.name, event.action, and event.shareType fields. See Exposure type alternatives above for complete details.

Sync Destination -- syncDestination -- Removed.
Consolidated into Destination name (destination.name).
Sync Username -- syncDestinationUsername -- Removed.
Consolidated into User (destination.user.email).
Actor -- actor -- Removed.
Consolidated into Username (user.email).
Event type -- eventType --

Removed.
Consolidated into Event action (event.action).

-- -- fieldErrors --

Removed.
Replaced by error fields specific to where the error applies. For example: file.hash.md5Errorfile.hash.sha256Errordestination.tabs.urlError

-- -- fileType --

Removed.
Indicated if the event was for a file or a folders (directory). Incydr only reports events for files (not folders), so this field was not necessary.

-- -- detectionSourceAlias --

Removed.
Indicated the name you provided when the cloud data connection was initially configured in the Code42 console. Use event.observer instead.

Risk Indicators - Off hours -- outsideActiveHours -- Removed.
This true/false field has been replaced by the Risk indicator (risk.indicators.name) value Off hours.
File type mismatch -- mimeTypeMismatch -- Removed.
This true/false field has been replaced by the Risk indicator (risk.indicators.name) value File mismatch.
Remote activity -- remoteActivity -- Removed.
This true/false field has been replaced by the Risk indicator (risk.indicators.name) value Remote.
Hostname -- osHostName -- Removed.
Consolidated into Source name (source.name).
Shared -- shared --

Removed.
True/false field that described the state of the file, not the specific event. Use Share Type (event.shareType) instead.

Shared with users -- sharedWith --

Removed.
Replaced by User (destination.user) to identify which users the file is shared with for each specific event.

-- -- emailDlpPolicyNames --

Removed.
No longer in use. Deprecated September 2021.

Source name -- sourceName -- Removed.
Replaced by Source name (source.name).
File exposure changed to -- sharingTypeAdded --

Removed.
Consolidated into Share type (event.shareType).

  • Was this article helpful?