Skip to content

configuration-reference.md

Latest commit

 

History

History
201 lines (145 loc) · 15.2 KB

configuration-reference.md

File metadata and controls

201 lines (145 loc) · 15.2 KB
Raw

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)
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 third-party dynamic .so compliance plugins. Does not affect the built-in stig/sans/firewall plugins (compiled into the binary; always available). Linux/macOS/FreeBSD only — Go's plugin package is not implemented on Windows. Third-party plugins run with full process privileges; opnDossier does not verify signatures. A preflight rejects symlinks, group/world-writable files and directories, and oversize (>64 MiB) files, and every load attempt is logged with a SHA-256 digest. See audit -- Third-Party Plugin Security for the full restriction list, threat scenarios, and operator responsibilities. Failed loads are non-fatal (warnings logged).
Failures only --failures-only boolean false Show only failing controls in compliance tables. Only valid with --mode blue and markdown format.

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

# Show only failing controls in blue mode
opndossier audit config.xml --mode blue --failures-only

# 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

Setting CLI Flag Environment Variable Config File Type Default Description
JSON output --json-output OPNDOSSIER_JSON_OUTPUT json_output boolean false Output validation errors in JSON format

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

Related