Manage Forensic Data Ingestion Tools with the API
Note
To use the data ingestion tool features, you can add the DFIR package to your instance of the Cybereason platform for an additional cost or request an Express IR environment (partners only). Contact your Customer Success representative to request access to this package or for details on how to submit the request, see How to Request a Cybereason Express IR Environment.
Using the Cybereason platform incident response architecture, you can collect and ingest forensic data to the Cybereason platform using the Cybereason platform data ingestion features. The Cybereason platform then correlates the forensic data with other existing data.
The forensic data ingestion tool package provided with your DFIR purchase includes the Velociraptor agent, an open-source forensic investigation tool, which regularly undergoes Cybereason performance and security testing. Any issues with the Velociraptor agent are the responsibility of and will be resolved by Rapid7 and the Velociraptor team.
This topic describes the steps necessary to manage the forensic data ingestion tool process with your Cybereason platform.
The use of forensic data ingestion tools is supported on Windows machines.
Note
You can also manage forensic data ingestion tools with the Cybereason platform’s main console. For details on how to use IR Tools screen to manage these tools, see Manage Incident Response and Forensic Data Ingestion Tools with the Platform.
In this topic:
Enable the DFIR package
If you do not use an Express IR environment as a Cybereason IR partner, you can purchase and enable the DFIR package in your environment.
Note
To enable the DFIR package, you must upgrade your environment. You cannot enable the DFIR package on an existing version without a version upgrade.
Open a Technical Support to upgrade your environment and add the DFIR package to your environment. As part of the DFIR package enablement, incident response tool management features are also enabled for your environment.
Before you begin
Because the ability to collect forensics data through the Cybereason platform uses the platform’s incident response management infrastructure, many of the initial steps required are the same as the incident response tool management process, including:
Deploy Cybereason sensors
Create a Responder L2 user
Log in to the platform
For details on these steps, see Manage Incident Response Tools with the API.
Deploy a forensic data ingestion tool
When you enable forensic data ingestion, the supported forensics data ingestion packages files are added to your environment. You only need to deploy these tools to the necessary machines.
To deploy a forensic data ingestion tool, follow these steps:
In your REST API client or script, create a request to get the list of supported forensic data ingestion packages files. For details on the API endpoint to retrieve this list, see the Retrieve the List of Supported Forensic Data Ingestion Tools topic in the API documentation.
In your REST API client or script, create and run the request to deploy the tool. The name of the package should be one of the names returned in the list of supported packages files.
For details on the API endpoint to deploy a forensics data ingestion tool, see the Deploy a Forensic Data Ingestion Tool topic.
During the deployment, you can track the progress using the Monitor Deployment of Forensic Data Ingestion Tools Deployment API endpoint.
Run a forensic data ingestion tool
Once you deploy the tool to the appropriate machines, you can run the tool on selected machines.
To run a forensic data ingestion tool on a machine, follow these steps:
In your REST API client or script, create the request to run the forensic data ingestion tools. For details on using the API endpoint to run the tools, see the Run a Forensic Data Ingestion Tool topic in the API documentation.
In your API request body, ensure that you run the tool on a specific sensor or a filtered group of sensors, but not both. Specifying a specific sensor and a filtered group of sensors will cause the request to fail.
You do not need to specify any run commands, queries, or output locations for the forensic tools. The tools you receive with your environment contain the required queries and settings to perform forensic ingestion from machines and then send this data directly to the Cybereason platform.
Run the request or script using your REST API client or automation framework.
You may only need to run the standard forensic data ingestion tool request one time. This initial request collects data on operations on the machine prior to the installation of the Cybereason sensor. However, after the Cybereason sensor is installed (which is required for forensic tool deployment and execution), the same information collected by the forensic ingestion tool is also collected by the Cybereason sensor.
If you run the forensic data ingestion tool again, you may end up with duplicate data that displays differently in the Investigation screen. For example, the same information may appear as part of the Process Element if the sensor collects the information and as part of the Forensic Artifacts Element if the forensic data ingestion tool collects the data. However, any data collected by the forensic data ingestion tool is not duplicated in the Forensic Artifacts Element if you run the forensic data ingestion tool more than one time.
The response for the request to run a forensic data ingestion tool contains a batch number which indicates the successful initiation of the tool on selected endpoints. In order to monitor the execution status on endpoints, see the Monitor Forensic Data Ingestion Tool Execution reference topic in the API documentation.
Evaluate collected forensic data
Upon the completion of a forensic tool execution run, the collected data is sent to your Cybereason platform’s detection servers, where it is integrated with existing data from other sources. The platform’s CMC engine evaluates and correlates the forensic data with all other data.
You can view data from forensic sources in a number of places:
The Forensic Artifacts Element enables you to build queries to find specific forensic information:
For details on the Forensic Artifacts Element, see the Query Elements and Features topic.
Because the platform correlates forensic data with other data, often items collected from forensic sources will be part of the details associated with a Malop, suspicion, or evidence. The platform displays items from forensic sources with a (forensic) string to indicate their origin:
Remove a forensic data ingestion tool
After you have completed the forensic data ingestion process, you can remove these tools from endpoint machines. For details on the API endpoint to remove the tool, see Delete a Forensic Data Ingestion Tool.
When you remove the forensic tool, you delete the tool from endpoint machines.