server.config.yaml

# 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.
version:
  name: velociraptor
  version: 0.6.4-rc4
  commit: f3264824
  build_time: "2022-04-13T02:24:43+10:00"

## 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.
Client:
  ## The Crypto options specifies cryptographic options.
  Crypto:
    ## 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!
    root_certs: |
        -----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.
  server_urls:
  - https://192.168.1.1:8000/
  - https://192.168.1.2:8000/

  ## 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.
  ca_certificate: |
    -----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.
  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 inside the Tools
  ## directory on Windows (it will be removed on uninstall).
  writeback_darwin: /etc/velociraptor.writeback.yaml
  writeback_linux: /tmp/velociraptor.writeback.yaml
  writeback_windows: $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.
  tempdir_windows: $ProgramFiles\Velociraptor\Tools

  ## 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,
  max_poll: 60

  ## 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.
  windows_installer:
    service_name: Velociraptor
    install_path: $ProgramFiles\Velociraptor\Velociraptor.exe
    service_description: Velociraptor service

  ## Settings used by the darwin `velociraptor service install` command.
  darwin_installer:
    service_name: com.velocidex.velociraptor
    install_path: /usr/local/sbin/velociraptor

  ## 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)
  use_self_signed_ssl: true

  ## Do not change this!
  pinned_server_name: VelociraptorServer

  ## The maximum size of the POST request the client will send to the
  ## server. Some proxy servers limit the size of POST messages.
  max_upload_size: 5242880

  ## 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).
  local_buffer:
    memory_size: 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.
    disk_size: 1073741824

    ## Where to store the files on the local disk for various
    ## operating systems.
    filename_linux: /var/tmp/Velociraptor_Buffer.bin
    filename_windows: $TEMP/Velociraptor_Buffer.bin
    filename_darwin: /var/tmp/Velociraptor_Buffer.bin

## This section configured the API service. The API server accepts
## connections from the GUI gRPC gateway, as well as connections from
## the gRPC API clients (e.g. pyvelociraptor).
API:
  ## 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).
  hostname: 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.
  bind_address: 127.0.0.1

  ## The port to listen on.
  bind_port: 8001

  ## Usually these do not need to be changed.
  bind_scheme: 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.
  pinned_gw_name: GRPC_GW

## Configure the GUI admin web application.
GUI:
  ## Allows additional links to be defined for site customization.
  links:
    ## The text of the link (visible in the GUI)
    - text: Google Search

      ## Where the link points to.
      url: https://www.google.com

      ## should the link be opened in a new tab?
      new_tab: true

      ## 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
      type: sidebar

      ## The icon before the link. This can be a data URL or a link to a png
      icon_url: data:image/svg+xml;base64,....

  ## 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.
  bind_address: 127.0.0.1

  ## Bind pot 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.
  bind_port: 8889

  ## The internal certificate for gRPC connections between the gateway
  ## and the API server. DO NOT Change this!
  gw_certificate: |
    -----BEGIN CERTIFICATE-----
    Generated by the config wizard!!!
    -----END CERTIFICATE-----
  gw_private_key: |
    -----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.
  reverse_proxy:
    ## Any paths below this route will be forwarded to the given URL
    ## (and the path copied into the target)
  - route: /CyberChef/

    ## The URL to forward to. This can be a file:// URL which allows
    ## you to host static files at this location.
    url: file:///shared/CyberChef/

    ## If this is set to true, the user needs to be authenticated to
    ## Velociraptor before they are proxied.
    require_auth: 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 API later.
  initial_users:
    ## Username to create
  - name: mic

    ## Password hashes - this is only useful for Basic Authenticator
    ## which uses passwords. They can be left empty for Oauth based
    ## authenticator.
    password_hash: aa3a779e09062dea3a46811e0c0624ba7999cf15a2d12dce7489aca339c3deff
    password_salt: f8707a7a9c876a4e6210d4f5bbdee4846adff7465d50efc43a305175aab8f146

  ## How to authenticate users to the server. Velociraptor comes with
  ## a large number of authenticators. The configures the
  ## authenticator to use.
  authenticator:
    ## The type of authenticator to use. Currently:
    ## basic, google, azure, oidc-cognito, github, saml, oidc, multi
    type: basic

    ## Used by SAML authenticator
    saml_certificate: |
      -----BEGIN CERTIFICATE-----
      -----END CERTIFICATE-----
    saml_private_key: |
      -----BEGIN RSA PRIVATE KEY-----
      -----END RSA PRIVATE KEY-----
    saml_idp_metadata_url: http://localhost:8080/simplesaml/saml2/idp/metadata.php
    saml_root_url: https://localhost:8889
    saml_user_attribute: email

## This is the internal Velociraptor CA configuration. It is needed to
## sign new API keys. Secure deployments can remove this part of the
## config offline.
CA:
  ## CA private key - the public certificate is in
  ## Client.ca_certificate
  private_key: |
    -----BEGIN RSA PRIVATE KEY-----
    -----END RSA PRIVATE KEY-----

## Configuration of the frontend. The Frontend is the service that
## directory talks with clients.
Frontend:
  ## Velociraptor can attempt to obfuscate artifact names when
  ## compiling them into raw VQL. If this is set this obfuscation is
  ## removed.
  do_not_compress_artifacts: true

  ## The publicly accessible hostname of the frontend.
  hostname: 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.
  bind_address: 0.0.0.0
  bind_port: 8000

  ## The internal frontend certificate. In self signed mode this will
  ## also be used for TLS certificate.
  certificate: |
    -----BEGIN CERTIFICATE-----
    -----END CERTIFICATE-----
  private_key: |
    -----BEGIN RSA PRIVATE KEY-----
    -----END RSA PRIVATE KEY-----

  ## If configured, Velociraptor will attempt to update the dynamic
  ## DNS server with its public IP address.
  dyn_dns: {}

  ## When creating the initial client monitoring artifact table, these
  ## artifacts will be assigned to all clients.
  default_client_monitoring_artifacts:
  - Generic.Client.Stats

  ## When the server is created initially, these server artifacts will
  ## be collected. You can use this to fire custom initialization
  ## sequences.
  initial_server_artifacts:
  - MySpecialArtifact

  ## Number of gRPC connections in the pool to use to connect to the
  ## API server.
  GRPC_pool_max_size: 100
  GRPC_pool_max_wait: 60

  ## Sets resource limitations on the server.
  resources:
    connections_per_second: 300
    notifications_per_second: 1000
    enrollments_per_second: 100
    concurrency: 20
    max_upload_size: 10485760
    expected_clients: 10000
    index_snapshot_frequency: 10

## Define additional frontend servers (e.g. Minions).
ExtraFrontends:
- hostname: 192.168.1.11
  bind_address: 0.0.0.0
  bind_port: 8100
  resources:
    connections_per_second: 300
    notifications_per_second: 1000
    enrollments_per_second: 100
    concurrency: 20
    max_upload_size: 10485760
    expected_clients: 10000
- hostname: 192.168.1.11
  bind_address: 0.0.0.0
  bind_port: 8200
  resources:
    connections_per_second: 300
    notifications_per_second: 1000
    enrollments_per_second: 100
    concurrency: 20
    max_upload_size: 10485760
    expected_clients: 10000

## Velociraptor has a datastore abstraction and can use a number of
## possible data storage engines. This section configures the data
## store implementation.
Datastore:
  ## The data store implementation to use. This is usually set to
  ## FileBaseDataStore.
  implementation: FileBaseDataStore

  ## The directory under which we store small files.
  location: /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.
  filestore_directory: /mnt/data

  ## The MemcacheFileDataStore separates writers into a writing
  ## pool. These set the number of writer threads in that pool.
  memcache_write_mutation_writers: 100

  ## How long before a write is forced from the pool for delayed writes
  memcache_write_mutation_max_age: 1

  ## MemcacheFileDataStore will cache small files in memory to improve
  ## efficiency. This is the mac size of the cache.
  memcache_datastore_max_size: 10000

  ## 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.
  minion_implementation: RemoteFileDataStore
  master_implementation: MemcacheFileDataStore

## The Writeback part of the configuration - This is read from the
## writeback file, overriding any configuration here.
Writeback:
  private_key: |
    -----BEGIN RSA PRIVATE KEY-----
    Generated by client
    -----END RSA PRIVATE KEY-----
  client_id: C.1352adc54e292a23
  hunt_last_timestamp: 1234
  last_server_serial_number: 1
  event_queries:
    event:
    - query_id: 1
      total_queries: 2
      precondition: SELECT OS From info() where OS = 'windows'
      env:
        - key: Frequency
          value: "10"
      version: 123

## Configure the mail server (deprecated!) Do not use.
Mail: {}

## Configure logging behavior
Logging:
  ## A directory to write log files in .
  output_directory: /mnt/data/logs

  ## 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
  separate_logs_per_component: true

  ## Specific configuration for each log level. If a log level is not
  ## configured here it is logged as normal.
  debug: {}

## 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.
Monitoring:
  bind_address: 127.0.0.1
  bind_port: 8003

## Configures any API client configuration (e.g. pyvelociraptor
## connections over the API).
api_config: {}

## Run these automatically when the binary starts.
autoexec:
  ## 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.
  artifact_definitions:
    # 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.
  - name: Generic.Client.InfoXXX

    # A Human readable description of the artifact. This should have a
    # single summary paragraph
    description: Artifact Description

    ## The artifact author
    author: Author

    # Type of the artifact: CLIENT, SERVER, CLIENT_EVENT, SERVER_EVENT
    type: CLIENT

    ## A list of references
    reference:
      - 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.
    tools:
      # The name of the tool
      - name: MyTool

        # The URL to fetch the tool from when we upload it the first
        # time, or when we update.
        url: 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.
        github_project: GitHubProject
        github_asset_regex: 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.
        serve_locally: 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.
        admin_override: 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.
        serve_url: https://www.google.com

        # Only valid for local dummy inventory.
        serve_path: Where to read the file from the filesystem

        # A filestore path where the file can be downloaded from - if
        # served locally.
        filestore_path: /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.
        filename: MyTool.exe

        # Hex encoded sha256 hash of the file. Endpoints will check
        # this hash against their fetch file to ensure it was
        # correctly transferred.
        hash: 1234

        # If set on a request we refresh the hash.
        materialize: true

    # A list of permissions the user needs to possess before they are
    # allowed to collect this artifact.
    required_permissions:
      - EXECVE

    resources:
      # Default timeout for this artifact
      timeout: 600
      ops_per_second: 100
      cpu_limit: 20
      iops_limit: 20

      # Default resource use for the entire collection.
      max_rows: 1000000
      max_upload_bytes: 1000000

    # 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).
    precondition: 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.
    parameters:
        # The name of the parameter. This name will appear in the
        # scope during query execution.
      - name: Foo

        ## A human friendly name for the parameter (if not specified
        ## we show the name).
        friendly_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.
        default: "10"

        ## A description of this parameter to be shown in the GUI
        description: 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
        type: int

        # For parameters of type "choices" this is a list of possible
        # choices.
        choices:
          - One
          - Two

    # A snippet of VQL that can be imported by other artifacts
    export: VQL here

    # A list of artifacts that will be imported by this artifact.
    imports:
      - Artifact.Name

    # A list of queries to gather data from.
    sources:
      # An optional name for the query
    - name: MySource
      description: A description for the source
      query: SELECT * FROM info()

      # An internal list of compiled queries. For backwards
      # compatibility with very old artifacts.
      queries:
        - DO NOT USE

      # A precondition applying to this source only.
      precondition: 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.
      notebook:
        # The type of the notebook cell: e.g. suggestion adds a cell
        # to the suggestion button. Also can be vql or markdown.
        - type: suggestion
          # Parameters to pre-populate in the cell.
          env:
            - key: X
              value: Y
          template: Text here


server_type: 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.
obfuscation_nonce: zKJDb3KcWh8=

## Various defaults used by various things.
defaults:
  ## 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.
  notebook_cell_timeout_min: 10

  ## When exporting to CSV from the GUI the usual separator is comma
  ## (`,`). This setting allows to change the default to any single
  ## character.
  csv_delimiter: ','

  ## By default hunts expire in 7 days but you can change this using
  ## this setting.
  hunt_expiry_hours: 168