Skip to content

event-generator_suite_explain.md

Latest commit

 

History

History
122 lines (84 loc) · 5.02 KB

event-generator_suite_explain.md

File metadata and controls

122 lines (84 loc) · 5.02 KB
Raw

event-generator suite explain

Document test(s) YAML description properties

Synopsis

Document test(s) YAML description properties.

This command produces documentation for the YAML description language consumed by event-generator suite run and event-generator suite test. The documentation is generated by following the property hierarchies declared in the schema, so it always reflects the version of the language compiled into the binary in use.

This is especially useful when exploring the language interactively: the user can ask "what fields does the processes context accept?" or "what arguments does openat2 take?" and get an authoritative, version-matched answer without opening the source code.

Property path expressions

The [<propertyPathExpr>] positional argument selects which slice of the schema is documented. The expression is composed by one or multiple dot-separated property path segments. Each segment follows the syntax:

<propertyName>[{<enumProperty1>=<value1>}[{<enumProperty2>=<value2>}...]]

The optional {<enumPropertyX>=<valueX>} parts are called enum requirements. An enum requirement sets the value of an enumerated property to a specific value, which unlocks the documentation for the additional properties that are available only for that value of the enum. Enum requirements are evaluated in their appearing order, so order matters.

Without any positional argument, the command documents the properties available at the root of the YAML document.

Two practical examples (see also PR #255):

# Document tests, context and processes, plus everything available under processes.
event-generator suite explain tests.context.processes

# Document tests, steps, args and how (the openat2-specific arguments), plus everything under how.
event-generator suite explain tests.steps{type=syscall}{syscall=openat2}.args.how

In the second example, the segment steps{type=syscall}{syscall=openat2} carries two enum requirements:

  1. The syscall enum property is available under steps only if the enum property type is set to syscall.
  2. The args property under steps is openat2-specific only if syscall is then set to openat2.

Enum requirements can also be provided as --with clauses instead of being inlined in the path. The two forms are mutually exclusive: the command rejects a path that already contains enum requirements when --with is also passed. This avoids ambiguity around the evaluation order. Equivalent invocations:

event-generator suite explain tests.steps{type=syscall}{syscall=openat2}.args.how
event-generator suite explain tests.steps.args.how --with tests.steps.type=syscall,tests.steps.syscall=openat2

Output formats

The output format is selected by -f/--format:

  • text (default): a custom textual representation, similar to YAML but laid out for readability.
  • yaml: a strict YAML encoding, suitable for being diffed across versions or piped into another YAML tool.
event-generator suite explain [<propertyPathExpr>] [flags]

Examples

Show what a test can contain (start from the root, follow tests):

event-generator suite explain tests

Show the full set of arguments accepted by the write system call step:

event-generator suite explain tests.steps{type=syscall}{syscall=write}.args

Same query, as YAML, useful to feed back into editor tooling:

event-generator suite explain --format yaml tests.steps{type=syscall}{syscall=write}.args

Document the clientServer resource:

event-generator suite explain tests.resources{type=clientServer}

Document every fd resource subtype in turn:

for subtype in file directory pipe event signalfd eventpoll inotify memfd; do
  echo "=== $subtype ==="
  event-generator suite explain --with tests.resources.type=fd,tests.resources.subtype=$subtype tests.resources
done

Options

  -f, --format format   The output format for the documentation; can be 'text' or 'yaml' (default text)
  -h, --help            help for explain
      --with strings    A list of comma-separated enum requirements. An enum requirement is expressed as a <key>=<value> expression. Each key is a dot-separated list of property path segments leading to a property accepting enumerated values. This flag cannot be used if <propertyPathExpr> contains enum requirements. Example: '--with tests.steps.type=syscall,tests.steps.syscall=write'

Options inherited from parent commands

  -c, --config string      Config file path (default $HOME/.falco-event-generator.yaml if exists)
      --logformat string   available formats: "text" or "json" (default "text")
  -l, --loglevel string    Log level (default "info")

SEE ALSO