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 Data Collector

Advanced Data Collector

Quick(ish) Start

  1. Download the collector binary to a machine in your network. On Linux or MacOS, make it executable: chmod +x collector*
  2. Create a configuration file by running (adjust for your collector): ./collector config init. A collect.hcl file will be created in the current directory.
  3. Open and edit the newly created collect.hcl following the comments in the file
  4. Run the collection: ./collector run
  5. If there are any remaining configuration questions that need to be answered, you will be prompted to enter that at the command line. Otherwise, the collector will begin running.
  6. At the end, each target in the configuration will have a results-<targetname>-<datetime>.xylok file produced, ready for upload to Xylok.

Details

Background

Xylok’s data collection typically uses human-readable scripts generated in a native scripting language of the target machine, such as BASH or PowerShell. This strategy runs commands just like a system administrator might and works very well for most DISA-produced STIGs. In addition, the scripts are produced from Xylok are machine-specific, tailored to the exact benchmarks selected for each device.

However, some devices need more control to collect all the needed data. For example, a firewall which offers its configuration via a REST API might need many related queries to collect all the required data. For these cases, Xylok offers the “advanced collector,” a binary written in Go which allows for more advanced data collection. This binary is offered for a variety of target platforms. Because it is a compiled binary, we create a single binary for each Xylok release, rather than binaries customized to your machines. The exact benchmarks run by the collector are instead controlled via a configuration file which Xylok will help you generate.

Downloads

The following binaries are included in this release. If you have a machine that does not work with these, contact support@xylok.io.

Configuration

The advanced collector is still under development. It’s possible that the configuration format will change over time.

When the collector starts, it looks for a configuration file to control its operation. The following search is performed at the start:

  • ./collect.hcl (current working directory, not the directory where the collector itself is located)
  • $XDG_CONFIG_HOME/xylok/collect.hcl (typically this is ~/.config/xylok/collect.hcl)
  • /etc/xylok/collect.hcl

The first configuration file found is used and the search stops. Alternatively, the configuration path can be specified with the --config option.

Configuration is in Hashicorp Configuration Language (HCL), the configuration language used by many of Hashicorp’s tools like Terraform. A commented example configuration file is available by running the collector with the subcommand config example. During development of the advanced collector, this is the easiest way to maintain an accurate example.

Execution

  1. Download collector binary to a machine in your network. If you’re collecting from a device over the network (i.e., you’re going to collect firewall data from a different machine), ensure the host you download the collector to has access to the target device.

  2. Run the collector with the run subcommand. For example, running the collector from a Linux device would look like this:

    $ chmod +x collector.linux-amd64
$ ./collector.linux-amd64 run
11:16AM INF Starting collector collector=cisco-fmc
...
Add the -h flag to any collector call to get more help information and additional flags you can use.
  1. If there are any remaining configuration questions that need to be answered, you will be prompted to enter that at the command line. Otherwise, the collector will begin running.
  2. At the end, each target in the configuration will have a results-<targetname>-<datetime>.xylok file produced, ready for upload to Xylok.

Results file

The results file from the advanced collector is a different format than the traditional script. It’s line-delimited JSON, with each line (after some header lines) representing the results for one or more checks. Results are compressed and base64-encoded if it will save space, then the result is signed to allow for verification later.

Security Information

Because the collector is offered as a binary that will be introduced onto your network, Xylok offers the following reports below use in evaluating its security. All reports are automatically generated for every Xylok release.

gdoc_arrow_left_alt Windows (Powershell) Devices Downloading Scripts gdoc_arrow_right_alt