Skip to content

Configuration Reference

Complete reference for all opnDossier configuration options. Configuration can be set via command-line flags, environment variables, or configuration file with clear precedence order.

For how configuration precedence works, see the Configuration Guide.

Global Options

These options are persistent flags available on all subcommands.

Logging & Output

Setting CLI Flag Environment Variable Config File Type Default Description
Verbose logging --verbose OPNDOSSIER_VERBOSE verbose boolean false Enable debug-level logging
Quiet mode --quiet OPNDOSSIER_QUIET quiet boolean false Suppress all output except errors
Color output --color OPNDOSSIER_COLOR - string "auto" Color output: auto, always, never
No progress --no-progress OPNDOSSIER_NO_PROGRESS no_progress boolean false Disable progress indicators
Timestamps --timestamps - - boolean false Include timestamps in log output
Minimal mode --minimal OPNDOSSIER_MINIMAL minimal boolean false Minimal output (suppress progress/verbose)
JSON output --json-output OPNDOSSIER_JSON_OUTPUT json_output boolean false Output errors in JSON format
Device type --device-type - - string "" Force device type (auto-detected if empty)
Config file --config - - string "" Custom config file path

Convert Command Options

Output Control

Setting CLI Flag Environment Variable Config File Type Default Description
Output file -o, --output OPNDOSSIER_OUTPUT_FILE output_file string stdout Output file path
Format -f, --format OPNDOSSIER_FORMAT format string "markdown" Output format (see below)
Force --force - - boolean false Overwrite existing files without prompt

Supported formats: markdown (md), json, yaml (yml), text (txt), html (htm)

Content & Formatting

Setting CLI Flag Environment Variable Config File Type Default Description
Sections --section OPNDOSSIER_SECTIONS sections string[] [] Sections: system, network, firewall, services, security
Wrap width --wrap OPNDOSSIER_WRAP wrap int -1 Text wrap width (-1=auto, 0=off, >0=cols)
No wrap --no-wrap - - boolean false Disable text wrapping (alias for --wrap 0)
Comprehensive --comprehensive - - boolean false Generate comprehensive detailed reports
Include tunables --include-tunables - - boolean false Include all system tunables in report output (markdown, text, HTML only; JSON/YAML always include all tunables)
Redact --redact - - boolean false Redact sensitive fields (passwords, keys, etc.)

Audit Command Options

The audit command is the dedicated entry point for security audit and compliance checks. See the audit command documentation for complete details.

Audit-Specific Flags

Setting CLI Flag Type Default Description
Audit mode --mode string "blue" Audit mode: blue (defensive audit with compliance), red (attack surface)
Compliance plugins --plugins string[] [] Comma-separated list: stig, sans, firewall. Only valid with --mode blue. Empty = all plugins run.
Plugin directory --plugin-dir string "" Directory containing dynamic .so compliance plugins. Failed plugin loads are non-fatal (warnings logged).

Shared Output Flags

The audit command shares the following output and formatting flags with convert:

  • --format / -f -- Output format (markdown, json, yaml, text, html)
  • --output / -o -- Output file path (cannot be used with multiple input files)
  • --force -- Overwrite existing files without prompt
  • --comprehensive -- Generate detailed comprehensive reports
  • --redact -- Redact sensitive fields (passwords, keys, etc.)
  • --wrap -- Text wrap width
  • --no-wrap -- Disable text wrapping
  • --include-tunables -- Include all system tunables (markdown, text, HTML only)
  • --section -- Filter output to specific sections

Multi-File Audit Behavior

When auditing multiple files, the --output flag cannot be used. Each report is auto-named with an -audit suffix and format extension:

# Single file: --output allowed
opndossier audit config.xml --mode blue -o security-report.md

# Multiple files: auto-named outputs (config1-audit.md, config2-audit.md)
opndossier audit config1.xml config2.xml --mode blue

Path encoding for multi-file output:

  • Bare filenames: config.xml → config-audit.md
  • Paths with directories: prod/site-a/config.xml → prod_site-a_config-audit.md

Usage Examples

# Blue team audit with all plugins (default when no --plugins specified)
opndossier audit config.xml --mode blue

# Blue team audit with specific plugins
opndossier audit config.xml --mode blue --plugins stig,sans

# Red team attack surface analysis
opndossier audit config.xml --mode red

# Custom plugins directory
opndossier audit config.xml --mode blue --plugin-dir /opt/plugins

# Multi-file audit with JSON output
opndossier audit config1.xml config2.xml --mode blue --format json

Display Command Options

Setting CLI Flag Environment Variable Config File Type Default Description
Theme --theme OPNDOSSIER_THEME theme string "" Rendering theme: auto, dark, light, none
Sections --section OPNDOSSIER_SECTIONS sections string[] [] Sections: system, network, firewall, services, security
Wrap width --wrap OPNDOSSIER_WRAP wrap int -1 Text wrap width (-1=auto, 0=off, >0=cols)
No wrap --no-wrap - - boolean false Disable text wrapping
Comprehensive --comprehensive - - boolean false Generate comprehensive reports
Include tunables --include-tunables - - boolean false Include all system tunables in report output (markdown, text, HTML only; JSON/YAML always include all tunables)
Redact --redact - - boolean false Redact sensitive fields in output

Validate Command Options

The validate command uses only global flags. It has no command-specific flags.

Configuration File Format

YAML Configuration File

Create ~/.opnDossier.yaml with your preferred settings:

# Logging Configuration
verbose: false
quiet: false

# Output Settings
format: markdown
wrap: 120
sections: []

# File Paths
input_file: ''
output_file: ''

# Display
theme: ''

# Advanced
no_progress: false
json_output: false
minimal: false

Environment Variables

All configuration options can be set via environment variables with the OPNDOSSIER_ prefix:

# Logging
export OPNDOSSIER_VERBOSE=true
export OPNDOSSIER_QUIET=false

# Output
export OPNDOSSIER_FORMAT=markdown
export OPNDOSSIER_WRAP=100

# File Paths
export OPNDOSSIER_INPUT_FILE="/path/to/config.xml"
export OPNDOSSIER_OUTPUT_FILE="./documentation.md"

Configuration Validation

opnDossier validates configuration values on startup. Invalid values will result in clear error messages:

# Invalid format
$ opndossier convert -f invalid config.xml
Error: invalid format "invalid", must be one of: markdown, md, json, yaml, yml, text, txt, html, htm

# Mutually exclusive flags
$ opndossier --verbose --quiet convert config.xml
Error: if any flags in the group [verbose quiet] are set none of the others can be

# Invalid color mode
$ opndossier --color invalid convert config.xml
Error: invalid color "invalid", must be one of: auto, always, never