...
However, as command outputs are generally unstructured plain text, it is necessary to preprocess these outputs in oder order to provide both efficient mechanisms for checking compliance with an organization's rules. The section on Configuration Parses describes how this works.
...
The configuration status document has no prescribed structure but must be representable as a JSON document - this basically means that you can use nested lists (or arrays), hashes and the usual types of singleton scalars to express and arrange the characteristics that you consider relevant for your your node. Naturally the structure that you choose for your parsers to produce must match up with the properties that your policy rules examine.
...
For example, your high-level policy restriction might be "No MySQL servers may not have a Web server active"; this would be translated into a set of policy statements that find systems which are active MySQL servers and tests whether there is a web server software package installed and/or the ports 80 or 443 are active.
...
- All parser modules must consist of valid perl code, but don't need to be 'complete' perl Packages or Modules, or even use function definitions: the code is executed as given, sequentially, in a sandbox with a few variables and functions predefined.
- Parser modules may not contain "
use Some::Other::Module;" constructs at this point. - The variable "
$input" always corresponds to the textual input of the command to analyze. The parser may consume and destroy the contents. - The variable
"$input_structure" contains a hash reference to the structural structural representation of the command output, IF and Only IF that command output was detected as tree-structured.
Otherwise$input_structureis undef(ined). At this time only Open-AudIT Enterprise imports provide structured command outputs. - The variable
"$node" contains the node name in question, and"$command" is the name of the command that produced this output. This This can be handy if you want to use one parser for two or more command types with similar outputs. - The function '
&logger("severity","some message")' can be used to create diagnostic messages for the opConfig log files. Severity must be one of "debug", "info", "warn", "error" or "fatal". - If the parser detects an non-recoverable problem with the input then it must return a single string, containing an error message.
- If the parser has successfully analyzed an input text, it must build a tree representation of the collected properties (a deep hash in Perl terms) and return a reference to that tree structure.
...
- Parsers currently cannot receive structured document representations for XML or HTML command outputs, only for JSON-formatted material. As a parser isn't allowed to make use of external Perl modules (e.g. an XML parser), this limits acceptable inputs to plain text or JSON. This limitation will likely be removed in a future version of opConfig.
- The output structure of a parser MAY overlap with other parsers' output hashes wrt. to the hash keys; thus a parser MAY amend another's config structure by filling in new material - but you need to note the following restrictions:
- Overwriting of hash structure with a scalar is not supported - the scalar value is ignored.
- Overwriting of a scalar is not supported - the earlier value remains set and the new value is discarded. This affects only entries that have been set explicitelyexplicitly.
- all other cases are merged sensibly (ie. scalars are added to arrays, arrays and hashes are merged, etc.)
Because of this order dependency, parsers must be configured in order of priority.
If you do use overlapping structures, the most specific parsers need to run first, and establish correct values, while other parsers can later only fill in the blanks. If all your parsers are written so as to create separate (sub)structures this is not an issue.- Parsers must not produce structure keys that contain "." (more specificalyspecifically: that contain any characters outside of a-z, A-Z, 0-9, "-" and "_") or keys that are fully numeric.
These restrictions are necessary to make dot-style structure selector expressions possible and unambiguous.
...
While you are fine-tuning your parser behaviours, you will therefore likely want to force opConfig to reparse re-parse and re-extract the command outputs, which is of course possible:
...
An IF statement can contain any number of structure access expressions, operators and Perl constructs. All structure accesses ($THISNTHAT.substruct...) are replaced as described above, then Perl is usd used to evaluate the expression. Evaluation errors (ie. syntactical mistakes) result in "Rule Error" exceptions.
...