Skip to main content

Who is this article for?

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

Find your product plan in the Code42 console on the Account menu.
Not an Incydr customer? For CrashPlan articles, search or browse.

Instructor, no.

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

Incydr Basic, Advanced, and Gov F1, yes.

CrashPlan Cloud, no.

Retired product plans, no.

CrashPlan for Small Business, no.

HOME
GETTING STARTED
RELEASE NOTES
FAQs
APIs
SYSTEM STATUS
Code42 Support

Customize applications monitored for file exfiltration

Who is this article for?

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

Find your product plan in the Code42 console on the Account menu.
Not an Incydr customer? For CrashPlan articles, search or browse.

Instructor, no.

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

Incydr Basic, Advanced, and Gov F1, yes.

CrashPlan Cloud, no.

Retired product plans, no.

CrashPlan for Small Business, no.

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.

Monitoring custom applications may cause unexpected results
The default applications monitored by Code42 are tested regularly to ensure high fidelity results. Adding custom applications, especially if they are used for normal business purposes, may cause unexpected and undesirable behavior, including:
  • Unnecessary noise: custom applications may report events for "normal" file activity not related to file exfiltration risk.
  • Missing destination details and other metadata: custom applications may not capture all metadata, including destination details such as Tab title and URL. In addition, destination categories and destination risk indicators are reported as Unknown.
  • Inability to evaluate trust: since destination information is not captured for custom applications, events cannot be filtered based on your list of trusted activity. This means all activity in custom applications is considered untrusted.

For all the reasons listed above, do not add custom applications that are approved for normal business purposes. Without the destination information, it is very difficult to differentiate between "normal" and risky use.

Considerations

Code42 Developer Portal
See the Code42 Developer Portal for more API documentation and resources. The portal provides:

Use the Code42 Developer Portal for your API needs as much as possible. APIs in the portal are the preferred way to integrate with Code42 for Incydr users. If you use Code42 APIs that do not appear on the Code42 Developer Portal, contact our Customer Champions for guidance on the best way to integrate with Code42. 

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 1: Find the numeric OrgID

To view and edit the list of monitored applications, you must first identify the numeric ID of the applicable organization.

  1. Sign in to the Code42 console.
  2. Select Administration > Environment > Organizations.
  3. Select an organization:
    • To apply the same values to your entire Code42 environment, select ​​​​your top-level organization. This organization is at the top of the organizational hierarchy and is the parent for all other organizations.
    • To apply different values based on organization, select each organization you want to modify and repeat the steps below for each organization individually.
  4. In the web browser's address bar, note the numeric ID in the URL after "organization" but before any query or token parameters. In this example, the OrgID is 123456: https://console.us.code42.com/console/#/organization/123456?t=78910

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:

Copied!
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:

Copied!
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

To remove your customized list of monitored applications, follow the Step 3: Update applications section above to update the list of custom applications to an empty value:

"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:

Copied!
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

Related topics

  • Was this article helpful?