Customize applications monitored for file exfiltration

Overview

This article explains how to use the Code42 API to customize the list of applications monitored for file exfiltration. By default, Code42 monitors activity of applications typically used to upload and download files, such as web browsers, Slack, AirDrop, FileZilla, FTP, and cURL. Follow the steps below to add to the default list of monitored applications.

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

Considerations

• You must have credentials for a Code42 user with the Org Admin or Cross Org Admin role.
• Adding customizations does not change the list of applications Code42 monitors by default.
• On Mac devices, grant full disk access to Code42 to ensure the necessary permissions to monitor applications for file exfiltration. See macOS permissions for the insider risk agent for more details.

API request details

• Request URL 
  • United States:
    • If you sign in to the Code42 console at https://console.us.code42.com (US1), use: 
      https://console.us.code42.com/api/v1/
    • If you sign in to the Code42 console at https://console.us2.code42.com (US2), use:
      https://console.us2.code42.com/api/v1/
    • If you sign in to the Code42 console for the Code42 federal environment at https://console.gov.code42.com (US3), use: 
      https://console.gov.code42.com/api/v1/
  • Ireland:
    • If you sign in to the Code42 console at https://console.ie.code42.com (EU1), use: 
      https://console.ie.code42.com/api/v1/
• Resource: OrgSettings
• Keys:
  • Windows: device_org_winAppActivity_binaryWhitelist
  • Mac: device_org_macAppActivity_binaryWhitelist
• Methods: GET to view your customizations; PUT to modify customizations; DELETE to remove customizations

View and update monitored applications

Step 2: View existing customizations

Use the GET method to view existing custom applications being monitored for file exfiltration. The OrgSettings resource also contains keys for numerous other Code42 settings. Therefore, to view only your customizations, you must include the device_org_winAppActivity_binaryWhitelist or device_org_macAppActivity_binaryWhitelist key as a query parameter.

The example below assumes basic familiarity with curl commands. Use this as a template to create a command specific to your Code42 environment:

Copy to clipboardCopied!

curl -X GET \
  '<request_url>/api/v1/OrgSettings/<OrgID>?keys=device_org_winAppActivity_binaryWhitelist' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer <auth_token>'

1. Replace <request_url> with the address of your Code42 environment (do not include the brackets in your request).
2. Replace <OrgID> with the number identified in Step 1 above (do not include the brackets in your request).
3. Replace <auth_token> with the authentication token.
4. Execute the curl command in your command-line tool of choice. When prompted, enter your password.
   The Code42 API returns the list of custom applications. If there are no custom applications, the data parameter in the response is empty. 
5. For Mac devices, repeat the steps above using the key device_org_macAppActivity_binaryWhitelist. 

Step 3: Update applications

Use the PUT method to update the existing list of custom applications. Before sending any updates, make sure to complete Step 2 above to obtain the list of existing customizations.

Updates overwrite existing values
The OrgSettings API resource does not automatically add to existing values. All PUT requests completely replace existing values. Therefore, to change existing customizations, you must first obtain a list of current values, make changes to the list, and then submit the changed list.

The steps below assume basic familiarity with curl commands. Use the following example as a template to create a command specific to your Code42 environment:

Copy to clipboardCopied!

curl -X PUT \
  '<request_url>/api/v1/OrgSettings/<OrgID>' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer <auth_token>' \
  -d '{ 
    "packets": [
        {
            "key": "device_org_winAppActivity_binaryWhitelist",
            "value": "customProcess.exe,customProcess2.exe",
            "locked": true
        }
    ]
}'

1. Replace <request_url> with the address of your Code42 environment (do not include the brackets in your request).
2. Replace <OrgID> with the number identified in Step 1 above (do not include the brackets in your request).
3. Replace <auth_token> with the authentication token.
4. Edit the list inside the quotation marks  of the value parameter to include the names of the applications you want to monitor.
5. Execute the curl command in your command-line tool of choice.
6. For Mac devices:
   • Repeat the steps above using the key device_org_macAppActivity_binaryWhitelist
   • Use the name of the process, not the name of the app bundle.
   • Do not add extra quotes or escape characters if the process name contains a space. For example: "value": "CustomProcess1,Custom Process 2" is the correct format.
7. To confirm the new settings are applied, re-submit the GET request described in Step 2 above and review the list of custom applications.

Remove your customizations

Insider risk agent

Requires insider risk agent version 1.7.0 or later. For insider risk agent 1.6.2 and earlier, follow the steps below to update the list of custom applications to an empty value.

Use the DELETE method to remove your customized list of monitored applications.

Include key parameter to prevent removal of other system settings
To test this request, submit it first as a GET request described in Step 2 above and make sure the response includes only the device_org_winAppActivity_binaryWhitelist or device_org_macAppActivity_binaryWhitelist key. Then resubmit it as a DELETE request.

The OrgSetting resource also contains keys for numerous other Code42 settings. Therefore, it is very important to list the correct key as a query parameter in the request URL. Failure to specify only this key will cause other system settings to be deleted by this request.

The steps below assume basic familiarity with curl commands. Use the following example as a template to create a command specific to your Code42 environment:

Copy to clipboardCopied!

curl -X DELETE \
  '<request_url>/api/v1/OrgSettings/<OrgID>?keys=device_org_winAppActivity_binaryWhitelist' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \  
  -H 'Authorization: Bearer <auth_token>'

1. Replace <request_url> with the address of your Code42 environment (do not include the brackets in your request).
2. Replace <OrgID> with the number identified in Step 1 above (do not include the brackets in your request).
3. Replace <auth_token> with the authentication token.
4. Execute the curl command in your command-line tool of choice.
   A 204 No Content response indicates the Code42 cloud received the request and deleted your custom list of monitored applications.
5. For Mac devices, repeat the steps above using the key device_org_macAppActivity_binaryWhitelist.
6. To confirm your customizations are removed, re-submit the GET request described in Step 2 above and review the list of monitored applications.

"value": ""

View Code42 defaults

By default, Code42 monitors activity of applications typically used to upload and download files, such as web browsers, Slack, AirDrop, FileZilla, FTP, and cURL. Reviewing the defaults can help you determine if customizations are necessary (if the application is already being monitored, you do not need to add it to your customized list).

To view the Code42 defaults, use the steps above to submit a GET request, but use the org_securityTools_win_binary_whitelist (Windows) or org_securityTools_mac_binary_whitelist (Mac) key instead. For example:

Copy to clipboardCopied!

curl -X GET \
  '<request_url>/api/v1/OrgSettings/<OrgID>?keys=org_securityTools_win_binary_whitelist' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \  
  -H 'Authorization: Bearer <auth_token>'

1. Replace <request_url> with the address of your Code42 environment (do not include the brackets in your request).
2. Replace <OrgID> with the number identified in Step 1 above (do not include the brackets in your request).
3. Replace <auth_token> with the authentication token.
4. Execute the curl command in your command-line tool of choice.

These are read-only keys; you can view the default values but you cannot change them. Also note that Code42 may update these defaults as necessary to improve exfiltration detection. 

External resources

• Curl: Command line tool and library reference

Related topics

• Forensic Search API
• File Metadata Collection exclusions via API
• Create and manage alert rules 
• File event metadata reference