This is an annotated server.config.yaml with complete explanations
for all options currently available.
The values you see are the default values that will be used when the
option is omitted.
This is the version of the Velociraptor binary used to generate
this configuration file. It simply annotates the produced file and
can not be changed. When Velociraptor loads the configuration file,
this field will be updated so for example `velociraptor config
show` will update this to the present version.
The Client block will be copied into the client.config.yaml and it
is expected to be used by clients. It contains no secrets and can
be embedded into clients. The server must also have this block as
it needs to refer to client specific information sometimes.
These are the root CA certs the client will trust. This is
needed when going through a MITM proxy. Certificates are in PEM
format one after the next. Certificates do not have to have the
CA basic constraint!
Clients may connect to servers which use a self-signed certificate.
This list allows to specify a set of certificate thumbprints (SHA256)
which are used to validate TLS server certificates.
Fingerprints can be generated with the OpenSSL command line utility:
openssl s_client -connect www.google.com:443 < /dev/null | openssl x509 -fingerprint -sha256 -noout
Certificate thumbprints may or may not include colon characters. Capitalization
of the hex digits is ignored by Velociraptor. A thumbprint of any of the
forms used below (or combinations thereof) is fine.
Velociraptor supports several ways of verifying TLS certificates. The
certificate_verification_mode specifies which of the three modes is applied.
Currently, three modes are available:
PKI (the default):
verify TLS certs against public CA lists, the list of additional root_certs (see above),
and the built-in CA cert
PKI_OR_THUMBPRINT:
the same as PKI with the addition that certificates which have a thumbprint that is
present in certificate_thumbprints will be accepted as well
THUMBPRINT_ONLY:
Velociraptor only accepts certificates which have a matching thumbprint in
certificate_thumbprints. All other certificates will be rejected. This mode is
also known as certificate pinning.
By default velociraptor uses TLS 1.3 to secure it's
communications. Some networks use a MITM TLS proxy which does
not support more secure protocols so this setting can be
applied to make the server allow lower TLS versions.
If you want to use mTLS to mutually authenticate clients to the
server, place a pem encoded client certificate here. This
certificate will be presented to the server before a TLS
connection can be made.
This is an additional level of security that controls
connections between clients and server. It is normally not
needed as client connections are controlled via the embedded
nonce. However mTLS authentication allows termination of the
TLS before the server (e.g. using a reverse proxy).
To configure this feature you can create a certificate signed
by the Velociraptor CA:
velociraptor --config server.config.yaml config api_client --name "Client" api.config.yaml
This will create an api config file with the key pair encoded
as PEM strings. You can then copy and paste those into the
settings below. Only clients configured with these keys can
talk with the server
To require the frontend to only talk with mTLS authenticated
clients, set the Frontend.require_client_certificates to true.
A list of one or more URLs the clients will try to connect
to. When all connections fail the client will back off for a
while. Clients will choose one of these at random so it is a good
way of achieving fault tolerance and load balancing. As of
version 0.72, You can choose to use websockets here for a better
experience by setting the URL to start with wss://
A URL to a proxy that will be used to connect to the server. Some
environments have egress filtering requiring Velociraptor to use
a proxy to be able to reach the server. NOTE: We do not support
PAC based proxy configurations or Windows domain authentication -
you might need to add an allow rule to the proxy config to allow
the Velociraptor server URL without authentication.
If this is set we ignore the HTTP_PROXY and HTTPS_PROXY
environment variables. By default we allow these environment
variables to override the settings in this file.
The Internal Velociraptor CA certificate used to verify the
server certificates. Do not change this! This will be generated
by the config wizard and can not be replaced. It is only used
internally.
-----BEGIN CERTIFICATE-----
Generated by the config wizard!!!
-----END CERTIFICATE-----
This is a shared secret between servers and clients. The server
will refuse to communicate with clients having the wrong nonce.
The nonce is used to group clients into Org Groups - so clients
from different orgs have different nonce.
The following are the locations to write the writeback file- this
file is used to keep client state (See Writeback section). In the
default configuration, writeback files persist across
uninstall/reinstall cycles to keep the client id consistent. If
you don't want this you can change the location of the writeback
to be inside the inside the tempdir_windows directory (it will be
removed on uninstall).
From 0.7.0-3: On Windows if the writeback path starts with HKLM\
the path will be interpreted as a registry key that will be used
to store the writeback instead of files on disk.
If this value is specified, Velociraptor will create a level 2
writeback file. This second file is used as a backup and to write
more frequently updated content. This scheme should reduce the
likelihood that the file is corrupted to the point that the client
id is lost.
This is the directory Velociraptor will use for temporary
files. If not specified or not writable, Velociraptor will use
the $TMP or $TEMP env variable.
Number of seconds to wait before polling. Typically Velociraptor
connections are persistent but will force a re-connection every
max_poll seconds to refresh the connection. NOTE that typically
Velociraptor reuses TCP connections so this only applies to the
HTTP transactions, i.e. The TCP connections are always up.
If this is set, the nanny will exit if we are not able to send
messages to the server within this many seconds. NOTE - even a
failed connection will reset the counter, the nanny will only fire
if the client has failed in some way - e.g. the communicator is
stopped for some reason
The default max time to wait before we send partial VQL
results. This setting is used to ensure we dont send too many
small requests by batching the rows into time batches.
Maximum number of concurrent queries the client will allow
(default 2). This ensures we do not overwhelm the client by
scheduling too many concurrent queries. NOTE: Queries marked as
URGENT will skip this control and run anyway.
If set the client will hard exit when it uses this much memory (in
bytes). This is a safety feature to prevent runaway process -
ensure this is not set too low.
Clients will send a Server.Internal.ClientInfo message to the
server every this many seconds. This helps to keep the server info
up to date about each client. This should not be sent too
frequently. The default is 1 day (86400 seconds).
When a collection starts on the client, the client writes a
checkpoint file so it can detect when it crashed previously and
restarted. If this option is set we disable client checkpoints
and so we can not report to the server when the client crashes
while collecting an artifact.
These settings are used by the `velociraptor service install`
command. We typically do not use this as we prefer to distribute
MSI packages via package management systems.
If this setting is true, Velociraptor will expect the server to
use self signed TLS certificates. The client will verify the TLS
connection by checking that the server certificate is signed by
the Velociraptor internal CA. With this setting it is possible to
use an IP address for the server URL (not recommended though)
It is possible to pre-label clients using the configuration
file. The server will add these labels to the clients
automatically upon enrollment. This allows different client
packages to be distributed in the real world and have them
automatically identified.
The client normally does not write any logs on the
endpoint. However this makes it hard to debug any issues so you
can choose to have the client write its logs in a file on the
endpoint. The file will be written in an encrypted form which can
only be decrypted by the Generic.Client.LocalLogsRetrieve
artifact.
Path relative to the relevant tmpdir above where client side logs
are kept. These logs are encrypted client side and need to be
decrypted on the server to read.
On Windows, the client usually runs as a service. If a crash occurs
while Velociraptor is running as a Windows service the traceback of
the error is printed to Stderr, however a Windows service discards
these messages. This means that if Velociraptor crashes we lose the
panic backtrace which is useful for debugging why it crashed. This
setting allows us to specify a path to a log file on the client where
Velociraptor will write stdout and stderr in the event of a crash.
This feature is currently not implemented for non-Windows platforms
where this setting will have no effect.
Velociraptor keeps a local buffer file to store query results
while they are being shipped across the network. There are two
types of buffers - an in memory buffer and a local file based
buffer file. When the buffer is exceeded the query is paused so
it is important to have reasonable size available for the buffer
file to prevent queries taking too long (and possibly timing
out).
Setting this will write clear text network traces to this
file. This is used for debugging network communications in complex
scenarios (e.g. in the presence of proxies etc). Do not leave this
configured in production! This setting will also disable TLS
verification for the server name so it will be possible to MITM
the client->server connection.
NOTE: Velociraptor has 2 layers of encryption - this setting
bypasses the outer TLS layer to expose the underlying HTTP
communications. Client->server communication still remain
encrypted however.
This section configures the API service. The API server accepts
connections from the GUI gRPC gateway, as well as connections from
the gRPC API clients (e.g. with pyvelociraptor).
This is the hostname used to connect to - it is used here to copy
into new api client configuration files to assist gRPC API
connections (e.g. pyvelociraptor).
Do not change this. It is the common name of the certificate that
will be trusted to be from the GUI. ACL checks will be disabled
for all connections from this name.
Allows the GUI to start with no encryption - **WARNING** This only
makes sense if you have TLS proxy in front. In fact the GUI **will
not work** without a TLS proxy because the CSRF cookie is still
set to secure only.
A list of CIDR addresses from permitted networks. If this is not
set, permit all connections to the GUI from anywhere. This is
useful when you want to limit access to the GUI by IP address but
still allow access to clients from any IP, while running both the
frontend and GUI on the same port (normally port 443)
Header defined by the proxy containing the remote address. This
header will be used in the allowed_cidr matching if specified.
NOTE: Only use this if you do have a reverse proxy in front of
the server. Otherwise an attacker can simply send this header
to pretend to come from any IP address. If this setting is
specified we take the src address from the header, otherwise
from the remote IP address. Default is not set.
The type of links. Currently:
sidebar: This link will appear in the sidebar navigation menu
context: Will appear as part of the context (right click) menu
For context menu the value in the cell can be relayed to the
target URL. This setting controls the encoding of the value
and the parameter to attach it to.
Bind the GUI to this port. By default: For self signed SSL the
GUI will be bound to the localhost only! For Let's Encrypt
deployments the GUI will be bound on 0.0.0.0 making it accessible
from anywhere. NOTE: The **only** valid settings here are 0.0.0.0
for external access and 127.0.0.1 for localhost - Do not specify
any other address unless you know what you are doing!
When the Velociraptor server starts for the first time, the
server can create the following initial user with admin level
access. This is designed to automate deployment and allow users
to sign in immediately to the GUI. You can remove these accounts
or change their ACLs/Roles later.
Name of this authenticator to show in the GUI (e.g company
name). Note that you can provide many OIDC authenticators as
part of the multi authenticator so having a name here helps keep
them recognizable.
Certs authenticator: If a user presents a certificate but does
not exist in the system, the user will automatically receive a
default role. If this is not set the user will be rejected and
you will have to manually add the user to a role before they are
allowed.
This is the internal Velociraptor CA configuration. It is needed to
sign new API keys. Secure deployments can remove this part of the
config and safely store it offline.
This allows the frontends to listen on plain HTTP - It is useful
if you have SSL offloading (e.g. ngix). This is not configured by
the wizard - you will need to manually configure it. You better
know what you are doing here!
Enabling this requires the clients to present a valid certificate
(signed by one of the Root CAs listed in Client.Crypto.root_certs
or the Velociraptor built in CA itself). NOTE: If you use
configurations that place the Frontend and the GUI on the same
port then you **MUST** use the ClientCertificate authenticator.
See further discussions at Client.Crypto.client_certificate.
If this setting is enabled it becomes more difficult to
troubleshoot the server since a simple curl command will be
rejected. To test connectivity with the server you should instead
provide client cert and key files:
curl -kv https://localhost:8000/server.pem --cert client.pem --key key.pem
A proxy setting to use - Velociraptor needs to connect to download
tools. This setting will force it to go out over this proxy. NOTE-
If you dont want to allow outbound connections, just set this to
an non existent setting (e.g. http://127.0.0.1:3128).
These are used to secure the client/server communications - Even
when using external TLS certificates! This certificate must be
signed by the Velociraptor root CA in all cases
(tls_certificate_filename for that). If using an external TLS
configuration this layer of encryption happens **in addition** to
the external TLS certificates.
If you want to use your own certificates for TLS as an alternative
to Autocert, then you can set those here. These certificates will
be used for TLS on both the frontend and GUI. NOTE: We expect
these to be proper certificates - i.e. NOT self signed. If you
want to use certificates issued by another CA you will also need
to add that CA cert to the Client.Crypto.root_certs field.
Be sure to set Client.use_self_signed_ssl=false when you set this.
If configured, Velociraptor will attempt to update the dynamic
DNS server with its public IP address. Currently we only support
Google Domains although other providers may also work.
Header defined by the proxy containing the remote address. If this
is not set we use the remote IP address from the TCP
connection. This setting is needed if you have a reverse proxy in
front of the server.
The user that the frontend should run as. If set we refuse to run
as a different user. This is normally set by the Ubuntu deb
package as it is running as a low privilege user called
"velociraptor". This setting is important as it stops users from
running velociraptor as root with sudo - doing this will break the
velociraptor datastore when it creates files only readable by
root.
A regular expression that if matches any log messages from the
client's query represent a failure of the collection. Marking the
collection as failed can highlight potential problems with the VQL
so this regex tries to detect common issues (e.g. Symbol not
found) to draw attention to failures.
Sets resource limitations on the server. These parameters
represent the set of tunable parameters you can use to optimize
performance on loaded servers.
The rate at which we notify clients of new work (e.g. a new hunt
is started). Slower notification rate helps to slow down the
swarm effect and reduced load on the server.
The maximum number of concurrent client connections we can
process. Concurrency limits helps to ensure the server is not
overloaded serving too many clients at the same time.
Concurrency refers to the actual serving time of a client
(i.e. time taken to read the response and write to the
datastore), not the total number of clients served by
server. Default is number of cores * 2.
The maximum time a client will be waiting for a concurrency slot
before timing out. A small value will result in many
reconnections under load and may degrade performance.
This setting controls the size of various LRU caches in the
frontend (e.g. the session key cache, client info cache). This
number should be larger than the number of actual clients or
else the system will see high CPU load from cache misses.
Bandwidth control: Per client and global rates in
bytes/sec. This is useful for low bandwidth deployments where we
want to ensure Velociraptor does not saturate slow links. The
bandwidth limitation caps the total bandwidth used by the server
per client and globally.
Wait time for collecting events from clients - smaller means
less latency to respond to client events but also means more
TLS handshake and network overheads due to frequent POST.
Minions batch updates to the master so as to minimize RPC as
much as possible, this controls how often these batches are
flushed to the master (default 10 sec).
Number of seconds before expiring client info cache
entries. Default (0) means do not expire at all. Expiring
client info from cache too frequently can result in a lot more
IO. Default size of this cache is the expected_clients above.
The journal files are used to queue messages between event
generators and event consumers when the consumer is unable to
drain these quickly enough. The setting specifies the maximum
size of the file - when it is exceeded, the file will be
truncated and events will be lost. Default is 1gb
Larger result sets and uploads are stored in the
filestore_directory. This is usually the same as the location
setting but it can be different to keep larger slower storage
options away from smaller and faster data.
When using a master/minion setup it is necessary to have the
Master and Minion nodes use different filesystem
implementations. These more specific parameters can control
datastore implementations on the master and minion separately.
Cap directories to this size after reporting error - this should
not happen normally but may happen if the deployment has been very
active or due to a bug!
Set to the min required disk space. When we fall below this
available disk space, we refuse to write files. This avoids the
possibility of writing corrupted files. Default is 50mb. Set to -1
to disable disk space monitoring.
How many mutations to queue up ahead of busy writers. By
default 0 means writes will be blocked until they are handed
off to a writer thread. Set to -1 to disable asynchronous
writes.
The MemcacheFileDataStore separates writers into a writing
pool. These set the number of writer threads in that pool.
Number of writing threads - increase for high latency
filesystems (default 100).
How long to delay writes so they can be combined. This applies for
writing result sets - we keep the writes in memory for min_age
seconds in order to combine further writes. If another write
occurs to the same result sets the TTL is extended and writes are
delayed. However, once we reach max_age, a write is forced. The aim
is to keep combining separate writes as much as possible into larger
writes but at the same time prevent frequently written files from
never flushing to disk.
MemcacheFileDataStore will cache small files in memory to improve
efficiency. This is the maximum size of the cache.
Maximum size of memcache lru (default 10000)
If this is set the logs will be separated into different
components (eg. Frontend, GUI, Audit etc). This makes it easier
to find the source of the log messages
This controls the Monitoring server (i.e. Prometheus) If you have a
monitoring service like Grafana or Data Dog then change this server
to bind to 0.0.0.0 and point your scraper at it.
When starting without any command line parameters, this argv array
will be used as if it was typed on the command line. This is a way
to get Velociraptor to automatically execute a function as
startup when used without parameters.
Load these artifact definitions into the binary at startup. NOTE:
These definitions are considered "built-in" which will ensure they
can not be modified at runtime.
The format of these fields is an artifact definition - so the
following description also covers artifact definitions more
generally.
Artifacts can specify third party tools to load. Velociraptor
will attempt to fetch these tools when a user wants to collect
this artifact. Velociraptor will push the tool to the endpoint
so the artifact may use it.
As an alternative to a url we allow scrapping of GitHub
releases using the github API. NOTE: When this method is
specified, the file will always be served locally.
Once the tool is added with the above fields, the following
fields are used to keep state on it.
The URL we serve the tool from when we serve locally. If this
is empty we just let the endpoint download its own tool from
the url above.
The name of the cached file on the endpoint. This file will
persist and can be accessed again if this tool is needed in
future. If the file is missing (or has the wrong hash), then it
will be downloaded again.
If the artifact specifies a precondition the client will
evaluate this query before evaluating the main artifact. If the
precondition returns no rows (ie. FALSE) then the artifact will
not be collected. You can use the precondition to protect
incompatible clients from collecting the artifact (usually the
OS condition).
A default value for the parameter. NOTE: Parameters are
always strings so this field needs to be the string
representation of the type - e.g. "10" rather than 10.
The type of this parameter. Currently one of:
string, regex, yara, upload, int, int64, integer, timestamp,
csv, artifactset, json, json_array, bool, choices
This is used to obfuscate artifact names when sending to the
client. NOTE: This is currently not very robust - i.e. it does not
hide the artifact names very well - you should not name artifacts
in a sensitive way.
Normally notebook queries timeout in 10 minutes (can not be
changed from within the notebook). This is done to reduce load on
the server. If you want to increase notebook timeout you can
change this.
When running on a shared server notebook calculations can
increases memory use and affect other users. The following
settings control notebook calculations to ensure they do not use
too much memory. You should set the following in accordance with
the VM settings of the server with a small margin of safety.
When calculating a new cell we do not start calculation until the
process memory is smaller than the low memory mark.
Since Version 0.7.1, notebook queries are run in separate worker
threads, even on single server configurations. This parameters
sets the number of workers available.
Set to -1 to disable local workers. The default is 5 local
workers. If you want the master to **not** perform any notebook
computations reduce this to -1 and set
Minion.notebook_number_of_local_workers to 5.
If set we actively notify all clients as soon as event table is
changed. This causes a lot of load on large deployments so it is
off by default. It means that you will need to wait for the client
to reconnect before it receives updates to its event table
(usually about 5 min). When running `velociraptor gui` we set this
to true in order to get a responsive GUI.
The number of rows to keep in memory during a group by
operation. Once this is exceeded we switch to disk mode which
is a lot slower but has no memory limitations. Default 30000
If these are set we enforce VQL to only have the specified allowed
VQL plugins and functions. This is a way to harden the server by
removing potentially sensitive functionality to allow only
approved VQL plugins to run.
Controls how exports work (creating hunt or collection exports to a
zip file). On slow filesystems, increase the number of worker
threads to increase parallelism. You can also increase the timeout
if the filesystem is too slow to build large hunt zip files within
the default 10 minute timeout.
The server maintains an index of all hunts in order to quickly
allow the GUI to filter/sort them. This setting controls how often
to rebuild the hunt index (default 600 sec). You probably dont
need to change it.
Period in seconds when to produce a backup. Velociraptor will
generate a backup of important metadata about the server. By
default this happens daily but you can change it here (set to -1)
to disable backups.
The server's client info manager runs housekeeping tasks
periodically to determine if clients need to be notified. This
setting controls how often to run the client info's house keeping
thread in seconds (default 60 sec)
Disable unicode usernames. By default Velociraptor allows
usernames to consist of any Unicode character for i8n support,
however this opens the possibility for Homoglyph attacks. Setting
the following to true will restrict usernames to the set a-z and
0-9
The client metadata is an arbitrary key/value store that holds
user defined information per client. You can normally store
anything in the client metadata but this information is not
indexed, making searching on it slow (using VQL each client's
metadata blob needs to be opened, read and matched).
This setting allows you to define **some** fields in the client
metadata that will be indexed. These fields should not be too
large so as to keep the index size smallish so it is recommended
to use only small strings. Once fields are defined here, the extra
data can be searched in the GUI search bar using a verb such as
:match.
For example, define here:
indexed_client_metadata:
- department
Then a search for `department:accounting` will match all clients
with the key department and value contains accounting in their
client metadata.
The Velociraptor server may be placed into "lockdown" mode. While in
lockdown mode certain permissions are denied - even for
administrators. This additional protection mode helps to mitigate
the case when a Velociraptor administrator's account is
compromised. The server can be taken out of lockdown mode by setting
lockdown to false and restarting the server.
This configuration applies for minions. On minions this will
override the settings elsewhere in the config file allowing an easy
way to manage the difference between minions and master nodes.
This override occurs at config load times so you can see the final configuration using
velociraptor --minion --config server.config.yaml config show
Used to override Defaults.notebook_worker_priority. By default
minion workers have higher priority than the master node allowing
minions to take over notebook calculations most of he time.