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-eventsCode42 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-eventsto/v2/file-events.- The
/v1/file-eventsendpoint 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-eventsendpoint. - No immediate changes are required if you use the
/v1/file-eventsendpoint in scripts or integrations. However, it will eventually be deprecated in a future release.
- The
- The new data model groups all fields under parent categories. The
/v2/file-eventsendpoint field names reflect this new structure. For example,removableMediaNameis nowdestination.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 ( |
| 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
In the |
| API only. Not visible in the Code42 console. | tabURL | Deprecated February 2021 and replaced by tabURLs
in the
In the |
| 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 |
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. |
| -- | -- | 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. |
| 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. |
| -- | -- | fieldErrors | -- |
Removed. |
| -- | -- | fileType | -- |
Removed. |
| -- | -- | detectionSourceAlias | -- |
Removed. |
| 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. |
| Shared with users | -- | sharedWith | -- |
Removed. |
| -- | -- | emailDlpPolicyNames | -- |
Removed. |
| Source name | -- | sourceName | -- | Removed. Replaced by Source name ( source.name). |
| File exposure changed to | -- | sharingTypeAdded | -- |
Removed. |