Configuration file Reference

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.
    • Name of the agent - always "velociraptor"
    • velociraptor
    • The release version on GitHub.
    • 0.6.4-rc4
    • The commit at which this binary was built. This is more accurate than the version for reporting issues etc.
    • f3264824
    • The time the binary was built.
    • 2022-04-13T02:24:43+10:00
    • The URL to the Github Action CI job that built this binary.
    • https://github.com/Velocidex/velociraptor/actions/runs/3391188003
    • The version of the Go compiler that built this binary
    • go1.19.2
  • 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.
    • The Crypto options specifies cryptographic options.
      • 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!
      • -----BEGIN CERTIFICATE----- <certificate 1> -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- <certificate 2> -----END CERTIFICATE-----
    • 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 acheiving fault tolerance and load balancing.
      • https://192.168.1.1:8000/
      • https://192.168.1.2:8000/
    • 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.
    • https://proxy:3128/
    • 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.
    • rKNKAYam310=
    • 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).
    • /etc/velociraptor.writeback.yaml
    • /tmp/velociraptor.writeback.yaml
    • $ProgramFiles\Velociraptor\velociraptor.writeback.yaml
    • 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.
    • $ProgramFiles\Velociraptor\Tools
    • /tmp/
    • /tmp/
    • 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.
    • 60
    • Standard deviation between polls adds randomness to the poll period. This ensures that clients are not synchronized to even up the load on the server.
    • 30
    • 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
    • 0
    • If this is set, prevent arbitrary code execution on clients. NOTE: This will vastly reduce the capabilities of the client.
    • false
    • 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.
    • 60
    • 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.
    • 2
    • 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.
    • Settings used by the darwin `velociraptor service install` command.
    • 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)
    • true
    • Do not change this!
    • VelociraptorServer
    • The maximum size of the POST request the client will send to the server. Some proxy servers limit the size of POST messages.
    • 5242880
    • Maximum timeout for connection retry - the length of time we try a connection before restarting it (default 5 min).
    • 300
    • Disable client/server compression. Typically no need to change this.
    • false
    • 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.
      • Label1
      • Label1
    • 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).
      • Maximum size of the in-memory buffer. When this size is exhausted the query is paused until the data is sent over the network.
      • 52428800
      • If the disk size of the local buffer is set to 0, no disk file will be used, only a memory buffer will be used.
      • 1073741824
      • Where to store the files on the local disk for the various operating systems.
      • /var/tmp/Velociraptor_Buffer.bin
      • $TEMP/Velociraptor_Buffer.bin
      • /var/tmp/Velociraptor_Buffer.bin
  • 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).
    • 192.168.1.11
    • Interface to bind to - by default only bind to 127.0.0.1 but will need to be exposed on 0.0.0.0 for external pyvelociraptor clients to connect.
    • 127.0.0.1
    • The port to listen on.
    • 8001
    • Usually these do not need to be changed.
    • tcp
    • 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.
    • GRPC_GW
  • Configure the GUI admin web application.
    • 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.
    • false
    • You can serve Velociraptor at a sub path of the server. All URLs will then be formed below the base path.
    • /
    • The public URL of this server. Change this if you are proxying the GUI using a different URL.
    • http://velo.example.com
    • Allows additional links to be defined for site customization.
      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.
    • 127.0.0.1
    • Bind port for the GUI. When using Let's Encrypt the GUI is bound to port 443 and this setting is ignored because Let's Encrypt only supports port 443.
    • 8889
    • The internal certificate for gRPC connections between the gateway and the API server. DO NOT Change this!
    • -----BEGIN CERTIFICATE----- Generated by the config wizard!!! -----END CERTIFICATE-----
    • -----BEGIN RSA PRIVATE KEY----- Generated by the config wizard!!! -----END RSA PRIVATE KEY-----
    • Velociraptor supports a reverse proxy allowing you to place other applications behind the Velociraptor Oauth2/TLS server.
        • Any paths below this route will be forwarded to the given URL (and the path copied into the target)
        • /CyberChef/
        • The URL to forward to. This can be a file:// URL which allows you to host static files at this location.
        • file:///shared/CyberChef/
        • If this is set to true, the user needs to be authenticated to Velociraptor before they are proxied.
        • true
    • 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.
        • Username to create
        • mic
        • Password hashes - this is only useful for Basic Authenticator which uses passwords. They can be left empty for Oauth based authenticator.
        • aa3a779e09062dea3a46811e0c0624ba7999cf15a2d12dce7489aca339c3deff
        • f8707a7a9c876a4e6210d4f5bbdee4846adff7465d50efc43a305175aab8f146
    • When Velociraptor starts the first time these orgs will be created.
        • O1234
        • My Company
        • If this is empty we use the org id. The nonce is a shared secret in the client configuration which binds clients to this Org. See Client.nonce.
        • O1234
    • How to authenticate users to the server. Velociraptor comes with a large number of authenticators. This section configures the authenticator to use.
      • The type of authenticator to use. Currently: basic, google, azure, oidc-cognito, github, saml, oidc, multi
      • basic
      • Used by SAML authenticator
      • -----BEGIN CERTIFICATE----- -----END CERTIFICATE-----
      • -----BEGIN RSA PRIVATE KEY----- -----END RSA PRIVATE KEY-----
      • http://localhost:8080/simplesaml/saml2/idp/metadata.php
      • https://localhost:8889
      • email
      • URL to OIDC Configuration Document. The configuration should be available in the 'oidc_issuer + /.well-known/openid-configuration' endpoint.
      • 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.
      • Company Name
      • http://www.example.com/icon.png
      • These are required for the oauth flow - get from the OIDC provider.
      • C123445
      • X23456
      • This is specifically required by the Azure authenticator only.
      • O...
      • URL to redirect to on Unauthorized API call. If blank we just cycle to the logon screen again.
      • http://www.google.com
      • How long to keep the session alive between auth flows - default 24 hours
      • 8000
      • Used by the multi authenticator to provide multiple authenticators. NOTE: Sub authenticators must be oauth based (i.e. not basic auth).
  • 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.
    • CA private key - the public certificate is in Client.ca_certificate
    • -----BEGIN RSA PRIVATE KEY----- -----END RSA PRIVATE KEY-----
  • Configuration of the frontend. The Frontend is the service that directly talks with clients.
    • Serve the Frontend from this base path instead of "/"
    • /
    • 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!
    • false
    • 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. 127.0.0.1:3128).
    • Velociraptor can attempt to obfuscate artifact names when compiling them into raw VQL. If this is set this obfuscation is removed.
    • true
    • The publicly accessible hostname of the frontend.
    • 192.168.1.11
    • Which interface to bind to. Usually the frontend is bound to 0.0.0.0 to allow all clients to connect from anywhere.
    • 0.0.0.0
    • 8000
    • 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.
    • -----BEGIN CERTIFICATE----- -----END CERTIFICATE-----
    • -----BEGIN RSA PRIVATE KEY----- -----END RSA PRIVATE KEY-----
    • 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 Frontend.Crypto.root_certs and Client.Crypto.root_certs field. Be sure to set Client.use_self_signed_ssl=false when you set this.
    • /etc/cert.pem
    • /etc/cert.key
    • 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.
      • The hostname to update
      • www.velo.com
      • 1234233452
      • 2313e2324
      • If empty we use Google Domains.
      • http://dyndns.provider.com/
      • How often to check for IP assigned
      • 60
      • The url we will use to check the ip. Should return a plain IP address (default is Google Domains)
      • http://dyndns.provider.com/checkip
      • DNS server we query for our own hostname/ip mapping (default 8.8.8.8:53)
      • 8.8.8.8:53
    • 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.
    • X-Forwarded-For
    • We have the Server.Monitor.Health enabled always but these are any additional artifacts that should be installed by default.
      • Server.Monitor.Health
    • When creating the initial client monitoring artifact table, these artifacts will be assigned to all clients.
      • Generic.Client.Stats
    • 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 priv 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.
    • velociraptor
    • When the server is created initially, these server artifacts will be collected. You can use this to fire custom initialization sequences.
      • MySpecialArtifact
    • Number of gRPC connections in the pool to use to connect to the API server.
    • 100
    • 60
    • Load artifacts from this directory at startup
    • /tmp/
    • 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.
    • ERROR:
    • Sets resource limitations on the server. These parameters represent the set of tunable parameters you can use to optimize performance on loaded servers.
      • Load shed connections faster than this to preserve stability.
      • 300
      • The rate at which we notify clients of new work (e.g. a new hunt is started). Slower notification rate helps to slow dows the swarm effect and reduced load on the server.
      • 1000
      • How quickly do we enroll clients (default 100/s, -1 to disable enrollments)
      • 100
      • 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.
      • 20
      • 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.
      • 600
      • Increasing this allows the frontend to receive larger POST messages lowering crypto overheads but this comes at the expense of more memory use.
      • 10485760
      • 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.
      • 10000
      • 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.
      • 0
      • 0
      • 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.
      • 100
      • 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).
      • 10
      • 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.
      • 0
      • How often to sync client info records (ms) between minion and master.
      • 0
      • 0
      • 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
      • 1000000000
      • How often to save an index snapshot to storage (default 600 sec). Index files are typically 150kb / 1000 clients.
      • 10
  • Velociraptor has a datastore abstraction and can use a number of possible data storage engines. This section configures the data store implementation.
    • The data store implementation to use. This is usually set to FileBaseDataStore.
    • FileBaseDataStore
    • The directory under which we store small files.
    • /mnt/data
    • 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.
    • /mnt/data
    • How long before a write is forced from the pool for delayed writes
    • 1
    • 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.
    • RemoteFileDataStore
    • MemcacheFileDataStore
    • 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!
    • 50000
    • The following apply to the MemcacheFileDataStore How long to expire the memcache (default 10 min)
    • 6000
    • 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.
    • 100
    • 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).
    • 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.
    • 1000
    • 5000
    • 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)
    • 10000
    • Do not cache large objects in memory - falls back to FileBaseDataStore
    • 1000
    • 50000
  • Configure logging behavior
  • 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.
  • Run these automatically when the binary starts.
    • 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.
      • artifacts
      • collect
      • Generic.Client.Info
    • 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.
        • The name of the artifact. Artifacts are referred to by name within the system.
        • Generic.Client.InfoXXX
        • A Human readable description of the artifact. This should have a single summary paragraph
        • Artifact Description
        • The artifact author
        • Author
        • Type of the artifact: CLIENT, SERVER, CLIENT_EVENT, SERVER_EVENT
        • CLIENT
        • A list of references
          • https://www.google.com
        • 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.
            • The name of the tool
            • MyTool
            • The URL to fetch the tool from when we upload it the first time, or when we update.
            • http://www.google.com
            • 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.
            • GitHubProject
            • GitHubAsset
            • If set, the tool will be served locally from the filestore path - otherwise the endpoint will download the file by itself from the url above.
            • true
            • This is set when an admin explicitly overrides a tool. If this is set we will not update the tool definition when upgrading server versions.
            • true
            • 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.
            • https://www.google.com
            • Only valid for local dummy inventory.
            • Where to read the file from the filesystem
            • A filestore path where the file can be downloaded from - if served locally.
            • /public/1234
            • 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.
            • MyTool.exe
            • Hex encoded sha256 hash of the file. Endpoints will check this hash against their fetch file to ensure it was correctly transferred.
            • 1234
            • If set on a request we refresh the hash.
            • true
        • A list of permissions the user needs to possess before they are allowed to collect this artifact.
          • EXECVE
        • 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).
        • SELECT OS FROM info() WHERE OS =~ "windows"
        • Parameters are provided to the artifact by the user. They can change the way the VQL is evaluated.
            • The name of the parameter. This name will appear in the scope during query execution.
            • Foo
            • A human friendly name for the parameter (if not specified we show the name).
            • A Foo Variable
            • 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.
            • 10
            • A description of this parameter to be shown in the GUI
            • A parameter
            • The type of this parameter. Currently one of: string, regex, yara, upload, int, int64, integer, timestamp, csv, artifactset, json, json_array, bool, choices
            • int
            • For parameters of type "choices" this is a list of possible choices.
              • One
              • Two
        • A snippet of VQL that can be imported by other artifacts
        • VQL here
        • A list of artifacts that will be imported by this artifact.
          • Artifact.Name
        • A list of queries to gather data from.
            • An optional name for the query
            • MySource
            • A description for the source
            • SELECT * FROM info()
            • An internal list of compiled queries. For backwards compatibility with very old artifacts.
              • DO NOT USE
            • A precondition applying to this source only.
            • SELECT OS FROM info() WHERE OS =~ "windows"
            • An artifact source may define multiple notebook cells to be used when the artifact is collected or hunted for.
              • The type of the notebook cell: e.g. suggestion adds a cell to the suggestion button. Also can be vql or markdown.
  • linux
  • 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.
  • zKJDb3KcWh8=
  • Path to store autocert certificates.
  • /tmp/
  • Various defaults used by various things.
    • 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.
    • 10
    • When exporting to CSV from the GUI the usual separator is comma (`,`). This setting allows to change the default to any single character.
    • ,
    • By default hunts expire in 7 days but you can change this using this setting.
    • 168
    • Default value of max_wait and relevant jitter for new event queries the GUI creates.
    • 100
    • 30
    • 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.
    • false
    • When viewing the VFS on a client we create objects in the data store to facilitate the GUI navigation. If the directory is too large the GUI performance suffers so we truncate the directory at this size (default 1000 files).
    • 1000
    • Additional directories to load artifacts from on start up.
      • /etc/artifacts/
    • 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
    • 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.
      • glob
      • dict
      • auto
    • How long to cache ACL policies (default 60 sec)
    • 60
    • Ignore messages from unauthenticated clients for this long - gives them a chance to enrol first (default 10 sec).
    • 10
comments powered by Disqus