Skip to main content

Who is this article for?

Incydr
Code42 for Enterprise
CrashPlan for Enterprise

Incydr, yes.

CrashPlan for Enterprise, no.

Code42 for Enterprise, no.

CrashPlan for Small Business, no.

This article applies to Code42 cloud environments.

HOME
GETTING STARTED
RELEASE NOTES
FAQs
APIs
SYSTEM STATUS
Code42 Support

Respond to an alert with the Code42 API

Overview

You can use the Code42 APIs to respond to a high-value alert and add it to a case for further investigation. This article explains how to use APIs to:

  1. Search alerts to find one of interest.
  2. View the alert's details.
  3. Open a case.
  4. Add file events from the alert to the case.

For more information about the APIs described in this article, see:

Considerations

Before you begin

Set up monitoring and alerts

Before you can receive alerts about employees' file activity, do the following:

  1. Enable endpoint monitoring.
    See Enable endpoint monitoring for file exfiltration detection.
  2. Create rules to alert you when suspicious file activity occurs.
    See the following articles:
  3. (Optional) Set up additional monitoring to capture file activity.
    See the following articles:

Plan your work

Before you start writing scripts to handle alerts using the Code42 APIs, consider the following questions to help you plan your work:

Why do you want to automate responding to alerts?

Using APIs to automatically respond to alerts provides economies of scale. If you monitor insider risk at a small company, you could use the Alerts in the Code42 console to receive notifications about suspicious file activity. But for larger companies with many more employees to track, automating the process with the Code42 APIs provides a much faster and efficient method. As an added benefit, you can integrate the Code42 APIs with other systems such as your company's security tools. Planning and implementing Code42 APIs can take some time. Before you begin using Code42 APIs to manage alerts, consider the effort involved to set them up versus the time savings provided when they run.

What kind of alerts do you want to receive?

Alerts generated when users perform actions that are considered high risk are of highest value. Determine the kinds of actions that you want to receive alerts about and then create alerts that will be triggered by those actions. Creating the right kinds of alerts provides the best monitoring possible of high risk file activity. 

Gather your inputs

Before attempting to write scripts using the Code42 API examples in this article, gather the following inputs:

  • Authentication token
    Authentication tokens are required to run the APIs. The tokens must be generated by a Code42 administrator with the proper role assignments.
  • Tenant ID
    Your company's entity in the Code42 cloud is known as a "tenant". To obtain your tenant ID, use your Code42 administrator credentials to submit a request to the customer API.
  • Code42 usernames for the people you want to add to alert rules
    The names of employees you want to add to alert rules may come from a number of sources, such as an HR system or a directory service. While you can integrate with such systems using the Code42 API, remember that you need the Code42 username of these employees to be able to add them to alerts. The Code42 username is assigned when the user is added to Code42. You can obtain usernames via CSV export or the user API

Steps

Step 1: Search for significant alerts

Alerts help notify you about suspicious file activity. However, some alerts are more likely to warrant further investigation than others.

To identify alerts that you want to investigate, use the api/v1/query-alerts API command to search for alert notifications by alert filter criteria. By using filters you can uncover only the alerts that you want to follow up on.

Copied!
curl -X POST \
"<RequestURL>/query-alerts" \
-H "accept: text/plain" \
-H "Authorization: v3_user_token <AuthToken>" \
-H "Content-Type: application/json" \
-d '{ "tenantId": "<SampleTenant>", "groups": [ { "filters": [ { "term": "<FilterType>", "operator": "<OperatorValue>", "value": "<Criteria>" } ], "filterClause": "AND" } ], "groupClause": "OR", "pgSize": "20", "pgNum": "0", "srtKey": "CreatedAt", "srtDirection": "DESC" }'

In the preceding example:

  • Replace <RequestURL> with the request URL of your Code42 cloud instance, for example,
    https://alert-service-default.prod.ffs.us2.code42.com/svc/api/v1/
  • Replace <AuthToken> with the authentication token.
  • Replace <SampleTenant> with the tenant ID.
  • For the filter syntax, replace <FilterType> with the filter, <OperatorValue> with the operator option, and <Criteria> with the search term to use in the search. 

A successful response returns basic information about the alert notifications that match your search criteria, including the alert IDs of notifications returned by the query (look for the "id" entry):

{"type$":"ALERT_SUMMARY","tenantId":"123456","type":"FED_ENDPOINT_EXFILTRATION","name":"Departing employee endpoint exfiltration system rule","description":"System rule for departing employee endpoint exfiltration.","actor":"burt.morales@example.com","target":"N/A","severity":"HIGH","ruleId":"123456789424242","ruleSource":"Departing Employee","id":"987654321424242","createdAt":"2020-04-03T15:21:44.6139300Z","state":"OPEN"}],"totalCount":1,"problems":[]}

Filter alerts further

You can further filter alerts by adding more filter types to your query. For example, you could use the Severity filter to find only those alerts that were high severity, or the RuleName filter to find only alerts from a particular rule.

Step 2: View alert details

After you've located the ID for an alert you want to investigate further, use the /api/v1/query-details API command to view details about the alert, including the files involved in the file events that triggered the alert.

Copied!
curl -X POST \
"<RequestURL>/query-details" \
-H "accept: text/plain" \
-H "Authorization: v3_user_token <AuthToken>" \
-H "Content-Type: application/json" \
-d '{ "alertIds": [ "<SampleAlertID>" ]}'

In the preceding example:

  • Replace <RequestURL> with the request URL of your Code42 cloud instance.
  • Replace <AuthToken> with the authentication token.
  • Replace <SampleAlertID> with the ID of an alert notification listed in the response in Step 1

A successful response returns full details about the alert notification, including event IDs (look for "eventid\") and a list of files involved in the event (look for "files\" followed by "name\").

{"type$":"ALERT_DETAILS_RESPONSE","alerts":[{"type$":"ALERT_DETAILS","tenantId":"123456","type":"FED_ENDPOINT_EXFILTRATION","name":"Departing employee endpoint exfiltration system rule","description":"System rule for departing employee endpoint exfiltration.","actor":"burt.morales@example.com","target":"N/A","severity":"HIGH","ruleId":"123456789424242","ruleSource":"Departing Employee","id":"987654321424242","createdAt":"2020-04-08T13:50:25.3644410Z","state":"OPEN","observations":[{"type$":"OBSERVATION","id":"112233445566","observedAt":"2020-04-08T13:40:00.0000000Z","type":"FedEndpointExfiltration","data":"{\"type$\":\"OBSERVED_ENDPOINT_ACTIVITY\",\"id\":\"665544332211\",\"sources\":[\"Endpoint\"],\"exposureTypes\":[\"ApplicationRead\",\"CloudStorage\"],\"firstActivityAt\":\"2020-04-08T13:40:00.0000000Z\",\"lastActivityAt\":\"2020-04-08T13:45:00.0000000Z\",\"fileCount\":2,\"totalFileSize\":311096,\"fileCategories\":[{\"type$\":\"OBSERVED_FILE_CATEGORY\",\"category\":\"Image\",\"fileCount\":2,\"totalFileSize\":311096,\"isSignificant\":false}],\"files\":[{\"type$\":\"OBSERVED_FILE\",\"eventId\":\"998877665544\",\"path\":\"C:/Users/burt.morales/\",\"name\":\"1586353274_family_photo.png\",\"category\":\"Image\"},],\"syncToServices\":[\"Dropbox\"],\"sendingIpAddresses\":[\"192.0.2.0\"]}"}]}]}

Optional: Look for the files involved in the alert

Use the Forensic Search APIs to look for the files identified in the preceding alert query response.

The following Forensic Search API sample request demonstrates a search for all files on all devices with the file extension .docx that exist anywhere in the file path C:/Users. For more complicated examples with multiple groups and additional filters, see the sample use cases. 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.

Copied!
curl -X POST  <RequestURL>/api/v1/fileevent \
-H 'content-type: application/json' \
-H "authorization: v3_user_token <AuthToken>" \
-d '{
    "groups": [{
        "filters": [{
            "operator": "IS", 
            "term": "fileName", 
            "value": "*.docx"       
        },
        {
            "operator": "IS",
            "term": "filePath",
            "value": "C:/Users*"
        }
    ],
    "filterClause": "AND"
    }], 
    "groupClause": "AND",
    "pgNum": 1, 
    "pgSize": 100
}'

Step 3: Open a case

To track your investigation of the event that triggered the alert, use the /api/v1/case API command to create a case.

Only the name field is required. To leave a field blank, supply the value null .

Copied!
curl -X POST '<RequestURL>/api/v1/case' \
-H 'content-type: application/json' \
-H 'authorization: v3_user_token <AuthToken>' \
-d '{
    "name": "Sample case name",
    "description": "Sample description",
    "findings": "Sample findings",
    "subject":  null,
    "assignee": null
}'

In the preceding example:

Following is an example response showing the case number.

{
    "number": 1,
    "name": "Sample case name",
    "createdAt": "2020-10-27T15:16:05.369203Z",
    "updatedAt": "2020-10-27T15:16:05.369203Z",
    "description": "Sample description",
    "findings": "Sample findings",
    "subject": null,
    "subjectUsername": null,
    "status": "OPEN",
    "assignee": null,
    "assigneeUsername": null,
    "createdByUserUid": "806150685834341101",
    "createdByUsername": "05c28ad3-7eca-4d99-8bb7-a5d0995806c8",
    "lastModifiedByUserUid": "806150685834341101",
    "lastModifiedByUsername": "05c28ad3-7eca-4d99-8bb7-a5d0995806c8"
}

Step 4: Add file events to the case

To populate the new case with information about the alert, add file events to the case using an event ID obtained from the response in Step 2. The following example shows how to add a single file event to a case. Repeat this action for all the file events from the alert.

Copied!
curl -X POST '<RequestURL>/api/v1/case/<CaseNumber>/fileevent/<EventID>' \
-H 'content-type: application/json' \
-H 'authorization: v3_user_token <AuthToken>'

In the preceding example:

  • Replace <RequestURL> with the request URL of your Code42 cloud instance.
  • Replace <CaseNumber> with the case number shown in the response of Step 3.
  • Replace <EventID> with an event ID shown in the response in Step 2.
  • Replace <AuthToken> with the authentication token.

Related topics

 

  • Was this article helpful?