Xylok Documentation
Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Back to homepage
  2. /
  3. Data Collection
  4. /
  5. Advanced Collector Configuration Schema

Advanced Collector Configuration Schema

The Xylok advanced collector is configured with a single HashiCorp Configuration Language (HCL) file. By default the collector searches for collect.hcl in the current directory, $XDG_CONFIG_HOME/xylok/collect.hcl (usually ~/.config/xylok/collect.hcl), and /etc/xylok/collect.hcl. The first file found is used, or you can pass an explicit path with the --config flag.

This page documents the complete schema for that file. Values shown as optional may be omitted; required values must be provided. A working commented example is also available by running:

./collector config example

Top-level structure

The configuration file consists of four top-level blocks:

general { /* global collector settings */ }

results { /* result file settings */ }

access "name" { /* access method */ }

target "name" {
  benchmark "benchmark_id" { /* benchmark settings */ }
}

Only target blocks are required; a configuration with no targets causes the collector to create an impromptu local target and save it to disk. All other blocks are optional.

general block

Controls global collector behavior.

Attribute Type Required Default Description
log-level string No "info" Logging verbosity. Valid values: "debug", "info", "warn", "error". The -v CLI flag overrides this to "debug".
fail-fast bool No false If true, panics during collection stop the collector instead of continuing with the next benchmark. Individual collectors may also use this for stricter debugging behavior.
ignore-user bool No false If true, the shell collector does not require root or administrator privileges. Set to true only when the target device does not need elevated permissions, such as some API-based collectors.
shell-concurrency int No 3 Default maximum number of shell commands that may run at the same time on each target. Can be overridden per target with the target-level shell-concurrency attribute.
shell-timeout-secs int No 600 Default number of seconds a shell command may run before it is killed. Can be overridden by individual benchmark commands.
random-delay-secs int No 0 Maximum number of seconds to wait before starting collection. When non-zero the collector sleeps for a random duration between 0 and this value. Useful for staging collection start times across many devices.

server nested block

Configures automatic upload of result files to an XSS API server after collection completes. To upload results you must also set results.auto-upload = true.

Attribute Type Required Description
server string Yes Base URL of the XSS server, for example https://xss.example.com.
token string No* API token used to authenticate uploads. Either token or token-encrypted is required when the block is present.
token-encrypted string No* Encrypted API token produced with ./collector encrypt. Either token or token-encrypted is required when the block is present.
ignore-ssl-certs bool No If true, SSL certificate verification is disabled when uploading. Defaults to false.

results block

Controls how, where, and whether result files are produced.

Attribute Type Required Default Description
directory string No "." Directory where result files are written. May be absolute or relative. ~ is expanded to the current user’s home directory.
compression string No "auto" Controls compression of result data. Valid values: "never" (never compress, keeps text readable), "always" (always compress), "auto" (compress only when it reduces size).
auto-upload bool No false If true, result files are uploaded to the XSS server configured in general.server after collection finishes.

access block

Defines a named access path that can be referenced from benchmarks. Access paths are currently parsed and saved in configuration files, but they are not yet enforced by the collector. This block exists for future support.

Element Type Required Description
Block label ("name") string Yes A name you choose so that targets or benchmarks can reference this access path with access-from.
hop block block Yes One or more hops that describe the path to the target. Hops are evaluated in order.

target block

Represents one device that the collector will gather data from.

Attribute Type Required Default Description
Block label ("name") string Yes A human-readable name for the target. It does not need to match the machine name in Xylok, but using the same name makes configuration easier to manage.
id string Yes The UUID of the machine in Xylok. This is the UUID that appears in the machine details URL, e.g. https://xss.example.com/client/machine/<uuid>/.
disabled bool No false If true, the target is skipped but kept in the configuration file.
os string No auto-detected Operating system key for the target, such as "rhel 9" or "VMWareNSX". Required when the collector cannot auto-detect the OS (for example, remote API targets). Use ./collector config oses to list all supported OS keys.
benchmark-detect bool No false If true, the collector attempts to auto-detect which benchmarks should run on this target. This works for local shell targets where detection scripts are available.
shell-concurrency int No general.shell-concurrency Maximum number of shell commands that may run at the same time on this target. Overrides the global default.

benchmark block

Each benchmark block inside a target tells the collector to run one benchmark against that target.

Attribute Type Required Default Description
Block label ("benchmark_id") string Yes The benchmark identifier. This is the collector/benchmark name, for example "rhel_9_stig", "vmw_nsx_4-x_manager_ndm_stig", or "cisco-fmc". Use ./collector collectors to list the names of all available collectors.
disabled bool No false If true, this benchmark is skipped for the target.
access-from string No Name of an access block to follow before running this benchmark. Currently parsed but not enforced.

All other attributes on a benchmark block are treated as free-form collector or benchmark settings. Values may be strings or booleans, and any string value may be encrypted with the -encrypted suffix.

Common benchmark settings

Setting Type Description Used by
target string Target IP, hostname, or API endpoint URL for the device. NSX collectors, Cisco FMC collector
username string Username for authenticating to the target API or device. NSX collectors, Cisco FMC collector
password string Password for authenticating to the target API or device. NSX collectors, Cisco FMC collector
token string API token used instead of username/password. Cisco FMC collector (requires domain)
domain string Cisco FMC domain UUID. Required when using token authentication with the Cisco FMC collector. Cisco FMC collector
interview-only bool If true, normal command collection is skipped and only interview questions are produced. Interview and shell collectors

Runner-provided settings

Benchmarks that use non-shell runners may require additional settings that correspond to the runner’s questions. These settings have the same processing_id that the collector prompts for when the value is missing. Common runner setting keys include:

Runner Setting keys
MariaDB mariadb_host, mariadb_user, mariadb_password
MySQL mysql_host, mysql_user, mysql_password
PostgreSQL postgres_host, postgres_user, postgres_password
SQLite sqlite_db
Oracle DB oracle_connect_string
ESXi PowerCLI esxi_host, esxi_user, esxi_pw

Question answers

Benchmarks may also define their own questions. Any question’s processing_id may be supplied as a benchmark attribute to pre-answer it. If a required value is not provided in the file, the collector will prompt for it at run time.

Encrypted values

Any string setting may be stored in encrypted form by appending -encrypted to the attribute name. The collector decrypts the value at load time using the passphrase passed with the --passphrase CLI flag.

To encrypt a value:

./collector encrypt --passphrase my-passphrase secretpassword

Use the output as the value of an encrypted attribute:

benchmark "cisco-fmc" {
  target           = "https://fmc.example.com"
  username         = "admin"
  password-encrypted = "eyJrZXlBbGdvIjoiYXJnb24yaWQiLCJrZXlJdGVyIjoxLCJrZXlNZW0iOjY1NTM2LCJrZXlUaHJlYWRzIjo4LCJzYWx0IjoiNHR4dUE3SXZFeUlSVFA1a3RuTlRMZHRKeDd0WmNBcUM0S056N0QvVkRoOD0iLCJlbmNBbGdvIjoiYWVzLTI1Ni1nY20iLCJkYXRhIjoiS0hnQ1V4VEJUeVRUNWNwb29kd3RvbmFUM0dFTmFWdmdGTXFCUmN3bWtwb1ZUempFandhQmMrSlgifQ=="
}

Then run the collector with:

./collector run --passphrase my-passphrase

Complete example 

general {
  log-level          = "info"
  fail-fast          = false
  ignore-user        = false
  shell-concurrency  = 3
  shell-timeout-secs = 600
  random-delay-secs  = 0

  server {
    server           = "https://xss.example.com"
    token            = "my-api-token"
    ignore-ssl-certs = false
  }
}

results {
  directory    = "."
  compression  = "auto"
  auto-upload  = true
}

target "local-rhel" {
  id   = "bb4c44d2-68c5-4221-a8e1-49a7955acd30"
  os   = "rhel 9"

  benchmark "rhel_9_stig" {}
}

target "nsx-manager" {
  id   = "917746ab-d3dc-4919-8aa3-9d0ff02c5acc"
  os   = "VMWareNSX"

  benchmark "vmw_nsx_4-x_manager_ndm_stig" {
    target   = "https://nsxmgr.example.com"
    username = "admin"
    password = "admin-password"
  }
}

For a version of this example that matches your exact collector build, use the ./collector config example command.

gdoc_arrow_left_alt Windows (Powershell) Devices Advanced Data Collector gdoc_arrow_right_alt