Forensic Search API

Last updated
Save as PDF
Share
1. Share
2. Tweet

Who is this article for?

CrashPlan for Small Business

Incydr, yes.

CrashPlan for Enterprise, no.

Code42 for Enterprise, yes.

CrashPlan for Small Business, no.

This article applies to Code42 cloud environments.

Forensic Search administrator guide Step 6 of 7

Overview

This article explains how to use the Code42 API with Forensic Search. While the Code42 console contains a flexible and powerful web interface to perform searches and view results, the Code42 API provides additional capabilities for performing more complicated or customized searches.

The examples in this article use curl, but the concepts apply to any tool you choose for interacting with the Code42 API.

Code42 Developer Portal
This article applies to non-Incydr product plans. If you have an Incydr product plan, see the Code42 Developer Portal for API documentation and resources. The portal provides:

A single access point for documentation of methods for Incydr, including Code42's REST API, Python SDK py42, and command-line interface (CLI)
A single request URL for Code42 API calls to each cloud instance
API reference documentation as well as guides that describe how to use the APIs

Forensic Search API structure and syntax

Summary

Request URL
- United States:
  - If you sign in to the Code42 console at https://console.us.code42.com/console, use:
    https://forensicsearch-east.us.code42.com/forensic-search/queryservice/api/v1/
  - If you sign in to the Code42 console at https://www.crashplan.com/console, use:
    https://forensicsearch-default.prod.ffs.us2.code42.com/forensic-search/queryservice/api/v1/
  - If you sign in to the Code42 console for the Code42 federal environment at https://console.gov.code42.com/console, use:
    https://forensicsearch-default.gov.code42.com/forensic-search/queryservice/api/v1/
- Ireland: https://forensicsearch-default.ie.code42.com/forensic-search/queryservice/api/v1/
Resource names:
- fileevent: To search file activity and receive results in JSON format
- fileevent/export: To search file activity receive results in CSV format
- fileevent/grouping: To group file activity results by a particular value and receive a count of unique events in each group
Authentication method: In the authorization request header, specify a scheme of Bearer and include the token as the credentials. See the Authentication section below for steps to obtain the token.
Complete API documentation
- United States:
- Ireland: https://forensicsearch-default.ie.code42.com/forensic-search/queryservice/swagger-ui.html#/file-event-controller

API limits

Request rate: To ensure optimal performance throughout your Code42 environment, Code42 limits API requests to 120 per minute. Requests that exceed this limit are blocked and do not return results.
Result set:
- fileevent results are limited to 10,000 events per request. Requesting a page number that exceeds these limits returns an error (for example, a fileevent query with a pgSize of 10,000 cannot display pgNum 2). To obtain more than 10,000 results, use the pgToken and nextPgToken request fields to submit multiple requests. (For pgToken implementation details: from the Complete API documentation links above, see the Model tab in the SearchRequest and FileEventResponse sections.)
- fileevent/export queries are limited to 200,000 events.
- fileevent/grouping queries are limited to 1,000 groups.

Authentication

Authentication tokens are required in the header of all requests. To obtain an authentication token, use your Code42 administrator credentials to submit a GET request to:

United States:
- If you sign in to the Code42 console at https://console.us.code42.com/console, use:
  https://console.us.code42.com/c42api/v3/auth/jwt?useBody=true
- If you sign in to the Code42 console at https://www.crashplan.com/console, use:
  https://www.crashplan.com/c42api/v3/auth/jwt?useBody=true
- If you sign in to the Code42 console for the Code42 federal environment at https://console.gov.code42.com/console, use:
  https://console.gov.code42.com/c42api/v3/auth/jwt?useBody=true
Ireland: https://console.ie.code42.com/c42api/v3/auth/jwt?useBody=true

For example:

curl -X GET -u "username" -H "Accept: application/json" "https://console.us.code42.com/c42api/v3/auth/jwt?useBody=true"

Authentication cookies are not supported
You must include the ?useBody=true query parameter in the auth/jwt request to return the token in the response body. Omitting the ?useBody=true query parameter or using ?useBody=false results in the token being returned in an authentication cookie, which is not supported by the Code42 API. Include the returned token in subsequent API requests using the authorization header with the Bearer scheme, for example, -H 'authorization: Bearer <token>'

If your organization uses two-factor authentication for local users, you must also include a totp-auth header value containing the Time-based One-Time Password (TOTP) supplied by the Google Authenticator mobile app. The example below includes a TOTP value of 424242.

curl -X GET -u "username" -H "totp-auth: 424242" "Accept: application/json" "https://console.us.code42.com/c42api/v3/auth/jwt?useBody=true"

A successful request returns an authentication token. For example:

{
    "v3_user_token": "eyJjdHkiOiJKV1QiLCJlbmMiOiJBMTI4R0NNIiwiZXhwIjoiMjAxOC0wNC0zMFQyMTo0MDoyNy4xMDZaIiwiYWxnIjoiUlNBLU9BRVAtMjU2In0.0H-4bl43zA3cIE5D3o_8vZzJIUgtJt64mZbimNa2TNha761RgVBFaTfttMODXF1ntLUTHl-rD0JuHEAMrIxjpnaODictPizrDVeTA1PgkPrsKot9jp6D7uTEC1Y56qHS1qjP6WHQBpv6ADBfrAfePX3NnwkA5a1I8pB88kSWc1MXZ4uMt-rFcNtlLLPVfwtEXHyNG_bxYJOOn28y2ysJGSBD_Xx1-uK4zKvjWwXfVQG581TntFPy0LamJfJ7IM4wOIG-QrKeV796fJAaHBxNfOe4UWC8WeNcDEvgNZvOPchWTHY4l66OaOjHNeEkoKkxvc35j4V_QpYxe6GXRYK4NA.TJXe9M6goiZbw-tr.y0lUTHHkHU5tRS7bWI8jntMLcxv0HajXTXquV62IG4400i7wi0YSX-6vpsXVgivzztxnPaukgUsLavhZ8-wCiMdEkut4GfijTlDAM_tfmJyZG6Cn5GKIJgSCENrR1JTxvC6dhTvHc41p6T3jXqBWikoJwD9z9Ec3u-OhM3gotQZUfCq0rR8T043RZSN9-0TpxhpPUEUAS6rkAI07QP08l_nUqdQTsNF0Tafe1yfPTYJabkslHhYMlLRYuXwhWr_39h5BY89ud0cW_OyUtjzz83m9iGxv6sba9VBIb2Y95ipXLu6Ie-5wz8zivfjizX6ZQatp5Ep4UZxzsMdqD9j0BFXkXQZuITJLtKfmUX-FZYR8utNrbwtt8u2tvNUK8Ix4Fwa3bWPxlkwrhOdz70M-mxluxpR6EKSrf8xwHagMcahzVPcW5NVL2khr4MwMUKyRV69dAdGiaTKh2rd52znA0aE3OCtelnBrBn4rls0KX71_qZEAdPaLyyqZ4VaurWUfl35zSi2LW_a3-TebgIebHZxC-MxvFEH4DQq6gJDdoX92_YEYEn4tO_dhUTlD0CZ9HhT39XFrO9MBe4DoDzG-Iql_A-nhmCyOrRmQvUlR72XpHVFQQx3X6tqdPxFocgDh5z03-kLB4SjznQSlzJNbzl_knXTBGopoFLn3WHvjX8q327Vmwx1hjrQnO8Eg5rJMoXTJCMEEOkMyjkbFeEzEhTf2jcvvAlnNnxdtjb1Zo05RWwMsPwwHAgGr-0mm-ungNjIGW0MyMTZtK0StP1uRqfI1Q6ghqnGZxEZN_0fvsVlsz4u9A1eBYRE0xzg8p-0g62nAQ8GftpYaUoymgqbL2WCL15r38emLklXSruztosGU4Dtusg4JHEhYPxO4ieqeBu6FLX9fPSA_y3zmd_AEjW40-_6zC3quPYJwytaEIwVH6phtfa2phsOLLw-U-b2QY09-d27YirIjgNRZ7rO4GF3iX8hW3LfFIWj0WKA5HGtGHg.JzHVCE8zfy1qRBf__rhchA"
}

Token considerations

Use this authentication token in your search requests (see examples below).
Authentication tokens expire after one hour.
You must have credentials for a Code42 user with either the Customer Cloud Admin or Security Center User role.
The example above only applies to users who authenticate locally with Code42. Single sign-on (SSO) users must also complete SAML authentication with their SSO provider. If you need assistance with this process, contact your SSO provider.
The URL to obtain the authentication token is different than the URL used to query file event data.

Groups and filters

Forensic Search API queries are organized by groups of filters. This structure facilitates complicated requests with multiple "AND" or "OR" conditions. For example, use case 1 in the next section searches for files matching any one of 11 different file extensions that also exist in any one of nine different locations. Search queries are limited to a total of 1,024 criteria per request.

For example, the JSON below uses two groups of filters:

The first group uses a filterClause value of OR, which returns results if any of the four MD5 values are found (db349b97c37d22f5ea1d1841e3c89eb4 or 84c82835a5d21bbcf75a61706d8ab549 or f351e1fcca0c4ea05fc44d15a17f8b36 or 7bf2b57f2a205768755c07f238fb32cc).
The second group uses a filterClause value of AND, which returns results only if all criteria in the filter are met (in this example, on or after 2018-02-01 and on or before 2018-02-07).
Finally, to link these two groups together, the groupClause value of AND returns results only if both the first group and second group criteria are met.

{
  "groups": [
    {
      "filters": [
        {
          "operator": "IS",
          "term": "md5Checksum",
          "value": "db349b97c37d22f5ea1d1841e3c89eb4"
        },
        {
          "operator": "IS",
          "term": "md5Checksum",
          "value": "84c82835a5d21bbcf75a61706d8ab549"
        },
        {
          "operator": "IS",
          "term": "md5Checksum",
          "value": "f351e1fcca0c4ea05fc44d15a17f8b36"
        },
        {
          "operator": "IS",
          "term": "md5Checksum",
          "value": "7bf2b57f2a205768755c07f238fb32cc"
        }
      ],
      "filterClause": "OR"
    },
    {
      "filters": [
        {
          "operator": "ON_OR_AFTER",
          "term": "eventTimestamp",
          "value": "2018-02-01T00:00:00.00Z"
        },
        {
          "operator": "ON_OR_BEFORE",
          "term": "eventTimestamp",
          "value": "2018-02-07T23:59:59.59Z"
        }
      ],
      "filterClause": "AND"
    }
  ],
  "groupClause": "AND",
  "pgNum": 1,
  "pgSize": 100,
  "srtDir": "asc",
  "srtKey": "eventTimestamp"
}

Sample request

This simple example demonstrates a search for all files on all devices with the file extension .docx that exist anywhere except the file path C:/Users. For more complicated examples with multiple groups and additional filters, see the sample use cases in the next section. Use this simple example as a starting point for your own searches and replace the content of the -d section with your specific search criteria.

curl -X POST  https://forensicsearch-east.us.code42.com/forensic-search/queryservice/api/v1/fileevent \
-H 'content-type: application/json' \
-H "authorization: Bearer <authentication token goes here (without the angle brackets)>" \
-d '{
    "groups": [{
        "filters": [{
            "operator": "IS", 
            "term": "fileName", 
            "value": "*.docx"       
        },
        {
            "operator": "IS_NOT",
            "term": "filePath",
            "value": "C:/Users*"
        }
    ],
    "filterClause": "AND"
    }], 
    "groupClause": "AND",
    "pgNum": 1, 
    "pgSize": 100
}'

Format results as CSV
To receive results in CSV format instead of JSON, use the fileevent/export resource instead of fileevent. For example: https://forensicsearch-east.us.code42.com/forensic-search/queryservice/api/v1/fileevent/export

Field name mapping and definitions

The table below lists all file event metadata fields and the corresponding labels in the Forensic Search user interface, the CSV export, the JSON data, and Common Event Format (CEF).

Click to download the table below as a CSV file.

Some fields in the JSON are not included in the Forensic Search interface or CSV export. Those fields are marked with -- below.
In the JSON data response, fields that do not apply to a specific event return the value null.
The table below is sorted based on the order in which fields are returned via JSON, which also loosely corresponds to the order of fields in the Forensic Search interface. To apply a custom sort, download the CSV file linked above.
Depending on your screen size, you may need to scroll horizontally to see all of the columns in the table below.

Forensic Search user interface	CSV Export	JSON	CEF	Data Type	Description	Sample value
--	Event ID	eventId		string	The unique identifier for the event.	0_c4b5e830-824a-40a3-a6d9-345664cfbb33_941983451917189059_974935592122324249_54
Event Type	Event type	eventType		string	Indicates the type of file event observed.	MODIFIED
Date Observed	Date Observed (UTC)	eventTimestamp	end	string($date-time)	Date and time that the Code42 service on the device detected an event; based on the device’s system clock and reported in Coordinated Universal Time (UTC).	2020-10-04T23:34:31.009Z
--	Date inserted (UTC)	insertionTimestamp	rt	string($date-time)	Date and time that the event was received for indexing by Code42; timestamp is based on the Code42 cloud system clock and reported in Coordinated Universal Time (UTC).	2020-10-04T23:34:31.009Z
--	--	fieldErrors		string	List fields with errors and the reasons why they could not be determined.	{"field": "md5Checksum", "error": "GDRIVE_NATIVE_HASH"}, {"field": "sha256Checksum", "error": "GDRIVE_NATIVE_HASH"}
File Path	File path	filePath	filePath	string	The file location on the user’s device; a path forward or backslash should be included at the end of the filepath. Possibly null if the file event occurred on a cloud provider.	C:/Users/
Filename	Filename	fileName	fname	string	The name of the file, including the file extension.	Q1 Forecast.xlsx
--	File type	fileType		string	The type of file detected; only FILE types are searchable The most common values are: FILE: Indicates the event applies to a file DIR: Indicates the event applies to a directory SYSMLINK: Indicates the event applies to symlink (also called a symoblic link or soft link) Under very rare circumstances, it may also be possible to see the following values: UNKNOWN, WIN_NDS (named data stream), MAC_RSRC (Mac resource fork), FIFO (a named pipe), BLOCK_DEVICE, CHAR_DEVICE,SOCKET, BUNDLE	FILE
File Category	File Category	fileCategory	fileType	string	A categorization of the file that is inferred from the MIME type.	SPREADSHEET
--	Identified Extension Category	fileCategoryByBytes		string	A categorization of the file based on its contents.	Document
--	Current Extension Category	fileCategoryByExtension		string	A categorization of the file based on its extension.	Document
File Size	File size (bytes)	fileSize	fsize	integer($int64)	Size of the file, in bytes.	2613250
File Owner	File Owner	fileOwner		string	The name of the user who owns the file, as reported by the device’s file system.	first.last
MD5 Hash	MD5 Hash	md5Checksum	fileHash	string	The MD5 hash of the file contents.	426b7d71e7ea804086e474fda7f3d6e7
SHA256 Hash	SHA-256 Hash	sha256Checksum		string	The SHA256 hash of the file contents.	f4d2911665f2392fe774d5e64eef5d8313331700b45f333da069507db00944a8
File Created Date	Create Date	createTimestamp	fileCreateTime	string($date-time)	File creation timestamp as reported by the device’s operating system in Coordinated Universal Time (UTC); available for Mac and Windows NTFS devices only.	2020-02-10T04:37:56Z
File Modified Date	Modified Date	modifyTimestamp	fileModificationTime	string($date-time)	File modification timestamp as reported by the device’s operating system. This only indicates changes to file contents. Changes to file permissions, file owner, or other metadata are not reflected in this timestamp. Date is reported in Coordinated Universal Time (UTC).	2020-02-10T04:37:56Z
Username (Code42)	Username	deviceUserName	suser	string	The Code42 username used to sign in to the Code42 app on the device. Null if the file event occurred on a cloud provider.	first.last@example.com
Hostname	Hostname	osHostName	shost	string	The name reported by the device’s operating system. This may be different than the device name in the Code42 console.	LAPTOP-0001
Fully Qualified Domain Name	Fully Qualified Domain Name	domainName		string	Fully qualified domain name (FQDN) for the user’s device at the time the event is recorded. If the device is unable to resolve the domain name of the host, it reports the IP address of the host.	LAPTOP-0001.example.com
IP Address (public)	IP address (public)	publicIpAddress	src	string	The external IP address of the user’s device.	192.0.2.0
IP Address (private)	IP address (private)	privateIpAddresses		string	The IP address of the user’s device on your internal network, including Network interfaces, Virtual Network Interface controllers (NICs), and Loopback/non-routable addresses.	["192.0.4.0", "0:0:0:0:0:0:0:1"]
--	--	deviceUid		string	Unique identifier for the device. Null if the file event occurred on a cloud provider.	421983451917189059
--	User UID	userUid	suid	string	Unique identifier for the user of the Code42 app on the device. Null if the file event occurred on a cloud provider.	429428473202283166
Actor	Actor	actor		string	Name of the user reported by the cloud provider for the user who performed this file activity.	first.last
Directory ID	Directory ID	directoryId		string	Unique identifier of the parent drive that contain the file; searching on directoryId will return events for all of the files contained in the parent drive.	42BwMEK7Bcbq2MqnIkwFBOLCXhzLQYdLM
Source	Source	source		string	Data source for a file event.	Endpoint
--	URL	url		string	URL reported by the cloud provider at the time the event occurred.	https://drive.google.com/drive/folders/42_HMsEj0GIvFO0_nLw_ZTcrw6z
Shared	Shared	shared		string	Indicates the shared status as reported by the cloud provider at the time the event occurred. A shared file indicates that one or more users have been granted explicit access to the file. It does not capture whether or not a link to the file has been shared.	TRUE
Shared With Users	Shared With Users	sharedWith		string	A list of users who have been granted explicit rights to the file at the time the event occurred.	first.last@example.com
File exposure changed to	File exposure changed to	sharingTypeAdded		string	Public sharing types that were added by this event.	Public via direct link
--	Cloud drive ID	cloudDriveId		string	Unique identifier reported by the cloud provider for the drive containing the file at the time the event occurred.	42BwMEK7Bcbq2MqnIkwFBOLCXhzLQYdLM
--	Detection Source Alias	detectionSourceAlias		string	Name provided by your Customer Cloud Administrator when the cloud data connection was initially configured in the Code42 console.	Google Drive US
--	--	fileId		string	Unique identifier reported by the cloud provider for the file associated with the event.	423156543288
Exposure Type	Exposure Type	exposure	reason	string	The type of exposure risk. For example, file activity on removable media or files shared outside your list of trusted domains.	RemovableMedia
Process User	Process Owner	processOwner	spriv	string	For events generated when a file is read in a browser or other app, indicates the operating system owner for the process.	first.last
Executable Name (Browser or Other App)	Process Name	processName	sproc	string	For events generated when a file is read in a browser or other app, indicates the specific operating system process.	\Program Files\Google\Chrome\Application\chrome.exe
Active tab titles and URLs	Tab Titles	tabTitles		string	For events generated when a file is read in a browser or other app, the tab or window title(s) that had activity at the time of the event. If the user accessed more than one tab while uploads were in progress, all tab titles visited during the upload are listed. In the Forensic Search user interface, the tab title and tab URL are combined into the single Active tab titles and URLs field.	Marketing Assets - Google Drive - Google Chrome
Active tab titles and URLs	Tab URLs	tabURLs		string	For events generated when a file is read in a browser or other app, the URL that had activity at the time of the event. If the user accessed more than one tab while uploads were in progress, all URLs visited during the upload are listed. In the Forensic Search user interface, the tab title and tab URL are combined into the single Active tab titles and URLs field.	https://drive.google.com/drive/folders/42n7XSBQIfJ-a9B4Egv0GONOeC2EIVRbr
Tab/Window Title (Browser or Other App)	Tab/Window Title	windowTitle		string	For events generated when a file is read in a browser or other app, the tab or window title(s) that had activity at the time of the event. Deprecated February 2021. Use `tabTitles` instead.	Marketing Assets - Google Drive - Google Chrome
Tab URL (Browser)	Tab URL	tabUrl	request	string	For events generated when a file is read in a browser or other app, the URL that had activity at the time of the event. Deprecated February 2021. Use `tabURLs` instead.	https://drive.google.com/drive/folders/42n7XSBQIfJ-a9B4Egv0GONOeC2EIVRbr
Device Vendor (Removable Media)	Removable Media Vendor	removableMediaVendor		string	For events detected on removable media, indicates the vendor of the removable device.	SanDisk
Device Name (Removable Media)	Removable Media Name	removableMediaName		string	For events detected on removable media, indicates the name of the removable device.	Ultra USB 3.0
Device Serial Number (Removable Media)	Removable Media Serial Number	removableMediaSerialNumber		string	For events detected on removable media, indicates the serial number of the removable device.	42B2796EF73C48D0AA7768CB0E684842
Device Capacity (Removable Media)	Removable Media Capacity	removableMediaCapacity		integer($int64)	For events detected on removable media, indicates the capacity of the removable device in bytes.	34359738368
Device Bus Type (Removable Media)	Removable Media Bus Type	removableMediaBusType		string	For events detected on removable media, indicates the connection used to transfer data between the host and the removable device. For example: USB, eSATA, Thunderbird.	USB
Device Media Name (Removable Media)	Removable Media Media Name	removableMediaMediaName		string	For events detected on removable media, the media name of the device, as reported by the vendor/device. This name can vary based on the type of device. For example, if the device is a hard drive in a USB enclosure, the name may be the combination of the drive model and the enclosure model. This value is not provided by all devices, so it may be null in some cases.	SanDisk Ultra USB 3.0 Media
Device Volume Name (Removable Media)	Removable Media Volume Name	removableMediaVolumeName		string	For events detected on removable media, the name assigned to the volume when it was formatted, as reported by the device’s operating system. This is also frequently called the “partition” name.	Example Volume
Device Partition ID (Removable Media)	Removable Media Partition Id	removableMediaPartitionId		string	For events detected on removable media, a unique identifier assigned to the volume/partition when it was formatted. Windows devices refer to this as the `VolumeGuid`. On Mac devices, this is the `Disk / Partition UUID`, which appears when running the Terminal command `diskUtil` info.	00000001-0000-0000-0000-000000000000
Sync Destination (Cloud)	Sync Destination	syncDestination	destinationServiceName	string	For events detected within a cloud storage sync destination on a device, the cloud storage vendor.	Google Backup and Sync
Sync Username (Cloud)	Sync Destination Username	syncDestinationUserName		string	For events detected within a cloud storage sync destination on a device, indicates the username logged into the cloud storage provider when the file activity was observed.	first.last@example.com
Email DLP Policy Names	Email DLP Policy Names	emailDlpPolicyNames		string	The name of the data loss prevention (DLP) policy that detected this file, as defined in your Microsoft Office 365 Security & Compliance Center. If the attachment is detected by more than one policy, only one policy is listed.	Sensitive Information (IP)
Subject	Email DLP Subject	emailSubject		string	The subject of the email that matched on a DLP rule.	FWD: Confidential analysis
Sender	Email DLP Sender	emailSender		string	The address of the entity responsible for transmitting the message. In many cases, this is the same as From, but it can be different if the message is sent by a server or other mail agent on behalf of someone else.	first.last@example.com
From	Email DLP From	emailFrom		string	The display name of the sender, as it appears in the "From" field in the email. In many cases, this is the same as Sender, but it can be different if the message is sent by a server or other mail agent on behalf of someone else.	first.last@example.com
Recipients	Email DLP Recipients	emailRecipients		string	The email addresses of those who received the email. Includes the To, Cc, and Bcc recipients.	first.last@example.com
Risk Indicators - Off hours	Outside Active Hours	outsideActiveHours		boolean	Indicates whether or not this event occurred outside of the user’s typical active hours using data modeling from the this user’s prior activity.	FALSE
--	Identified Extension MIME Type	mimeTypeByBytes		string	The MIME type of the file based on its contents.	text/plain
--	Current Extension MIME Type	mimeTypeByExtension		string	The MIME type of the file based on its extension.	text/x-sql
--	Suspicious File Type Mismatch	mimeTypeMismatch		boolean	Indicates whether or not the MIME type of the file based on its contents conflicts with the MIME type based on its extension.	FALSE
Print Job Name	Print Job Name	printJobName		string	For print events, the name of the print job, as reported by the user’s device.	ipp://localhost/printers/DeskJet_4200_series
Printer Name	Printer Name	printerName		string	For print events, the name of the printer the job was sent to.	Microsoft Word - Resume.doc
--	--	printedFilesBackupPath		string	For print events, the path on disk where Code42 stores printer cache files.	/Sample/Path/d42001_6d45b6d4-a2cd-4c93-9986-29cf23916921/ zURJNo5.txt.octet-stream
Remote Activity	Remote Activity	remoteActivity		string	For endpoint events, compares the IP address of the file event to your defined list of addresses in the Data Preferences > IP addresses section of the Code42 console. TRUE = The IP address from the file event does not match the list of in-network IP addresses FALSE = The IP address does match the list of in-network IP addresses	TRUE
Trusted Activity	Trusted	trusted		boolean	Indicates whether or not the file activity occurred on your list of trusted domains.	FALSE
Username (signed in to device)	Logged in Operating System User	operatingSystemUser		string	The username logged in to the device when the file activity was observed, as reported by the device’s operating system.	first.last
Destination Category	Destination Category	destinationCategory		string	General category of where data was sent for a file exposure event. For example: Cloud Storage, Email, Social Media.	Cloud Storage
Destination Name	Destination Name	destinationName		string	Specific target of where data was sent for a file exposure event. For example: Google Drive, Outlook, Slack.	Dropbox

Sample Use Cases

Use case 1: Search for application files in unexpected locations

The sample JSON below shows how to search for files with any of these extensions (.action, .app, .bat, .bin, .cmd, .com, .command, .cpl, .exe, .msc, .osx) that exist outside these locations:

C:\Program Files
/Applications
/Library
/User/*/Applications
/User/*/Library
/usr/bin
/usr/local/bin
/sbin
/bin

Sample JSON search query for application files in specific locations

Modify this sample to fit your environment and then include it in a request (as shown in the Sample request section above).

{
  "groups": [
    {
      "filters": [
        {
          "operator": "IS",
          "term": "fileName",
          "value": "*.action"
        },
        {
          "operator": "IS",
          "term": "fileName",
          "value": "*.app"
        },
        {
          "operator": "IS",
          "term": "fileName",
          "value": "*.bat"
        },
        {
          "operator": "IS",
          "term": "fileName",
          "value": "*.bin"
        },
        {
          "operator": "IS",
          "term": "fileName",
          "value": "*.cmd"
        },
        {
          "operator": "IS",
          "term": "fileName",
          "value": "*.com"
        },
        {
          "operator": "IS",
          "term": "fileName",
          "value": "*.command"
        },
        {
          "operator": "IS",
          "term": "fileName",
          "value": "*.cpl"
        },
        {
          "operator": "IS",
          "term": "fileName",
          "value": "*.exe"
        },
        {
          "operator": "IS",
          "term": "fileName",
          "value": "*.msc"
        },
        {
          "operator": "IS",
          "term": "fileName",
          "value": "*.osx"
        }
      ],
      "filterClause": "OR"
    },
    {
      "filters": [
        {
          "operator": "IS_NOT",
          "term": "filePath",
          "value": "C:\Program Files*"
        },
        {
          "operator": "IS_NOT",
          "term": "filePath",
          "value": "/Applications*"
        },
        {
          "operator": "IS_NOT",
          "term": "filePath",
          "value": "/Library*"
        },
        {
          "operator": "IS_NOT",
          "term": "filePath",
          "value": "/User/*/Applications*"
        },
        {
          "operator": "IS_NOT",
          "term": "filePath",
          "value": "/User/*/Library*"
        },
        {
          "operator": "IS_NOT",
          "term": "filePath",
          "value": "/usr/bin*"
        },
        {
          "operator": "IS_NOT",
          "term": "filePath",
          "value": "/usr/local/bin*"
        },
        {
          "operator": "IS_NOT",
          "term": "filePath",
          "value": "/sbin*"
        },
        {
          "operator": "IS_NOT",
          "term": "filePath",
          "value": "/bin*"
        }
      ],
      "filterClause": "AND"
    }
  ],
  "groupClause": "AND",
  "pgNum": 1,
  "pgSize": 100,
  "srtDir": "asc",
  "srtKey": "eventTimestamp"
}

Sample results of application files in specific locations

{
    "totalCount": 3,
    "fileEvents": [
        {
            "eventId": "0_1dcc9b7c-123d-40d7-b0fb-436520b2cab8_843278037859030533_843318595055164516_6",
            "eventType": "CREATED",
            "eventTimestamp": "2018-04-10T23:57:33.682Z",
            "filePath": "C:/$GetCurrent/SafeOS/",
            "fileName": "SetupComplete.cmd",
            "fileType": "FILE",
            "fileSize": 307,
            "fileOwner": "Administrators",
            "md5Checksum": "0582b19fa3b500db28f976ed33efa487",
            "createTimestamp": "2018-03-19T18:10:42.041Z",
            "modifyTimestamp": "2018-03-19T18:10:42.120Z",
            "deviceUserName": "clyde@example.com",
            "osHostName": "CO-SAMPLE-1",
            "domainName": 192.0.2.0,
            "publicIpAddress": "192.0.2.0",
            "privateIpAddresses": [
                "2001:db8:49a3:7d3:1309:8a2e:370:7342",
                "192.0.4.0",
                "0:0:0:0:0:0:0:1",
                "127.0.0.1"
            ],
            "deviceUid": "423278037859030542",
            "userUid": "424242424242424242"
        },
        {
            "eventId": "0_1dcc9b7c-123d-40d7-b0fb-436520b2cab8_843278037859030533_843318595055164516_7",
            "eventType": "CREATED",
            "eventTimestamp": "2018-04-10T23:57:33.682Z",
            "filePath": "C:/$GetCurrent/SafeOS/",
            "fileName": "preoobe.cmd",
            "fileType": "FILE",
            "fileSize": 74,
            "fileOwner": "Administrators",
            "md5Checksum": "2f9537b7f7cb5b559ed6ec3694832fe6",
            "createTimestamp": "2018-03-19T18:10:41.936Z",
            "modifyTimestamp": "2018-03-19T18:10:42.041Z",
            "deviceUserName": "paige@example.com",
            "osHostName": "CO-SAMPLE-2",
            "domainName": 192.0.2.0,
            "publicIpAddress": "192.0.2.0",
            "privateIpAddresses": [
                "2001:db8:49a3:7d3:1309:8a2e:370:7342",
                "192.0.4.0",
                "0:0:0:0:0:0:0:1",
                "127.0.0.1"
            ],
            "deviceUid": "423278037859030542",
            "userUid": "424242424242424243"
        },       
        {
            "eventId": "0_1dcc9b7c-123d-40d7-b0fb-436520b2cab8_843278037859030533_843419521787010148_344",
            "eventType": "CREATED",
            "eventTimestamp": "2018-04-11T16:40:11.090Z",
            "filePath": "C:/Windows/en-US/",
            "fileName": "bootfix.bin",
            "fileType": "FILE",
            "fileSize": 1024,
            "fileOwner": "TrustedInstaller",
            "md5Checksum": "eb145d5f87ddf43c8bd6f27e97db8bf2",
            "createTimestamp": "2017-09-29T14:41:10.345Z",
            "modifyTimestamp": "2017-09-29T14:41:10.346Z",
            "deviceUserName": "clyde@example.com",
            "osHostName": "CO-SAMPLE-3",
            "domainName": 192.0.4.0,
            "publicIpAddress": "192.0.4.0",
            "privateIpAddresses": [
                "2001:db8:49a3:7d3:1309:8a2e:370:7342",
                "192.0.4.0",
                "0:0:0:0:0:0:0:1",
                "127.0.0.1"
            ],
            "deviceUid": "423278037859030542",
            "userUid": "424242424242424242"
        }
    ],
    "problems": null
}

Use case 2: Search for files on a device within a specific date range based on MD5 values

The sample JSON below shows how to search for files files matching any of four MD5 values that existed on devices between February 1 and 7, 2018.

The Code42 API also supports SHA256 searches
To search for SHA256 hash values instead of MD5, replace md5Checksum with sha256Checksum in the sample JSON below.

Sample JSON search query for MD5 values between two dates

Modify this sample to fit your environment and then include it in a request (as shown in the Sample request section above).

{
  "groups": [
    {
      "filters": [
        {
          "operator": "IS",
          "term": "md5Checksum",
          "value": "db349b97c37d22f5ea1d1841e3c89eb4"
        },
        {
          "operator": "IS",
          "term": "md5Checksum",
          "value": "84c82835a5d21bbcf75a61706d8ab549"
        },
        {
          "operator": "IS",
          "term": "md5Checksum",
          "value": "f351e1fcca0c4ea05fc44d15a17f8b36"
        },
        {
          "operator": "IS",
          "term": "md5Checksum",
          "value": "7bf2b57f2a205768755c07f238fb32cc"
        }
      ],
      "filterClause": "OR"
    },
    {
      "filters": [
        {
          "operator": "ON_OR_AFTER",
          "term": "eventTimestamp",
          "value": "2018-02-01T00:00:00.00Z"
        },
        {
          "operator": "ON_OR_BEFORE",
          "term": "eventTimestamp",
          "value": "2018-02-07T23:59:59.59Z"
        }
      ],
      "filterClause": "AND"
    }
  ],
  "groupClause": "AND",
  "pgNum": 1,
  "pgSize": 100,
  "srtDir": "asc",
  "srtKey": "eventTimestamp"
}

Sample results of file events matching the MD5 values and date range

{
    "totalCount": 2,
    "fileEvents": [
        {
            "eventId": "0_1dcc9b7c-123d-40d7-b0fb-436520b2cab8_843278037859030533_843279264407737861_1",
            "eventType": "CREATED",
            "eventTimestamp": "2018-02-04T18:40:37.790Z",
            "filePath": "C:/Windows/",
            "fileName": "mssecsvc.exe",
            "fileType": "FILE",
            "fileSize": 282,
            "fileOwner": "clyde",
            "md5Checksum": "db349b97c37d22f5ea1d1841e3c89eb4",
            "createTimestamp": "2018-02-03T15:43:29.388Z",
            "modifyTimestamp": "2018-02-04T15:13:28.783Z",
            "deviceUserName": "clyde@example.com",
            "osHostName": "CO-SAMPLE-01",
            "domainName": 192.0.2.0,
            "publicIpAddress": "192.0.2.0",
            "privateIpAddresses": [
                "2001:db8:49a3:7d3:1309:8a2e:370:7342",
                "192.0.4.0",
                "0:0:0:0:0:0:0:1",
                "127.0.0.1"
            ],
            "deviceUid": "425916091791253442",
            "userUid": "424242424242424242"
        },
        {
            "eventId": "0_1dcc9b7c-123d-40d7-b0fb-436520b2cab8_843278037859030533_843317905847131236_1",
            "eventType": "MODIFIED",
            "eventTimestamp": "2018-02-02T23:50:42.294Z",
            "filePath": "C:/Users/Paige/Downloads/",
            "fileName": "tasksche.exe",
            "fileType": "FILE",
            "fileSize": 282,
            "fileOwner": "paige",
            "md5Checksum": "84c82835a5d21bbcf75a61706d8ab549",
            "createTimestamp": "2018-02-01T15:43:29.388Z",
            "modifyTimestamp": "2018-02-02T23:47:04.336Z",
            "deviceUserName": "paige@example.com",
            "osHostName": "CO-SAMPLE-02",
            "domainName": 192.0.4.0,
            "publicIpAddress": "192.0.4.0",
            "privateIpAddresses": [
                "2001:db8:49a3:7d3:1309:8a2e:370:7342",
                "192.0.4.0",
                "0:0:0:0:0:0:0:1",
                "127.0.0.1"
            ],
            "deviceUid": "423278037859030542",
            "userUid": "424242424242424243"
        }
    ],
    "problems": null
}

Use case 3: See all cloud sync destinations for a user

The sample JSON below shows how to use the fileevent/grouping resource to find an approximate count of Synced to cloud service file events for a specific user for each cloud service. This sample groups by the syncDestination value, but you can choose any groupingTerm listed in the Code42 API documentation viewer in your requests.

Sample JSON search query for cloud service file event counts

Modify this sample to fit your environment and then include it in a request (as shown in the Sample request section above). For grouping queries, you must use the fileevent/grouping resource.

{
    "groupingTerm": "syncDestination",
    "groups": [
        {
            "filters": [
                {
                    "operator": "IS",
                    "term": "deviceUserName",
                    "value": "clyde@example.com"
                }
            ]
        }
    ]
}

Sample results of cloud service file event counts

{
  "groups": [
    {
      "value": "Dropbox",
      "docCount": 114
    },
    {
      "value": "Google Drive",
      "docCount": 8
    }
  ]
}

Missing or unknown values
Some file events may not capture all metadata. Reasons for omitted metadata can include:

The file did not exist on disk long enough for Code42 to capture all the metadata.
Several values, including deviceUserName and userUid, are captured and reported from the Code42 cloud instead of directly from the user device. If those values haven't been reported yet, they may be blank or may display as UNKNOWN or NAME_NOT_AVAILABLE. In those cases, you can use the deviceUid to get details via the Computer API resource.

External resources

Curl: Command line tool and library reference