Integrate Code42 with Rapid7
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
Windows automated task
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.
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.
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 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 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
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
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
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
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
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
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
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
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
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
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