# 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:
``` yaml
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](https://github.com/Velocidex/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>>