NAV

Respond to an alert

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 provides a use case showing how to use the 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:

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 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 faster and more 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 against the time savings provided when they run.

What are the kinds of alerts you want to receive?

You want to receive alerts when users perform actions that are considered high risk. 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 tokens are required to run the APIs. The tokens must be generated by a Code42 administrator with the proper role assignments.

Your company's entity in the Code42 cloud is known as a "tenant". To obtain your tenant ID, submit a request to the customer API.

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, user reports, or the user API.

Steps

Search for significant alerts

Alerts are an excellent way to get notifications about suspicious file activity. However, sometimes it can be difficult to separate the truly important ones from the rest. To find alerts that are worthy of further investigation, use the /v1/alerts/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.

curl -X POST "<RequestURL>/v1/alerts/query-alerts" \
-H "accept: text/plain" \
-H "Authorization: Bearer <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:

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": []
}

Note: 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.

View alert details

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

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

In the preceding example:

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\"]}"
        }
      ]
    }
  ]
}

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 using the /v1/file-events API command demonstrates a search for all files on all devices with the file extension .docx that exist anywhere in the file path C:/Users. 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  <RequestURL>/v1/file-events \
-H 'content-type: application/json' \
-H "authorization: Bearer <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
}'

Open a case

To track your investigation of the event that triggered the alert, use the /v1/cases API command to create a case. Only the "name" parameter is required. To leave a field blank, supply the value null.

curl -X POST <RequestURL>/v1/cases \
-H 'content-type: application/json' \
-H 'authorization: Bearer <AuthToken>' \
-d '{
  "name": "Sample case name",
  "description": "Sample description",
  "findings": "Sample findings",
  "subject": "<UserUID>",
  "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": "806154242834341101",
  "createdByUsername": "user@example.com",
  "lastModifiedByUserUid": "806154242834341101",
  "lastModifiedByUsername": "user@example.com"
}

Add file events to the case

To populate the new case with information about the alert, add file events from the alert to the case using the /v1/cases/<CaseNumber>/fileevent/<EventID> API command. Repeat this action for all the file events from the alert.

curl -X POST '<RequestURL>/v1/cases/<CaseNumber>/fileevent/<EventID>' \
-H 'content-type: application/json' \
-H 'authorization: Bearer <AuthToken>'

In the preceding example: