Velociraptor API client and command line tool

Command line tool

Features:

• server-side query: Subcommand query
• client-side shell commands, like
  • VQL query: client <client-id> query
  • Bash: client <client-id> bash
  • Cmd.exe: client <client-id> cmd
  • Powershell: client <client-id> powershell
• result file downloads: Subcommend fetch

Simple help is available for all commands.

The main purpose of this tool is as a building block for VQL development and test workflows that are organized around a text editor instead of Velociraptor's web interface.

Configuration

The client needs an API key file that can be generated by running

velociraptor config api_client

on the server.

This file should be named apiclient.yaml and be placed into the configuration directory:

• Unix: $XDG_CONFIG_HOME/velociraptor or $HOME/.config/velociraptor
• MacOSX: $HOME/Library/Application Support/velociraptor
• Windows: %userprofile%\AppData\Roaming\velociraptor

If API keys for multiple server or profiles are needed, the should be named apiclient-$INSTANCE.yaml; they can be selected using the --instance parameter.

The apiclient.yaml file is expected to have the following shape:

ca_certificate: |
  -----BEGIN CERTIFICATE-----
  ...
  -----END CERTIFICATE-----
client_cert: |
  -----BEGIN CERTIFICATE-----
  ...
  -----END CERTIFICATE-----
client_private_key: |
  -----BEGIN RSA PRIVATE KEY-----
  ...
  -----END RSA PRIVATE KEY-----
api_connection_string: velociraptor-server.example:8001
name: velouser

Ad-hoc VQL queries

The output of server-side and client-side VQL queries consists pretty-printed JSON, suitable for post-processing by tools such as jq. For example:

$ velociraptor-client --instance test client C.02749d29d382534f query 'select * from info()'
[
  {
    "Architecture": "amd64",
    "BootTime": 1684997214,
    "ClientStart": "2023-05-25T22:29:21.525425229Z",
    "CompilerVersion": "go1.20.3",
    "Exe": "/usr/local/bin/velociraptor_client",
    "Fqdn": "foo",
    "HostID": "76dabd94-de78-4ab6-884a-ac63e38424aa",
    "Hostname": "foo",
    "IsAdmin": true,
    "KernelVersion": "5.14.21-150400.24.60-default",
    "OS": "linux",
    "Platform": "opensuse-leap",
    "PlatformFamily": "suse",
    "PlatformVersion": "15.4",
    "Procs": 98,
    "Uptime": 12057434,
    "VirtualizationRole": "",
    "VirtualizationSystem": ""
  }
]

Ad-hoc shell commands

Executing a simple bash command looks like this:

$ velociraptor-client --instance test client C.02749d29d382534f bash 'cat /etc/motd'
openSUSE Leap 15.4 x86_64 (64-bit)

As "root" use the:
- zypper command for package management
- yast command for configuration management

Have a lot of fun...

Standard output and standard error streams are written to separate local output streams.

API client library

This is an attempt to port pyvelociraptor to Rust. The fetch and query functions are implemented. (I haven't figured out what to do with event.) Refer to the Rustdoc documentation (or the source code) for details.

Please do not use this for anything near production as interfaces are still likely to change.

Author

Hilko Bengen <bengen@hilluzination.de>