Integrate Code42 with Rapid7

Last updated
Save as PDF

Overview

Rapid7 InsightIDR is a security center solution that contains security information and event management (SIEM), user behavior analytics (UBA), and endpoint detection and response (EDR) solutions. This tutorial explains how to ingest file exfiltration event data from Code42 into Rapid7 InsightIDR using a Rapid7 Collector and the Code42 command-line interface (CLI).

Considerations

Rapid7

For more detailed information about setting up and configuring the Rapid7 Collector, see Rapid7's InsightIDR Collector Overview documentation.
This article describes, as an example, how to download, install, and configure the Rapid7 Collector on the same dedicated machine (CentOS 7.3) as the Code42 CLI.

Code42 command-line interface (CLI)

Python version 3.5 or later is required. For instructions on downloading and installing Python, see the Python documentation.
Your orchestration server must be able to connect via SSL (ports 80 and 443) to your Code42 console address.
For instructor-led training on using the Code42 CLI, visit the Code42 University.

Before you begin

Create an API client

In the Code42 console, create an API client to provide permissions in the CLI for the integration with Rapid7:

User role: As a user with the Insider Risk Admin role, create an API client solely to be used by the integration with Rapid7.
Permissions: Set the necessary API permissions in the API client to the minimal permissions needed by the integration. (After granting access in the CLI with the API client ID and secret, test to confirm that the necessary data is accessible in Rapid7.)

Install and configure the Code42 CLI

To integrate with Rapid7, you must first install the Code42 CLI and create a profile following the instructions in https://clidocs.code42.com.

Step 1: Collect file exfiltration event data

After you've completed the steps of creating a user and setting up the Code42 CLI, create an automated task or cron job for running a query on a scheduled basis.

Linux cron job

Create a cron job for the user account on the Linux system. The script below is a static example. Modify it to meet the needs of your local environment.
Copied!
```
crontab -e
 
*/15 * * * * dbus-run-session -- /home/exampledirectory/scriptname.sh
```
(Optional) To log the cron job, add the following at the end of the script:
Copied!
```
>> /home/exampledirectory/<examplelogname.log> 2>&1
```

Ensure that the script is executable.
The script below is a dynamic example for the most recent file events.

cat c42aedpull
# See commented code42 command for a non-incremental example
 
printf '[%s] %s\n' "$(date '+%Y-%m-%d %H:%M:%S')" "Run: - Enable Dbus session and run command"
eval "$(printf '\n' | gnome-keyring-daemon --unlock)"
eval "$(printf '\n' | /usr/bin/gnome-keyring-daemon --start)"
#/home/exampledirectory/.local/bin/code42 security-data -b "2020-04-27 00:12:00" -f CEF --profile yourprofile --c42-username your.user@example.com > /home/yourdirectory/code42cef-out
/home/exampledirectory/.local/bin/code42 security-data send-to 172.19.50.70:2014 -b "2020-04-27 00:12:00" --use-checkpoint example_checkpoint -f JSON --profile demo --c42-username your.user@example.com --include-non-exposure
printf '[%s] %s\n' "$(date '+%Y-%m-%d %H:%M:%S')" "Complete:"

Windows automated task

Step 1: Create a script

Create a script (for example, batch, Powershell, or other) to execute the Code42 CLI command with the arguments required. The script makes it easy to perform adjustments or execute complex (compound) queries. In the example below, run.bat is used.

@echo off
 
code42 security-data send-to 172.19.50.70:2014 -f CEF -b 2021-04-27 --use-checkpoint example-checkpoint --profile demo_profile >> c:\rapid7\c42\code42data.txt
code42 additional queries here as needed

Step 2: Create a scheduled task

Use Task Scheduler to create a scheduled task to repeat as needed.

From the Triggers tab, create a new trigger.
Set the trigger to run Daily.
Set the trigger to Recur every: 1 days.
Select Repeat task every and choose a time frame.
Choose the duration of: Indefinitely.
(Optional) Select Stop task if it runs longer than: 30 minutes.
From the Actions tab, create the action to execute batch script (for example, run.bat).
(Optional) From the Settings tab, select the retry and force stop settings that match the recurring schedule.

Step 2: Configure log collection into Rapid7 InsightIDR

Download, install, and configure the Rapid7 InsightIDR collector either on the orchestration server you are using for the Code42 CLI or on another dedicated system. For more information, see the Rapid7 documentation.

Download and install the collector

Sign in to the Rapid7 InsightIDR console.
If necessary based on your Rapid7 products, click Open on the Insight IDR tile.
From the left menu, select Data Collection.
Select Setup Collector > Download Collector.
Select the download option for your environment (Windows or Linux).
Install the collector following the instructions in the Rapid7 documentation.

Copy Agent key for Linux installations
Once the installation completes successfully, copy the Agent key as directed in the instructions for Linux. The Agent key is required for activating the collector in the following steps.

Activate the collector

Once the collector is installed and the service is started, go back to the Rapid7 InsightIDR console in your web browser.

Select Data Collection from the left menu.
Select Setup Collector > Activate Collector.
Enter a Collector Name.
Paste the agent key from the previous step into the Activation Token field.
Once the activation process completes, the collector appears on the Collectors screen.

Step 3: Configure the Code42 source for collection by the agent

From the Data Collection Management page, select the Event Sources tab.
Click Add Event Source.
Scroll down to the Raw Data section and select Custom Logs.

The Add Event Source window opens.
Select the collector you added previously.
For the Event Source Type, select Rapid7 Custom Logs.
For the Collection Method, select Listen on Network Port if you're using the Code42 CLI to send your data to the Rapid7 collector via syslog.
Complete the rest of the required fields.
Select Save.
The source is now configured and logs begin flowing from the orchestration server to your Rapid7 InsightIDR environment.

Log type

The available log type is Code42 Exposure Events.

Sample log message

{"eventId": "0_c4b5e830-824a-40a3-a6d9-345664cfbb33_941983451917189059_971295845574006661_193", 
"eventType": "READ_BY_APP", "eventTimestamp": "2020-09-09T20:55:47.087Z", 
"insertionTimestamp": "2020-09-09T20:57:22.179901Z", "fieldErrors": [], 
"filePath": "C:/Users/first.last/Documents/", "fileName": "filename.png", 
"fileType": "FILE", "fileCategory": "IMAGE", "fileCategoryByBytes": "Image", 
"fileCategoryByExtension": "Image", "fileSize": 4052619, "fileOwner": 
"first.last", "md5Checksum": "4d43da7448e03de913622559d35d84af", 
"sha256Checksum": "f25e1fb2665a6fa3edd505f4c4ffb8b5bd84a5f3e5373c0db8b76ebea678bedd", 
"createTimestamp": "2020-02-10T04:38:42Z", "modifyTimestamp": 
"2020-02-10T04:38:42Z", "deviceUserName": "vistor.welch@example.com", 
"osHostName": "FIRSTL-WIN10", "domainName": " FIRSTL-WIN10.example.com", 
"publicIpAddress": "XXX.XXX.XX.XXX", "privateIpAddresses": ["XXX.XXX.XX.XXX 
", "fe80:0:0:0:1d77:dcdf:c593:1143%eth4", "0:0:0:0:0:0:0:1", "127.0.0.1"], 
"deviceUid": "941983451917189059", "userUid": "902428473202283166", "actor": 
null, "directoryId": [], "source": "Endpoint", "url": null, "shared": null, 
"sharedWith": [], "sharingTypeAdded": [], "cloudDriveId": null, 
"detectionSourceAlias": null, "fileId": null, "exposure": 
["ApplicationRead"], "processOwner": "first.last", "processName": "\\Device\
\HarddiskVolume2\\Program Files (x86)\\Google\\Chrome\\Application\
\chrome.exe", "windowTitle": ["Files - OneDrive - Google Chrome"], "tabUrl": 
"https://my.sharepoint.com/personal/first_last_onmicrosoft_com/_layouts/15/
onedrive.aspx", "removableMediaVendor": null, "removableMediaName": null, 
"removableMediaSerialNumber": null, "removableMediaCapacity": null, 
"removableMediaBusType": null, "removableMediaMediaName": null, 
"removableMediaVolumeName": [], "removableMediaPartitionId": [], 
"syncDestination": null, "syncDestinationUsername": [], 
"emailDlpPolicyNames": null, "emailSubject": null, "emailSender": null, 
"emailFrom": null, "emailRecipients": null, "outsideActiveHours": false, 
"mimeTypeByBytes": "image/png", "mimeTypeByExtension": "image/png", 
"mimeTypeMismatch": false, "printJobName": null, "printerName": null, 
"printedFilesBackupPath": null, "remoteActivity": "TRUE", "trusted": true, 
"operatingSystemUser": "first.last"}

Step 4: Configure the Code42 dashboard

Configure a dashboard in Rapid7 InsightIDR with visualizations based on specific Code42 use cases.

Select Dashboards and Reporting.
Create a new dashboard. See the Rapid7 documentation for detailed instructions.
Customize the visualization cards and create dashboards to meet your needs. These visualizations are only based on Code42 data and do not contain other data sources.

Code42_Dashboard

Visualization card samples

Below are details about the visualization cards displayed above, including the visualization name, the type of visualization, and the query used for the visualization.

Total exposures

This visualization shows the total count of all Code42 exposure events in the last 30 days.

Log Set: Code42 Incydr data
Query: calculate(count)
Visualization Option: # Calculated Number

Total_exposures

Total exposures by source

This visualization shows the number of Code42 exposure events in the last 30 days, per source.

Log Set: Code42 Incydr data
Query: groupBy(source)calculate(count)
Visualization Option: Table Data

Total_Exposures_by_Source

Total Count - Untrusted Activity

This visualization shows the total count of Code42 exposure events from outside your trusted domains, in the last 30 days.

Log Set: Code42 Incydr data
Query: where(trusted=false)calculate(count)
Visualization Option: # Calculated Number

TotalCountUntrustedActivity

Mime Type Mismatch Activity

This visualization shows file mismatch activity within the last 30 days, grouped by Device Username, filemane, and md5Checksum.

Log Set: Code42 Incydr data
Query: where(mimeTypeMismatch=true)groupBy(deviceUserName, fileName, md5Checksum)
Visualization Option: Table Data

MimeTypeMismatchActivity

Removable Media Activity

This visualization shows the exposure events where users have moved files to removable media. It is grouped by username and filename.

Log Set: Code42 Incydr data
Query: where(exposure.0=RemovableMedia) groupBy(deviceUserName, fileName)
Visualization Option: Pie Chart

RemovableMediaActivity

Cloud Sharing Activity

This visualization shows Code42 cloud sharing exposure events (GoogleDrive, Box, and OneDrive only) in the last 30 days, grouped by source, exposure type, and actor.

Log Set: Code42 Incydr data
Query: where(source = Box OR GoogleDrive OR OneDrive) groupBy(source, exposure.0, actor)
Visualization Option: Pie Chart

CloudSharingActivity

Unsanctioned DropBox Activity by User

This visualization shows Code42 exposure events related to DropBox for the last 30 days. If Dropbox is not an approved application within your organization, this visualization helps identify unsanctioned cloud sharing activity.

Log Set: Code42 Incydr data
Query: where(destinationName = Dropbox)groupBy(deviceUserName)calculate(count)
Visualization Option: Table Data

UnsanctionedDropBoxActivitybyUser

Zip File Exposures by User

This visualization shows Code42 zip file exposure events in the last 30 days, grouped by username.

Log Set: Code42 Incydr data
Query: where(fileCategory = Archive )groupBy(deviceUserName)calculate(count)
Visualization Option: Table Data

ZipFileExposuresbyUser

Cloud Sharing Activity by File Category

This visualization shows Code42 cloud sharing activity, grouped by File Category and filename, in the last 30 days.

Log Set: Code42 Incydr data
Query: where(source = Box OR GoogleDrive OR OneDrive) groupBy(source, actor, exposure.0, fileCategory, fileName))
Visualization Option: Table Data

CloudSharingActivitybyFileCategory

Outside active hours

This visualization shows file exposure activity that happened outside the hours an employee is typically active, in the last 30 days.

Log Set: Code42 Incydr data
Query: where(outsideActiveHours=true) groupBy(deviceUserName, fileName)
Visualization Option: Table Data

OutsideActiveHours

AirDrop Syncs

This visualization shows the files shared via AirDrop in the last 30 days, grouped by user and file name.

Log Set: Code42 Incydr data
Query: where(processName="/usr/libexec/sharingd")groupBy(deviceUserName, fileName)
Visualization Option: Table Data

AirDropSyncs

Email exposures

This visualization shows the files uploaded to an email provider via web browser in the last 30 days, grouped by username and filename.

Log Set: Code42 Incydr data
Query: where(destinationCategory = Email)groupBy(deviceUserName, fileName)
Visualization Option: Pie Chart

EmailExposures

Source Code Repository Activity

This visualization shows the files uploaded to a source code repository, by user, in the last 30 days.

Log Set: Code42 Incydr data
Query: where(destinationCategory = "Source Code Repository")groupBy(deviceUserName, destinationName)
Visualization Option: Pie Chart

SourceCodeRepositoryActivity