API Reference#

opndossier/
├── cmd/ # CLI commands (Cobra framework)
│ ├── root.go # Root command, global flags, version subcommand
│ ├── context.go # CommandContext for dependency injection
│ ├── convert.go # Convert command
│ ├── display.go # Display command
│ ├── validate.go # Validate command
│ ├── shared_flags.go # Shared flags (section, wrap, audit)
│ ├── exitcodes.go # Structured exit codes
│ └── help.go # Custom help templates
├── internal/ # Private application logic
│ ├── analysis/ # Canonical finding and severity types
│ ├── cfgparser/ # XML parsing and validation
│ ├── config/ # Configuration management (Viper)
│ ├── converter/ # Data conversion and report generation
│ │ ├── builder/ # Programmatic markdown builder
│ │ └── formatters/ # Security scoring, transformers
│ ├── compliance/ # Plugin interfaces
│ ├── plugins/ # Plugin implementations (stig, sans, firewall)
│ ├── audit/ # Audit engine and plugin management
│ ├── display/ # Terminal display formatting
│ ├── export/ # File export functionality
│ ├── logging/ # Structured logging (charmbracelet/log)
│ ├── progress/ # CLI progress indicators
│ ├── processor/ # Security analysis and report generation
│ └── validator/ # Configuration validation
├── pkg/ # Public API packages
│ ├── model/ # Platform-agnostic CommonDevice domain model
│ ├── parser/ # Factory + DeviceParser interface
│ │ └── opnsense/ # OPNsense parser + schema→CommonDevice converter
│ └── schema/
│ └── opnsense/ # Canonical OPNsense XML data model structs
└── main.go # Entry point

// GetRootCmd returns the root Cobra command
func GetRootCmd() *cobra.Command

type CommandContext struct {
    Config *config.Config
    Logger *logging.Logger
}

// Access in subcommands:
cmdCtx := GetCommandContext(cmd)
logger := cmdCtx.Logger
config := cmdCtx.Config

type DeviceParser interface {
    // Parse reads and converts the configuration, returning non-fatal conversion warnings.
    Parse(ctx context.Context, r io.Reader) (*common.CommonDevice, []common.ConversionWarning, error)
    // ParseAndValidate reads, converts, and validates the configuration, returning non-fatal conversion warnings.
    ParseAndValidate(ctx context.Context, r io.Reader) (*common.CommonDevice, []common.ConversionWarning, error)
}

type DeviceParserRegistry struct {
    // Thread-safe registry of parser constructors keyed by device type
}

// ConstructorFunc is the factory function signature for creating DeviceParser instances.
type ConstructorFunc = func(XMLDecoder) DeviceParser

// Register adds a constructor for the given device type. Device type names are
// normalized to lowercase with whitespace trimmed. Panics on duplicate registration,
// nil factory, or empty device type to surface wiring conflicts at startup.
func (r *DeviceParserRegistry) Register(deviceType string, fn ConstructorFunc)

// Get returns the constructor for the given device type, or (nil, false) if not registered.
func (r *DeviceParserRegistry) Get(deviceType string) (ConstructorFunc, bool)

// List returns a sorted slice of all registered device type names.
func (r *DeviceParserRegistry) List() []string

// DefaultRegistry returns the package-level singleton registry.
func DefaultRegistry() *DeviceParserRegistry

// Register is a package-level convenience wrapper around DefaultRegistry().Register().
func Register(deviceType string, fn ConstructorFunc)

// In pkg/parser/opnsense/parser.go
func NewParserFactory(decoder parser.XMLDecoder) parser.DeviceParser {
    return NewParser(decoder)
}

func init() {
    parser.Register("opnsense", NewParserFactory)
}

import (
    "github.com/EvilBit-Labs/opnDossier/pkg/parser"
    _ "github.com/EvilBit-Labs/opnDossier/pkg/parser/opnsense" // self-registers via init()
)

// Create a factory with a custom registry
registry := parser.NewDeviceParserRegistry()
registry.Register("testdevice", testConstructor)
factory := parser.NewFactoryWithRegistry(decoder, registry)

import (
    "github.com/EvilBit-Labs/opnDossier/pkg/parser"
    _ "github.com/EvilBit-Labs/opnDossier/pkg/parser/opnsense" // Required: self-registers via init()
)

factory := parser.NewFactory(cfgparser.NewXMLParser())

file, err := os.Open("config.xml")
if err != nil {
    return err
}
defer file.Close()

// Auto-detect device type and parse to CommonDevice
device, warnings, err := factory.CreateDevice(context.Background(), file, "", false)
if err != nil {
    return fmt.Errorf("parse failed: %w", err)
}
// Handle warnings (e.g., log them)
for _, w := range warnings {
    logger.Warn("conversion warning", "field", w.Field, "message", w.Message)
}

// With validation
device, warnings, err := factory.CreateDevice(context.Background(), file, "", true)
if err != nil {
    return fmt.Errorf("parse and validate failed: %w", err)
}

type CommonDevice struct {
    DeviceType DeviceType `json:"device_type" yaml:"device_type"`
    Version string `json:"version,omitempty" yaml:"version,omitempty"`
    System System `json:"system" yaml:"system,omitempty"`
    Interfaces []Interface `json:"interfaces,omitempty" yaml:"interfaces,omitempty"`
    FirewallRules []FirewallRule `json:"firewallRules,omitempty" yaml:"firewallRules,omitempty"`
    NAT NATConfig `json:"nat" yaml:"nat,omitempty"`
    VPN VPN `json:"vpn" yaml:"vpn,omitempty"`
    Routing Routing `json:"routing" yaml:"routing,omitempty"`
    DNS DNSConfig `json:"dns" yaml:"dns,omitempty"`
    DHCP []DHCPScope `json:"dhcp,omitempty" yaml:"dhcp,omitempty"`
    // ... additional fields (Users, Groups, Certificates, etc.)

    // Computed/enrichment fields (populated by prepareForExport)
    Statistics *Statistics `json:"statistics,omitempty"`
    SecurityAssessment *SecurityAssessment `json:"securityAssessment,omitempty"`
    // ...
}

type FirewallRuleType string

const (
    RuleTypePass FirewallRuleType = "pass" // Allow matching traffic
    RuleTypeBlock FirewallRuleType = "block" // Silently drop matching traffic
    RuleTypeReject FirewallRuleType = "reject" // Drop and send rejection response
)

// Creating rules with typed constants
rule := common.FirewallRule{
    Type: common.RuleTypePass,
    Description: "Allow HTTPS",
    // ...
}

// Comparing rule types
if rule.Type == common.RuleTypeBlock {
    // Handle blocked traffic
}

// Filtering rules by type
passRules := builder.FilterRulesByType(rules, common.RuleTypePass)

type NATOutboundMode string

const (
    OutboundAutomatic NATOutboundMode = "automatic" // Automatic outbound NAT rules
    OutboundHybrid NATOutboundMode = "hybrid" // Combined automatic and manual rules
    OutboundAdvanced NATOutboundMode = "advanced" // Manual rules only
    OutboundDisabled NATOutboundMode = "disabled" // Outbound NAT disabled
)

nat := common.NATConfig{
    OutboundMode: common.OutboundHybrid,
    // ...
}

type IPProtocol string

const (
    IPProtocolInet IPProtocol = "inet" // IPv4
    IPProtocolInet6 IPProtocol = "inet6" // IPv6
)

type FirewallDirection string

const (
    DirectionIn FirewallDirection = "in" // Inbound traffic
    DirectionOut FirewallDirection = "out" // Outbound traffic
    DirectionAny FirewallDirection = "any" // Either direction
)

type LAGGProtocol string

const (
    LAGGProtocolLACP LAGGProtocol = "lacp" // IEEE 802.3ad LACP
    LAGGProtocolFailover LAGGProtocol = "failover" // Active/standby failover
    LAGGProtocolLoadBalance LAGGProtocol = "loadbalance" // Hash-based distribution
    LAGGProtocolRoundRobin LAGGProtocol = "roundrobin" // Round-robin distribution
)

type VIPMode string

const (
    VIPModeCarp VIPMode = "carp" // CARP HA failover
    VIPModeIPAlias VIPMode = "ipalias" // Additional IP address
    VIPModeProxyARP VIPMode = "proxyarp" // ARP proxying
)

type ConversionWarning struct {
    // Field is the dot-path of the problematic field (e.g., "FirewallRules[0].Type").
    Field string
    // Value provides context to identify the affected config element (e.g., rule UUID,
    // gateway name, or certificate description). When the warning is about a missing or
    // empty field, this contains a sibling identifier rather than the empty field itself.
    Value string
    // Message is a human-readable description of the issue.
    Message string
    // Severity indicates the importance of the warning.
    Severity analysis.Severity
}

device, warnings, err := parser.Parse(ctx, reader)
if err != nil {
    return fmt.Errorf("parse failed: %w", err)
}
for _, w := range warnings {
    logger.Warn("conversion issue", 
        "field", w.Field, 
        "value", w.Value, 
        "message", w.Message, 
        "severity", w.Severity)
}
// Continue with device processing

type Converter interface {
    ToMarkdown(ctx context.Context, data *common.CommonDevice) (string, error)
}

type Generator interface {
    Generate(ctx context.Context, cfg *common.CommonDevice, opts Options) (string, error)
}

type StreamingGenerator interface {
    Generator
    GenerateToWriter(ctx context.Context, w io.Writer, cfg *common.CommonDevice, opts Options) error
}

builder := builder.NewMarkdownBuilder()

// Generate a standard report
report, err := builder.BuildStandardReport(doc)

// Generate a comprehensive report
report, err := builder.BuildComprehensiveReport(doc)

// Build individual sections
systemSection := builder.BuildSystemSection(doc)
networkSection := builder.BuildNetworkSection(doc)
securitySection := builder.BuildSecuritySection(doc)
servicesSection := builder.BuildServicesSection(doc)

// Filter rules by type using typed constants
passRules := builder.FilterRulesByType(rules, common.RuleTypePass)
blockRules := builder.FilterRulesByType(rules, common.RuleTypeBlock)
rejectRules := builder.FilterRulesByType(rules, common.RuleTypeReject)

// Standalone security assessment functions
formatters.AssessRiskLevel("high") // Returns: "🟠 High Risk"
formatters.CalculateSecurityScore(doc) // Returns: 0-100
formatters.AssessServiceRisk("telnet") // Returns: risk label string
formatters.FilterSystemTunables(items, true) // Filter security-related tunables
formatters.GroupServicesByStatus(services) // Group by running/stopped

type Config struct {
    InputFile string `mapstructure:"input_file"`
    OutputFile string `mapstructure:"output_file"`
    Verbose bool `mapstructure:"verbose"`
    Quiet bool `mapstructure:"quiet"`
    Theme string `mapstructure:"theme"`
    Format string `mapstructure:"format"`
    Sections []string `mapstructure:"sections"`
    WrapWidth int `mapstructure:"wrap"`
    JSONOutput bool `mapstructure:"json_output"`
    Minimal bool `mapstructure:"minimal"`
    NoProgress bool `mapstructure:"no_progress"`
    // ... additional fields
}

// Load with default config file location
cfg, err := config.LoadConfig("")

// Load with CLI flag binding
cfg, err := config.LoadConfigWithFlags(configFile, cmd.Flags())

// Load with custom Viper instance
cfg, err := config.LoadConfigWithViper(configFile, v)

type FileExporter struct {
    // ...
}

func NewFileExporter(logger *logging.Logger) *FileExporter

// Export writes content to a file with path validation and atomic writes
func (e *FileExporter) Export(ctx context.Context, content, path string) error

logger, err := logging.New(logging.Config{
    Level: "info",
    Format: "text",
    Output: os.Stderr,
    ReportCaller: true,
    ReportTimestamp: true,
})

logger.Info("Processing file", "filename", path, "size", fileSize)
logger.Debug("Detailed info", "key", value)
logger.Warn("Potential issue", "error", err)
logger.Error("Operation failed", "error", err)

// Create scoped loggers
fileLogger := logger.WithFields("operation", "convert", "file", filename)

type Finding struct {
    // Type categorizes the finding (e.g., "security", "performance", "compliance")
    Type string `json:"type"`
    // Severity indicates the severity level of the finding
    Severity string `json:"severity,omitempty"`
    // Title is a brief description of the finding
    Title string `json:"title"`
    // Description provides detailed information about the finding
    Description string `json:"description"`
    // Recommendation suggests how to address the finding
    Recommendation string `json:"recommendation"`
    // Component identifies the configuration component involved
    Component string `json:"component"`
    // Reference provides additional information or documentation links
    Reference string `json:"reference"`

    // Generic references and metadata
    // References contains related standard or control identifiers
    References []string `json:"references,omitempty"`
    // Tags contains classification labels for the finding
    Tags []string `json:"tags,omitempty"`
    // Metadata contains arbitrary key-value pairs for additional context
    Metadata map[string]string `json:"metadata,omitempty"`
}

type Severity string

const (
    SeverityCritical Severity = "critical"
    SeverityHigh Severity = "high"
    SeverityMedium Severity = "medium"
    SeverityLow Severity = "low"
    SeverityInfo Severity = "info"
)

// ValidSeverities returns a fresh copy of all valid severity values
func ValidSeverities() []Severity

// IsValidSeverity checks whether the given severity is a recognized value
func IsValidSeverity(s Severity) bool

// String returns the string representation of the severity
func (s Severity) String() string

type Plugin interface {
    Name() string
    Version() string
    Description() string
    RunChecks(device *common.CommonDevice) []Finding
    GetControls() []Control
    GetControlByID(id string) (*Control, error)
    ValidateConfiguration() error
}

// Finding is a type alias for the canonical analysis.Finding type
type Finding = analysis.Finding

func (pr *PluginRegistry) RunComplianceChecks(
    device *common.CommonDevice,
    pluginNames []string,
    logger *logging.Logger,
) (*ComplianceResult, error)

type ComplianceResult struct {
    Findings []compliance.Finding `json:"findings"`
    PluginFindings map[string][]compliance.Finding `json:"pluginFindings"`
    Compliance map[string]map[string]bool `json:"compliance"`
    Summary *ComplianceSummary `json:"summary"`
    PluginInfo map[string]PluginInfo `json:"pluginInfo"`
}

type ComplianceSummary struct {
    TotalFindings int `json:"totalFindings"`
    CriticalFindings int `json:"criticalFindings"`
    HighFindings int `json:"highFindings"`
    MediumFindings int `json:"mediumFindings"`
    LowFindings int `json:"lowFindings"`
    PluginCount int `json:"pluginCount"`
    Compliance map[string]PluginCompliance `json:"compliance"`
}

// Finding is a type alias for the canonical analysis.Finding type
type Finding = analysis.Finding

// Severity is a type alias for the canonical analysis.Severity type
type Severity = analysis.Severity

// Severity constants re-exported from the canonical analysis package
const (
    SeverityCritical = analysis.SeverityCritical
    SeverityHigh = analysis.SeverityHigh
    SeverityMedium = analysis.SeverityMedium
    SeverityLow = analysis.SeverityLow
    SeverityInfo = analysis.SeverityInfo
)

if err := someOperation(); err != nil {
    return fmt.Errorf("operation context: %w", err)
}

// cfgparser package
var ErrMissingOpnSenseDocumentRoot = errors.New("invalid XML: missing opnsense root element")

// converter package
var ErrNilDevice = errors.New("device configuration is nil")