Velociraptor

Velociraptor is a Digital Forensic and Incident Response (DFIR) tool that integrates with the Insight Platform as a component of the Insight Agent. You can use Velociraptor alongside InsightIDR to add DFIR capabilities to your investigative toolset, allowing a greater level of monitoring and swifter responses to issues.

On its own, you can use Velociraptor to continuously monitor endpoints for unusual or suspicious events. When integrated, you can send the event data that Velociraptor collects to InsightIDR. This integration provides you with a single place to detect on and investigate all of the event data in your environment.

Requirements

To access Velociraptor in InsightIDR, you'll need:

  • An InsightIDR Ultimate, Managed Threat Complete Ultimate, or Threat Complete Ultimate license
  • A deployed Insight Agent

Velociraptor access for Managed Threat Complete

For Managed Threat Complete customers, only the Ultimate tier includes access to Velociraptor. Velociraptor is not included in the Managed Threat Complete Essential and Advanced tiers.

User access control

To access Velociraptor, request that your Platform Administrator assign a custom role to your user account with either read-only or full use permissions to the Velociraptor toolset.

Create a custom role with Velociraptor access

Only a Platform Administrator has permission to create custom Platform roles.

To configure a custom role as a Platform Administrator:

  1. From the Insight Platform, navigate to User Management and select Roles.
  2. Click Create Role.
  3. Enter a name and optional description for the new role.
  4. In the Permissions table, select the Hosted Velociraptor feature, and then select the permission level.
  5. After saving the new role, you can assign it to users or user groups as you would other existing roles.

Configure Velociraptor to integrate with InsightIDR

Before you can use InsightIDR to detect on data that Velociraptor collects, you need to configure Velociraptor to monitor clients, track processes, and send data.

Task 1: Set up client monitoring

Velociraptor’s client monitoring feature is a powerful supplement to InsightIDR's detection rules. With client monitoring, you can run continuous queries on each endpoint, retrieving only the events that match the query.

When you set up client monitoring in Velociraptor, you specify the query—also known as an artifact—to run and the endpoints to monitor.

When it's combined with InsightIDR's detection rules, client monitoring allows you to monitor threats and other notable activity in more endpoint data sources, at a greater level of detail. For example, you might use client monitoring to scan your endpoints for known vulnerabilities that have been recently disclosed, using artifacts from the open source Artifact Exchange.

To set up client monitoring:

Task 2: Enable the process tracker

You can use a designated type of client monitoring to track the processes that occur on your endpoints.

Rapid7 recommends setting up Velociraptor's process tracker to gather details about parent and child processes in hunts and collections.

You can enable the process tracker on Windows endpoints only.

Want to learn more?

Read the blog post to understand how the process tracker can be used as an on-endpoint supplement to Log Search's historical tracking, and view examples of how to use the data for DFIR.

To enable the process tracker:

  1. From the Insight Platform navigation menu, select Velociraptor. Velociraptor opens in a new tab.
2. Create a client monitoring group for Windows

Specify the Windows endpoints that you want to monitor and track processes for by creating a client monitoring group.

  1. Navigate to the Client page.
  2. Search for os:windows.
  3. Select all of the search results.
  4. Select the label button.
  5. Add a new label named windows_monitoring.
  6. Select the Client ID button for each Windows endpoint, which ensures that you are connected to the endpoints during the subsequent steps.
3. Configure client monitoring

When you configure client monitoring, you select an artifact that allows you to start monitoring and tracking processes for the endpoints specified in step 2. Configuring client event monitoring enables the process tracker on these endpoints.

  1. Navigate to the Client Events page. (You must be connected to a client to access this page.)
  2. Select the Edit icon.
  3. Select the windows_monitoring label that you created in step 2.
  4. Navigate to the Select Artifacts screen, and select Windows.Events.TrackProcesses.UseExistingSysmonOnly, which is the artifact that enables the process tracker.
  5. Select Configure Parameters to view the default artifact options.
  6. Select Review to view the JSON-formatted update that will be deployed to clients.
  7. Select Launch. Velociraptor starts deploying the update to the endpoints in the windows_monitoring group. It can take up to 10 minutes for the deployment to complete.
4. Verify that the process tracker is enabled

After setting up client monitoring for the specified endpoints, view collected data to check that the process tracker was enabled successfully.

This artifact uses Sysmon data

The Windows.Events.TrackProcesses.UseExistingSysmonOnly artifact that you selected in step 3 enables Velociraptor's process tracking plugins to use Sysmon data. If Sysmon data is unavailable for a specific process, the process tracker still captures data, but with fewer details.

  1. Once the deployment from step 3 is complete, select Windows.Events.TrackProcesses.UseExistingSysmonOnly from the Artifact dropdown.
  2. In the upper right, change the dropdown from Raw Data to Logs.
  3. While still connected to the Windows clients, navigate to Collected Artifacts.
  4. Select the Add icon to create a new collection:
    1. Locate Generic.System.Pstree in the artifacts list.
    2. Select IncludePstree in Configure Parameters.
    3. Optionally, enter ir_agent in the CommandlineRegex field to refine the results.
    4. Review the information on the Specify Resources and Review screens.
    5. Select Launch. After about 10 minutes, the collection starts sending messages to the Log tab to indicate its progress.
  5. When the collection finishes, select Results or Notebook to view the process trees. Refer to Example processes for the information that you can expect to display.

Example processes

The process tracker collects Sysmon process data, which is typically more detailed than other types of process data.

Keep in mind that some processes might be missing Sysmon data if the process started before the artifact was deployed.

Example process with Sysmon data
1
{
2
"Pid":"4300-1684320864"
3
"Ppid":"2632-1683687903"
4
"Name":"ir_agent.exe"
5
"StartTime":"2023-05-17T10:54:24.546Z"
6
"EndTime":"2023-05-17T10:54:29.732Z"
7
"Username":"NT AUTHORITY\SYSTEM"
8
"Exe":"C:\Program Files\Rapid7\Insight Agent\components\insight_agent\3.3.0.2\ir_agent.exe"
9
"CommandLine":""C:\Program Files\Rapid7\Insight Agent\
10
components\insight_agent\3.3.0.2\ir_agent.exe" "--multiproces..."
11
"CurrentDirectory":"C:\Program Files\Rapid7\Insight Agent\components\insight_agent\common\"
12
"FileVersion":"3.3.0.2"
13
"Description":"Rapid7 Insight Agent"
14
"Company":"Rapid7, LLC."
15
"Product":"Insight Agent"
16
"ParentImage":"C:\Program Files\Rapid7\Insight Agent\components\insight_agent\3.3.0.2\ir_agent.exe"
17
"ParentCommandLine":""C:\Program Files\Rapid7\Insight Agent\components\insight_agent\3.3.0.2\ir_agent.exe" "--multiproces..."
18
"TerminalSessionId":"0"
19
"IntegrityLevel":"System"
20
"Hashes":{
21
...
22
}
23
}
Example process without Sysmon data
1
{
2
"Name":"ir_agent.exe"
3
"Username":
4
"NT AUTHORITY\SYSTEM""Exe":
5
"C:\Program Files\Rapid7\Insight Agent\components\insight_agent\3.3.0.2\ir_agent.exe"
6
"CommandLine":""C:\Program Files\Rapid7\Insight Agent\components\
7
insight_agent\3.3.0.2\ir_agent.exe" "--multiproces...""
8
StartTime":"2023-05-10T03:05:09.1065166Z"
9
"EndTime":"2023-05-17T14:13:44.263Z"
10
"Pid":"3340-1683687909"
11
"Ppid":"5012"
12
}

Task 3: Send Velociraptor data to InsightIDR

Once you've started collecting event data through client monitoring, you can send that data to InsightIDR to be detected on.

You send data to InsightIDR by specifying the word Alert in Velociraptor artifact names. Velociraptor sends only the event data retrieved from artifacts that have the word Alert in their name. For example, events from Alert.Windows.ETW.AMSI are sent to InsightIDR, but events from Windows.ETW.AMSI are not.

Refer to the open source Velociraptor documentation to learn how to manage artifacts.

We recommend testing artifacts before sending data to InsightIDR

When using an artifact for the first time—especially a custom artifact—we recommend testing the artifact without Alert in the name. During testing, observe the number of events returned and note potential false positives, and then update artifact name to start sending data to InsightIDR.

Modify Velociraptor detection rules

Once you've configured Velociraptor to send data to InsightIDR, you can modify InsightIDR detection rules to best suit the needs of your environment.

Your InsightIDR Ultimate license provides access to built-in detection rules that monitor events retrieved from Velociraptor. For a complete list of these rules and their details, refer to the Detection Library.

To modify Velociraptor detection rules:

  1. In InsightIDR, navigate to Detection Rules from the left menu.
  2. On the Attacker Behavior Analytics tab, filter for Velociraptor Rules.
  3. Modify the detection rules as needed by changing the Rule Action or Rule Priority, or by adding exceptions.

We recommend tuning detections in InsightIDR, rather than Velociraptor

You can refine detections by modifying artifacts in Velociraptor or by adding exceptions to detection rules in InsightIDR. However, we recommend tuning detections through InsightIDR to keep your detection logic in a single place.

Velociraptor investigations

When an event occurs that meets the logic for a Velociraptor detection rule and the Rule Action is set to Creates Investigation, InsightIDR creates a new investigation. You can take action on Velociraptor investigations in the same ways that you would act on investigations created from other detection rules.

Velociraptor investigations also offer some additional features, including:

  • The ability to inspect the evidence sent from Velociraptor directly in the investigation. When InsightIDR detects on an event that was sent from Velociraptor, the resulting investigation contains information about the associated Velociraptor artifact and the JSON-formatted event data.
  • The ability to select View in Velociraptor, which opens Velociraptor to the endpoint and artifact event page associated with the investigation. Because Velociraptor displays events in a time-bound table, this view can contain additional events that might not be available in the investigation.

Some investigation details are not reflected in Velociraptor

InsightIDR includes some fields in investigations, which are not present in Velociraptor. You can view the investigation disposition, priority, assignee, status, and reason in the InsightIDR investigation only.

Use Velociraptor for DFIR

When integrated with the Insight Platform, you can access Velociraptor and its DFIR features using your Insight Platform login credentials. Read the open source Velociraptor documentation to learn more about using Velociraptor.

To navigate to Velociraptor from the Insight Platform:

  1. Log in to the Insight Platform.
  2. From the platform navigation menu, select Velociraptor. Velociraptor opens in a new tab.
  3. If you have access to multiple organizations, you can select the organization that you want to view directly in Velociraptor.

To navigate to Velociraptor from an investigation:

  1. In InsightIDR, navigate to an investigation that was created from a Velociraptor detection rule.
  2. Click View in Velociraptor. Velociraptor opens in a new tab to the endpoint and artifact event page associated with the investigation.

Troubleshooting

Velociraptor integrated with the Insight Platform offers the majority of the same capabilities as the open source version. However, due to security and performance considerations, integrated Velociraptor has certain differences.

Feature limitations

Integrated Velociraptor limits some features available in the open source version, including:

  • Functions and plugins that interact with the server’s file system are disabled.
  • The inventory service that hosts external tools is disabled. Artifacts that require access to the inventory service will not work as expected.
  • The http_client plugin is disabled on the server. Server-side enrichment workflows that require contacting external services will not work as expected.
  • Access to Velociraptor's gRPC API is unavailable.
  • To prevent loss of communication with other Rapid7 Insight products, Velociraptor's quarantine function is unavailable. Endpoints quarantined using the Insight Agent's quarantine feature will still be able to communicate with the Platform-hosted Velociraptor server.
Performance and polling

To manage the large number of endpoints connected to the Insight Platform, Rapid7’s implementation of the Velociraptor client communicates in two polling modes:

  • Slow poll mode - This is the default mode. As long as a client has not received a task from the server in more than 15 minutes, it checks for new tasks every 10 minutes.
  • Fast poll mode - Once a client receives a task, it switches to fast poll mode, checking every minute for new work.

As a result, when you create a hunt, client collection, or VFS query, it can take up to 10 minutes before results appear. Hunts also won't have a populated client list until the client starts the associated collection job and begins sending logs or results.

It's normal for a hunt not to show any activity for several minutes, especially if the targeted endpoints have been idle.