The Velociraptor API And FUSE

Mike Cohen

The Velociraptor GUI is very useful, but for the power user, the Velociraptor API provides a powerful mechanism to integrate and automate. We previously discussed how the Velociraptor API can be used by external programs. This post explore a sample program that uses the API and presents a client’s VFS as a FUSE directory.

This allows us to navigate the remote end point’s file system as if it was mounted locally — we can list directories or fetch files, or even open remote files using third party programs. All the while, these actions are fully audited on the server and the collected files are stored in Velociraptor’s file store for archiving and evidence preservation.


Consider an analyst investigating an end point. The analyst has some third party tools on their workstation which they would like to use on files obtained from the end point.

Filesystem in Usespace (FUSE) is a way of creating the illusion of a real filesystem using software. When various programs on the computer requests filesystem operations, such as listing files in a directory or reading a file, Velociraptor takes over and emulates these requests.

Velociraptor’s built in FUSE program emulates a filesystem by exporting a client’s cached VFS on the server to the FUSE layer. If the analyst attempts to list a directory that the server has no cache of — the server will issue a new directory listing request from the endpoint. If the endpoint is currently online, the updated directory listing will be returned to the server, and in turn relayed to the analyst’s workstation.

The overall effect is that as the analyst navigates around the FUSE filesystem on their workstation, they are issuing collection requests from the endpoint, and reading their responses in such as way that it appears the endpoint is really mounted on the FUSE filesystem.

The above figure shows all the components and how they are related. Assume the FUSE filesystem is mounted on drive Q: in the analyst’s workstation:

  1. Suppose the analyst is navigating the file Q:\file\ using Windows Explorer.
  2. Velociraptor’s FUSE program running on the analyst workstation will issue an API request to list the file directory within the client’s VFS on the server.
  3. If the server has a locally cached version of this VFS directory in its data store it will return it immediately.
  4. However, if no server side cache exists, the FUSE program will issue a directory listing request to the endpoint.
  5. The endpoint will respond to this and return the directory listing (if it is currently online).
  6. Now the server will contain a cached copy of the VFS directory and can return it (just as in step 3 above).
  7. The Velociraptor FUSE program on the workstation can return the directory listing to the Windows kernel and this will be fed back into the Windows Explorer. The end result is that Windows Explorer appears to be navigating the endpoint’s filesystem directly.

You can see this process in the screenshot below:

Tip: Do not run the fuse API command as a different user to what is currently logged in (e.g. do not run as Administrator). If you do then you will not be able to see the FUSE drive in your user’s desktop session.

For example if you are logged in as user “Test”, then any FUSE drives created by Velociraptor running as user Test are only visible to user Test. If you run the above command as an elevated UAC prompt then user Test will be unable to see the new drive.

Running the FUSE program

On Windows filesystem in userspace is implemented by the WinFSP project. You will need to download and install it first.

We require an API key to use the fuse feature so generate one first on the server:

Now simply copy the generated api_client.yaml file to the analyst’s workstation. You can mount any client’s VFS by simply specifying its client id and a drive letter to access it:

Simply press Ctrl-C to stop the FUSE program as any time.


The FUSE feature is a perfect example of a useful API program. The program fully automates the Velociraptor server — it received cached information about the client’s VFS status, and then automatically issues new collection requests as needed.

This kind of automated control of the Velociraptor server opens the door to many such applications. From automated response to remediation and automated evidence collection.

Note: Some users has asked us what the difference between the FUSE program and other tools, e.g. F-Response which also create the illusion that the remote system is mounted on the analyst’s workstation. The main difference is that Velociraptor does not export the raw block device from the endpoint — it simply exports the files and directories we collected already. So for example, it is not possible to run a low level disk analysis system (such as X-Ways) on the mounted FUSE drive. However you can still run specialized file parsers (such as Kape or log2timeline) as long as they do not require access to the raw devices.

Originally published on the Velociraptor Blog

Mike Cohen

Written by

Founder of Velocidex, a digital forensics and incident response startup. Developer of Velociraptor — an advanced EDR platform

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade