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.

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, 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.

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 Technical Support Engineers 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

Incydr Professional, Enterprise, Horizon, and Gov F2

  1. Sign in to the Code42 console.
  2. Select Administration > Environment > Organizations.
  3. Select Export.
  4. Open the CSV organizations list file that downloads.
  5. Locate the organization that contains your Amazon WorkSpaces users.
  6. Note the numeric ID in the orgID column.

Incydr Basic, Advanced, and Gov F1 

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

Incydr Professional, Enterprise, Horizon, and Gov F2

Incydr Basic, Advanced, and Gov F1

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?