Skip to content

Command Line Options

Matthias Vallentin edited this page Aug 30, 2014 · 4 revisions

Command Line

VAST supports a variety of command line options to control which components to run with what parameters. There exist both long and short options. Long options have generally the form --prefix.option with prefix representing a group of related options, though a few generic options come without a prefix. Short options act as shortcuts for long options and have the form -c with c being a single character.

Basics

Get a succinct summary of key options:
vast -h
vast --help
Display all available options:
vast -z
vast --advanced

VAST comes with a logger printing to both console and file. The flag --console-verbosity or -v controls the terminal output and --file-verbosity or V controls the verbosity of the log file. These flags take a numeric argument, which have the following meaning:

  • 0: quiet, do not generate any output
  • 1: error, show errors
  • 2: warn, report recoverable or weird conditions
  • 3: info, display informational messages
  • 4: verbose, print more detailed context
  • 5: debug, dump all debugging information

Based on the configure option --log-level, some values may not be available.

Component Control

VAST consists of several components which can roughly be divided into the following three components and their corresponding actors:

  1. core: RECEIVER, TRACKER, SEARCH, ARCHIVE, INDEX
  2. import: IMPORTER
  3. export: EXPORTER

It is possible to deploy VAST in various options. Typically one would deploy a VAST core on a beefy box or a cluster of commodity machines, and spin up IMPORTER and EXPORTER as needed in separate processes. But it is also possible to run multiple components in a single process, thereby bypassing any IPC/network communication and avoiding message serialization. Some restrictions apply which components can run together, as described below.

Core

Launch the core:
vast -C

Import

To get data into VAST, one spawns an IMPORTER and specifies which source format to use.

Import a single Bro log:
vast -I bro -r conn.log

VAST also takes data from standard input by specifying -r -. This is the default and can be omitted. Relying on standard input comes in handy when dealing with compressed logs or when preprocessing the data:

zcat *.log.gz | vast -I bro

One specifies the input format with -I <format>. VAST currently supports Bro logs (bro) and PCAP (pcap). For the PCAP format, VAST can either sniff directly off an interface via -i <iface> or read packets from a trace file via -r <trace>.

Export

The extract data from VAST, one can either use the export component or the interactive query console.

Run the interactive query console:
vast -Q
Execute a single query:
vast -E bro -q `&type == "conn" && :addr in 192.168.0.0/24`

This command spawn an EXPORTER with -E <format> and sends a query, specified with -q <expr>, to SEARCH. Typically SEARCH runs remotely as part of a core deployment. Alternatively, one could spin up SEARCH, ARCHIVE, and INDEX as well and run the entire query in a single process.

One can further control the output format with -o <format> with format currently being bro, json, or pcap. The default output channel is standard output, implicitly specified with -w -. For JSON output, one can specify a file as an alternative, and for Bro log output, one should specify a path to a (existing or non-existing) directory where to store the logs in. Because Bro log output consists of a header that describes the schema, it is only possible to print exactly one event type on standard output, although this restriction does not apply when writing to a directory where VAST can store multiple logs.

Furthermore, when specifying the flag -l <N>, VAST terminates after having received at most N results.

Execute a single query, print results in JSON, and terminate after at most 100 results:
vast -E json -l 100 -q `ts > now - 2h`
You can’t perform that action at this time.