Knowledge Base on Velociraptor - Digging deeper!

How to create and use an offline collector as a tool

Thu, 26 Mar 2026 00:00:00 +0000

How to create and use an offline collector as a tool

This article demonstrates how to create a generic offline collector and then use it as a Velociraptor tool with conventional “online” clients.

Velociraptor offline collectors are a popular deployment mode in which one or more artifacts are collected from endpoints, the results are packaged inside a zip container, and then optionally uploaded to a remote storage destination. Typically the remote destination is a cloud storage provider such as AWS S3, Azure, or Google Cloud Storage, but it can also be a storage service set up on the local network.

Offline collectors provide the same capabilities as normal network-connected clients, but perform a one-off collection of predefined artifacts rather than being tasked to collect artifacts as needed by the server.

However, you might have Velociraptor clients deployed, and you are using these network-connected “online” clients to run smaller more focused queries, but you also occasionally want to do an offline-collector-style bulk file acquisitions.

With network-connected clients the results are uploaded to the Velociraptor server. File uploads are also done separately rather than being bundled into a single zip archive. This might not be desirable in certain circumstances, for example:

if the server’s storage is not spec’d to handle the total size of these bulk collections, which are typically large if they consist mostly of copied files. In that case, you might want the collections uploaded to an alternative destination where storage space is less constrained.
if you want to post-process these collection zips using other tools, then you might already have a process that includes retrieving them from the remote storage location. In that case, having the collected data in per-endpoint collection zips might also help with the retrieval and post-processing.

Offline collectors are created by the Server.Utils.CreateCollector server artifact, which creates a special embeddable configuration with the selected client artifacts, tools, and remote upload configuration included. Since it’s all just VQL you could, in theory, create a client artifact that replicates the actions of any offline collector. However, in practice the Server.Utils.CreateCollector artifact is significantly complex. Creating a custom version of it that can be run by clients would be a daunting task. It’s much easier to create the offline collector in the normal way, and then run it via a client as a tool. This is the approach taken in this article.

Offline collectors are sometimes used in situations when they aren’t really needed, or aren’t actually the best option.

Before deciding to use an offline collector, you should consider the following points.

You can collect exactly the same artifacts with online clients that you can collect with offline collectors.
Offline collectors are not the only available option when you can’t install clients. If you can’t (or don’t want to) install clients, you still have the option of using clients without installing them, as explained in the KB article How to create an “online collector” binary.

Overview

The overall goal here is to have the client download an offline collector as a tool from the server and run it. The offline collector will in turn create a collection container zip and upload it to a remote S3 server.

Process overview

In this case I’ll use Garage which is an open source S3-compatible server written in Rust, but you could use AWS S3, or MinIO, or any other S3-compatible server, or even one the other remote destination options that are supported by Velociraptor offline collectors.

The high-level steps to achieve this goal are:

Set up an S3-compatible storage server (Garage).
Create a generic offline collector and store it in the Velociraptor tools repository.
Create a client artifact to run the offline collector on a live client, using the collector as a tool.
Run the collection on a single endpoint or multiple endpoints.
Download the collection zip files from the S3 bucket and work with the results.

The Velociraptor server and clients are assumed to be set up and working correctly. As mentioned previously, the clients don’t necessarily need to be installed - they could be running without installation.

1. Set up the Garage S3 server

To keep things as simple as possible, I’ll use a single-node Garage server as the remote destination for the offline collector uploads. This is similar to using an SFTP or SMB server running on the local network.

Generate a basic configuration file as explained in the Garage Quickstart guide.

Configure the Garage server’s storage and access keys, also as per their quickstart guide.

Here are the commands I used (for brevity, the corresponding output is not shown):

# start the server
garage -c ./garage.toml server

# check the server status and get the node ID
garage -c ./garage.toml status

# create a cluster layout
garage -c ./garage.toml layout assign -z dc1 -c 1G d7d19e6f32edec53

# apply the layout
garage -c ./garage.toml layout apply --version 1

# create a bucket
garage -c ./garage.toml bucket create offline-collections

# check that the bucket has been created
garage -c ./garage.toml bucket list

# view the bucket configuration
garage -c ./garage.toml bucket info offline-collections

# create an identity for the collector to use
garage -c ./garage.toml key create offline-collections-key

# assign write-only access to the bucket for this user
garage -c ./garage.toml bucket allow --write offline-collections --key offline-collections-key

# create a bucket admin user
garage -c ./garage.toml key create offline-collections-owner

# assign full access to the bucket for this user
garage -c ./garage.toml bucket allow --write --read --owner offline-collections --key offline-collections-owner

I’ve created one bucket to receive the collection zips, named offline-collections, and I’ve created 2 keys with access to it.
- offline-collections-key: with only write access, that will be used by the clients to upload their collection zips
- offline-collections-owner: with full access for browsing and downloading the collection zips.
The reason for creating 2 keys is that the write-only key will be included in the offline collector for the purpose of uploading the collection zips. Because it’s possible to extract the key from the offline collector I want it to have no greater permissions than are necessary. It only needs to be able to upload files to the bucket, and cannot list/download/modify/delete other files in the bucket.

The final bucket and access configuration can be inspected with the command: garage -c ./garage.toml bucket info offline-collections.
```
==== BUCKET INFORMATION ====
Bucket:          d5f9982666e004de45114bcfc1e9428755c15d12f55a2dac7bc77dc495343e97
Created:         2026-03-16 16:28:13.689 +02:00

Size:            0 B (0 B)
Objects:         0

Website access:  false

Global alias:    offline-collections

==== KEYS FOR THIS BUCKET ====
Permissions  Access key                                             Local aliases
W           GKaa23dd92075b4dc6fc9fe54f  offline-collections-key
RWO          GK08c8137adf22d3b08c6ea088  offline-collections-owner
```

I’ll access the bucket using the offline-collections-owner credentials on the command line using the mc (MinIO client) utility available from https://dl.min.io/client/mc/release/.

# download the tool and make it executable
wget https://dl.min.io/client/mc/release/linux-amd64/mc
chmod +x ./mc

# Save credentials and connection info for the mc tool
mc alias set \
garage \
http://192.168.56.1:3900 \
GK08c8137adf22d3b08c6ea088 \
389adafacb2e3b1c96f9216b9a77c89b74b4d64949d1a0e90f3ca88378f2ca4e \
--api S3v4

With the credentials configured, I’ll test access by uploading a file to the bucket, then listing the bucket’s contents, and finally clearing everything from the bucket (command output is omitted).

# copy a file to the bucket
mc cp /proc/cpuinfo garage/offline-collections/cpuinfo.txt

# list bucket contents
mc ls garage/offline-collections

# remove everything from the bucket
mc rm --force --recursive garage/offline-collections

Looks good. The S3 server is ready, so now we can create the offline collector.

2. Create a generic collector and store it in the Velociraptor tools repository.

In this step I am going to create a generic collector and add it to the server’s tools inventory.

There are several ways that this could be done, but I want to:

automate the creation of the offline collector via a server artifact, and also
have it also add the tool to the tools inventory.

To achieve this I’ll create a server artifact that runs Server.Utils.CreateCollector and stores the resulting offline collector file as a tool that other client artifacts can use.

By having an artifact that performs this step, I’ll be able to easily create additional collectors with different sets of artifact selections as tools. These other collectors could have artifact selections for alternative Windows use cases, or they might be selections of artifacts chosen to target non-Windows platforms. All I need to do is select appropriate artifacts when creating additional collectors and give each collector a unique tool name.

For my first collector I intend to target Windows and have it run the following artifacts:

Windows.Triage.Targets (with HighLevelTargets = _Live)
Generic.Forensic.SQLiteHunter
Generic.Client.Info

2.1 Create a collector test build

As a test, and to ensure that I get the collector configuration right, I’ll first create it manually. Then I’ll test it on a Windows endpoint to ensure that the S3 upload aspect works correctly. To do this I run the “Build offline collector” wizard which is launched from the Server Artifacts screen.

Choose the artifacts I want to collect, as listed above.

Artifact selections
Configure the artifact parameters.

In this case all I did was configure Windows.Triage.Targets with the _Live High Level Target.

Artifact parameters
Configure the collector itself.

The reason I want to create and use a generic collector is because the client already has the correct Velociraptor binary - the one from which the client itself is running. There’s no reason to repack and distribute another full binary. The generic collector will be significantly smaller and provide exactly the same result.

Collector configuration

Here I used the following settings, which correspond to my specific environment, including the configuration of my Garage S3 server. Settings not listed here were left as default.
- Target Operating System: Generic Collector
- Encryption Scheme: X509 Certificate/Frontend Certificate
- Collection Type: AWS Bucket
- S3 Bucket: offline-collections
- Credentials Key: [ my Key ID for offline-collections-key ]
- Credentials Secret: [ my Secret Key for offline-collections-key ]
- Region garage
- Endpoint: http://192.168.56.1:3900 (my garage server IP and S3_api port)
- Skip Cert Verification: Y
- Pause For Prompt: Y
- Collector Name: collector-windows-triage
- Delete Collection at Exit: Y
Launch the artifact and let it create the collector.

Now I can go download the collector from the artifact’s Uploaded Files tab.

Download the collector

I copy it over to a Windows machine that already has a Velociraptor client installed, and that therefore has the binary with which I can run the generic collector (as administrator).

C:\Program Files\Velociraptor>velociraptor -- --embedded_config collector-windows-triage

Manually running the generic collector

At the end of the collection it pauses, and I can see the that it reports successfully uploading the results to the Garage S3 server.

The “Delete Collection at Exit” setting removed the collection zip from the local disk after uploading it to the S3 bucket.

From my workstation I can connect to the Garage server and confirm that the collection zip and the collection log were uploaded:

$ mc ls garage/offline-collections
[2026-03-25 11:19:48 SAST] 107KiB STANDARD Collection-WIN-KMODJ1W0CYG-2026-03-25T09_19_03Z.log
[2026-03-25 11:19:44 SAST] 611MiB STANDARD Collection-WIN-KMODJ1W0CYG-2026-03-25T09_19_03Z.zip

So the manual collection works as expected, which means the collector settings are correct. However this was just a test step. The next step it to automate the creation of the collector and add it to Velociraptor’s tools inventory.

2.2 Create a collector-generating server artifact

Now that I’m satisfied that my collector configuration works as expected, I’ll create a server artifact that reproduces the creation of that collector.

I want to make a few of the options configurable so I’ll add those as artifact parameters.

name: Custom.CreateCollectorTool
description: |
  Creates a generic offline collector and adds it to the tool inventory.

type: SERVER

parameters:
  - name: artifacts
    type: json_array
    default: '["Windows.Triage.Targets", "Generic.Client.Info", "Generic.Forensic.SQLiteHunter"]'

  - name: artifact_parameters
    type: json
    default: |
      {
        "Generic.Forensic.SQLiteHunter": {
          "DateAfter": "1970-01-01T00:00:00Z",
          "DateBefore": "2100-01-01T00:00:00Z"
        },
        "Windows.Triage.Targets": {
          "HighLevelTargets": "[\"_Live\"]"
        }
      }

  - name: collector_target_args
    type: json
    default: |
      {
       "bucket": "offline-collections",
       "credentialsKey": "GKaa23dd92075b4dc6fc9fe54f",
       "credentialsSecret": "0bdfb02186ded9c01e0f755661c62e087ea2a280443d138ccaa05948e68faa78",
       "region": "garage",
       "endpoint": "http://192.168.56.1:3900",
       "noverifycert": "Y"
      }

  - name: collector_tool_name
    default: 'collector-windows-triage'

  - name: collector_tool_version
    default: '1'

  - name: collector_target
    default: 'S3'

sources:
  - query: |
      LET collector_spec <= dict(
          OS="Generic",
          artifacts=artifacts,
          parameters=artifact_parameters,
          target=collector_target,
          target_args=collector_target_args,
          encryption_scheme="X509",
          opt_verbose="Y",
          opt_banner="Y",
          opt_prompt="Y",
          opt_admin="Y",
          opt_level=5,
          opt_concurrency=2,
          opt_format="jsonl",
          opt_filename_template="Collection-%Hostname%-%TIMESTAMP%",
          opt_collector_filename=collector_tool_name,
          opt_cpu_limit=0,
          opt_progress_timeout=1800,
          opt_timeout=1800,
          opt_delete_at_exit="Y")

      SELECT inventory_add(tool=collector_tool_name,
                                accessor="fs",
                                file=Repacked.Components,
                                version=collector_tool_version,
                                serve_locally=true) AS CollectorTool
      FROM Artifact.Server.Utils.CreateCollector(`**`=collector_spec)

Some things to notice about this artifact:

The Server.Utils.CreateCollector artifact accepts many parameters. I’ve constructed a dict with key names matching the ones that can be seen in the Requests tab after running Server.Utils.CreateCollector in the previous test build.

The Server.Utils.CreateCollector Requests tab
The Server.Utils.CreateCollector has some parameters that I want to be able to easily change, so I’ve added those as parameters to my artifact. Dealing with some of their values is a bit tricky because the JSON that you see in the Requests tab is heavily backslash-escaped. In my artifact:
- the artifacts parameter needs to be a valid JSON array
- the artifact_parametersand collector_target_args parameters need to be a valid JSON objects
To validate your JSON for these parameters, you can use an online tool such as https://jsonlint.com/, which also allows you to prettify it once it’s validated.
Tool versioning is quite important and useful, so I’ve added the tool version as an artifact parameter. This allows me to store multiple versions of the same tool in the tools inventory, and potentially choose a particular version when I run my client artifact.
In the collector_target_args parameter there are a few child fields that are left empty by Server.Utils.CreateCollector, so I’ve omitted those from the JSON to simplify it. I could have done the same with the date filter parameters in Generic.Forensic.SQLiteHunter, and it would just use the defaults for those parameters, but I deliberately kept those fields to highlight the nested JSON structure.
When passing the collector_spec dict to Server.Utils.CreateCollector I’ve used argument unpacking (**= syntax) to make the SELECT clause more succinct.

2.3 Run the server artifact

I can now run this artifact on my server to generate the offline collector and store it in the tools repository.

Custom.CreateCollectorTool Uploaded Files

The Uploaded Files tab of the collection makes the offline collector and associated spec file available for download, but I don’t need to do that because the tool is already stored in the tools inventory.

On the Results tab I can see that the tool has been added to the inventory.

Custom.CreateCollectorTool Uploaded Files

I can also verify that the tool is in the inventory by running the following query in a notebook:

SELECT name, hash, version, serve_locally FROM inventory()
WHERE name =~ "collector-windows-triage"

Querying the inventory in a notebook

3. Create a client artifact to run the offline collector

With the tool added to the inventory, I can now create my client artifact that will use it.

It’s a very simple artifact that leverages the Generic.Utils.FetchBinary utility artifact to fetch the generic collector file from the tools repository.

name: Custom.RunOfflineCollectorTool
description: |
  Runs a generic offline collector retrieved from the server's tools repository.

required_permissions:
  - EXECVE

implied_permissions:
  - FILESYSTEM_WRITE

tools:
# All we need here is the tool name and version because it already exists in
# the tools repository
  - name: collector-windows-triage
    version: "1"

parameters:
# You can have multiple collectors to choose from but they all need to be
# included under the `tools` top-level key.
  - name: collector_name
    type: choices
    default: collector-windows-triage
    choices:
      - collector-windows-triage

sources:
  - query: |
      LET collector <= SELECT *
        FROM Artifact.Generic.Utils.FetchBinary(
                                          ToolName=collector_name,
                                          IsExecutable=FALSE,
                                          SleepDuration="0",
                                          TemporaryOnly=TRUE)

      LET host_info <= SELECT * FROM info()

      LET cmd_args <= (host_info[0].Exe, "--", "--embedded_config",
            collector[0].OSPath)

      SELECT *
      FROM execve(argv=cmd_args, sep="\n")

Some things to notice about this artifact:

It uses the info() plugin to get the full path to the Velociraptor client’s own binary. It then uses that to run the generic collector.
For the Generic.Utils.FetchBinary artifact I’ve specified the parameter TemporaryOnly=TRUE because it’s easy for an adversary to print out the collector config and see what I’m collecting if the file is left lying around on the filesystem. So by avoiding caching the file in the local tools cache, there’s less chance of some else finding it abusing it. It’s also very unlikely that I’d want to run the same offline collector twice, so caching it isn’t really useful.
The artifact makes provision for adding more offline collectors, but I only have one at this stage.
in the tools section I have specified a version number. If I create subsequent versions of the same tool, then I can switch to a specific version if needed by changing this value. If I want it to always use the highest version of the tool, I could not specify a version and it will automatically choose the highest number (taking into account Semantic Versioning if I had chosen to use that scheme).

4. Run the client artifact

I now collect the Custom.RunOfflineCollectorTool on a client. I’m doing this for a single client but it could just as easily be run via a hunt to target many clients.

The collection proceeds on the client and I can view the results, which will come though in near-realtime as the offline collector is running. The collection results are just a line-parsed view the output from Stdout and Stderr.

Near the end of the results I can see that it uploaded the collection container zip to the S3 bucket.

Collection results

On the collections Log tab, I can view the steps taken on the client to run the collector, including things like the command that was used and post-execution cleanup steps.

Collection log

The offline collector doesn’t know it’s being run by a Velociraptor client and, as I mentioned in the overview, the collection data is therefore independent of the Velociraptor server. The client was just being used to run the collector. The collection results and collection log only provide information about running the collector.

5. Download collection zips from the S3 server.

With the collection zips stored in the S3 bucket, any external process can take over from there. You may have an automated process that monitors the bucket for new arrivals, downloads them, and feeds them into a processing pipeline.

In my case, I’m just going to download them manually using the MinIO mc utility that I set up previously.

First I list what’s in the bucket:

mc ls garage/offline-collections

Bucket listing

I then download the files to my desktop using mc:

mc cp --recursive garage/offline-collections /tmp/collections/

At this point I have many options regarding how I might want to work with the collection container zips.

For example I could:

extract the collection zips and work with their contents using other tools, perhaps also using Velociraptor’s command line analysis capabilities alongside the other tools.

or
run an Instant Velociraptor instance on my local workstation, or a set up separate Velociraptor server dedicated to analysis, and then either:
- import the collection container zips before working with their contents, or
- work with the collection container contents without importing them.

As always, Velociraptor give you many options and you’ll need to decide which options work best for your situation. Hopefully the steps demonstrated here are generic enough that they can be easily adapted for similar scenarios.

Encrypt and decrypt an offline collector using PGP public and private keys

Sat, 07 Mar 2026 00:00:00 +0000

Encrypt and decrypt an offline collector using PGP public and private keys

Velociraptor supports three modes for encrypting Offline Collectors: Password, X.509 Secured, and PGP-secured (as described here). While X.509 is the standard for automatic server imports, using PGP is a great alternative when you need to decrypt collections independently of the Velociraptor Server.

The PGP Encryption Workflow: When using PGP, Velociraptor follows a “hybrid” encryption approach:

Generation: Velociraptor generates a high-entropy random password.
Encryption: The collected data is encrypted with this password.
Envelope: The password itself is encrypted using your PGP Public Key and stored in the metadata.
Decryption: To access the data, you must first decrypt the password using your PGP Private Key, then decompress the protected zip using the password.

Step 1: Generate a PGP key-pair

First, generate an RSA key-pair. We will use a batch file for automation, but you can also do this interactively.

gpg --batch --generate-key <<EOF
    Key-Type: RSA
    Key-Length: 3072
    Subkey-Type: RSA
    Subkey-Length: 3072
    Name-Real: Ilo
    Name-Email: ilo@test.com
    Expire-Date: 1y
    %no-protection
    %commit
EOF

# Export the public key for use in the collector
gpg --armor --export ilo@test.com > key.pub

Step 2: Configure the Collector Spec

The easiest way to build the Offline Collector is in the GUI. This approach will generate a Velociraptor Offline Collector and a spec.yaml.

The following will show how to build the offline collector using CLI:

Setup a datastore location
Setup a artifact location (only needed if external artifacts will be used)
Create a template-spec.yaml
Create the Velociraptor Offline Collector

Prepare the CLI environment

mkdir datastore artifacts

# Download reference artifacts and the Velociraptor binary
wget https://triage.velocidex.com/artifacts/Velociraptor_Triage_v0.1.zip -P artifacts
7z x artifacts/Velociraptor_Triage_v0.1.zip -oartifacts
wget https://github.com/Velocidex/velociraptor/releases/download/v0.75/velociraptor-v0.75.6-linux-amd64
chmod +x velociraptor-v0.75.6-linux-amd64

# Generate a base template
./velociraptor-v0.75.6-linux-amd64 collector > template-spec.yaml

Update template-spec.yaml

Edit your YAML file to include your public key in the field public_key. Ensure the EncryptionScheme is set to PGP.

OS: Windows
Artifacts:
 Windows.Triage.Targets:
   HighLevelTargets: '["_SANS_Triage", "_KapeTriage"]'
   Devices: '["C:","D:","E:"]'
Target: ZIP
EncryptionScheme: PGP
EncryptionArgs:
  public_key: |-
    -----BEGIN PGP PUBLIC KEY BLOCK-----

    REDACTED...
    -----END PGP PUBLIC KEY BLOCK-----
  password: ""
OptVerbose: Y
OptBanner: Y
OptPrompt: N
OptAdmin: Y
OptTempdir: ""
OptLevel: 9
OptConcurrency: 2
OptFilenameTemplate: "Collection-%Hostname%-%TIMESTAMP%"
OptCollectorTemplate: ""
OptFormat: jsonl
OptOutputDirectory: ""
OptCpuLimit: 0
OptProgressTimeout: 1800
OptTimeout: 0
OptVersion: ""
OptDeleteAtExit: N

Step 3: Build the Offline Collector

Run the following command to “repack” the Velociraptor binary into a standalone collector based on your spec.

./velociraptor-v0.75.6-linux-amd64 collector --datastore datastore --definitions artifacts template-spec.yaml

[
 {
  "Repacked": {
   "Path": "/REDACTED/datastore/Collector_velociraptor-v0.75.6-windows-amd64.exe",
   "Size": 87421951,
   "UploadId": 0,
   "sha256": "f1487b5686c9616def5c55cd32266b4726162758456d7f5149ebfde51bc3a582",
   "md5": "d46f704b4014dd7a76fa2847b21f813e",
   "Components": [
    "Collector_velociraptor-v0.75.6-windows-amd64.exe"
   ]
  },
  "_Source": "Server.Utils.CreateCollector"
 }
]

Step 4: Decrypt the Results

The Velociraptor Offline Collector will generate a Collector.zip file. The file structure within the container is documented as described here:

data.zip
metadata.json

Within the metadata.json file you fill find the encrypted password in the EncryptedPass entry:

[
 {
  "EncryptedPass": "REDACTED",
  "Scheme": "PGP",
  "PublicKey": "-----BEGIN PGP PUBLIC KEY BLOCK-----\n\nREDACTED\n-----END PGP PUBLIC KEY BLOCK-----"
 }
]

You can decrypt the password and the data using the following commands:

# 1. Extract the encrypted pass from metadata
# 2. Base64 decode it
# 3. Decrypt with GPG
# 4. Use the result as the password for the data zip
PASS=$(7z e -so Collection.zip metadata.json | jq -r '.[].EncryptedPass' | base64 -d | gpg --decrypt)
7z x Collection.zip "-p$PASS" -y

This assumes that the private key is in your gpg vault.

Working with the data

Working with the Offline Collection data is described here

How to set up OIDC authentication using ADFS

Mon, 26 Jan 2026 00:00:00 +0000

How to set up OIDC authentication using ADFS

This guide walks you through the configuration of Microsoft ADFS as an OIDC authentication provider for Velociraptor.

This procedure has been tested with Windows Server 2022 and ADFS 4.0 Velociraptor has been deployed using self signed certificate

ADFS OpenID Configuration can be read with https://auth.domain.local/adfs/.well-known/openid-configuration SSL certificate on ADFS is provided by Let’s Encrypt. Velociraptor Server is on velociraptor.local

setup_adfs

The high-level steps of this setup process are:

Deploy Velociraptor using Self Signed Certificates.
Create a new Application Group in ADFS.
Add the authenticator settings to your Velociraptor config.
Start Velociraptor
Add test users to Velociraptor.
Test the authentication process.

1. Deploy Velociraptor using Self Signed Certificates

Velociraptor quickstart > https://docs.velociraptor.app/docs/deployment/quickstart/

2. Create a new Application Group in ADFS

1. Open ADFS Management Open Server Manager > Tool > AD FS Management

2. Create a New Application Group Select Application Groups and create a new one

3. Welcome Enter a name and select Server Application accessing a web API

4. Server application Enter your Redirect URI : https://velociraptor.local:8889/auth/oidc/callback and add it Save your client identifier, we will use it on velociraptor config file

5. Configure Application Credentials Generate a shared secret and save it

6. Configure WEB API Enter your application identifier and add it

7. Access Control Policy On next window, Choose Access Control Policy and filter as needed

8. Configure Application Permissions Select email, openid, profile

9. Summary Validate your summary and click Next, then complete.

3. Add the authenticator settings to your Velociraptor config

In the GUI section of your Velociraptor config you should have the following authenticator settings by default:

  authenticator:
    type: Basic

We no longer want Basic auth and instead want SSO, so replace that with these new settings to match our Keycloak configuration:

    type: oidc
    oidc_issuer: https://domain.local/adfs
    oidc_name: adfs
    oauth_client_id: e49d074b-c157-40cd-a1b4-0a863bac99aa
    oauth_client_secret: scwp-348TOdnNJ7hzP3pKGXcYS4Ohu2q0JMCyDT0
    # uncommment below if you want a full debug
    # oidc_debug: true

The oauth_client_secret is the value we obtained at the end of step 5. The oauth_client_id is the name we used for the OIDC Client ID in that same section in step 4.

4. Start Velociraptor

The server should now start cleanly and continue running. In the log messages you should see GUI will use the oidc authenticator. That means everything is OK with the authenticator config.

While configuring, testing and potentially troubleshooting problems, it’s easier if you can see Velociraptor’s log messages. You can stop the server service and then run the server manually on the command line by using the following commands:

sudo systemctl stop velociraptor_server
sudo -u velociraptor bash
velociraptor -c /etc/velociraptor/server.config.yaml frontend -v

This will display the log messages in the terminal.

5. Add Users

Even if you have added groups/users through Access Control Policy in step 7, you have to create users in Velociraptor. Users can be created using VQL in Velociraptor notebooks but since we have now switched authentication providers we no longer have access to the GUI. Of course we could have added the users before we switched but let’s pretend we didn’t and instead do it from the command line.

We will make bob@domain.local a server admin and grant fred@domain.local the “reader” role, which provides minimal access to Velociraptor’s GUI. Note that you have to use the user email field in Active Directory. The following two commands will create these users:

velociraptor --config server.config.yaml user add --role administrator bob@domain.local
velociraptor --config server.config.yaml user add --role reader fred@domain.local

NOTE: We provide the --config flag so that this invocation of the velociraptor binary knows which datastore to add the new users to. This can be done while the server service is running or not running, but either way the service will need to be restarted to update itself with the datastore changes.

Because of our OIDC authenticator config, when adding each user we will receive an acknowledgement message saying "Authentication will occur via oidc - therefore no password needs to be set."

6. Test authentication process

Test the authentication process by going to https://velociraptor.local:8889/

You will be presented with the choice to log in with Keycloak (multiple authentication providers are supported but we only have one configured).

Enter initial credentials using DOMAIN\bob or bob@domain.local

How to create an "online collector" binary

Fri, 14 Nov 2025 00:00:00 +0000

How to create an “online collector” binary

Velociraptor offline collectors are immensely popular with our users. They are an appealing option because of the simplicity and convenience of having a single executable file that any desktop-support-level person in a remote environment can run. The collector can then exfiltrate… oops, I mean “upload”… the collected data from the environment to a cloud storage service such as S3, GCS, Azure, etc.

Another reason why they are so popular is that many DFIR practitioners need to investigate systems in environments where there is strong resistance to installing any new software. Offline collectors do their work without installation, which overcomes that obstacle to a large degree.

So offline collectors are a great option because “it’s just an exe” and it doesn’t require any user interaction besides clicking it. It’s hard not to love that level of simplicity!

However there are downsides to offline collectors:

You really need to plan ahead about what you want to collect. An offline collection is often a one-shot opportunity to collect what you need. Iteration would require creating a new collector each time. By contrast a network-connected “online” client makes it easy to quickly pivot and dig deeper in response to findings.
Offline collectors need to be packaged with the artifacts and tools that they need. This means that you can’t quickly create a new artifact and add it to your offline collector without rebuilding and redistributing a new binary. If your artifacts need tools then bundling them into a collector binary can significantly increase the file size.
Because offline collectors do not provide progress updates and resource telemetry to the server, we cannot get feedback on how the collection is going or on the resource utilization.

Collections vs. File acquisitions

Many users see the word “collector” in the term offline collector and take that to mean that it’s intended to be a bulk file collector (like KAPE and many other file acquisition / triage tools). This is not the case: in Velociraptor a “collection” is the execution of any VQL on the endpoint. Velociraptor collections typically return JSON-structured data, and can optionally include file copies. But most often Velociraptor collections don’t copy files unless there’s a good reason to do so, like for preservation purposes after detecting potential evidence in the file.

Cloud-storage-in-the-middle architecture

I’ve also observed that some users will use offline collectors to upload collection data to a cloud storage service and then have their server import the collections from that storage service. If the offline collector on the endpoint can access the internet (to upload files to a cloud storage provider, for example) and your Velociraptor server is likely also accessible - or can be made accessible - from the internet then a Velociraptor client on the endpoint can probably connect the server. I suspect that sometimes this “cloud dropbox” approach might be driven more by the alluring convenience of offline collectors rather than being a sensible system architecture choice. Even if it’s somehow technically justifiable, it’s still an awfully inefficient way to do things.

Of course there may be some unusual technical constraints that force one to use cloud storage as an intermediary, but there’s also a good chance that this is being done purely because of the simplicity that the offline collector offers. And in that case the investigation is incurring delays and wasting resources by routing the data via cloud storage - even if you manage to automate the transfers.

So the question to ask yourself is: Should I really be using an offline collector?

If your offline collector can connect to a storage service on the internet then it might be worth having it just connect to your Velociraptor server via the internet. In terms of the data collected, the exact same data can be collected by a client (including files).

The Velociraptor client can be repacked to replicate the offline collector’s single-file, no-installation, “just run it” simplicity. Here’s how:

Creating an online (client) collector

Assuming that client-server connectivity is possible, you can repack a client using the same config embedding and autoexec mechanisms that offline collectors use. You can create a binary that starts in client mode and that doesn’t require installation. It can do all the same collections that an offline collector would do, with none of the disadvantages mentioned above. And all it needs is to be run locally by some suitably privileged person such as a desktop admin.

Here’s how to create and run such a client binary:

Download the latest Velociraptor binary for the target platform. In this case I am going to use the Windows binary for the target platform and I am going to repack it on Linux (where my binary is aliased as velociraptor).
Download the client config from the server Dashboard page.
Edit the client config and add an autoexec section above the existing config:
```
autoexec:
  argv: ["client", "-v", "--require_admin"]
```
The -v is added so that the terminal gives some visual feedback to let the local helper who started it know that “it’s busy”.

The --require_admin is added since an installed client normally runs with elevated privileges. Offline collectors usually also enforce this requirement.
Also add a label section to the Client section of the config - i.e. Client.labels. This label will be used to kick off an initial hunt when the client enrolls.
```
  labels:
  - autocollect
```
The config file should look something like this

Now we do the repacking step:

velociraptor config repack --exe=velociraptor-v0.75.4-windows-amd64.exe client.root.config.yaml autocollector.exe

and the results should look something like this:

...
[
 {
  "RepackInfo": {
   "Path": "/tmp/autoclient/autocollector.exe",
   "Size": 69291504,
   "UploadId": 0,
   "sha256": "398e0b37bd279f46c03508edd50649b2655516409d682fd1cd4be866b7b03bc1",
   "md5": "24a4cd934d91a95c72853985d2766db0",
   "Components": [
    "autocollector.exe"
   ]
  }
 }
]

On your Velociraptor server set up a new hunt targeting the autocollect label.

The hunt should include the same artifacts that you would have chosen for an offline collector.

Don’t forget to start the hunt!

target the hunt by label (and yes, I know you still want to KAPE everything!)
Send the autocollector.exe file to a helpful administrator or other support staff who will run it on the machines in their environment. Tell them to ‘Run As Administrator’ and to consider the machines “busy” as long as the terminal window stays open.
When the exe is run (as administrator) it will open a terminal window and show activity as it connects to the server, enrolls, joins the hunt, and collects the data.

busy collecting…
On the server the client is a normal client. You will be able to see it join the hunt and be able to view the collection results when it’s completed the hunt.

collection completed successfully
Now the same collection as an offline collector is completed, except that the results having been sent back directly to the server. The terminal window is still be open on the endpoint, so you are now free to do more collections as you would do with any live client, but which would not be possible with an offline collector.
Finally, you’ve instructed the local admins to leave the machines alone as long as the terminal windows are open. But now you’re done with a specific computer. So now you want to close the terminal on that machine to signal to the admins that it’s done.

Copy the client_id for that machine and in a global notebook and run this VQL, substituting your target client’s ID:
```
SELECT killkillkill(client_id="C.c6ec9a50598f590b") FROM scope()
```
The client will be sent the kill signal and the terminal will close.

So… Online collector vs. Offline collector?

By using a non-persistent client we are able to do exactly the same collections as could be done with an offline collector, but with all the benefits of an online client and none of the disadvantages of an offline collector!

From the perspective of the helpful person running the client locally on the endpoints, there is no difference between running this or running an offline collector (with an offline collector you also should advise them to leave it alone until the terminal closes).

If your goal is to do bulk file acquisition then with this method you have all the files in your server’s datastore without the cost, hassles and delays of sending the data via a cloud storage service and then importing collection archives into the server.

How to set up a GCS Bucket for file uploads

Fri, 14 Nov 2025 00:00:00 +0000

How to set up a GCS Bucket for file uploads

Google Cloud Storage buckets can be a useful upload destination for receiving files from Velociraptor clients or collection containers from offline collectors in scenarios where the source system is internet connected and you do not want to stand up storage services on the local network.

This is made possible by the upload_s3 VQL function.

Prior to release 0.76, Velociraptor had a dedicated upload_gcs plugin, however after this release that plugin was removed since it increased the binary size significantly. Google provides an AWS compatibility mode which allows us to use the upload_s3 function instead.

This article explains how to set up a GCS bucket with appropriate security for file uploads.

Setup steps

Before we can upload files to a bucket we need to have a project in place. For this example I will created a new project called velociraptor-demo:

Create a new project

Our plan is to distribute to our accomplices the packed binary as before, but this time we want Velociraptor to automatically upload results for us into our bucket.

In order to do this we need a service account with credentials allowing it to upload to our bucket. Go to IAM & Admin / Service Accounts / Create Service Account:

Since the service account will be able to upload by itself (i.e. the user does not authenticate on its behalf), we need to identify it with a JSON key. The key allows Velociraptor to act as the service account on this cloud project. Clicking the Create button will download a JSON file to your system with the private key in it.

Note the service account’s email address. Currently this account has no permissions at all, but we will allow it to write objects into our upload bucket later.

Next we create a bucket to store our collected zip files I will call it velociraptor-uploads-121:

Selecting the Permissions tab, we are able to add the service account as a member — we will only give it the ability to write on a bucket and create new objects. This is important since is means that the service account is unable to read or list objects in this bucket. Since we will embed the service account key in our config file we need to make sure it can not be misused to compromise collections from other machines.

Setting up service account HMAC keys. This provides the GCP S3 compatibility layer. These keys allow the caller to log into the service account. Note that the keys only provide the same permissions that the service account has above - they are simply an alternative way of logging in.

Setting up HMAC keys

Select Settings -> Interoperability -> Access keys for service accounts

Use these keys as parameters for the upload_s3() plugin:

endpoint=“https://storage.googleapis.com”
credentials_key=“HMAC KEY”,
credentials_secret=“HMAC KEY SECRET”,

How to set up a SMB share for file uploads

Fri, 14 Nov 2025 00:00:00 +0000

SMB is the Microsoft file-sharing protocol which is a convenient option for Windows systems. A SMB share can be a useful upload destination for receiving files from Velociraptor clients or collection containers from offline collectors in scenarios where you want the files to be sent to a central storage location on the local network rather than to the Velociraptor server or to a cloud storage service.

This is made possible by the upload_smb VQL function.

This article explains how to set up a SMB share with appropriate security for file uploads.

Setup steps

Create a new local uploader user on one of the windows systems accessible to the host the collection is running on.

Creating a local user for uploads

Create a directory to receive the files.
Share the directory out to the local uploader user.

Right click on directory and select properties/sharing tab then click the share button

Adjust directory ACLs to only permit the user to write files without being able to list the directory or read the files. This is required because the uploader user credentials must be embedded in the offline collector so we do not want these misused to alter any of the other uploads.

Adjusting directory permissions to only provide write access

It is best to test the SMB configuration works as desired using the simple VQL query in a notebook.

LET SMB_CREDENTIALS <= dict(`192.168.1.112`="uploader:test!password")

SELECT upload_smb(accessor="data",
    file="Hello world",
    name="hello.txt",
    server_address="//192.168.1.112/uploads")
FROM scope()

SELECT *
FROM glob(globs="*",
    root="//192.168.1.112/uploads",
    accessor="smb")

The above query:

Sets the global credential cache for use of SMB
Uploads a test file called “hello.txt” to the uploader directory
Attempts to list the uploads directory using the glob plugin.

The upload file should succeed but the uploader user should not be able to list the directory.

Testing the SMB permissions with a VQL query

We are now ready to specify the details to the offline collection GUI. NOTE: Usually it is better to use the IP of the server rather than the name for improved reliability.

Creating the SMB offline collector

How to set up Azure Blob Storage for file uploads

Fri, 14 Nov 2025 00:00:00 +0000

How to set up Azure Blob Storage for file uploads

Microsoft Azure’s Blob Storage service can be a useful upload destination for receiving files from Velociraptor clients or collection containers from offline collectors in scenarios where the source system is internet connected and you do not want to stand up storage services on the local network.

This is made possible by the upload_azure VQL function.

Azure supports an authentication policy called Shared Access Signature (SAS) making it convenient and secure to provide limited access to the a storage container. Using this method, we can embed a simple SAS URL that provides access to upload data to the storage container without granting the ability to download or remove any data.

This article explains how to set up an Azure storage container with appropriate security for file uploads.

Setup steps

Create a storage account.
Create a new data storage container to receive the uploads

Creating a new Azure Blob storage container

Add a role assignment to allow the storage account to manage the storage

Adding a role assignment to the storage account

Generate a SAS Policy URL.

Right click on the container to generate a SAS policy

Create a SAS policy with only write and create access. You can specify an appropriate expiry time for the SAS URL. After this time the uploader will no longer work.

SAS Policy should have only Write and Create Access

Test the SAS URL works properly

Test the SAS Policy by uploading a small file in the notebook

Embed the SAS URL in the offline collector.

Simply paste the SAS URL in the collector GUI

Backing up and restoring a server.

Thu, 13 Nov 2025 00:00:00 +0000

Backing up and restoring a server.

Many users ask us about how to back up Velociraptor or achieve a High Availability (HA) configuration. The answer to that is nuanced and depends on exactly what data is backed up and what the end goal is.

In this article I discuss the different mechanisms and approaches used for backup and disaster recovery.

Simplest option: Re-deploy server

Let’s consider the deployment process. What if the Velociraptor server is suddenly completely gone! How can we recover?

The most difficult part of a Velociraptor deployment is the client deployment. This usually involves pushing packages to endpoints, such as an MSI or Debian/RPM packages. The process usually involves change management, approvals etc. These processes take time and so we definitely do not want to have to re-deploy clients!

Luckily the client ID is actually a property of the clients themselves. The Velociraptor Client ID is derived from the client’s cryptographic key and so it is not managed by the server at all - instead it is stored on the client’s in their writeback file. Additionally, client registration (or enrollment in Velociraptor terminology), is done automatically the first time the client is seen by the server.

So if the Velociraptor server is suddenly gone, we can simply redeploy the server package onto a new server and everything should work again:

Provision a new server VM or physical machine
Install the same server Debian package (which contains the same key material and configuration files).
Update DNS records to point to the new server IP. The clients will use these DNS records to find the new server.
After a short time, all clients will re-enrol and the system will become functional again.

For a successful recovery we need:

A backup of the server debian packages last used to upgrade the server (this will contain the server configuration file).
A backup of the server configuration file if it was updated since the last package upgrade.
A DNS record for the public interface of the server - this allows us to redeploy the server to a new IP address easily.

Restoring from daily backups

While deploying a new server gets the system operational again, it is not enough:

Custom artifacts are not restored
Existing hunts are not recovered
All collected data from clients are lost
Labels on existing clients are lost
User accounts and ACLs are lost
Multi-tenanted orgs are lost

To address some of these issues, Velociraptor creates a backup package daily by default. If you need more frequent backups, you can configure the backup interval in your server config using the defaults.backup_period_seconds setting.

You can also force Velociraptor to create a backup package using the VQL backup() function, but if you do not you can still find the scheduled (daily by default) packages in the backup directory <filestore>/backups/. Note that the backup package in the root org will contain all other orgs’ backups as well.

SELECT * FROM backup(name="MyBackup")

Creating a backup package

As you can see above, the backup package contains data from various Providers. Each provider is responsible for saving some aspect of the server’s configuration. To keep the size down, providers do not save bulky items like collected data, rather only metadata is stored about the server.

For example, the hunts are saved, but not the list of clients that have already provided results to the hunt (since the associated collection data is not backed up). This means that when restoring the backup on a new server, clients will participate in existing hunts again.

To restore the backup, you must copy the backup file into the backups directory on the new server.

SELECT * FROM backup_restore(name="MyBackup")

Restoring a backup package

Backups always include the data from all Providers, but when restoring you can choose a subset that you want to restore the using the backup_restore() providers parameter.

The current backup providers are:

ACLBackupProvider
ClientInfoBackupProvider
HuntBackupProvider
NotebookBackupProvider
RepositoryBackupProvider

Note that ACL records are not automatically restored for security reasons. However you can restore them from the backup data in a Velociraptor notebook, after carefully reviewing the data. For example, this VQL would restore the users and ACLs for a specific org:

SELECT *
FROM foreach(
  row={
    SELECT *
    FROM parse_jsonl(
      filename="/tmp/extracted_backups/orgs/O123/acls.json")
  },
  query={
    SELECT
    user_create(
      user=Principal.name,
      orgs=Principal.orgs[0].id,
      roles=Policy.roles),
    user_grant(
      user=Principal.name,
      orgs=Principal.orgs[0].id,
      policy=Policy)
    FROM scope()
  })

Backing up collected data

The data collected from endpoints is typically much larger and can take a while to back up. Deciding if you need that data backed up really depends on how you use Velociraptor.

Since Velociraptor is typically used to respond to incidents, the data collected is typically only useful for a short time. Velociraptor can capture a snapshot of the state of endpoints, but this data may not be relevant months or weeks later since the state of the endpoints evolve over time.

In some situations we do want to preserve the data collected from the endpoint:

In order to preserve evidence of compromise. This is needed to support further actions, such as disclosure or legal procedures.
As provenance or audit of the actions taken, what was found and justifications of further actions.

In the above use cases it is important to ensure that the data is readable outside of Velociraptor itself. For example sharing collections as generic Zip files containing CSV or JSON files is preferable to files that can only be viewed in Velociraptor.

Therefore, we really need Data Export capability from Velociraptor. This is generated using the create_flow_download() and create_hunt_download() plugins. Those plugins are the equivalent of the Download Results option in the Velociraptor GUI.

An export ZIP of a hunt contains all the data collected for that hunt by each client that participated.
An export ZIP of a collection contains all the files collected by the specific client.

For example, to archive all hunts you could use a query like:

SELECT create_hunt_download(hunt_id=hunt_id, wait=TRUE)
FROM hunts()

The VQL function create_hunt_download() will return the filestore path you can use to read the file (with the fs accessor).

You can also upload those files to, e.g. an S3 bucket:

SELECT upload_s3(secret="S3Token",
                 accessor="fs",
                 file=create_hunt_download(
                     hunt_id=hunt_id, wait=TRUE))
FROM hunts()

This approach is fairly selective as you can add and remove interesting collections from certain hunts using the GUI - so in a real investigation the hunts can serve as a staging container for interesting collections.

To export specific collections, simply use the create_flow_download() function. For example to export all collections on the server completed in the past week:

LET OneWeek <= 7 * 24 * 60 * 60
LET DestDir <= "/tmp/exports/"

SELECT client_id,
       session_id,
       LastActiveTime,
       copy(filename=Export,
            accessor="fs",
            dest=DestDir + Export.Base) AS Export
FROM foreach(row={
  SELECT * FROM clients()
}, query={
  SELECT *, timestamp(epoch=active_time) AS LastActiveTime,
         create_flow_download(client_id=client_id,
                            flow_id=session_id,
                            wait=TRUE) AS Export
  FROM flows(client_id=client_id)
  WHERE LastActiveTime > now() - OneWeek
})

The above query:

Iterates over all clients
For each client, iterate over all flows
If the flow is more recent than 1 week, generate a flow download.
Copy the flow download into a destination directory, preserving the base name generated by the system (which contains the client id and flow id). Note that we need the “fs” accessor to read the download file generated.

Importing the collections into the new server

To import the collections into the new server we need to read them from the shared directory.

LET DestDir <= "/tmp/imports/"

SELECT OSPath, import_collection(filename=OSPath)
FROM glob(globs="*.zip", root=DestDir)

Importing new collections recreates the clients

Complete backup of the datastore

One of the reasons Velociraptor is very easy to deploy and manage, is because everything in Velociraptor is simply a file. There is no need for complicated backend dependencies like databases - all you need to provide is a directory to store files on.

This makes it very easy to back the files up using regular backup solutions. It is perfectly safe to run incremental backups on the datastore and restore it at any time. Velociraptor does not use file locking so there is no problem with a backup software reading all files inside the data store directory.

It is possible to back up the datastore directory using rsync, a network filesystem, or other solutions to keep a hot spare server on standby. Then fail over is simply a matter of switching the DNS or load balancer to the other server.

This is a more complete backup/high availability solution, but it has some caveats:

The internal Velociraptor files are now compressed so you would typically need Velociraptor to be able to read the data.
This type of backup solution is indiscriminate - all data is backed up regardless of how relevant it is. Storage costs can accumulate rapidly.

Conclusions

Backups, Disaster Recovery and High Availability are important aspect to consider when deploying Velociraptor. However, due to the nature of Velociraptor’s use cases, there are several nuances in how to achieve this.

By thinking carefully about what exactly we want to get out of a backup solution, what data we want to protect and how quickly we want for it to be restored we can make more informed decision about which strategy works best.

For ephemeral installations, where Velociraptor collected data is immediately exported on to other systems (for example using the Elastic or Splunk connectors), it may not be worth worrying about backups at all! A new deployment can be setup in minutes and the system can be quickly recovered.

However for most elaborate deployments, more thought can be given to backups, collection exports for preservation and maybe even a complete backup/hot standby architecture.

Pre-populating a server with clients, hunts and flows

Tue, 14 Oct 2025 00:00:00 +0000

Pre-populating a server with clients, hunts and flows

When setting up a Velociraptor server for training or demonstration, it is sometimes desirable to have some data already populated.

For a realistic training exercise, some people use a Cyber Range to fully emulate a real environment. However, managing a large Cyber Range is complex and expensive.

Sometimes, we just want a simple Velociraptor server with pre-populated data, so users can learn how to analyze hunt results, and improve their VQL skills!

In Velociraptor - Everything is a file!

The Velociraptor server simply keeps all the data as simple files on disk. These files are organized into higher level concepts like Clients, Flows, Hunts and notebooks.

Conceptually you can think of these as just storage hierarchies which can be easily recreated:

A Flow is a single collection that occurred as a particular time. Flows Contain artifact results, and uploaded files.
A Client represents an endpoint. The Velociraptor server stores all flows under the client’s directory in the file store. Clients have a unique client id which is how we can identify them.
A Hunt is a logical set of clients and flows which can be processed together using plugins like hunt_results() or source()

Creating clients.

Normally a client will be created on the server when a physical client first connects to it. However, it is possible to create new “client” objects using the VQL client_create() function.

Let’s create 100 clients:

SELECT client_create(os="windows",
   hostname=format(format="Host%d", args=_value)) AS ClientId
FROM range(end=100)

Adding flows to the clients.

Normally, we would schedule a collection on clients to gather real data from the endpoint. But this is not essential, we can also import an existing collection into the client’s storage space.

The existing collection can be taken on any Velociraptor instance - it is just a zip file export of a collection.

For this article, I will collect the Generic.Client.Info artifact and export the collection into a ZIP file in the collection overview page.

Exporting a collection

Next we import the collection into each client on the server:

SELECT import_collection(client_id=client_id,
    filename="/tmp/Generic.Info.zip")
FROM clients()

Assign collections to a hunt

A Hunt is a managed container of collections. Normally we schedule a hunt so the Velociraptor server can automatically schedule flows on clients that match the hunt criteria, and keep track of these in a central location.

However, we can also just add arbitrary flows to a hunt using VQL. In this example I will add all the Generic.Client.Info collections we imported previously into a new hunt so I can analyze them together.

First I create a hunt using the GUI to collect the Generic.Client.Info artifact, but I will leave the hunt in the STOPPED state.

Creating an empty hunt

The hunt currently has no clients or flows associated with it.

I can now assign the latest Generic.Client.Info collection from each client:

LET HuntId <= "H.D35CUR4S00IHC"

SELECT client_id,
       session_id,
       HuntId,
       hunt_add(client_id=client_id, hunt_id=HuntId, flow_id=session_id)
FROM foreach(row={
    SELECT * FROM clients()
}, query={
    SELECT *
    FROM flows(client_id=client_id)
    WHERE artifacts_with_results =~ "Generic.Client.Info"
    LIMIT 1
})

The above query:

Iterates over all clients
For each client, iterates over all flows in that client
Select the first flow with artifact results of Generic.Client.Info
After one flow matches for each client, go to the next client (this is the LIMIT clause).
Add the flow to the hunt we created earlier.

Post process the collections

Depending on the scenarios you want to demonstrate, you can create different clients (perhaps a “Compromised” set) and import different collections into them.

This method allows running any post processing steps in notebooks as if these client are real endpoints.

Manipulating VQL columns and rows

Fri, 26 Sep 2025 00:00:00 +0000

Manipulating VQL columns and rows

VQL has a very simple syntax inspired by SQL. At the heart of the language is a SELECT query which returns a set of Rows. A VQL Row consists of Columns and Cell Values.

You can think of the result of a query is simply a list of Dicts, where a dict contains key/value pairs. This is easiest to see in the GUI’s Raw JSON view:

SELECT * FROM info()

This returns a JSON result containing a list of JSON objects, each representing a single row (in this case only one row is returned):

[
  {
    "Hostname": "WIN-SJE0CKQO83P",
    "Uptime": 776266,
    "BootTime": 1758078331,
    "OS": "windows",
    "Platform": "Microsoft Windows Server 2022 Standard Evaluation",
    "PlatformFamily": "Server",
    "PlatformVersion": "21H2",
    "KernelVersion": "10.0.20348.4052 Build 20348.4052",
    "VirtualizationSystem": "",
    "VirtualizationRole": "",
    "CompilerVersion": "go1.24.7",
    "HostID": "6b65a0af-a752-429a-a65c-83367f882ebe",
    "Exe": "c:\\velociraptor.exe",
    "CWD": "C:\\Users\\Administrator",
    "IsAdmin": true,
    "ClientStart": "2025-09-23T04:12:06.2778472Z",
    "LocalTZ": "PDT",
    "LocalTZOffset": -25200,
    "Fqdn": "WIN-SJE0CKQO83P",
    "Architecture": "amd64"
  }
]

We can select specific columns in this using the Column Specifiers following the SELECT clause:

SELECT Hostname FROM info()

However, what if we wanted to automatically manipulate the columns in a more sophisticated way? This is often needed when we don’t know the names of all the columns in advance.

Some use cases are:

If we do not know the names of the columns in advance but want to select only some columns by e.g. a Regular Expression.
We want to generate a hash based on a selection of columns.

This post shows how to convert any VQL query into a list of dicts, thereby providing access to the Columns in a more convenient way. We then show how to deconstruct the dict back into a row.

For the following examples, we use the query SELECT * FROM info() as a simple example of a query, but any query could be used. Typically these techniques are more useful for generic queries for which we don’t know the types of columns returned. For example SELECT * FROM source(), SELECT * FROM parse_csv() etc.

Step 1: Convert rows into dicts

In order to deal with a row as a dict we need to use the items() plugin:

SELECT * FROM items(item={ SELECT * FROM info() })

[
  {
      "_key": 0,
      "_value": {
          "Hostname": "WIN-SJE0CKQO83P",
              ...
          "Architecture": "amd64"
      }
  }
]

When the items() plugin operates on another query, it emits two columns:

_key is a counter of row number
_value is the entire row given as a dict.

Once we have the row as a dict, we can manipulate it easily using a number of dict manipulation tools.

Step 2: Perform operations on the row dict.

Now that we have the row as a dict we can perform any operations on it. In the following we see two methods for manipulating dicts:

Set operations: allow us to add, remove or merge dicts based on their keys. See Set operations.
Dict reconstruction: is a more powerful technique for tearing the dict apart and reconstructing it again.

Example: Select only columns that match a regular expression.

For this example, let’s assume we don’t know all the exact columns in advance but want to match certain columns based on some regular expression.

The key for this technique is to transform a dict’s columns based on a regular expression: We need to iterate over all the keys in the dict , only including some keys based on their name, and then put it back together into a dict:

LET FilterKeys(Dict) = to_dict(item={
  SELECT * FROM items(item=Dict)
    WHERE _key =~ "Host|Arch"
})

SELECT _key, FilterKeys(Dict=_value) AS _value
FROM items(item={ SELECT * FROM info() })

To make the filtering operation simpler to understand and reuse, I extracted it into a VQL function. The FilterKeys function builds a new dict using the to_dict() function based on a query. The query we use uses the items() plugin again. But this time, since it is operating on a dict, the plugin iterates over the dict’s keys and values as the _key and _value columns.

For this example, we just remove the keys that do not match the regular expression Host|Arch. This results in a smaller dict with only keys matching the regular expression:

[
  {
    "_key": 0,
    "_value": {
        "Hostname": "WIN-SJE0CKQO83P",
        "HostID": "6b65a0af-a752-429a-a65c-83367f882ebe",
        "Architecture": "amd64"
    }
  }
]

Example: Hash a subset of columns

For this example, suppose we have a set of columns that we consider to be a representative of the row and we want to generate a hash based on those. This technique allows us to tag similar rows with a unique representative ID.

For our example we want to create another dict with the columns Hostname, Exe and Architecture. We consider those columns to be fully representative of the row, that is we accept that other columns may vary but as long as those fields are the same, we consider the rows to be duplicates.

We can quickly extract only those fields by using Set intersection (In VQL this is implemented by dict multiplication):

LET FingerPrint <= dict(Hostname=TRUE, Exe=TRUE, Architecture=TRUE)

SELECT _key, _value * FingerPrint AS _value
FROM items(item={
    SELECT * FROM info()
})

[
  {
    "_key": 0,
    "_value": {
        "Hostname": "WIN-SJE0CKQO83P",
        "Exe": "c:\\velociraptor.exe",
        "Architecture": "amd64"
    }
  }
]

Now we produce a hash of these fields by serializing the dict into a JSON object. This hash will be the same for every row with the same set of values for these specific fields:

SELECT _key,
    hash(accessor="data", path=serialize(item=_value * FingerPrint) ).MD5 AS _value
FROM items(item={
    SELECT * FROM info()
})

Similarly we can use dict subtraction to remove fields from the dict (e.g. a timestamp field may change all the time so we may want to remove it).

Now in this example, I will add the new hash into the row dict as an additional field:

SELECT _key,
       _value + dict(
         _HashID=hash(accessor="data",
                      path=serialize(item=_value * FingerPrint)).MD5) AS _value
FROM items(item={
    SELECT * FROM info()
})

This works using dict addition. I create a new dict with a single key of _HashID containing the hash that I got earlier. By adding this new dict to the original row dict, I get a new dict with an additional key.

[
  {
    "_key": 0,
    "_value": {
        "Hostname": "WIN-SJE0CKQO83P",
        "Architecture": "amd64",
            ....
        "_HashID": "ae7b6e78e5fce4b5e18d371be5916472"
    }
  }
]

Step 3: Turn a dict back into a row

The final step is to turn our dict back into a regular VQL Row. This will allow it to be viewed nicely in the GUI as a regular table. The dict keys will turn back into column headers, and the values will be table cells.

This operation is done using the foreach() plugin using it column argument:

LET MyFilteredRow = SELECT
    _key, FilterKeys(Dict=_value) AS _value
FROM items(item={ SELECT * FROM info() })

SELECT * FROM foreach(row=MyFilteredRow, column="_value")

To enhance readability, I converted the previous query into a stored query by naming it MyFilteredRow, then I can just use it as an argument to the foreach() plugin. The column parameter tells the foreach() plugin to extract the dict found in the column _value into the row itself (with other columns ignored).

Manipulating VQL Columns and Rows

Detecting Velociraptor misuse

Thu, 28 Aug 2025 00:00:00 +0000

Detecting Velociraptor misuse

Velociraptor is widely used by defenders for legitimate forensic and response workflows, and, just like many other security and administrative tools, it can also be abused when in the wrong hands.

Threat actors use legitimate software to their advantage at various stages of the attack lifecycle. In the past, we have seen many legitimate tools that were abused by threat actors (PsExec, AnyDesk, ScreenConnect, etc.). Threat actors will continue to abuse legitimate tools to facilitate their attacks.

Recently, we observed that the Velociraptor tool was one of them.

In this instance, the threat actor downloaded the Velociraptor binary and, in its configuration file, specified the command-and-control server. After Velociraptor was executed on the compromised asset, it established a communication with the C2 server. Once the communication was established, the threat actor used Velociraptor to perform further actions, such as downloading additional files or executing commands on the compromised asset. While this is not a vulnerability in the tool itself, it can be used for malicious purposes.

On October 8th 2025, Cisco Talos reported observations from a threat actor abusing Velociraptor version (version 0.73.4) to distribute ransomware.

How can I detect Velociraptor misuse in my environment?

In order to help organizations detect Velociraptor misuse, Velociraptor deliberately creates some IOCs which are easy to detect:

When Velociraptor starts, the binary registers a new event log source with the name Velociraptor. This will create a new key at the location HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\EventLog\Application\Velociraptor.

Typically the modification time for this key is a good indicator of the first time the Velociraptor binary was launched on the system.
Each time the binary is launched, the binary logs the command line arguments used into the Application event log with an event id of 1000. For example, when run as a service, the message looks similar to:

Velociraptor startup ARGV: ["C:\\Program Files\\Velociraptor\\Velociraptor.exe","--config","C:\\Program Files\\Velociraptor\\/client.config.yaml","service","run"]

Of course, since Velociraptor is an open source tool it is possible for attackers to remove these indicators and rebuild the program. However, the resulting binary will not be signed by Rapid7 and so will most likely remain an unsigned binary, thereby raising a further indicator that may be used: Detecting any execution of unsigned binaries in the environment. The official Rapid7 signed binary will always leave detectable traces of execution.
Another more robust detection for a potentially malicious rebuilt Velociraptor binary may use the following Yara rule:

rule velociraptor_strings {
  meta:
    description = "Detects unique strings in Velociraptor binaries"

  strings:
    $s1 = "www.velocidex.com/golang/velociraptor/" wide ascii
    $s2 = "proto.VelociraptorUser, error" wide ascii
    $s3 = "Welcome to the Velociraptor multi-frontend configuration generator" wide ascii
    $s4 = "Go build ID:" wide ascii

  condition:
    3 of them
}

The following experimental Sigma rule will detect the installation or running of the Velociraptor binary. This could lead to false positive alerts when you have installed Velociraptor by default or running it for an investigation. However it will trigger an alert when Velociraptor is not supposed to be installed into the network and can be seen as a potential abuse of the tool.

itle: Suspicious Velociraptor Execution or Misuse
id: 12345678-ABCD-1234-ABCD-1234567890AB
description: |
    Detect execution of Velociraptor binary with suspicious arguments or as unsigned binary,
    potentially indicating misuse or attacker-controlled instance.
status: experimental
author: Rapid7 Labs
references:
  - https://docs.velociraptor.app/knowledge_base/tips/velocirator_misuse/
tags:
  - attack.execution
  - attack.persistence
  - tool.abuse
logsource:
  product: windows
  category: process_creation
detection:
  selection_velociraptor:
    Image|endswith: '\Velociraptor.exe'
  selection_suspicious_args:
    CommandLine|contains:
      - "--config"
      - "client.config.yaml"
      - "service run"
  selection_unsigned:
    Signature|endswith:
      - "Unsigned"
  condition: selection_velociraptor and (selection_suspicious_args or selection_unsigned)
falsepositives:
  - Legitimate Velociraptor use by admins / security teams (especially if unsigned binary is used legitimately)
  - Test or dev environments
level: high

For organizations that are concerned about unauthorized deployments and already have Velociraptor deployed, Rapid7 has published a Velociraptor inception artifact that automates the above techniques and can help detect unexpected instances. This can be viewed here: https://github.com/rapid7/Rapid7-Labs/blob/main/Vql/VelociraptorInception.yaml

For organizations that do not already have Velociraptor deployed, the above detections methods can be easily implemented using whatever technology stack they already have deployed.

What if I am already using Velociraptor?

If Velociraptor use is already expected in your environment, misuse of Velociraptor may blend in with legitimate use. In this case:

Forward the audit logs centrally and look for unusual sets of command line arguments (if Velociraptor is usually installed as a service it will always be started similar to the example above).
Check the integrity of the Velociraptor agent configuration to to ensure that it is not tampered with.
Check the process lineage of the Velociraptor binary in your EDR to ensure it is always started by the service control manager in the usual way.

How to set up a MinIO (S3-compatible) dropbox server for file uploads

Sat, 05 Jul 2025 00:00:00 +0000

How to set up a MinIO (S3-compatible) dropbox server for file uploads

AWS S3 buckets can be a useful upload destination for receiving files from Velociraptor clients or collection containers from offline collectors in scenarios where the source system is internet connected and you do not want to stand up storage services on the local network.

This is made possible by the upload_s3 VQL function.

However, if you want similar functionality to AWS S3 and prefer to keep things local, or at least fully under your own control, then MinIO is a great open source, self-hosted, S3-compatible dropbox server. It’s easy to install and works on all mainstream operating systems. A MinIO server is a single Go binary licensed under the AGPL.

Here we describe the steps to quickly set up a MinIO server.

Setup steps

For this example we assume the dropbox server has the IP 192.168.1.1

First download the MinIO binary from the MinIO GitHub page. For example, on Linux the binary can be fetched from https://dl.min.io/server/minio/release/linux-amd64/minio
Start the server using the following command:

MINIO_ROOT_USER=admin MINIO_ROOT_PASSWORD=password ./minio server /tmp/minio --console-address ":9001" --address ":4566"

This will start a server with the admin password provided and store all files in the /tmp/minio directory. The web console will be available on port 9001 and the API port will be 4566. You can view the web console for MinIO by navigating the browser to http://192.168.1.1:9001

Please use a more complex password in reality, for this demonstration we will use a weak password.

To administrate the MinIO server from the commandline we will use the mc command available from https://dl.min.io/client/mc/release/

wget https://dl.min.io/client/mc/release/linux-amd64/mc
chmod +x ./mc

# Save credentials for the mc tool
./mc alias set 'myminio' 'http://192.168.1.11:4566' 'admin' 'password'

# Create a new bucket called uploads
./mc mv myminio/uploads

Next we need to create a new client key and secret - this a similar process to what we need to do on the AWS S3 console, but using the command line it is quicker

# Add a new uploader user with specific access key and secret key
./mc admin user add uploader access_key_123 secret_key_123

Next we need to restrict the policy allowed for this user (the user is basically identified by the access key). We create a JSON policy with an editor and store it for example in /tmp/uploader.policy.json

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "s3:PutObject",
            "Resource": "arn:aws:s3:::uploads/*"
        }
    ]
}

# Create the policy from the JSON file
 ./mc admin policy create myminio uploader /tmp/uploader.policy.json

# Attach the policy to the new user
./mc admin policy attach myminio --user=access_key_123 uploader

Test the bucket and the permissions using the following VQL. Paste the following code into a file say /tmp/test.vql

SELECT
    upload_s3(accessor="data",
              file="Hello",
              name="test.txt",
              endpoint="http://192.168.1.11:4566",
              credentials_key="access_key_123",
              credentials_secret="secret_key_123",
              bucket="uploads")
FROM scope()

LET S3_CREDENTIALS <= dict(endpoint='http://192.168.1.11:4566/',
                           credentials_key='access_key_123',
                           credentials_secret='secret_key_123',
                           no_verify_cert=1)

SELECT *, read_file(filename=OSPath, length=10, accessor='s3') AS Data
FROM glob(globs='/uploads/*', accessor='s3')

Run this query with Velociraptor:

velociraptor-v0.74.4-linux-amd64 -v query -f /tmp/test.vql

The first query uploads a test file to the bucket, we then try to read it back out - this should be denied:

[INFO] 2025-07-05T02:26:32Z upload_S3: Uploading test.txt to uploads
[
 {
  "upload_s3(accessor=\"data\", file=\"Hello\", name=\"test.txt\", endpoint=\"http://192.168.1.11:4566\", credentials_key=\"access_key_123\", credentials_secret=\"secret_key_123\", bucket=\"uploads\")": {
   "Path": "http://192.168.1.11:4566/uploads/test.txt",
   "Size": 5
  }
 }
][][INFO] 2025-07-05T02:26:32Z Globber: operation error S3: ListBuckets, https response error StatusCode: 403, RequestID: 184F39DAD67D435B, HostID: f2a388c21e253e519af7cec24c2e281b7821740cf65cb6ff168ac3a3ce38718c, api error AccessDenied: Access Denied. while processing /

You can verify the file is there using the MinIO Console.

Exporting the files. MinIO uses its internal data to store bucket data but you can use it to copy files in raw format into another directory. The --watch flag will continuously watch the bucket to export files in real time (omit it for one shot export).

./mc mirror --watch myminio/uploads /tmp/backup/

How to automatically post process flows with an external program.

Sun, 29 Jun 2025 00:00:00 +0000

How to automatically post process flows with an external program.

Sometimes we want to automatically post process a collection using an external program - for example a Python script. This short article will illustrate how to launch a python program automatically to post process a collection.

For our example we will write a Python program to post process the Generic.Client.Info artifact. As soon as the artifact is collected we want to extract the Hostname field from the BasicInformation source and greet the host with a welcome message.

1. Finding the result files in a flow.

Velociraptor collects artifacts in Flows which are stored as a collection of files within the VFS. You can see all the files in a particular flow using the enumerate_flow() plugin:

SELECT * FROM enumerate_flow(client_id=ClientId, flow_id=FlowId)

Enumerating Flow Files

You will notice that each file has a Type field and the path to the file is given using the file store path. This allows the file to be opened using the fs accessor in VQL.

However to receive the full file on disk, the file_store() function can be used.

When collecting an artifact, each source query in the artifact is stored in a single file on disk. In our case we want to know the file that contains the BasicInformation source:

SELECT file_store(path=Data.VFSPath) AS Path
FROM enumerate_flow(client_id=ClientId, flow_id=FlowId)
WHERE Type = "Result" AND Path =~ "BasicInformation"

2. Launching the Python program

Now that we can find the path to the correct file, we need to launch an external program to receive this path.

Let’s encapsulate the logic in a VQL function:

LET _GetPath(ClientId, FlowId) =
  SELECT file_store(path=Data.VFSPath) AS Path
  FROM enumerate_flow(client_id=ClientId, flow_id=FlowId)
  WHERE Type = "Result" AND Path =~ "BasicInformation"

LET GetPath(ClientId, FlowId) = _GetPath(ClientId=ClientId, FlowId=FlowId)[0].Path

SELECT *
FROM execve(argv=["python.exe", "C:/MyScript.py", GetPath(ClientId=ClientId, FlowId=FlowId)])

This query will extract the path to the BasicInformation source and launch my python script, while passing it the path to the result set.

While working in a notebook I can iterate on developing my python script by recalculating the cell all the time.

Iterating development of the python script

My goal is to write a python script which reads the result set from disk (which is just a line separated JSON file), then extracts the Hostname column. Finally the python program will emit a JSON object per line into Stdout

import sys
import json

if __name__ == "__main__":
    PathName = sys.argv[1]
    with open(PathName, mode="r") as fd:
        for line in fd.readlines():
            try:
                data = json.loads(line)
                response = dict(Greeting = "Hello " + data["Hostname"])
                print(json.dumps(response))
            except Exception as e:
                print("Exception %s" % e)
                continue

Now that I have a python program which generates a JSON object per line, I can expand the JSON object into a row using the foreach() plugin:

LET _GetPath(ClientId, FlowId) =
  SELECT file_store(path=Data.VFSPath) AS Path
  FROM enumerate_flow(client_id=ClientId, flow_id=FlowId)
  WHERE Type = "Result" AND Path =~ "BasicInformation"

LET GetPath(ClientId, FlowId) = _GetPath(ClientId=ClientId, FlowId=FlowId)[0].Path

SELECT *
FROM foreach(row={
    SELECT parse_json(data=Stdout) AS Row
    FROM execve(argv=["python.exe", "C:/MyScript.py",
                  GetPath(ClientId=ClientId, FlowId=FlowId)])
  },
  column="Row")

3. Automating post processing.

So far I was working in a notebook, but now I want to write the artifact that will trigger it automatically. I want the server itself to monitor when a new Generic.Client.Info collection is made and automatically post process it - So I need a Server Event Monitor artifact.

When a collection is complete, the server emits a System.Flow.Completion event, which I can watch using watch_monitoring(). I can then filter collection by the artifacts they found to obtain the ClientId and FlowId.

Putting it all together:

LET Completions = SELECT FlowId, ClientId
   FROM watch_monitoring(artifact='System.Flow.Completion')
   WHERE Flow.artifacts_with_results =~ "Generic.Client.Info/BasicInformation"

LET PostProcess(ClientId, FlowId) = SELECT *
   FROM foreach(row={
      SELECT parse_json(data=Stdout) AS Row
      FROM execve(argv=["python.exe", "C:/MyScript.py",
                  GetPath(ClientId=ClientId, FlowId=FlowId)])
    },
    column="Row")

LET _GetPath(ClientId, FlowId) =
  SELECT file_store(path=Data.VFSPath) AS Path
  FROM enumerate_flow(client_id=ClientId, flow_id=FlowId)
  WHERE Type = "Result" AND Path =~ "BasicInformation"

LET GetPath(ClientId, FlowId) = _GetPath(ClientId=ClientId, FlowId=FlowId)[0].Path

SELECT * FROM foreach(row=Completions, query={
  SELECT * FROM PostProcess(ClientId=ClientId, FlowId=FlowId)
})

I can test this in a notebook and see it works!

4. Convert to an artifact and install

My Final artifact looks like this

name: Custom.BasicInformation.EnrichPython
type: SERVER_EVENT
sources:
  - query: |
        LET Completions = SELECT FlowId,
                                 ClientId
          FROM watch_monitoring(artifact='System.Flow.Completion')
          WHERE Flow.artifacts_with_results =~ "Generic.Client.Info/BasicInformation"

        LET PostProcess(ClientId, FlowId) = SELECT *
          FROM foreach(row={
            SELECT parse_json(data=Stdout) AS Row
            FROM execve(argv=["python.exe", "C:/MyScript.py",
                          GetPath(ClientId=ClientId, FlowId=FlowId)])
          },
                       column="Row")

        LET _GetPath(ClientId, FlowId) = SELECT file_store(path=Data.VFSPath) AS Path
          FROM enumerate_flow(client_id=ClientId, flow_id=FlowId)
          WHERE Type = "Result"
           AND Path =~ "BasicInformation"

        LET GetPath(ClientId, FlowId) = _GetPath(ClientId=ClientId, FlowId=FlowId)[0].Path

        SELECT *
        FROM foreach(row=Completions,
                     query={
            SELECT *
            FROM PostProcess(ClientId=ClientId, FlowId=FlowId)
          })

I can add it and install it as a server event monitor. Then each time I collect Generic.Client.Info the artifact will automatically post process the results.

Post processing the collections with Python!

This quick example shows how to automatically post process collections with external programs. You need to be able to shell out to the external program which will run on the server. We used Python in this example just for illustration purposes but you can use any language to write the external program.

You can also use watch_monitoring() with the name of the new artifact to watch for post processed results as well! … We need to go deeper! - for example use Elastic.Events.Upload to upload those to Elastic.

How do I configure Cloudflare Dynamic DNS?

Wed, 18 Jun 2025 00:00:00 +0000

How do I configure Cloudflare Dynamic DNS?

Setting up Cloudflare as your preferred dynamic DNS provider requires the following steps:

Sign into Cloudflare and buy a domain name.
go to https://dash.cloudflare.com/profile/api-tokens to generate an API token. Select Edit Zone DNS in the API Token templates.

You will require the “Edit” permission on Zone DNS and include the specific zone name you want to manage. The zone name is the domain you purchased for example “example.com”. You will be able to set the hostname under that domain, e.g. “velociraptor.example.com”

Using this information you can now create the dyndns configuration:

Frontend:
  ....
  dyn_dns:
    type: cloudflare
    api_token: XXXYYYZZZ
    zone_name: example.com

Make sure the Frontend.Hostname field is set to the correct hostname to update - for example

Frontend:
  hostname: velociraptor.example.com

This is the hostname that will be updated.

How do I setup Velociraptor with a CloudFlare Tunnel?

Mon, 19 May 2025 00:00:00 +0000

How do I setup Velociraptor with a CloudFlare Tunnel?

For this tutorial I have built Velociraptor on an Ubuntu 20.04 machine.

Step 1

Once you have Velociraptor installed, the first thing to do is to Generate a config file: velociraptor config generate -i

Generating configuration

Step 2

Follow the following steps:

Deployment Type: Self Signed SSL
What OS will the server be deployed on: Linux
Path to Datastore: /var/tmp/velociraptor
Path to the logs directory: /var/log/velociraptor
Internal PKI Certificate: 2 Years
Do you want to restrict VQL functionality on the server?: No
Use registry for client writeback?: No
What is the public DNS name of the Master Frontend: domain.com
DNS Type: None : Configure DNS Manually
Would you like to try the new experimental websocket comms?: No
Enter the frontend port to listen on.: 443
Enter the port for the GUI to listen on.: 443
Overwrite File: /etc/velociraptor/server.config.yaml

Step 3

Replace all the localhost IPs to listen on all interfaces (0.0.0.0) sed -e '/bind_address:/{s/127.0.0.1/0.0.0.0/}' -i /etc/velociraptor/server.config.yaml

Step 4

As CloudFlare is handling the certificate you need to disable the self signed certificate in the yaml file nano /etc/velociraptor/server.config.yaml

Remove the option for using self signed SSL

Step 5

In the CloudFlare Dashboard make a new public hostname pointing to your internal IP address. The setting is under Zero Trust > Networks > Tunnels > Your Tunnel Name

Remove TLS Verification from CloudFlare

Step 6

Start your Velociraptor velociraptor -c /etc/velociraptor/server.config.yaml frontend -v

How to set up authentication using Google OAuth SSO

Mon, 28 Apr 2025 00:00:00 +0000

How to set up authentication using Google OAuth SSO

This guide walks you through the configuration of Google OAuth SSO as an authentication provider. This requires a user to authenticate via Google Workspace using it’s associated authentication policy. For example if 2-factor authentication is required then users will need to satisfy this requirement.

Once the user authenticates to Google, they are redirected back into the Velociraptor application with a token that allows the application to request information about the user (for example, the username or email address).

Before You Begin

Please note the following requirements:

Your Velociraptor server must have a valid SSL certificate already issued and configured. This can be a certificate issued by Let’s Encrypt or another public CA.
Google restricts OAuth 2.0 applications to using Authorized Domains. According to Google:

To use a domain as an authorized domain for OAuth, it must be a “top private domain”, which is the domain component available for registration on a public suffix, such as the domain before the .com, .net, or .biz, or similar top-level domains. Subdomains are controlled by the parent domain and are not considered top private domains.

For example, if your application home page is https://sub.example.com/product, you would need to verify ownership of the example.com domain. This verification is necessary to ensure the security and trustworthiness of the application.

Registering Velociraptor as an OAuth application

Before using Google to authenticate, you need to register your Velociraptor deployment as an OAuth App with Google. You register Velociraptor as an OAuth app by accessing the Google cloud console at https://console.cloud.google.com. You must set up a cloud account and create a cloud project even if you do not host your server on Google’s Cloud Platform.

The ultimate goal of this step is to obtain OAuth credentials that will be used in the Velociraptor configuration, but there are a few things set up first.

Navigate to APIs and Services in the GCP console and select Credentials and the OAuth Consent Screen tab.

Creating application credentials

Further down the page you need to provide an authorized domain.

Authorizing domains

In order to add an Authorized Domain you need to verify it. Google’s help pages explain it further.

In this example we assume that you purchased your domain with Google domains which makes this step easier since it is already verified.

We can go back to the cloud console and Create Credentials > OAuth client ID:

Creating OAuth2 client ID

Now select Web App and set the Authorized redirect URIs to https://<Your Domain Name>/auth/google/callback - This is the URL that successful OAuth authentication will redirect to. Velociraptor accepts this redirect and uses it to log the user on.

Specifying the redirect URL

If all goes well the Google Cloud Console will give us a client ID and a client secret.

Generating configuration

To generate a server config file run the config generate command to invoke the configuration wizard:

velociraptor config generate -i

Select SSO deployment type

Select Google as authentication provider

Enter OAuth credentials

The configuration wizard asks a number of questions and creates a server configuration file. The first question is “Deployment Type” and you should choose the option Authenticate users with SSO.

In addition to other common configuration questions the following are relevant to configuring SSO:

What is the public DNS name of the Master Frontend: This should match the CN field of your valid SSL certificate.
Select the SSO Authentication Provider: Here you should choose the option “Google”.
Enter the OAuth Client ID: the name as specified in Google Cloud Console.
Enter the OAuth Client Secret: as specified in Google Cloud Console.
GUI Username or email address to authorize: The initial set of administrator accounts can be stored in the configuration file. When Velociraptor starts it will automatically add these accounts as administrators. When using SSO, Velociraptor does not use any passwords so only the user names will be requested. While accounts can be specified here it is optional as they can also be created later, as we’ll show below. Entering a blank value will cause the wizard to move on to the next question.

Grant Access to Velociraptor

The OAuth flow ensures the user’s identity is correct but does not give them permission to log into Velociraptor. Note that having an OAuth-enabled application on the web allows anyone with a Google identity to authenticate to the application but the user is still required to be authorized explicitly. If a user is rejected, you will see messages similar to the following in the Audit log:

   {
     "level": "error",
     "method": "GET",
     "msg": "User rejected by GUI",
     "remote": "192.168.0.10:40570",
     "time": "2018-12-21T18:17:47+10:00",
     "user": "mike@velocidex.com"
   }

In order to authorize the user we must explicitly add them using the Velociraptor Admin tool:

$ velociraptor --config ~/server.config.yaml user add mike@velocidex.com
Authentication will occur via Google - therefore no password needs to be set.

Note that Velociraptor does not ask for a password, since authentication will occur using Google’s SSO.

Authenticate and access the Velociraptor GUI

Since you have added users from the command line you will need to restart the Velociraptor service:

sudo systemctl restart velociraptor_server

Then access the GUI. If your web browser is already logged into Google then the authentication process should be transparent. If not then you will be directed to Google to authenticate and you will then be redirected back to the Velociraptor GUI after successful logon.

We can see that the logged in user is authenticated by Google, and we can also see the user’s Google avatar at the top right.

Velociraptor will retain its OAuth token for 24 hours. Each day users will need to re-grant OAuth credentials. Therefore revoking a user from the Google Admin console may take a full day to take effect. To remove access sooner you should simply remove all permissions from the user using velociraptor user grant '{}'.

How to set up a SFTP server for file uploads

Tue, 25 Feb 2025 00:00:00 +0000

How to set up a SFTP server for file uploads

There are many options for receiving file uploads from clients or collection archives from offline collectors, for example using S3 buckets, Azure storage services, and even the AWS SFTP transfer service.

However you might prefer to set up your own SFTP server to receive incoming uploads instead of using a cloud storage service.

This article explains how to set up a SFTP server with appropriate security for automated remote file uploads.

Setting up SSH and SFTP can be tricky for novice Linux users. It is easy to misconfigure things in ways that can leave a server open to exploitation.

Unless you have a strong reason to prefer using SFTP we recommend that you consider more self-contained alternative options such as the one described in How to set up a self-hosted S3-compatible dropbox server.

Setup steps

Create a new Linux based VM and open port 22 for incoming requests. This can be in the cloud or on prem.
Create an sftpupload user

sudo adduser sftpupload

Create a directory for files to be uploaded and set the directory to be writable by the user.

mkdir -p /var/sftp/files
chown root:root /var/sftp/files

# Allow anyone to write there
chmod o+wx /var/sftp/files

# No directory listing possible
chmod o-r /var/sftp/files

Add the following in the file /etc/ssh/sshd_config:

PasswordAuthentication no

Match User sftpupload
    ForceCommand internal-sftp
    PasswordAuthentication no
    ChrootDirectory /var/sftp
    PermitTunnel no
    AllowAgentForwarding no
    AllowTcpForwarding no
    X11Forwarding no

and then restart the sshd service:

$ sudo systemctl restarts sshd

Create keys for the sftpupload user

sudo -u sftpupload bash
$ ssh-keygen
Generating public/private rsa key pair.
Enter file in which to save the key (/home/sftpuser/.ssh/id_rsa)

# Authorize the user's public key for access
$ cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys

# Make sure that secure permissions are applied for the directory
$ chmod -v 600 /home/sftpupload/.ssh/

Verify you can connect to the server and upload files. Listing files will be denied.

$ sftp localhost

sftp> put /etc/passwd /files/passwd.txt
Uploading /etc/passwd to /files/passwd.txt

sftp> ls -l files
remote readdir("/files/"): Permission denied

As you can see the sftpupload user does not have permission to read the directory but can upload files to it.

If we try shell access via SSH it will correctly be denied:

$ ssh localhost
This service allows sftp connections only.
Connection to localhost closed.

Offline Collector configuration

In the offline collector configuration you should use the private key (/home/sftpupload/.ssh/id_rsa) of the form:

-----BEGIN OPENSSH PRIVATE KEY-----
.....
-----END OPENSSH PRIVATE KEY-----

and for the Endpoint field, specify the value in the form <hostname or IP>:<ssh port>.

How can I automatically add & update client metadata?

Thu, 30 Jan 2025 00:00:00 +0000

How can I automatically add & update client metadata?

Client metadata is used to store custom information associated with each client. Velociraptor always stores basic information about all clients but you may want to store additional information, for example asset information. Client metadata makes this possible by allowing you to store any kind of data and associate it with a client. Client metadata can also be used to search for and filter clients in the GUI and in VQL queries, as we will demonstrate below.

Metadata can be manually added and updated for any client in the client’s Overview page, but also via VQL using the client_set_metadata function.

We can automate the addition and updating of client metadata by running a Server Event Artifact which sets metadata based on results of queries run on the client.

Metadata is a set of fields associated with each client. Labels can also be regarded as information associated with a client, but in Velociraptor labels are a more transient kind of information and are designed to be added and removed relatively frequently. Labels provide a way to group clients whereas Metadata provides a way to store information about each client.

It’s important that you choose the appropriate one for your use case. This article is about automating Metadata but if you want to do similar automation of Labels then you may find this article more useful: How can I automatically apply labels to clients?

Adding/updating metadata during client interrogation

When a client connects for the first time in a Velociraptor deployment, the server instructs the client to enroll and also tells it to run the Generic.Client.Info artifact. This built-in artifact is designed to collect basic information about the endpoint. We refer to this process as “interrogation”.

As explained here, the default interrogation artifact can be overridden with a custom version. If such a custom artifact is present on the Velociraptor server then all clients will use it.

In this example we will use a custom interrogation artifact to collect custom information and then use a Server Event artifact to watch for any new collections of Custom.Generic.Client.Info and add or update metadata fields based on the results.

The interrogation flow can also be run manually by clicking the Interrogate button on the client Overview page, or by creating a hunt for the Generic.Client.Info artifact. Such a hunt can further be created on a scheduled basis as demonstrated by the Server.Monitoring.ScheduleHunt artifact.

Before we set up the event monitoring we first need to:

prepare our custom interrogation artifact (including subordinate artifacts), and
configure metadata indexing on the server.

Add custom interrogation artifacts

We are going to have our custom interrogation artifact (Custom.Generic.Client.Info) call 2 other artifacts which will each collect the particular results we are interested in having as metadata.

Add an artifact to collect some BIOS info

The first artifact will query the endpoint for some BIOS information which may be useful for asset management. On Windows it will use WMI and on Linux it will use the dmidecode program which is available by default on most modern Linux systems. These methods both return equivalent data.

name: Generic.Client.BiosInfo
description: |
  Extracts some key fields from the BIOS which may be useful for system
  inventory purposes. For demonstration purposes only. Currently does not cover macOS.

type: CLIENT

sources:
  - precondition: SELECT * From info() where OS = 'windows'
    query: |
      -- On Windows we use WMI
      SELECT Manufacturer AS BaseBoardManufacturer,
             Product AS BaseBoardProduct,
             Version AS BaseBoardVersion,
             SerialNumber AS BaseBoardSerialNumber
      FROM wmi(query="SELECT * FROM Win32_baseboard")

  - precondition: SELECT * From info() where OS = 'linux' AND IsAdmin
    query: |
      -- on Linux we use dmidecode
      LET info = SELECT * FROM chain(
      a={SELECT regex_replace(source=Stdout,re="([^[:graph:]])",replace="") AS BaseBoardManufacturer
         FROM execve(argv=["dmidecode", "-s", "baseboard-manufacturer"])},
      b={SELECT regex_replace(source=Stdout,re="([^[:graph:]])",replace="") AS BaseBoardProduct
         FROM execve(argv=["dmidecode", "-s", "baseboard-product-name"])},
      c={SELECT regex_replace(source=Stdout,re="([^[:graph:]])",replace="") AS BaseBoardVersion
         FROM execve(argv=["dmidecode", "-s", "baseboard-version"])},
      d={SELECT regex_replace(source=Stdout,re="([^[:graph:]])",replace="") AS BaseBoardSerialNumber
         FROM execve(argv=["dmidecode", "-s", "baseboard-serial-number"])}
      )
      SELECT info[0].BaseBoardManufacturer AS BaseBoardManufacturer,
             info[1].BaseBoardProduct AS BaseBoardProduct,
             info[2].BaseBoardVersion AS BaseBoardVersion,
             info[3].BaseBoardSerialNumber AS BaseBoardSerialNumber
      FROM scope()

The key thing to note is that we are interested in having the following fields as metadata fields:

BaseBoardManufacturer
BaseBoardProduct
BaseBoardVersion
BaseBoardSerialNumber

After creating the artifact you can run it and verify that it produces the expected results:

Windows BIOS info

Linux BIOS info

Add an artifact to collect the last logged on user

Because the BIOS information is unlikely to ever change we also want to collect something which does change. For purposes of demonstration let’s query the last logged on user. We already have built-in artifacts that provide the relevant source information for Windows and Linux so we will leverage those in our new artifact.

name: Generic.Client.LastUser

description: Query to find the last logged on user.

type: CLIENT

sources:
  - precondition: SELECT * From info() where OS = 'windows'
    query: |
      SELECT Name AS LastUser, Mtime AS LastLogin
      FROM Artifact.Windows.Sys.Users()
      ORDER BY LastLogin DESC
      LIMIT 1

  - precondition: SELECT * From info() where OS = 'linux'
    query: |
      SELECT login_User AS LastUser, login_time AS LastLogin
      FROM Artifact.Linux.Sys.LastUserLogin()
      ORDER BY LastLogin DESC
      LIMIT 1

As with any new artifact it’s always a good idea to run it and verify that it produces the expected result:

Windows last user logon

Linux last user logon

From this artifact we get the following two fields which we want to have as client metadata:

LastUser
LastLogin

Configure Metadata Indexing

When run, the above two artifacts will altogether return 6 fields which we want added as client metadata. As explained here, client metadata fields can be indexed or non-indexed. While all metadata is accessible - and therefore searchable - via VQL, indexed fields are also searchable via the search bar in the GUI. So you might be thinking “great, let’s make everything indexed and searchable!”. However there are performance consequences to indexing metadata fields, especially if you have a large number of clients. In our case we are also going to have fields who’s value may change with every interrogation and that will require changes to the index and consequent re-indexing. So ideally you should only index fields that are going to be useful for GUI searches. You can still search all fields in VQL.

BaseBoardManufacturer
BaseBoardProduct
BaseBoardVersion <- unlikely to be searched for, so it doesn’t need to be indexed
BaseBoardSerialNumber
LastUser
LastLogin <- a timestamp (string) which won’t be searched for, so it doesn’t need to be indexed

Given the above considerations, we need to add the following to the server configuration file (the “defaults” section should already exist in the config).

defaults:
  indexed_client_metadata:
    - BaseBoardManufacturer
    - BaseBoardProduct
    - BaseBoardSerialNumber
    - LastUser

After adding this configuration the server will need to be restarted so that it reads the updated config file. The change will cause those metadata fields to be created for every client. Initially the indexed metadata fields will be empty - our server event artifact will populate their values later. You can navigate to any client’s Overview page and verify that the fields exist.

Note: You can always edit any metadata field’s value, but you cannot delete metadata fields that are indexed.

Add custom interrogation artifact

When interrogation happens on the client we want it to also run the 2 new artifacts which we added in the previous steps.

As explained here, the default interrogation artifact can be overridden with a custom version. If such a custom artifact is present on the Velociraptor server then all clients will use it.

We want to modify the default artifact carefully and as little as possible (see warning in the artifact’s description!), so we are only going to add two new sources to it which won’t affect any of the default functionality:

The first new source will call the Generic.Client.BiosInfo artifact.
The second new source will call the Generic.Client.LastUser artifact.

We create our custom interrogation artifact by editing the default Generic.Client.Info artifact. By default the name of the edited artifact will be Custom.Generic.Client.Info which is exactly what we want it to be.

In the custom version we add the new sources after the existing ones (around line 115 in the current default artifact):

  - name: BiosInfo
    query: SELECT * FROM Artifact.Generic.Client.BiosInfo(preconditions=TRUE)

  - name: LastUserLogin
    query: SELECT * FROM Artifact.Generic.Client.LastUser(preconditions=TRUE)

As you can see we are calling the other artifacts rather than including their VQL directly in the interrogation artifact. This makes our addition more concise and also allows the dependent artifacts to be run separately which is useful for troubleshooting. The parameter preconditions=TRUE is necessary because the dependent artifacts include preconditions that must be checked so that the correct VQL is run for each platform.

As a check that the artifact works you can manually initiate a client interrogation. The results should now include the two new sources.

New sources have data

Configure Server Event Monitoring

At this point we have configured the collection of the required data. The next step is to create a server event artifact and add it to server monitoring. This will monitor for incoming results and then populate the metadata fields with data from these results.

Add a Server Event Monitoring artifact

Our server event artifact to be added has 2 sources - one to monitor each of the new client artifacts that we added to Custom.Generic.Client.Info.

name: AutomateClientMetadata
type: SERVER_EVENT
sources:
- name: WatchBiosInfo
  query: |
    LET interrogations = SELECT *
    FROM watch_monitoring(artifact="System.Flow.Completion")
    WHERE Flow.artifacts_with_results =~ "Custom.Generic.Client.Info/BiosInfo"

    LET results = SELECT *, ClientId
    FROM source(
       artifact="Custom.Generic.Client.Info/BiosInfo" ,
       client_id=ClientId, flow_id=FlowId)

    SELECT *,
      client_set_metadata(
                  client_id=ClientId,
                  metadata=dict(
                    BaseBoardManufacturer=BaseBoardManufacturer,
                    BaseBoardProduct=BaseBoardProduct,
                    BaseBoardVersion=BaseBoardVersion,
                    BaseBoardSerialNumber=BaseBoardSerialNumber
                    )
                  )
    FROM foreach(row=interrogations, query=results)

- name: WatchLastUserLogin
  query: |
    LET interrogations = SELECT *
    FROM watch_monitoring(artifact="System.Flow.Completion")
    WHERE Flow.artifacts_with_results =~ "Custom.Generic.Client.Info/LastUserLogin"

    -- we sleep this query to slightly stagger the update
    LET results = SELECT *, ClientId, sleep(time=3) AS _sleep
    FROM source(
       artifact="Custom.Generic.Client.Info/LastUserLogin" ,
       client_id=ClientId, flow_id=FlowId)

    SELECT *,
      client_set_metadata(
                  client_id=ClientId,
                  metadata=dict(
                    LastUser=LastUser,
                    LastLogin=LastLogin
                    )
                  )
    FROM foreach(row=interrogations, query=results)

We now add this server event artifact to our server monitoring:

Add artifact to server event monitoring

Test it!

If you now enroll a new client or perform a manual interrogation against an existing client you will see the metadata fields populated.

The indexed fields will now be available as search operators in the client search bar.

search by indexed fields

As mentioned, the interrogation flow can be run manually by clicking the Interrogate button on the client Overview page, or by creating a hunt for the Custom.Generic.Client.Info artifact. Such a hunt can further be created on a schedule as demonstrated by the Server.Monitoring.ScheduleHunt artifact.

Adding/updating metadata from normal collections

Although we previously linked the metadata to interrogations, it doesn’t have to be done that way. We could, for example, hunt for either of the 2 new client artifacts we created and have Server Monitoring add/update the metadata from the results. Here’s how to do that…

Add a new server monitoring artifact

This artifact is almost identical to the one we previously created. The only difference is that instead of watching for interrogation flow completions it watches for completions of the client artifacts themselves.

name: AutomateClientMetadataDirect
type: SERVER_EVENT
sources:
- name: WatchBiosInfo
  query: |
    LET interrogations = SELECT *
    FROM watch_monitoring(artifact="System.Flow.Completion")
    WHERE Flow.artifacts_with_results =~ "Generic.Client.BiosInfo"

    LET results = SELECT *, ClientId
    FROM source(
       artifact="Generic.Client.BiosInfo" ,
       client_id=ClientId, flow_id=FlowId)

    SELECT *,
      client_set_metadata(
                  client_id=ClientId,
                  metadata=dict(
                    BaseBoardManufacturer=BaseBoardManufacturer,
                    BaseBoardProduct=BaseBoardProduct,
                    BaseBoardVersion=BaseBoardVersion,
                    BaseBoardSerialNumber=BaseBoardSerialNumber
                    )
                  )
    FROM foreach(row=interrogations, query=results)

- name: WatchLastUserLogin
  query: |
    LET interrogations = SELECT *
    FROM watch_monitoring(artifact="System.Flow.Completion")
    WHERE Flow.artifacts_with_results =~ "Generic.Client.LastUser"

    LET results = SELECT *, ClientId
    FROM source(
       artifact="Generic.Client.LastUser" ,
       client_id=ClientId, flow_id=FlowId)

    SELECT *,
      client_set_metadata(
                  client_id=ClientId,
                  metadata=dict(
                    LastUser=LastUser,
                    LastLogin=LastLogin
                    )
                  )
    FROM foreach(row=interrogations, query=results)

We then add this new artifact to our Server Event Monitoring.

Add artifact to server event monitoring

Now all we need to do is run the artifacts directly and the metadata will be updated. You can create a hunt for these artifacts if you want to update the data for all your clients.

The two approaches are not mutually exclusive: You can have both AutomateClientMetadata and AutomateClientMetadataDirect added to Server Monitoring at the same time and either one will update the same metadata.

Searching metadata in VQL

Searching metadata values in VQL is easy. Here’s an example that will list all systems where Mary was the last user to log on.

SELECT client_id,
       os_info.hostname,
       client_metadata(client_id=client_id).LastUser AS LastUser,
       client_metadata(client_id=client_id).LastLogin AS LastLogin
FROM clients()
WHERE LastUser = "Mary"

Running a search in a notebook

How to set up OIDC authentication using Keycloak

Sat, 28 Dec 2024 00:00:00 +0000

How to set up OIDC authentication using Keycloak

This guide walks you through the configuration of Keycloak as an OIDC authentication provider for Velociraptor.

Keycloak, as a self-hosted, free, and open source solution, may be an attractive choice for Velociraptor deployments where using cloud-based and/or commercial providers is not practical or possible. Most of the steps shown here would be the same or similar for other self-hosted OIDC solutions (for example Zitadel or Authentik), so it may be useful even if you are not using Keycloak.

Keycloak is a Java application which can be installed manually or deployed via several officially documented container-based methods. This guide partly mirrors Keycloak’s Getting started guide which uses Docker to create a “development mode” instance of Keycloak. This method starts a working Keycloak instance but does not create a persistent database or a production-ready secured server, since the goal here is only to demonstrate the integration with Velociraptor.

For production-ready deployment guidance we refer you to Configuring Keycloak for production and the official Keycloak documentation.

As mentioned above, the goal of this guide is to demonstrate a working SSO configuration for Velociraptor using Keycloak. The basic steps and configuration will be very similar or even identical for production deployments however some of the steps shown here are deliberately over-simplified for reasons of brevity and therefore do not reflect security best practices. Also Keycloak has a vast array of options and capabilities, which we recommend you explore later, but the intention here is to get up and running with a basic working integration since it is better to start simple and be sure that it’s working as expected before possibly adding complexity to it.

In this simplified setup we have two hosts, with DNS names keycloak.local and velociraptor.local. Substitute your DNS names where applicable. The two hosts don’t need to be on the same network but the Velociraptor host needs to be able to DNS-resolve the name of the Keycloak server and reach it on port 443. It’s not necessary that the Keycloak server be able to resolve the Velociraptor server’s DNS name but your server probably already has a DNS name already so that clients can connect to it.

Network overview

The high-level steps of this setup process are:

Create a self-hosted Docker-based Keycloak instance.
Configure an authentication realm, OIDC client and test users in Keycloak.
Configure the authentication provider in Velociraptor.
Add test users to Velociraptor.
Test the authentication process.

Create a Docker-based Keycloak instance

We assume that Docker has already been installed and configured on the designated Keycloak host. We aren’t going to use Docker Compose but for production deployment you might prefer to do so, and example configurations can be found on the internet.

Before we install Keycloak we are going to need a certificate for it to use. Here we will generate a simple self-signed cert with corresponding private key but ideally in production you would have a cert signed by a trusted CA.

1. Generate a key pair

# Create keycloak-server.crt.pem and keycloak-server.key.pem
openssl req -newkey rsa:2048 -nodes -subj "/CN=keycloak.local" \
-addext "subjectAltName=DNS:keycloak.local,IP:192.168.56.1" \
-keyout keycloak-server.key.pem -x509 -days 3650 -out keycloak-server.crt.pem
# Set appropriate permissions on files
chmod -R 644 keycloak-server*

NOTE: The certificate SAN is required by Velociraptor. If not present you will receive this error when trying to start Velociraptor.
error: gui: starting frontend: Get "https://keycloak.local/.well-known/openid-configuration": x509: certificate relies on legacy Common Name field, use SANs instead
Putting the IP in the SAN is not really necessary but helpful if you need to connect to Keycloak’s admin page using it’s IP.

Now that we have the key pair we can run Docker which will pull the latest Keycloak image (26.0.7 at the time of writing).

2. Run the Docker command.

docker run -p 443:443 -e KC_HOSTNAME=keycloak.local \
-e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
-v /root/keycloak-server.crt.pem:/etc/x509/https/keycloak-server.crt.pem \
-v /root/keycloak-server.key.pem:/etc/x509/https/keycloak-server.key.pem \
-e KC_HTTPS_CERTIFICATE_FILE=/etc/x509/https/keycloak-server.crt.pem \
-e KC_HTTPS_CERTIFICATE_KEY_FILE=/etc/x509/https/keycloak-server.key.pem \
quay.io/keycloak/keycloak:latest start-dev --https-port=443

We set various Keycloak config options as Docker environment variables and make the cert and private key available inside the Docker using volume mapping.

If the Docker fails to start, you should inspect the command output for errors. If successful it should report Listening on: http://0.0.0.0:8080 and https://0.0.0.0:443.

The KC_BOOTSTRAP* variables create an initial user admin with password admin which we use to configure Keycloak in the next section.

Configure Keycloak

Next we go through the steps that are almost the same as described in Keycloak’s Getting started guide.

Connect to Keycloak’s Admin Console (in this case: https://keycloak.local) and log in with the admin user.

3. Create an authentication realm

You can use any name for the realm but here we are going to just use myrealm for convenience.

Click Create.

4. Create OIDC client configuration for Velociraptor

In this step we create a new client record and client secret which we will use later in the Velociraptor configuration. In the realm selection drop-down ensure that you are in the new myrealm realm.

In the sidebar select Clients and then select Create client.

This will start a 3-page configuration wizard. On the first page the Client ID is all that’s required. Enter velociraptor and click Next.

On the second page, choose Client authentication: ON and Authentication flow: Standard flow (only). Then click Next.

On the third page we use the following values (adapt to your DNS names if your are replicating the setup in your own environment):

Valid redirect URIs: https://velociraptor.local:8889/auth/oidc/keycloak/callback
Valid post logout redirect URIs: https://velociraptor.local:8889/app/logoff.html
Web origins: https://velociraptor.local

Then click Save. Your OIDC client configuration is now created.

On the page that follows, go to the Credentials tab. There you will find the Client secret which you will need for your Velociraptor configuration. It is randomly generated and you can regenerate it if desired, but if you do so then don’t forget to update your Velociraptor server’s config with the new secret. Typically you would only regenerate it if you suspected a compromised secret.

The next action is to configure email addresses as login usernames. To do that navigate via the sidebar to Realm settings > Login tab. Ensure that Email as username and Login with email are enabled. The additional user preferences shown in the following screenshot are optional and in your case would be determined by your organizational policies.

The last action in this step is to configure the required actions for authentication so that users don’t have to enter additional information when they first log in. Navigate via the sidebar to Authentication > Required actions tab. Disable all options except Update password.

5. Create test users

We will need at least one user account to test the authentication. From the sidebar select Users and then click the Create new user button.

For the user account I am going to create one named bob@local. Remember that we previously enabled Email as username and Login with email, so all other fields are optional. I also selected Email verified to avoid an email verification step when logging in.

After creating the account, go to the Credentials tab and set a password. Note that we leave Temporary:ON set so that the password must be changed on first logon. Note also that this is a simplified demonstration so for that reason we’re ONLY using password auth while Keycloak easily supports multi-factor authentication.

Repeat the user creation actions to also create a user account fred@local.

Now we are ready to move to configuring the Velociraptor side of things.

Configure Velociraptor

sudo systemctl stop velociraptor_server
sudo -u velociraptor bash
velociraptor -c /etc/velociraptor/server.config.yaml frontend -v

This will display the log messages in the terminal.

6. Add the authenticator settings to your Velciraptor config

In the GUI section of your Velociraptor config you should have the following authenticator settings by default:

  authenticator:
    type: Basic

We no longer want Basic auth and instead want SSO, so replace that with these new settings to match our Keycloak configuration:

    type: oidc
    oidc_issuer: https://keycloak.local/realms/myrealm
    oidc_name: keycloak
    avatar: https://www.keycloak.org/resources/images/logo.svg
    oauth_client_id: velociraptor
    oauth_client_secret: p4EABoniopnasbrmstDnsHrQcSukNmp2

The oauth_client_secret is the value we obtained at the end of step 4. The oauth_client_id is the name we used for the OIDC Client ID in that same section.

The oidc_name can be anything you want but it must exactly match (case-sensitive) the substring used in the Valid redirect URIs field of the client configuration in Keycloak.

Keycloak requires that the oidc_issuer field specify the path /realms/myrealm as this is where is serves the OpenID Endpoint Configuration that Velociraptor will need to access. If you have somehow gotten this wrong then Velociraptor will log an error such as: [ERROR] can not get information from OIDC provider, check https://keycloak.local/.well-known/openid-configuration is correct and accessible from the server.

Before you start Velociraptor, if you are using a self-signed cert for Keycloak then also attend to the next step.

7. Copy the Keycloak server cert to the trusted root store.

Because the Keycloak server is using a certificate that wasn’t issued by a trusted CA, we need to add it’s certificate to the trusted root store on the Velociraptor server. Assuming your server is Ubuntu or similar this means saving a copy of the certificate to /etc/ssl/certs.

Without this step you will see this error in the log when attempting to start Velociraptor: error: gui: starting frontend: Get "https://keycloak.local/...": x509: certificate signed by unknown authority (possibly because of "crypto/rsa: verification error" while trying to verify candidate authority certificate "keycloak.local")

8. Start Velociraptor

The server should now start cleanly and continue running. In the log messages you should see GUI will use the oidc authenticator. That means everything is OK with the authenticator config.

One possible gotcha is if the server’s GUI.public_url setting is still using an IP address or if GUI.bind_address is not set to 0.0.0.0 then you may get stopped with the error: error: gui: starting frontend: Authentication type 'oidc' requires valid public_url parameter

In this case the GUI.public_url is set to https://velociraptor.local:8889/.

Add test users

We have created 2 users in Keycloak but these users don’t yet exist in Velociraptor. Velociraptor has it’s own permissions model and therefore needs to know about any users so that once they authenticate the correct permissions can be applied.

Users can be created using VQL in Velociraptor notebooks but since we have now switched authentication providers we no longer have access to the GUI. Of course we could have added the users before we switched but let’s pretend we didn’t and instead do it from the command line.

We will make bob@local a server admin and grant fred@local the “reader” role, which provides minimal access to Velociraptor’s GUI. The following two commands will create these users:

9. Add users to the datastore

velociraptor --config server.config.yaml user add --role administrator bob@local
velociraptor --config server.config.yaml user add --role reader fred@local

Because of our OIDC authenticator config, when adding each user we will receive an acknowledgement message saying "Authentication will occur via oidc - therefore no password needs to be set."

Test authentication process

Test the authentication process by going to https://velociraptor.local:8889/

You will be presented with the choice to log in with Keycloak (multiple authentication providers are supported but we only have one configured).

Enter initial credentials (password that was set in Keycloak).

You will be required to change the password because we configured Temporary:ON when setting the account’s password.

Change the password

Successful login!

We can verify that the user has the server admin role.

We can sign out… and sign in again.

The same process applies to fred@local except that we can verify in Velociraptor that the user has the read-only role.

For testing multiple users in the same web browser you may have trouble fully logging a user out because while logged out of Velociraptor the OIDC session is still active.

Logout of the OIDC session can be achieved by navigating to the the endpoint https://keycloak.local/realms/myrealm/protocol/openid-connect/logout from within the same web browser and choosing to log out.

What next?

Once you have the working authentication setup, as per this guide, then you can begin experimenting with additional options while knowing that any change which causes a negative effect can be reverted back to a known working state. This is a much easier approach than diving in with a complex configuration and spending hours troubleshooting why it doesn’t work.

Since the Docker installation used in the guide is non-permanent it will reset when you restart the docker VM. For testing and experimenting that’s a good thing as you gain familiarity by going through the process. As mentioned, Keycloak supports multifactor authentication, complex authentication flow options, themeable login screens, and many other cool features. However for permanent configuration you will need to learn how to create a persistent Keycloak database, possibly using a different deployment method.

Set operations in VQL

Mon, 16 Dec 2024 00:00:00 +0000

Set operations in VQL

Set operations are useful in a number of useful scenarios.

What are sets?

Sets are a mathematical construct that allows set operations on groups of values. In VQL sets are analogous to dictionaries with the key being the set member and the values ignored (usually just set to TRUE). Set operations are emulated using dict addition and subtraction.

For example consider the following VQL


// Convert a list into a dict for set operations
LET SET(LIST) = to_dict(item={
  SELECT _value AS _key, TRUE AS _value FROM foreach(row=LIST)
})

// Convert a dict into a list of keys
LET KEYS(X) = items(item=X)._key

LET X <= SET(LIST=["A", "B"])
LET Y <= SET(LIST=["A", "C"])

SELECT X + Y AS Union,
       KEYS(X=X+Y) AS UnionKeys,
       X - Y AS Intersection,
       KEYS(X=X-Y) AS IntersectionKeys,
       X.A AS Membership,
       get(field="A", item=X) AS Membership2
FROM scope()

In the above example, we define a helper function SET() to create a dict from an array by iterating over each element of the array, and setting the value to TRUE.

A Set Union operation is the combination of all keys in the first set and the second set. This is achieved by adding the dicts. Similarly a Set Difference removes keys present in the second set from the first set. This is implemented by subtracting the second set from the first set.

Set membership check can be done by simply checking if the dict contains the value. This can be done directly when the key name is known in advance, or by using the get() function to access the named field.

Set Operations in VQL

Using Set operations in VQL

An example use case is in responding to a number of distinct artifact collections. For example, for post processing the results of some collections.

Generally to respond to server events we need to write a SERVER_EVENT artifact that watches for certain events on the server. In this case we watch for events from the System.Flow.Completion artifact, this artifact emits the flow object from each flow containing a list of artifacts_with_results.

LET SET(LIST) = to_dict(item={
  SELECT _value AS _key, TRUE AS _value FROM foreach(row=LIST)
})

LET FlowsToWatch <= SET(LIST=["Generic.Client.Info/Users",
   "Generic.Client.Info/WindowsInfo"])

SELECT Flow
FROM watch_monitoring(artifact="System.Flow.Completion")
WHERE any(items=Flow.artifacts_with_results, filter="x=>get(item=FlowsToWatch, field=x)")

The above query prepares a set into the variable FlowsToWatch. The query then filters out all flows except those that contain results from the set of interest.

An alternative to the previous query is to use a regular expression (This solution is more flexible as it allows matching artifact names by regular expressions):

LET FlowsToWatch <= join(array=["Generic.Client.Info/Users",
   "Generic.Client.Info/WindowsInfo"], sep="|")

SELECT Flow
FROM watch_monitoring(artifact="System.Flow.Completion")
WHERE Flow.artifacts_with_results =~ FlowsToWatch

This works because a regular expression match on an array is true if any of the members of the array match.

How do I get a list of hunts across multiple organizations?

Fri, 06 Dec 2024 00:00:00 +0000

How do I get a list of hunts across multiple organizations?

Are you looking for a way to generate user metrics across the entire server (like Hunts run per user)?

Orgs are separated out so when you run a query you are running that query within the context of the org. Normally the hunts scheduled in an organization can be accessed using the hunts() plugin, but that normally acts within a single Org.

To run a query in another org, you can switch org contexts using the query() plugin.

So for example to see all hunts in all orgs:

SELECT * FROM foreach(
  row={
    SELECT OrgId FROM orgs()
  },
  query={
    SELECT * FROM query(query={
      SELECT * FROM hunts()
    }, org_id=OrgId)
  })

This query iterates over all the orgs, then runs the SELECT * FROM hunts() query within the org context.

You can simplify the query using LET stored queries:

LET MyQuery = SELECT * FROM hunts()
LET AllOrgs = SELECT OrgId FROM orgs()

SELECT * FROM foreach(row=AllOrgs,
  query={
    SELECT * FROM query(query=MyQuery, org_id=OrgId)
  })

Of course your user account must have access to the orgs. Each org has a separate ACL for each user, so your user needs to have at least the READ_RESULTS permission to be able to see the org.

Some plugins (e.g. hunt() ) support orgs directly for convenience but generally you should use the above approach. This will also remind you that each such query is running in a separate org context and therefore can not see other data at the same time.

Error "Parameter refers to an unknown artifact" when collecting a CLIENT artifact

Sat, 31 Aug 2024 00:00:00 +0000

Error “Parameter refers to an unknown artifact” when collecting a CLIENT artifact

Before an artifact is collected from the client, the artifact is compiled into a VQL request by the artifact compiler. This actually transforms the vql and injects dependent artifacts into the request so the client can evaluate it. The client’s VQL engine will never use built in artifacts and must always have artifacts injected in the request.

The reason for that is that if an artifact is updated on the server (e.g. by upgrading the server or edit the custom artifact) the client must be given the latest version of the artifact.

When the VQL compiler sees a statement like:

SELECT * FROM Artifact.Dependant.Artifact()

It will recognize the the the VQL is dependent on the artifact Dependent.Artifact and will inject it into the VQL request. You can see this in the Request tab - the artifacts section of the request will include dependent artifact definitions (in this case the artifact calls Generic.Utils.FetchBinary).

[
  {
     "session_id": "F.CR3B2IIN3E8GK",
     "request_id": "1",
     "FlowRequest": {
         "VQLClientActions": [
         {
           "query_id": "1",
           "total_queries": "1",
           ....
           "artifacts": [
           {
               "name": "Generic.Utils.FetchBinary",
               "parameters": [

This issue comes up commonly in two scenarios:

Using the VQL shell to collect a custom artifact

In this case the GUI will collect the artifact Generic.Client.VQL which essentially evaluates the query provided as a string on the client.

Because the query is given as an opaque string parameter, the artifact compiler does not see any dependencies and can not inject them into the request. Built in artifacts are allowed in this case but custom artifacts are not supported.

If you need to collect a custom artifact from the endpoint, just collect it as normal - do not use the VQL shell for that.

Using the `collect()` plugin on the client to prepare a collection zip file.

Another similar issue occurs when writing a custom artifact that uses the collect() plugin. Similarly because the artifacts to collect are given as strings, the compiler has no idea these are a dependency.

For example this VQL code

SELECT * from collect(artifacts=['Generic.Collectors.File'],
   args=dict(`Generic.Collectors.File`=dict(`collectionSpec`=collectionSpec,
             `Root`=Root)),
   password='infected',
   output=tempzip)

To fix this artifact the Generic.Collectors.File artifact must be given as a dependency. Either include it in the artifact’s import section or add the following VQL statement:

LET _ = SELECT * FROM Artifact.Generic.Collectors.File()

That statement will not actually run the artifact (it is a lazy LET statement) but the compiler’s static analyzer will identify the artifact as a dependency and be able to inject it into the request.

How to manage storage space on the server

Fri, 19 Jul 2024 00:00:00 +0000

How to manage storage space on the server

Velociraptor can collect a lot of data quickly but usually the data is only relevant for short periods of time.

Disk space management is an important part of Velociraptor administrators tasks. You can keep an eye on the disk utilization as shown on the dashboard.

If you need to grow the disk during an investigation, and you are using a cloud VM from Amazon with Elastic Block Storage (EBS), disk space management is very easy. In the AWS cloud it is possible to resize disk space dynamically. See Requesting Modifications to Your EBS Volumes and Extending a Linux File System After Resizing a Volume. You can do this without even restarting the server.

If you must attach a new volume you can migrate data from the old datastore directory (as specified in the config file) to the new directory by simply copying all the files. You must ensure permissions remain the same (typically files are owned by the velociraptor low privilege local linux account).

It is also possible to start with an empty datastore directory and only copy selected files:

The users directory contains user accounts (hashed password etc)
The acl directory contains user ACLs
The artifact_definitions contains custom artifacts
The config directory contains various configuration settings.
The orgs directory contains data from various orgs.

Velociraptor will automatically re-enroll clients with the same client id (The client id is set by the client itself) as needed.

You can also check the backups directory to recover from backup.

Management of old collections

You can automatically delete old collections using the Server.Utils.DeleteManyFlows and Server.Utils.DeleteMonitoringData artifacts. These are server artifacts which can delete flows and monitoring data older than the specified time.

How do I enable password protected VFS downloads?

Mon, 18 Mar 2024 00:00:00 +0000

How do I enable password protected VFS downloads?

You can just export them from the GUI!

Set the password in your user preferences you can enable password protected exports.

Highlight the directory you want to export.

Hit the export button - this will start a server collection to take a snapshot of the vfs - you can set any filtering globs (so for example don’t export all the files - maybe only *.exe).

By default it just does ** which is everything under the directory. This makes a collection and adds a link to it.

Then click that and export like any other collection.

Password can be set in the user preferences (the top right tile with the username). This will enable the lock feature of the zip export - make sure to click close button to save the password (instead of just clicking outside the modal dialog).

How do you generate random characters?

Wed, 09 Aug 2023 00:00:00 +0000

How do you generate random characters?

Using the rand() function we can manipulate the results to output a character set then use the WHERE condition to filter for the characters of interest.

For example output 32 random printable characters:

  LET RandomChars = SELECT format(format="%c", args=rand(range=255)) AS Character
  FROM range(end=9999999999)
  WHERE Character =~ "[ -~]"
  LIMIT 32

SELECT join(array=RandomChars.Character) as Characters FROM scope()

Modify the Character WHERE regex and LIMIT for desired results.

How can I clone an organization with all its hunts and artifacts to another instance?

Mon, 24 Jul 2023 00:00:00 +0000

How can I clone an organization with all its hunts and artifacts to another instance?

There are a few use cases where you need to migrate data from an instance to another. It could be for educational purpose to provide pre-filled labs, or to provide a third party with the exact insights you had during your investigation. Event for archiving, being able to reload a dataset in Velociraptor to review what was done if something went amiss, being able to export and import an organization dataset could prove useful.

Exporting

Everything related to an organization is stored in a directory under <file store>/orgs. There is:

A directory with the org ID
A configuration file <orgId>.json.db

We need to transfer both to the destination server.

Identify the org ID, either with the Server.Orgs.ListOrgs Artifact or scrolling down the Velociraptor root org home page.
Archive the folder and the json.db file (mind the star)

tar czf transport-<org name>.tar.gz <file store>/orgs/<org id>*

Transfer the resulting archive to the destination Velociraptor server.

Importing

Decompress the archive under the <file store>/orgs directory.

The orgs directory is created with the first organization. After a fresh install of Velociraptor, it doesn’t exist until you create an org. You may also simply create the directory.

Verify file ownership and permissions are similar to other directories in the file store
Start Velociraptor
You should see the organization with all its content as it were on the origin server

Upon startup, Velociraptor will run the workers linked to the organization, so you can find a trace of it in the logs, but you may only see it in GUI if you are granted permissions on it. Just edit with your favorite text editor: <file store>/orgs/<org id>/acl/<username>.json.db to give the access rights to an existing user (or create a user with the name of a user who was allowed to see the org),

What to do about error "Plugin info not found"

Fri, 05 May 2023 00:00:00 +0000

What to do about error “Plugin info not found”

Velociraptor VQL queries can run on the server in the context of server artifacts or notebook queries. Usually server side VQL is used to post-process collected results, manage the server configuration, schedule new collections etc.

However, server side VQL can do a lot more than that - including shell out to external binaries, read and write files on the server or connect to external servers. In some deployments (especially shared deployments) it is desirable to block any functionality on the server which may interfere with other users or server security or configuration.

In recent Velociraptor versions the administrator can add an allow list to the configuration file. This forces server side VQL to only register plugins on the allow list, so potentially dangerous plugins are not present at all (regardless of the Velociraptor permission model).

The configuration wizard will offer this functionality using the question:

Do you want to restrict VQL functionality on the server?

This is useful for a shared server where users are not fully trusted.
It removes potentially dangerous plugins like execve(),filesystem access etc.

If you selected this during configuration you will receive these errors in the notebook (or using the API) for any plugins not in the allow list:

ERROR:Plugin info not found.

If you decide you need this particular plugin you can either add to the allow list in the server configuration file. Or you may remove the allow list entirely (which allows all plugins to be registered).

Custom quarantine exclusions

Sat, 04 Mar 2023 00:00:00 +0000

Custom quarantine exclusions

We may want to add custom exclusions to Velociraptor quarantine and allow communication to another IP

Add machine in scope to a new label: e.g NewQuarantine
Remove standard quarantine
Run a hunt targeting your label above or a collection on the single machine
Select relevant quarantine content: Windows.Remediation.Quarantine
Add additional IP exclusions Action = Permit SrcAddr = me DstAddr = IP to exclude Mirrored = yes for bidirectional communication Description

image

How can I convert decimal?

Wed, 02 Nov 2022 00:00:00 +0000

How can I convert decimal?

During investigation you may find logs or other data with decimal-encoded strings - we can leverage the format() function to convert to data.

LET decimal = ( 91,78,101,116,46,83,101,114,118,105,99,101,80,111,105,110,116,77,97,110,97,103,101,114,93,58,58,83,101,114,118,101,114,67,101,114,116,105,102,105,99,97,116,101,86,97,108,105,100,97,116,105,111,110,67,97,108,108,98,97,99,107,32,61,32,123,36,116,114,117,101,125,10,116,114,121,123,10,91,82,101,102,93,46,65,115,115,101,109,98,108,121,46,71,101,116,84,121,112,101,40,39,83,121,115,39,43,39,116,101,109,46,77,97,110,39,43,39,97,103,101,109,101,110,116,46,65,117,116,39,43,39,111,109,97,116,105,111,110,46,65,109,39,43,39,115,105,85,116,39,43,39,105,108,115,39,41,46,71,101,116,70,105,101,108,100,40,39,97,109,39,43,39,115,105,73,110,105,39,43,39,116,70,97,105,108,101,100,39,44,32,39,78,111,110,80,39,43,39,117,98,108,105,99,44,83,116,97,39,43,39,116,105,99,39,41,46,83,101,116,86,97,108,117,101,40,36,110,117,108,108,44,32,36,116,114,117,101,41,10,125,99,97,116,99,104,123,125,10,91,78,101,116,46,83,101,114,118,105,99,101,80,111,105,110,116,77,97,110,97,103,101,114,93,58,58,83,101,114,118,101,114,67,101,114,116,105,102,105,99,97,116,101,86,97,108,105,100,97,116,105,111,110,67,97,108,108,98,97,99,107,32,61,32,123,36,116,114,117,101,125,10,91,83,121,115,116,101,109,46,78,101,116,46,83,101,114,118,105,99,101,80,111,105,110,116,77,97,110,97,103,101,114,93,58,58,83,101,99,117,114,105,116,121,80,114,111,116,111,99,111,108,32,61,32,91,83,121,115,116,101,109,46,78,101,116,46,83,101,99,117,114,105,116,121,80,114,111,116,111,99,111,108,84,121,112,101,93,39,83,115,108,51,44,84,108,115,44,84,108,115,49,49,44,84,108,115,49,50,39,10,73,69,88,32,40,78,101,119,45,79,98,106,101,99,116,32,78,101,116,46,87,101,98,67,108,105,101,110,116,41,46,68,111,119,110,108,111,97,100,83,116,114,105,110,103,40,39,104,116,116,112,115,58,47,47,49,48,46,48,46,49,46,55,58,52,52,51,47,73,110,118,111,107,101,45,77,105,109,105,107,97,116,122,46,112,115,49,39,41,10,36,99,109,100,32,61,32,73,110,118,111,107,101,45,77,105,109,105,107,97,116,122,32,45,67,111,109,109,97,110,100,32,39,112,114,105,118,105,108,101,103,101,58,58,100,101,98,117,103,32,115,101,107,117,114,108,115,97,58,58,108,111,103,111,110,112,97,115,115,119,111,114,100,115,32,101,120,105,116,39,10,36,114,101,113,117,101,115,116,32,61,32,91,83,121,115,116,101,109,46,78,101,116,46,87,101,98,82,101,113,117,101,115,116,93,58,58,67,114,101,97,116,101,40,39,104,116,116,112,115,58,47,47,49,48,46,48,46,49,46,55,58,52,52,51,47,39,41,10,36,114,101,113,117,101,115,116,46,77,101,116,104,111,100,32,61,32,39,80,79,83,84,39,10,36,114,101,113,117,101,115,116,46,67,111,110,116,101,110,116,84,121,112,101,32,61,32,39,97,112,112,108,105,99,97,116,105,111,110,47,120,45,119,119,119,45,102,111,114,109,45,117,114,108,101,110,99,111,100,101,100,39,10,36,98,121,116,101,115,32,61,32,91,83,121,115,116,101,109,46,84,101,120,116,46,69,110,99,111,100,105,110,103,93,58,58,65,83,67,73,73,46,71,101,116,66,121,116,101,115,40,36,99,109,100,41,10,36,114,101,113,117,101,115,116,46,67,111,110,116,101,110,116,76,101,110,103,116,104,32,61,32,36,98,121,116,101,115,46,76,101,110,103,116,104,10,36,114,101,113,117,101,115,116,83,116,114,101,97,109,32,61,32,36,114,101,113,117,101,115,116,46,71,101,116,82,101,113,117,101,115,116,83,116,114,101,97,109,40,41,10,36,114,101,113,117,101,115,116,83,116,114,101,97,109,46,87,114,105,116,101,40,36,98,121,116,101,115,44,32,48,44,32,36,98,121,116,101,115,46,76,101,110,103,116,104,41,10,36,114,101,113,117,101,115,116,83,116,114,101,97,109,46,67,108,111,115,101,40,41,10,36,114,101,113,117,101,115,116,46,71,101,116,82,101,115,112,111,110,115,101,40,41 )

LET convert_decimal(data) = SELECT format(format='%c',args=_value) as Value FROM foreach(row=data)

SELECT join(array=convert_decimal(data=decimal).Value,sep='') as Data FROM scope()

image

How do I re-collect a failed artifact in a hunt?

Sat, 10 Sep 2022 00:00:00 +0000

How do I re-collect a failed artifact in a hunt?

Sometimes collecting an artifact in a hunt does not work as expected.

Most commonly the issue is that the timeout or upload limit for collecting the artifact is exceeded and Velociraptor cancels the collection to prevent placing the endpoint under too much strain.

How do we work around this? We can recollect the artifact only on that failed endpoint with a few button clicks.

In the following example I will start a collection for the $MFT but I will only set the timeout to 10 seconds and 100Mb uploaded.

Hunting for Files

In the hunt resources screen I can specify limits for collection from any one client. These limits are intended to set reasonable boundaries for how much data I am expecting to collect so we do not overload the network or the endpoint itself.

Setting resource limits

Clearly these limits are too small for this client because the collection was cancelled after 10 seconds. Normally the default timeout of 10 Minutes, but collecting such a lot of data may take longer than that.

Collection timed out

Although some data was transferred, not all the data was fully collected. This might be acceptable but if this machine is really compromised how can I recollect the same artifact?

By inspecting the collections for each client in the Clients tab, I can quickly see which one failed.

Inspecting failed collection

Since a hunt is just a grouping of regular collections, I can navigate to the client in the interface (by clicking the client button) and find the hunt’s collection that failed.

Copying the collection

Now I just copy the collection as normal and here I can update the resource limits if needed (or maybe change some of the parameters).

Successful Collection

Now that this collection is completed I can just look at the results of the collections by itself or download the collection files for further analysis.

However, it is much more useful to keep all related collections in the same hunt. This helps when analyzing the hunt results in the notebook or exporting all the related files at once.

It is best to think of a hunt as just a set of related artifact collections. You can add/remove collections from this set at will.

I am adding the new collection to the hunt manually by clicking the Add to Hunt button.

Manually Adding the collection to the hunt

The interface shows me all hunts that collected the same artifact so I choose which hunt to add it to.

The new collection is now part of the hunt

Now the new successful collection is part of the hunt. I can see it as a second entry in the client’s list.

Velociraptor does not automatically delete the old failed collection because it may still have some useful data (some data was transferred).

If you do not want the old data any more, then just click the Delete Flow button once a better collection is available.

Using VQL

The above discussion was how to manually redo collections in the GUI but if there are many collections, it might be easier to use VQL to do this.

LET NewCollections = SELECT ClientId, FlowId,
    collect_client(client_id=ClientId,
        artifacts=Flow.request.artifacts,
        spec=Flow.request.specs,
        max_bytes=1000000000,
        timeout=600) AS NewCollection
FROM hunt_flows(hunt_id=HuntId)
WHERE Flow.state =~ "ERROR"

SELECT ClientId, NewCollection, hunt_add(
   client_id=ClientId,
   hunt_id=HuntId,
   flow_id=NewCollection.flow_id) AS Hunt
FROM NewCollections

The NewCollections query gets all Flows in the ERROR state within a hunt and schedules a new collection using the same artifacts but increasing the maximum upload size to 1gb and timeout to 600 seconds.
The next query adds the new collection to the hunt.

Note this query will only work after #2067

How to control hunting by label groups?

Sat, 10 Sep 2022 00:00:00 +0000

How to control hunting by label groups?

In Velociraptor, Hunts are sets of the same collections across clients. For example, a hunt for Scheduled Tasks will automatically collect the scheduled tasks from each client.

When creating the hunt it is possible to target the hunt to a Label. This only schedules the hunt on clients that have that same label. This is useful when collecting a lot of data which does not make sense to collect from every machine in the fleet. For example in the following screenshot I am limiting the heavy triaging collection to machines with the label Triage.

Limiting a hunt to a label

Assigning clients to the hunt.

Normally when we limit a hunt for a label we immediately schedule the hunt on all machines with that label.

However it also works the other way around - When a label is added on a client, if the hunt targets this label, the client will be automatically added to the hunt!

This means it is possible to create heavy hunts targeting specific labels, and then as the investigation progresses, simply assign the label to the client to automatically cause the hunt to collect on that client.

Apply a label to a client to trigger hunt participation

How do I get the latest release binary?

Sat, 03 Sep 2022 00:00:00 +0000

How do I get the latest release binary?

The Velociraptor release process uses a release branch to prepare a new release. Releases go through a release candidate (RC) process with one or more release builds. Sometimes after the release a new patch release is made to backport critical bug fixes.

If you need to automate downloading of the latest release binary, simply use the GitHub API which presents detailed release information in JSON form. You can use a tool such as jq to extract the download URL:

WINDOWS_URL=$(curl -s https://api.github.com/repos/velocidex/velociraptor/releases/latest | jq
-r '[.assets | sort_by(.created_at) | reverse | .[] | .browser_download_url | select(test("windows-amd64.exe$"))][0]')
LINUX_URL=$(curl -s https://api.github.com/repos/velocidex/velociraptor/releases/latest | jq
-r '[.assets | sort_by(.created_at) | reverse | .[] | .browser_download_url | select(test("linux-amd64$"))][0]')
MACOS_URL=$(curl -s https://api.github.com/repos/velocidex/velociraptor/releases/latest | jq
-r '[.assets | sort_by(.created_at) | reverse | .[] | .browser_download_url | select(test("darwin-amd64$"))][0]')

The above jq filter sorts all asserts by creation data and filters the relevant binaries, then extracts the most recent binary.

Powershell can also be used to download the latest binary for 64 bit Windows as per this example:

#Get the latest entry from the GitHub API
$VeloLatest = Invoke-WebRequest https://api.github.com/repos/velocidex/velociraptor/releases/latest
#Parse out the url to the binary
$VeloURL = ($VeloLatest.content | convertfrom-json).assets.browser_download_url | select-string windows-amd64.exe | select-object -First 1
#Download and write to a file
Invoke-WebRequest -Uri $VeloURL.tostring() -OutFile velociraptor.exe
#Verify the Authenticode Signature
Get-AuthenticodeSignature .\velociraptor.exe

Verifying signatures

Velociraptor releases are signed using Authenticode on Windows as well as using GPG. To verify the signatures using gpg:

$ gpg --verify velociraptor-v0.6.5-2-linux-amd64.sig
gpg: assuming signed data in 'velociraptor-v0.6.5-2-linux-amd64'
gpg: Signature made Wed Jul 27 02:49:33 2022 AEST
gpg:                using RSA key 0572F28B4EF19A043F4CBBE0B22A7FB19CB6CFA1
gpg: Good signature from "Velociraptor Team (Velociraptor - Dig deeper!  https://docs.velociraptor.app/) <support@velocidex.com>" [unknown]
gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner.
Primary key fingerprint: 0572 F28B 4EF1 9A04 3F4C  BBE0 B22A 7FB1 9CB6 CFA1

You may need to import the key first into your keyring:

$ gpg --receive-keys 0572F28B4EF19A043F4CBBE0B22A7FB19CB6CFA1
gpg: key B22A7FB19CB6CFA1: public key "Velociraptor Team (Velociraptor - Dig deeper!  https://docs.velociraptor.app/) <support@velocidex.com>" imported
gpg: Total number processed: 1
gpg:               imported: 1

GitHub limits how many unauthenticated API requests are allowed per IP address. If you need to increase this limit, create a personal access token (see https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)

How can I url/percent decode a string?

Mon, 06 Jun 2022 00:00:00 +0000

How can I url/percent decode a string?

During investigation you may find logs or other data with percent-encoded strings. Since 0.6.5 we have included a lambda function in regex_replace() that enables decode and managing errors to enable analysis.

LET Line = '''http://target/login.asp?userid=bob%27%3b%20update%20logintable%20set%20passwd%3d%270wn3d%27%3b--%00'''

SELECT regex_replace(source=Line, replace_lambda="x=>unhex(string=x[1:]) || x", re="%..") as Decoded FROM scope()

Url Decode: results

Similarly, to URL encode we can run a similar function:

LET Line = '''http://target/login.asp?userid=bob'; update logintable set passwd='0wn3d';--'''

SELECT
    url(path=Line).String[1:] as URLFunction,
    regex_replace(source=Line,replace_lambda="x=>format(format='%%%02x',args=x)", re="[^a-z0-9\\-_.~:/?]") as ManualMethod
FROM scope()

Url Encode: results

How can I make a multipart/form-data POST request in VQL

Sat, 21 May 2022 00:00:00 +0000

How can I make a multipart/form-data POST request in VQL

NOTE: The technique described in this article should no longer be necessary since thehttp_client plugin now supports multipart uploads. However this information may still be useful in certain circumstances and for providing insight into advanced VQL.

VQL can be used to make http requests using the http_client() plugin. While GET requests are usually pretty straight forward, sometimes we need to upload using something called multipart/form-data POST. What is it and how can VQL do this?

What is `multipart/form-data` POST?

This is a standard way of serializing multiple “parts” into a single request. A “part” here is a value of a parameter or usually a file. Traditionally this came from a HTML “form” element, but often these are used for APIs now without a browser interface at all.

The idea is that we define a “boundary” - a special string which is so unique it might not appear accidentally in the data, then we separate the parts using this boundary:

--boundary
Headers

Data
--boundary
Headers

Data
--boundary--

Each part starts with “–” followed by the boundary and a line feed.
Next come the headers which describe things about this part followed by two line feeds.
Next come the body of the part
Finally after the last part, the end is signaled by “–” followed by the boundary and another “–” followed by new line.

The most confusing part of this is that when looking at examples, the boundary is often something like -----------------------------9051914041544843365972754266 making it virtually impossible to see the extra “–” at the start and end (you have to carefully count to realize the boundary header adds two extra dashes!).

Combining in VQL

Anyway once the whole this is demystified it is really easy to create this in VQL. Here is an example:

LET Boundary = "-----------------------------9051914041544843365972754266"

-- A Helper function to make a regular form variable.
LET Data(Name, Value) = format(
  format='--%s\r\nContent-Disposition: form-data; name="%s"\r\n\r\n\r\n%v\r\n',
  args=[Boundary, Name, Value])

-- A Helper function to embed a file content.
LET File(Filename, ParameterName, ContentType, Data) = format(
  format='--%s\r\nContent-Disposition: form-data; name="%s"; filename="%s"\r\nContent-Type: %s\r\n\r\n%v\r\n',
  args=[Boundary, ParameterName, Filename, ContentType, Data])

-- The End boundary signals the last part
LET END = format(format="%s--\r\n", args=Boundary)

-- Now make the HTTP request and post the form
-- Remember the Content-Type header which includes the boundary!
SELECT * FROM http_client(
  method="POST",
  url="http://www.example.com/formhandler",
  headers=dict(`Content-Type`="multipart/form-data; boundary=" + Boundary),
  data=Data(Name="name", Value="Bar") +
       File(Filename="Hello.txt", ParameterName="file_upload", ContentType="text/plain", Data="this is a test") +
       END)

In this example I used some utility functions to make it easier to build the different parts and make sure the encoding structure is always correct.

Applying labels to hunt results

Fri, 20 May 2022 00:00:00 +0000

Applying labels to hunt results

Sometimes it is useful to label clients from a hunt.

For the following example, I will label all machines with rows from the Windows.Carving.CobaltStrike artifact with a label “CobaltStrike”.

SELECT ClientId,Fqdn,Rule,
    label(client_id=ClientId,labels=['CobaltStrike'],op='set') as SetLabel
FROM source(artifact="Windows.Carving.CobaltStrike")
GROUP BY ClientId

Label clients from hunt

How can I quickly reconfigure an offline collector?

Fri, 06 May 2022 00:00:00 +0000

How can I quickly reconfigure an offline collector?

The offline collector is a pre-configured version of Velociraptor that automatically collects certain artifacts when invoked with no command line args.

The offline collector is a full Velociraptor binary that simply has a custom configuration embedded. So you can still use the collector binary to perform any operations that an unmodified Velociraptor binary is capable of.

Usually the collector is built using the GUI by selecting the correct artifacts and injecting parameters into the embedded configuration file. But sometimes we might want to slightly modify the embedded configuration, and firing up a GUI to rebuild a new collector from scratch is a bit too much work.

Here we describe an easy way to quickly modify the embedded configuration, which is suitable for small changes in the embedded configuration. While it is recommended that you use the GUI to prepare a completely new collector, for small tweaks to an existing offline collector this method may be quicker.

Also note that you can override or append command line arguments to those embedded in and offline collector using post-args, which may be sufficient when you want to change the collector behaviour on a once-off basis.

General Method

Assuming you have an existing offline collector named Collector_velociraptor-v0.74.3-windows-amd64.exe:

First extract the existing embedded config from the collector into a local file:

Collector_velociraptor-v0.74.3-windows-amd64.exe config show > config.yaml

Next, edit the config file - for example, you might want to tweak one or two parameters.
Finally, repack the new configuration file into a new collector:

Collector_velociraptor-v0.74.3-windows-amd64.exe config repack config.yaml new_collector.exe

You can verify that the new collector has the modified configuration using new_collector.exe config show.

In the example above the config repack command repacked the collector config into a copy of the binary which invoked the command. This is the default behaviour. If you wish to repack into a different binary then please see the next section.

Also note that the commands above are invoked using the offline collector binary itself, since this is just a normal Velociraptor binary which happens to have an embedded config. This is just for convenience - you could use any Velociraptor binary on any platform to do the config extraction or repacking, provided you also supply it with the target binary that it will use in generating the output file (see next section).

Repacking to a different binary

Repacking the config into a different binary will not transfer any bundled tools to the new binary! This will cause the collection to fail if the offline collector can’t access these tools from an alternative location, such as from a URL defined in the embedded artifacts’ tool definitions. And even if it can download the tool from an external location, you may not want it to.

If your collector uses artifacts which use tools then you should NOT use the method described here. You should instead rebuild your offline collector using the GUI or the CLI collector command.

You can use the --exe flag to specify a different target binary. This allows you to transfer an existing collector config to a different architecture, and/or to a newer binary version. For example:

# from Windows amd64 to i386
velociraptor-v0.74.3-windows-amd64.exe config repack --exe velociraptor-v0.74.3-windows-386.exe config.yaml new_collector.exe

# using Linux to repack a Windows collector
./velociraptor-v0.74.3-linux-amd64 config repack --exe velociraptor-v0.74.3-windows-amd64.exe config.yaml new_collector.exe

Repacking a Generic Collector

The Generic Collector is independent of any binary. It’s essentially a standalone collector config with compression applied. This allows it to be used with any Velociraptor binary since it is external to the binary.

You can unpack the Generic Collector into uncompressed YAML as follows:

First extract the existing embedded config from the collector into a local file:

velociraptor config show --embedded_config Collector_velociraptor-collector > Collector_velociraptor-collector.yaml

Then make minor tweaks if needed, as mentioned above.
And then repack it back into the Generic Collector format using the --exe flag. In this case the “exe” can be any generic collector file including the default “blank” one available on our GitHub Releases page (named velociraptor-collector).

velociraptor config repack --exe velociraptor-collector Collector_velociraptor-collector.yaml new_generic-collector

Even though the velociraptor-collector file is not actually an exe, this works because the generic collector file contains the same embedding section as any Velociraptor binary, so the config repack command recognizes it as a valid binary and therefore allows it as an alternative repacking target.

How can I override the configuration file?

Tue, 26 Apr 2022 00:00:00 +0000

How can I override the configuration file?

Velociraptor relies on the configuration file to control the operation of the server or client. Usually the configuration file is generated interactively using the velociraptor config generate -i command.

Many people want to automate the configuration generation or override the configuration in some way. This short tip covers some of the common ways to do that.

Automating configuration generation.

When generating a new configuration, Velociraptor will generate new key material and create a reasonable skeleton for the supported deployment scenario. In the following command, Velociraptor will emit a basic configuration file template to standard output, which can be easily redirected to a file:

$ velociraptor-v0.6.4-linux-amd64 config generate > /tmp/config.yaml

To customize the generated configuration we can apply a JSON merge/patch step. JSON merge and JSON patch are standard ways of specifying a transformation on a JSON object.

Normally the configuration file is in YAML but you can also view it in JSON using the --json flag to the config show command:

velociraptor --config config.yaml config show --json

Since YAML is a superset of JSON you can also provide this JSON blob to Velociraptor as the actual configuration (no need to convert it back to YAML). This helps to prepare the JSON merge patch - simply remove the fields you dont want to change and change the fields you do want to change.

For example, imagine we want to specify a new URL for clients to connect to. We can merge the following JSON blob with the config:

$ velociraptor --config /tmp/config.yaml config show --merge '{"Client":{"server_urls":["https://192.168.1.11:8000/", "https://192.168.1.12:8000/"]}}' > /tmp/new_config.yaml

It may be more convenient to store the JSON merge blob in a file instead of specifying on the command line - use the --merge_file option to provide it.

Overriding configuration at runtime

While the config show command can be used to manipulate the configuration file, sometimes we want to change a few values at runtime on a temporary basis.

Overriding configuration via command line flags

Velociraptor allows most configuration settings to be overriden by suitable command line flags. Since there are so many flags, the usual help shown with the --help flag does not include these configuration overriding flags.

You can see all the defined flags by enabling the DEBUG environment variable:

$ DEBUG=1 ./velociraptor --help

...
  --config.client-writeback-darwin=CONFIG.CLIENT-WRITEBACK-DARWIN
  --config.client-writeback-linux=CONFIG.CLIENT-WRITEBACK-LINUX
  --config.client-writeback-windows=CONFIG.CLIENT-WRITEBACK-WINDOWS
  --config.client-tempdir-linux=CONFIG.CLIENT-TEMPDIR-LINUX
  --config.client-tempdir-windows=CONFIG.CLIENT-TEMPDIR-WINDOWS

This is useful to override specific settings temporarily - for example when running the server in a cloud environment, the bind port is determined by the platform. In this case it is easier to simply override this on the command line rather than manipulate the config file.

velociraptor --config /etc/velociraptor/server.config.yaml frontend --config.frontend-bind-port=$PORT

How can I save my favorite collections for the future?

Tue, 26 Apr 2022 00:00:00 +0000

How can I save my favorite collections for the future?

Sometimes we tend to collect the same set of artifacts together, possibly with some specific parameters. It gets tedious to constantly reconfigure the New Collection interface with the same set of artifacts.

This where the favorites feature comes in. We can save existing collections including the artifacts collected and their parameters. Then in future we just need to restore our collections from our favorites.

Saving a collection as a favorite

The favorite can be restored in future by simply adding a new collection, clicking the favorite button and searching for it.

Restoring a favorite collection

Creating favorites programmatically

Favorites are stored into the user’s profile, since each user might have a different set of artifacts they normally use.

You can see your own favorites using the favorites_list() plugin. The below query will produce serialized spec strings that may be fed directly into favorites_save() below.

SELECT name, description, type, serialize(item=spec) AS Spec
FROM favorites_list()

It is possible however to create favorites using VQL with the favorites_save() function:

SELECT favorites_save(type="CLIENT", name="MyFavorite",
specs='''
[{"artifact":"Windows.Search.FileFinder",
  "parameters": {
    "env": [{
        "key": "SearchFilesGlob",
        "value": "HKEY_USERS/*/Software/Sysinternals/*/*"
    }, {
        "key": "Accessor",
        "value": "registry"
    }]}}]''')
FROM scope()

Note the spec parameter is a JSON encoded blob of the various artifact parameters.

By including the VQL in a notebook, any user can collect it and install the favorites in their own profile.

Applying favorites to other users

The above example showed how to programmatically set favorites in one’s own user profile, but sometimes we want to apply the favorites in other user’s profile as well. This helps to establish a common set of artifacts for the entire team.

To set other user’s favorites, you will need to be an administrator with the impersonation permission, and run the above query in the user’s context:

SELECT * FROM foreach(row={

    -- Iterate over all users in the current org
    -- (use all_org=TRUE to iterate over all users).
    SELECT * FROM gui_users()

}, query={

   -- Run this query in its own scope.
   -- Runas will switch to that user.

   SELECT * FROM query(runas=name, query={

        -- Here is the original query to be run in
        -- the user's context - same as above.
        SELECT favorites_save(type="CLIENT", name="MyFavorite",
        specs='''
        [{"artifact":"Windows.Search.FileFinder",
          "parameters": {
            "env": [{
                "key": "SearchFilesGlob",
                "value": "HKEY_USERS/*/Software/Sysinternals/*/*"
            }, {
                "key": "Accessor",
                "value": "registry"
            }]}}]''')
        FROM scope()
   })
})

How to fix "certificate has expired or not yet valid error"?

Tue, 26 Apr 2022 00:00:00 +0000

How to fix “certificate has expired or not yet valid error”?

When Velociraptor generates a configuration file it also generates some certificates to secure it’s internal PKI.

The CA certificate is embedded in the client’s configuration file and underpins the entire Velociraptor communications protocol - all certificates are issued by this internal CA. The Velociraptor CA is set to expire in 10 years.

The Server certificate is signed by the CA certificate and is set to expire in 1 year by default. When the certificate expires, clients will be unable to connect to the server any more.

You can check the expiry time of the server certificate using curl and openssl:

$ curl -s -k https://127.0.0.1:8000/server.pem | openssl x509 -text  | grep -A 2 Validity
Validity
   Not Before: Apr 13 12:05:46 2022 GMT
   Not After : Apr 13 12:05:46 2023 GMT

What happens when the certificate expires?

When the internal server certificate expires clients will not accept it and they will refuse to communicate. Clients will show as offline in the GUI and buffer data as long as possible, subject to their configured buffer limits.
New GUI sessions will fail with “500 Internal Server Error” and the response body {"code":2,"message":"Must set a username"} and fail to load.

For Velociraptor versions 0.74 and later there is a mechanism to mitigate the impact of unexpected certificate expiry:

Upon restarting the server service, if the certificate (Frontend.certificate) has expired, and if the server.config.yaml contains the CA private key then it will automatically issue a new cert with the same validity period as the expired one. This temporary certificate is held in memory only and is NOT written to the server.config.yaml.
In the server log you will see the following messages:

[ERROR] <log_date> Frontend Certificate is not valid: Certificate Valid NotBefore <start_date> and Not After <end_date> but Now is <current_date>. See https://docs.velociraptor.app/knowledge_base/tips/rolling_certificates/
[INFO] <log_date> Found CA private key in config, will automatically rotate keys, but you should consider updating the config file using `velociraptor config rotate`

If this is the case you should update your server certificate by reissuing a new one.

Rotating certificates

Reissuing a new server certificate can be performed at any time using the config reissue_certs command. You can even reissue a certificate with extended validity before you deploy your server.

The procedure amounts to generating a new server configuration which is derived from the old one, and then replacing the old config with the new config.

The config rotate_keys command can be used to regenerate both the server certificate and the associated private key. Although this is not necessary for operational purposes, it is considered good security practice to rotate keys and certificates periodically, and particularly after a suspected systems compromise.

For server versions older than 0.72.3 please use the following commands instead of those shown below:

Goal	Command for the current version	Command for versions <0.72.3
Reissue only the server cert	`velociraptor config reissue_certs`	`velociraptor config reissue_key`
Reissue the server cert and also the private key	`velociraptor config rotate_keys`	`velociraptor config rotate_key`

Setting a non-standard validity

When reissuing the certificate the --validity flag can be used to extend the validity beyond the default of one year. For example, to generate a config containing a server certificate which is valid for 2 years, you would run the command:

velociraptor --config server.config.yaml config reissue_certs --validity 730  > new.server.config.yaml

If you expect your server to be a long-term instance then you don’t have to start with the default 1-year validity and wait for the certificate to expire. You can generate a new config on day 1 based on the initial config using the config reissue_certs command. You can then use the new config for the new server installation.

In version 0.74 and later the configuration wizard (velociraptor config generate -i) allows you to issue the server certificate with either 1-year, 2-year or 10-year validity.

Option 1: Reissue only the server cert

To rotate server certificates, use the following command to generate a new configuration file containing rotated certificates:

$ velociraptor config reissue_certs --config /etc/velociraptor/server.config.yaml > /tmp/new_key.config.yaml

The config reissue_key command updates the following configuration items:

GUI.gw_certificate
Frontend.certificate

CA.private_key, Client.ca_certificate, GUI.gw_private_key, and Frontend.private_key are preserved.

Option 2: Reissue the server cert and also the private key

Alternatively, you can regenerate the server’s private keys and rotate the certificates at the same time:

$ velociraptor config rotate_keys --config /etc/velociraptor/server.config.yaml > /tmp/new_key.config.yaml

The config rotate_keys command updates the following configuration items:

GUI.gw_certificate
GUI.gw_private_key
Frontend.certificate
Frontend.private_key

CA.private_key and Client.ca_certificate are preserved.

The previous two commands will not affect the CA private key and certificate, which is valid for 10 years, as described previously.

You can view the new certificate using jq and openssl (here jq is used to show the PEM certificate of the frontend and openssl is used to decode it)

$ velociraptor --config /tmp/new_key.config.yaml config show --json | jq -r .Frontend.certificate | openssl x509 -text  | grep -A 2 Validity
Validity
   Not Before: Apr 25 21:01:51 2022 GMT
   Not After : Apr 25 21:01:51 2023 GMT

Now back up the old configuration file and replace it with the new file, then restart the server. Clients should reconnect automatically.

How to initialize a Velociraptor server with custom artifacts?

Tue, 26 Apr 2022 00:00:00 +0000

How to initialize a Velociraptor server with custom artifacts?

Velociraptor frontend process has a component called the Artifact Repository. This component knows about all the artifacts that are defined.

When the server starts up, it loads artifacts into the repository from the following sources.

Built-in artifacts that are embedded into the binary itself (compiled in).
Custom artifacts that are defined inside the configuration file itself.
Directories containing artifact YAML files that can be defined in one or more of the following ways:
- specified by the --definitions CLI flag: a single directory
- specified by Frontend.artifact_definitions_directory in the config: a single directory.
- specified by defaults.artifact_definitions_directories in the config: a list of directories.
Velociraptor will search these directories recursively for artifact YAML files.
Finally, the server will load artifacts from the configured filestore path under <filestore>/artifact_definitions. These are usually the custom artifacts defined through the GUI.

The location of where an artifact came from does not matter, Velociraptor organizes artifacts internally using the artifact name. It is customary to denote custom artifacts with the Custom. prefix but this is not mandatory.

Velociraptor does not allow a custom artifact to override a built in artifact (i.e. have the same name). Built in artifacts are protected because overriding built in artifacts may break the proper functionality of Velociraptor. If you want to customize a built in artifact, simply change the name when you save it.

Velociraptor considers artifacts defined in the config file, or given in the --definitions directory as “built in”.

Specifying a startup artifact.

When the Velociraptor server is run for the very first time, it creates an install record in the filestore <filestore>/config/install_time.json.db. It can then setup initial artifacts to collect as specified by the config file:

Frontend:
  default_client_monitoring_artifacts:
  - Generic.Client.Stats
  initial_server_artifacts:
  - MyServerArtifact
  default_server_monitoring_artifacts:
  - MyCustomServerMonitor

In the above snippet, we see the following parameters:

default_client_monitoring_artifacts specifies the initial client monitoring table that will be created. By default, Velociraptor collects endpoint CPU and Memory telemetry from all endpoints. You can remove this, or specify a different client artifact to collect.
default_server_monitoring_artifacts specifies an initial set of server event artifacts to collect.
initial_server_artifacts is a list of server artifacts that will be automatically launched on the server on initial startup. You can specify the names of any artifacts here (including custom artifacts) which can be bootstrapped to perform any kinds of server configuration needed. The artifacts are simply scheduled and will appear in the usual Server Artifacts screen.

Currently it is not possible to specify parameters for initial artifacts so if you need to tweak the parameters it is best to create a custom artifact that in turn launches the needed artifacts with the correct parameters. You can find an example below.

Initializing the server using a custom artifact.

For more complex initialization tasks you can write a custom artifact that will be collected the first time the server is started. The artifact can import any custom artifacts and start monitoring queries. The custom artifact should take no arguments. It is most reliable to add the custom artifact to the configuration file itself to ensure it is loaded and ready when the server initializes.

For example, the relevant part of the server configuration might be:

autoexec:
  artifact_definitions:
    - name: InitializeServer
      description: Setup the server on first run
      sources:
        - query: |
            LET _ <= SELECT *
                     FROM Artifact.Server.Import.CuratedSigma()

            SELECT add_client_monitoring(
                      label="Monitoring",
                      artifact="Windows.Hayabusa.Monitoring",
                      parameters=dict(RuleLevel="Critical, High, and Medium",
                                      RuleStatus="Stable")) AS Monitoring,
                  artifact_set_metadata(name="InitializeServer", hidden=TRUE)
            FROM scope()

Frontend:
  initial_server_artifacts:
    - InitializeServer

The above parts:

An artifact is defined inline in the config file.
The artifact imports the Sigma artifacts from the velociraptor sigma projects (you can add your own URLs to import your own set of custom artifacts).
A client monitoring artifact is added using the Hayabusa Sigma artifact targeting the “Monitoring” label. Parameters to the artifact are passed here.
Finally the server is configured to collect the InitializeServer artifact when first run.

What do I do about "version GLIBC_2.xx not found" errors?

Tue, 26 Apr 2022 00:00:00 +0000

What do I do about “version GLIBC_2.xx not found” errors?

Use the musl built binary for older Linux systems. You can find this build together with the others on the release page with the -musl suffix in the name.

On Linux, binaries always link to the C library dynamically. This happens even with a static binary like Velociraptor. The C library is intimately linked to the version of Linux installed on the system and it is generally not possible to upgrade the C library without also upgrading the entire Linux distribution.

During the build process, the compiler creates a version requirement for this C library embedded in the binary itself. You can see the exact version of all libraries needed at runtime using the read_elf program:

$ readelf -V velociraptor-v0.6.4-linux-amd64
...
Version needs section '.gnu.version_r' contains 3 entries:
 Addr: 0x00000000004106a0  Offset: 0x0106a0  Link: 7 (.dynstr)
   000000: Version: 1  File: libdl.so.2  Cnt: 1
   0x0010:   Name: GLIBC_2.2.5  Flags: none  Version: 10
   0x0020: Version: 1  File: libpthread.so.0  Cnt: 2
   0x0030:   Name: GLIBC_2.3.2  Flags: none  Version: 6
   0x0040:   Name: GLIBC_2.2.5  Flags: none  Version: 5
   0x0050: Version: 1  File: libc.so.6  Cnt: 8
   0x0060:   Name: GLIBC_2.11  Flags: none  Version: 12
   0x0070:   Name: GLIBC_2.7  Flags: none  Version: 11
   0x0080:   Name: GLIBC_2.14  Flags: none  Version: 9
   0x0090:   Name: GLIBC_2.15  Flags: none  Version: 8
   0x00a0:   Name: GLIBC_2.4  Flags: none  Version: 7
   0x00b0:   Name: GLIBC_2.3.4  Flags: none  Version: 4
   0x00c0:   Name: GLIBC_2.2.5  Flags: none  Version: 3
   0x00d0:   Name: GLIBC_2.3  Flags: none  Version: 2

In the above example this binary requires at least GLIBC_2.15 to run. You can tell what version of libc you have on any particular system using the local package manager.

$ dpkg -l libc6:amd64
Desired=Unknown/Install/Remove/Purge/Hold
| Status=Not/Inst/Conf-files/Unpacked/halF-conf/Half-inst/trig-aWait/Trig-pend
|/ Err?=(none)/Reinst-required (Status,Err: uppercase=bad)
||/ Name           Version       Architecture Description
+++-==============-=============-============-=================================
ii  libc6:amd64    2.33-0ubuntu5 amd64        GNU C Library: Shared libraries

In this case this system has GLIBC version 2.33 which is higher than the minimum required version of 2.15.

However for older systems, the locally installed GLIBC may be older than required. This results in an error when we attempt to run it. For example on an old CentOS 6 system:

$ ./velociraptor-v0.6.4-linux-amd64
./velociraptor-v0.6.4-linux-amd64: /lib64/libc.so.6: version `GLIBC_2.14' not found (required by ./velociraptor-v0.6.4-linux-amd64)
./velociraptor-v0.6.4-linux-amd64: /lib64/libc.so.6: version `GLIBC_2.15' not found (required by ./velociraptor-v0.6.4-linux-amd64)

Since the version requirement is added at build time, we really need to build on an old system to ensure the linked to GLIBC is old enough.

Velociraptor uses the musl project to build completely static binaries independent of the GLIBC installed on the system. While this feature is considered experimental it seems to work well and produces truly portable binaries.

We recommend that version to only be used for clients on older systems, although it might also work for a server too (but really you should be running servers on modern patched systems).

How do I search for registry keys

Mon, 25 Apr 2022 00:00:00 +0000

How do I search for registry keys

To search the registry simply use the “registry” accessor with the Windows.Search.FileFinder artifact.

This works because Velociraptor can glob the registry as if it were a filesystem (See Filesystem Accessors

Searching the registry

How do I use my own SSL certificates?

Mon, 18 Apr 2022 00:00:00 +0000

How do I use my own SSL certificates?

Use case: For an on-premises deployment, Let’s Encrypt may not be an option. You may want to use your own enterprise/corporate Certificate Authority (CA) or another 3rd party.

Thanks to recent enhancements by the Velociraptor developers, this is quite a simple task. The below is a simple test configuration used and may need adapting to your environment.

Prior to commencing we have a plaintext PEM private key, certificate for our Velociraptor server, and the certificate chain of our enterprise CA, including the root and multiple intermediaries.

Generate the configuration

Using Ubuntu we generated a stock standard “Self-signed SSL” configuration:

./velociraptor-v0.6.3-2-linux-amd64 config generate -i

Update the server.config.yaml

Locate the frontend section and add the tls_certificate_filename and tls_private_key_filename parameters. Enter the absolute path to these files. For testing, we placed in /etc however there are better places for production use.

Frontend:
  tls_certificate_filename: /etc/velociraptor.pem
  tls_private_key_filename: /etc/velociraptor.key

Update the client.config.yaml

In the client section modify use_self_signed_ssl to be false, and add the CA root/intermediary certificates to be trusted by the client:

use_self_signed_ssl: false

Crypto:
    root_certs: |
          -----BEGIN CERTIFICATE-----
          XXXXX
          -----END CERTIFICATE-----
          -----BEGIN CERTIFICATE-----
          XXXXX
          -----END CERTIFICATE-----
          -----BEGIN CERTIFICATE-----
          XXXXX
          -----END CERTIFICATE-----
          ...

Test

Launching the server we should be able to connect to the GUI using our new certificate. Note this must be trusted by browser/system to prevent errors.

Launching the client, it should connect securely without error, using the trusted CA chain and the new server certificate.

No changes need to be made to the pinned certificate name, nor do any certificates need to be modified in the configuration files.

How do I set a proxy for client communications?

Fri, 15 Apr 2022 00:00:00 +0000

How do I set a proxy for client communications?

Many enterprise environments require a proxy to be set before outbound web communications is allowed. The Velociraptor client uses HTTP to communicate with the server, and therefore must use a proxy to connect in such environments.

It is possible to specify the HTTP proxy using the configuration file or environment variables.

Environment variables.

Environment variables may be configured using group policy or similar methods. Setting the http_proxy and https_proxy environment variables will force the client to go through the specified proxy.

The rules for environment variables are described here:

// ProxyFromEnvironment returns the URL of the proxy to use for a
// given request, as indicated by the environment variables
// HTTP_PROXY, HTTPS_PROXY and NO_PROXY (or the lowercase versions
// thereof). HTTPS_PROXY takes precedence over HTTP_PROXY for https
// requests.
//
// The environment values may be either a complete URL or a
// "host[:port]", in which case the "http" scheme is assumed.
// The schemes "http", "https", and "socks5" are supported.
// An error is returned if the value is a different form.

Setting a proxy in the configuration file

You can also hard code the proxy in the configuration file’s Client section:

Client:
  proxy: http://proxy.example.com:3128/
  server_urls:
  - https://velo.example.com:8100/

How to increase notebook timeout

Tue, 29 Mar 2022 00:00:00 +0000

How to increase notebook timeout

In the notebook, VQL queries are limited to 10 minutes. Once the timeout is expired, the query is cancelled. Regular collections from clients also have a timeout, that timeout can be changed in the new collection wizard GUI to give the query more time.

But there is no similar control for the notebook cells. In the notebook, the time limit serves to limit server load - because the notebook queries are run on the server we don’t want them to take too long or make it too easy to extend the timeout too long.

If you find that your cell query is routinely exceeding the timeout, you can use one of the following approaches:

Make the query more efficient - for example using multi-threaded queries or the parallelize() plugin.
Turn the query into a server artifact. Large queries are often very reusable and if you can turn it into an artifact, it might be useful again. Running a server artifact allows the timeout to be increased if needed.
As a last resort update the default notebook timeout in the configuration file. Find or add the section called defaults and add the following setting:

Frontend:
... other settings ...
defaults:
    notebook_cell_timeout_min: 20

How do I upgrade my server and clients?

Sun, 27 Mar 2022 00:00:00 +0000

How do I upgrade my server and clients?

To upgrade the Velociraptor server to a new version, simply download the latest release binary from the GitHub Release Page and regenerate a new Debian package as described above, but using the existing configuration file.

See this page for more details

To upgrade the Velociraptor clients, you will need to push out new MSIs using the existing client configuration files.

More details on Client upgrades

Supported Upgrade Scenarios

Matching client and server versions is the most supported configuration. See the support policy

Before upgrading perform testing of the combination of client and server versions to be used, compatibility of mixed versions is best efforts based on community testing and issues being reported.

Check GitHub for issues reported by the community.
Read release notes for all versions between the current version, and the version you are moving to if skipping versions. Generally though avoid skipping versions.

Other tips

Recent versions of clients and servers generally can communicate with each other without a problem, but new functionality may not be available on old clients. Artifacts like this will (0.6.4+) help reduce this.
Upgrading the server before clients is more common, so version problems are more likely to have been caught in community testing with this approach.
Consider running a parallel deployment as the most compatible way to upgrade. Such as when upgrading and there are known breaking changes between the current client and target server versions (going from self-signed to auto cert), or when there are large version differences (unusual combinations of client and server).

In VQL, can I SELECT a column with special characters in its name?

Sun, 27 Mar 2022 00:00:00 +0000

In VQL, can I SELECT a column with special characters in its name?

Sometimes a VQL query will emit a column name with special characters in its name, such as a dot, space or other special characters.

You can still refer to this column using backticks around the identifier name:

-- This will not work because VQL will interpret the dot as an operator
SELECT Raddr.IP FROM ...

-- This will work because VQL will treat the entire thing as a single identifier
SELECT `Raddr.IP` FROM ...

You can read more about VQL identifiers

How can I automatically apply labels to clients?

Sat, 26 Mar 2022 00:00:00 +0000

How can I automatically apply labels to clients?

Labels are used to target clients in Velociraptor. All clients that share a particular label can be treated as a group in common operations such as hunts and client monitoring. Labels can also be used to search for and filter clients in the GUI and in VQL queries.

Sometimes it is useful to automatically label clients based on some property of the client or the results of a collection. You can do this by running a Server Event artifact which automatically applies labels based on some criteria that you define.

In this article we demonstrate two use cases: a basic and a more advanced one.

It’s important that you choose the appropriate one for your use case. This article is about automating Labels but if you want to do similar automation of Metadata then you may find this article more useful: How can I automatically add & update client metadata?

Basic Use Case: Labelling based on default interrogation data

We can watch the system for any new collections of Generic.Client.Info and apply labels based on the results.

The following example will label a client with the label “Server” if it is running any kind of Windows Server Operating System.

LET interrogations = SELECT *
  FROM watch_monitoring(artifact="System.Flow.Completion")
  WHERE Flow.artifacts_with_results =~ "Generic.Client.Info/BasicInformation"

LET results = SELECT *, ClientId
              FROM source(
                 artifact="Generic.Client.Info/BasicInformation" ,
                 client_id=ClientId, flow_id=FlowId)
              WHERE Platform =~ "Server"

SELECT *, label(client_id=ClientId, labels="Server", op="set")
FROM foreach(row=interrogations, query=results)

The interrogations query will watch for any flow completion with results for the Generic.Client.Info/BasicInformation source. This will provide the flow id and the client id.
The results query will read all the results from the collection. Typically the Platform field will contain the Windows Release information. We filter out all rows except those that match the word “Server” to only see results from the Windows Server platform.
Finally for each interrogation we get the results and finally “set” the label “Server” on the client id.

Now that we have the VQL worked out, we just package it in a SERVER_EVENT artifact.

name: AutomateServerLabels
type: SERVER_EVENT
sources:
- query: |
    LET interrogations = SELECT *
    FROM watch_monitoring(artifact="System.Flow.Completion")
    WHERE Flow.artifacts_with_results =~ "Generic.Client.Info/BasicInformation"

    LET results = SELECT *, ClientId
    FROM source(
       artifact="Generic.Client.Info/BasicInformation" ,
       client_id=ClientId, flow_id=FlowId)
    WHERE Platform =~ "Server"

    SELECT *
    label(client_id=ClientId, labels="Server", op="set")
    FROM foreach(row=interrogations, query=results)

Adding a new artifact

Now we can enable monitoring of these events by adding the artifact to the server event table.

Installing server event monitoring

Now when a new server enrolls the label “Server” will be applied.

Note that we don’t need to add a label for non-servers (i.e. “workstations”) because targeting a hunt, for example, allows us to exclude specific labels.

Label added

The above artifact will automatically label clients when the Generic.Client.Info collection is run on the clients. This collection runs when the client is first seen but you can run it at any time.

To relabel all clients - even after they were enrolled - you can just start a hunt for Generic.Client.Info at any time. It is fine to re-apply the label many times as duplicate labels cannot occur.

Bulk removal of a specific label is possible by running VQL in a notebook, for example:

SELECT client_id, label(client_id=client_id, labels=["Server"], op="remove")
FROM clients()

Advanced Use Case: Labelling based on custom interrogation data

In the previous example we used data that was already being gathered by the Generic.Client.Info artifact. In addition, the Platform information doesn’t ever change, so every time you run it you will get the same result. That’s a bit boring, so let’s do something more interesting!

Let’s look at applying a label based on data that isn’t included in the default interrogation artifact, and that is dynamic (i.e. where the outcome will change over time). Here we will use a Sigma rule from the Hayabusa Rules ruleset.

In order for this to work you’ll need to have already imported the “Velociraptor Hayabusa Ruleset” by running the Server.Import.CuratedSigma server artifact on your server. To learn more about Sigma rules in Velociraptor see this page.

Running Server.Import.CuratedSigma

The Sigma rule we will be using in this example is Windows Defender Threat Detected.

When interrogation happens on the client we want it to also check whether Windows Defender has detected any threats in the past 24 hours. This may be a somewhat contrived example but it (or something similar) may also have realworld usefulness in some scenarios, like for example: if you are rolling out Velociraptor clients in response to an incident. It may be useful to have endpoints flagged based on recent Defender detections to aid with triage.

As explained here, the default interrogation artifact can be overridden with a custom version. If such a custom artifact is present on the Velociraptor server then all clients will use it.

When creating our custom version, we want to modify the default artifact as little as possible, as advised in the artifact’s description, so we are only going to add a new source to it: one which calls the Windows.Hayabusa.Rules artifact.

We do this by editing the default Generic.Client.Info artifact. By default the name of the edited artifact will be Custom.Generic.Client.Info which is exactly what we want it to be.

In the custom version we add a new source after the existing ones (around line 115 in the current default artifact):

  - name: RecentDefenderDetections
    precondition: SELECT OS From info() where OS = 'windows'
    query: |
      LET past_day <= timestamp_format(time=now() - 86400)
      SELECT *
      FROM Artifact.Windows.Hayabusa.Rules(RuleLevel="All",
                                           RuleStatus="All Rules",
                                           RuleTitleFilter="Windows Defender Threat Detected",
                                           DateAfter=past_day)

If we now run an interrogation manually on a Windows client where we have deliberately triggered a detection using the EICAR test file, we see that the Sigma rule has run and that the detection has been included in the collection results.

Manual interrogation test

We have now extended our interrogation data with something more dynamic than in the first example. The remaining steps are essentially the same except that we are monitoring a different source and adding a different label.

We add a new SERVER_EVENT artifact:

name: LabelRecentDefenderDetections
type: SERVER_EVENT
sources:
- query: |
    LET interrogations = SELECT *
    FROM watch_monitoring(artifact="System.Flow.Completion")
    WHERE Flow.artifacts_with_results =~ "Custom.Generic.Client.Info/RecentDefenderDetections"

    SELECT *,
    label(client_id=ClientId, labels="Recent Threat Detection", op="set")
    FROM interrogations

This artifact is slightly simpler than the one in the previous example because we don’t need to check for any specific value in the results. If the results contain any rows then we want the label to be applied. Of course you could make it more sophisticated if you wanted.

Lastly we add the artifact to the server event table as we did with the first example.

Installing server event monitoring

Now the interrogation of any Windows client will also check the Windows Defender logs and if a threat was logged in the past 24 hours the client will be labelled “Recent Threat Detection”.

Label added!

As with the basic use case you can force all clients to re-run this check by creating a hunt for the Custom.Generic.Client.Info artifact.

How can I configure Velociraptor for multiple SSO providers

Sat, 26 Mar 2022 00:00:00 +0000

How can I configure Velociraptor for multiple SSO providers

Velociraptor can be configured to use a single SSO provider using the usual configuration building wizard (see Here), but the wizard does not offer to configure multiple providers.

Sometimes we want to have multiple providers so we can allow users from another organization to be able to log into Velociraptor. To do this we need to configure the SSO authenticator manually in the configuration file.

Simply run velociraptor config generate -i and select the OAuth provider for the first provider. In the end your config file will have the following section where oauth_client_id and oauth_client_secret refer to the Google OAuth app you created:

GUI:
  ... more settings ...
  authenticator:
    type: Google
    oauth_client_id: 12345.apps.googleusercontent.com
    oauth_client_secret: XYZ1234

To provide multiple authenticators, you will need to manually change to the multi authenticator type:

GUI:
  ... more settings ...
  authenticator:
    type: multi
    sub_authenticators:
     - type: Google
       oauth_client_id: 12345.apps.googleusercontent.com
       oauth_client_secret: XYZ1234
     - type: GitHub
       oauth_client_id: 123456
       oauth_client_secret: 76521376523
     - type: oidc
       oidc_issuer: https://accounts.google.com
       oidc_name: Rapid7
       avatar: https://example.com/avatar.png
       oauth_client_id: XXXXX
       oauth_client_secret: AAAAA

Note that you can have multiple OIDC authenticators and each can have a separate name and an icon associated with it (e.g. if multiple organizations use separate Okta logins).

Logging in with multiple providers

Granting a user a role.

Velociraptor will trust any of the configured authenticators, to identify the user and based on the username, grant the user the appropriate roles on the Velociraptor server. You will need to grant the user a role either through the command line:

velociraptor user add --role administrator mike@gmail.comm

Or via a notebook cell:

SELECT user_create(user="mike@gmail.com", role="administrator")
FROM scope()

Be aware that trusting multiple identity providers can result in account hijack if a user can get an account of the same name on another provider. Velociraptor just uses the account name provided by the OAuth provider to grant access and does not keep track of which provider actually identified the user.

In simple terms, if a user has username “mike” on OIDC provider 1 and another user can get say a GitHub account for the user “mike”, then the second user can impersonate the first user by logging in with the second provider.

How do I debug the client while it is running?

Mon, 21 Mar 2022 00:00:00 +0000

How do I debug the client while it is running?

Sometimes we collect artifacts from clients but for some reason things seem to take longer than expected. Velociraptor has mechanisms to gain visibility into how clients behave and what queries are running.

Query logs

The first port of call is viewing the query logs in the logs tab of the relevant collection.

Viewing the query logs

As the query is running, it will emit a message to let us know that it is waiting for rows. We use this to determine that the query is still running on the client.

Collecting profiles

The Generic.Client.Profile artifact allows us to collect internal state of the client. Simply collect this from the client, while other queries are running

Client Profile

The most common thing to collect include:

The Goroutine dump shows a stack trace of all currently running goroutines (similar to threads). This helps us understand if there is a deadlock or another bug.
The logs delivers a recent dump of client logs. Normally the client does not write it’s logs to file to avoid information leakage issues. You can see the logs on the console by running the client with the -v flag, but each client also keeps the last 1000 messages in a memory buffer so they can be available if needed. This option sends the recent logs to the server.
Query logs are a recent log of VQL queries running on the endpoint. This gives us an idea of exactly what the client is doing.
Metrics are internal program counters that provide visibility of performance related items.

When asking for help on Discord or our mailing list, we will often ask for the profiles collected from the client (or server). At a minimum we will need the above items to diagnose any issues.

The nice thing about collecting profiles is that the client does not need to be restarted and we do not need to run a special debug build - all clients are capable of collecting profile information at any time.

References

You can read more about profiling Velociraptor here.

How do I deploy the client as agentless (without install)?

Mon, 21 Mar 2022 00:00:00 +0000

How do I deploy the client as agentless (without install)?

Sometimes we need to deploy Velociraptor in an IR and can not install it permanently as a service.

Windows Environments

It is possible to deploy the client using Group Policy by using Scheduled task feature to cause domain connected machines to run the client. See details here.

The first step is to place the client and the generated client.config.yaml on a public read only windows share.
Update the config file’s writeback location to somewhere writable on the client (e.g. C:\Windows\Temp\velo.writeback.yaml)
Next create a Scheduled Task in a new group policy object that applies to the relevant OU.
The scheduled task should be launched as NT_AUTHORITY\SYSTEM from the read only share. With the appropriate command line. For example:

\\dc\deployment\velociraptor.exe --config \\dc\deployment\client.config.yaml client --mutant MyVeloName

Window’s Group Policy allows setting only a single instance of the program to run at the time, however we found in practice this is not reliable and sometimes GPO will launch dozens of copies of Velociraptor over time. To avoid this we use the --mutant flag which will exit if a mutant of this name already exists.

Linux Environments

Systemd

It is possible to execute a program in a “transient scope”, which enables it to be controlled and inspected just like a regular service (unit) in Linux, without the need to create persistent configurations. Using systemd-run the process will be executed and its parent will be the init process, and will not terminate until the host is rebooted.

To execute the Velociraptor binary run the following:

systemd-run -u velociraptor_tmp /tmp/velociraptor.bin client --config /tmp/client.config.yaml

Once the service is running, you should now be free to terminate the SSH / management session without terminating the process.

You can manually terminate the service with: systemctl stop velociraptor_tmp.service

You can check it’s status with: systemctl status velociraptor_tmp.service

On Linux /tmp is cleaned up by a service, which gets triggered on shutdown. You will need to arrange for the Velociraptor binary and configuration file to be transferred again if the host reboots.

You can read more about the systemd-run here for flags etc: https://www.freedesktop.org/software/systemd/man/systemd-run.html