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.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.