vast explore command correlates spatially and temporally related
Work In Progress
This documentation does not represent the current state of the
command. Only some of the options shown below are currently implemented.
First, VAST evaluates the provided query expression. The results serve as input
to generate further queries. Specifying temporal constraints (
--context) apply relative to the #timestamp field of the
results. Specifying spatial constraints can include a join field (
--by) or a
join expression (
--where) that references fields from the result set.
Restricting the exploration to specific sets of types (
--for) works in both
--context parameters create a time box around
every result of the query. For example, this invocation shows all events that
happened up to five minutes after each connection to 192.168.1.10:
--for option restricts the result set to specific types. Note that
--for cannot appear alone but must occur with at least one other of the
selection options. For example, this invocation shows all DNS requests captured
by Zeek up to 60 seconds after a connection to 192.168.1.10:
--by option takes a field name as argument and restricts the set of
returned records to those records that have a field with the same name and
where that field has the same value as the same field in the original record.
In other words, it performs an equi-join over the given field.
For example, to select all outgoing connections from some address up to five minutes after a connection to host 192.168.1.10 was made from that address:
--where option specifies a dynamic filter expression that restricts the
set of returned records to those for which the expression returns true.
Syntactically, the expression must be a boolean expression in the VAST query
language. Inside the expression, the special character
$ refers to an element
of the result set. Semantically, the
where expression generates a new query
for each result of the original query. In every copy of the query, the $
character refers to one specific result of the original query.
For example, the following query first looks for all DNS queries to the host
evil.com captured by Zeek, and then generates a result for every outgoing
connection where the destination IP was one of the IPs inside the
field of the DNS result.
Combined specification of the
--by options results in
the intersection of the result sets of the individual options. Omitting all of
--context options implicitly sets an infinite
range, i.e., it removes the temporal constraint.
Restricts the result set to those records with a timestamp in the interval [t, t+DURATION), where t is the timestamp of a result of the original query.
Restricts the result set to those records with a timestamp in the interval (t-DURATION, t], where t is the timestamp of a result of the original query.
Restricts the result set to those records with a timestamp in the interval (t-DURATION, t+DURATION), where t is the timestamp of a result of the original query.
Restricts the result set to those records for which the EXPRESSION evaluates to
true. The EXPRESSION is a boolean expression. It uses the same syntax as the
vast query language, with the addition of the special character
$ that can be
used to refer to the result of the QUERY.
Restricts the result set to those record types listed in the list RECORD_TYPES. This option must always be accompanied by at least one other of the selection options.
Restricts the result set to those records that have a field named FIELD and where the value of that field equals the value of the field with the same name in the query result.
An invocation of
vast explore will print at most N events. A value of 0
means unlimited. This option only restricts the output of
internally more than N results may be processed while preparing the results.
Restricts the number of results returned by the initial query and by every follow-up query, respectively. A value of 0 means unlimited.
Note that these limits apply before result deduplication, so the total number
of returned results can be less than
N*M, even if more results would be
Selects the output format of the explore command. Valid values are