feat: Add pfSense configuration parser with multi-device abstraction layer

[unclesp1d3r]

Summary

Add comprehensive support for parsing pfSense config.xml configuration files using the existing multi-device abstraction layer. The device-agnostic CommonDevice model, parser factory, and --device-type CLI flag are already in place — what remains is the pfSense-specific schema, parser, and validator, plus updating the markdown converter title and adding test coverage.

Background

pfSense and OPNsense share a common heritage (OPNsense forked from pfSense in 2014), resulting in similar but distinct XML configuration formats. Both store firewall state in a single config.xml file, but the root structure and several field names differ enough to require explicit support.

Key structural differences:

Feature	OPNsense	pfSense
Root element	<opnsense>	<pfsense>
Password field	<passwd>	<bcrypt-hash>
Default admin user	root	admin
Version field	<version>	<version>
Interface naming	Minor variations	Minor variations

Dependencies

Blocked by: #196 (Model restructuring for multi-device support)

Note: As of the current branch, Phase 1 and most of Phase 3 from the original plan have already been implemented as part of #196. This issue now covers the pfSense-specific work only.

Current Architecture (Already Implemented)

The multi-device abstraction layer is complete. The design uses a flat CommonDevice struct (not an interface) with an embedded DeviceType field, and a registry-based parser factory pattern.

Platform-Agnostic Model (pkg/model/device.go) ✅ DONE

type DeviceType string

const (
    DeviceTypeOPNsense DeviceType = "opnsense"
    DeviceTypePfSense  DeviceType = "pfsense"
    DeviceTypeUnknown  DeviceType = ""
)

// CommonDevice is the platform-agnostic root struct — all parsers produce this.
type CommonDevice struct {
    DeviceType DeviceType `json:"device_type" yaml:"device_type"`
    Version    string
    System     System
    // ... all configuration fields
}

Parser Factory (pkg/parser/factory.go) ✅ DONE

// Factory auto-detects device type from the XML root element and delegates
// to the appropriate registered DeviceParser.
func (f *Factory) CreateDevice(
    ctx context.Context,
    r io.Reader,
    deviceTypeOverride common.DeviceType,
    validateMode bool,
) (*common.CommonDevice, []common.ConversionWarning, error)

Parser Registry (pkg/parser/registry.go) ✅ DONE

// DeviceParser implementations register themselves via init() + blank import.
type DeviceParser interface {
    Parse(ctx context.Context, r io.Reader) (*common.CommonDevice, []common.ConversionWarning, error)
    ParseAndValidate(ctx context.Context, r io.Reader) (*common.CommonDevice, []common.ConversionWarning, error)
}

// Register adds a constructor for a device type (called from init()).
func Register(deviceType string, fn ConstructorFunc)

CLI --device-type Flag (cmd/shared_flags.go) ✅ DONE

The --device-type flag, validateDeviceType(), and resolveDeviceType() are already wired into the CLI.

Proposed Solution — What Remains

Proposed Package Layout

pkg/
  schema/
    pfsense/
      document.go      # PfSenseDocument XML structs (xml:"pfsense" root)   (NEW)
  parser/
    pfsense/
      parser.go        # pfSense DeviceParser + init() registration         (NEW)
      parser_test.go   # Unit tests                                         (NEW)
internal/
  validator/
    pfsense.go         # ValidatePfSenseDocument()                          (NEW)
  converter/
    markdown.go        # Update title to use device_type (not hardcoded)   (MODIFY)
testdata/
  pfsense/
    config-2.6.x.xml   # pfSense 2.6.x fixture                             (NEW)
    config-2.7.x.xml   # pfSense 2.7.x fixture                             (NEW)

pfSense Schema Root (pkg/schema/pfsense/document.go)

type PfSenseDocument struct {
    XMLName xml.Name      `xml:"pfsense"`
    Version string        `xml:"version"`
    System  PfSenseSystem `xml:"system"`
    // ...
}

pfSense Parser (pkg/parser/pfsense/parser.go)

// Parser implements DeviceParser for pfSense configuration files.
type Parser struct {
    decoder parser.XMLDecoder
}

// init registers this parser with the global registry.
func init() {
    parser.Register("pfsense", func(d parser.XMLDecoder) parser.DeviceParser {
        return NewParser(d)
    })
}

func (p *Parser) Parse(ctx context.Context, r io.Reader) (*common.CommonDevice, []common.ConversionWarning, error)
func (p *Parser) ParseAndValidate(ctx context.Context, r io.Reader) (*common.CommonDevice, []common.ConversionWarning, error)

Implementation Phases

Phase 1: Multi-Device Abstraction Layer ✅ COMPLETE

• pkg/model/device.go — DeviceType constants, CommonDevice struct with DeviceType field
• pkg/parser/factory.go — Factory.CreateDevice() with auto-detection via root-element peek
• pkg/parser/registry.go — DeviceParserRegistry, DefaultRegistry(), Register()
• pkg/parser/opnsense/parser.go — OPNsense DeviceParser, registered in init()
• internal/cfgparser/ — low-level XML streaming parser (unchanged)

Phase 2: pfSense Parser Implementation ⬜ TODO

• Define pfSense schema structs with xml:"pfsense" root tag in pkg/schema/pfsense/
• Implement streaming token-based DeviceParser in pkg/parser/pfsense/parser.go, registered via init()
• Add ValidatePfSenseDocument() in internal/validator/pfsense.go, reusing existing IP/CIDR/MTU helpers from internal/validator/
• Apply same security hardening: XXE prevention, XML bomb protection, charset normalization (via shared internal/cfgparser reader)

Phase 3: CLI and Converter Integration ⬜ PARTIALLY DONE

• Converters (markdown.go, json.go, yaml.go) already accept *common.CommonDevice — device_type field is already in JSON/YAML output ✅
• --device-type flag already wired in cmd/shared_flags.go ✅
• Remaining: Update the markdown output title in internal/converter/markdown.go — currently hardcoded as "OPNsense Configuration", should be device-type-aware (e.g. "pfSense Configuration")
• Remaining: Optionally add a typed ErrUnsupportedConfigType sentinel to internal/cfgparser/errors.go (currently the factory returns inline fmt.Errorf)

Phase 4: Testing and Documentation ⬜ TODO

• Add pfSense 2.6.x and 2.7.x test fixtures in testdata/pfsense/
• Unit tests in pkg/parser/pfsense/parser_test.go
• Integration tests for Factory.CreateDevice() auto-detection with pfSense configs
• Update README.md to announce pfSense support
• Update docs/dev-guide/architecture.md to describe the registry-based parser pattern

Research & Analysis

• Analyze pfSense config.xml structure across versions
• Document key differences from OPNsense format
• Design abstraction layer approach
• Multi-device abstraction layer implemented (Refactor model layer to support multi-device configurations (OPNsense, pfSense, and future platforms) #196)
• Gather sample pfSense configs for test suite
• Identify edge cases in pfSense format variations

Acceptance Criteria

Functional Requirements:

• pfSense config.xml files parse successfully for versions 2.6.x and 2.7.x
• Auto-detection correctly identifies OPNsense vs pfSense via root element (<pfsense>)
• All output formats (JSON, YAML, Markdown) work with pfSense configurations
• device_type: pfsense appears in JSON/YAML output
• Markdown report title reflects device type (e.g. "pfSense Configuration")
• --device-type pfsense flag allows manual override

Code Quality:

• pfSense parser follows same DeviceParser interface as pkg/parser/opnsense/parser.go
• pfSense parser registered via init() in pkg/parser/pfsense/parser.go
• Common validation rules reused via internal/validator/ helpers
• Comprehensive unit and integration tests (target: ≥ 80% coverage on new code)
• No regression in existing OPNsense parsing functionality

Security:

• XXE injection prevented (Go's xml.Decoder + explicit dec.Entity = map[string]string{})
• XML bomb / entity expansion attacks mitigated (io.LimitReader with DefaultMaxInputSize)
• Proper charset handling via shared internal/cfgparser.charsetReader

Documentation:

• README updated to announce pfSense support
• Usage examples for pfSense configuration files
• Architecture docs describe DeviceParserRegistry and factory pattern

Technical Notes

How to add a new device type (based on existing OPNsense implementation):

1. Create schema structs in pkg/schema/<device>/
2. Create a converter that maps schema → *common.CommonDevice (set DeviceType field)
3. Create a DeviceParser in pkg/parser/<device>/parser.go that calls the converter
4. Register in init(): parser.Register("<root-element>", func(d parser.XMLDecoder) parser.DeviceParser { ... })
5. Blank-import the parser package from main.go to trigger init()

Security — reuse existing infrastructure:

• Input size limiting: use io.LimitReader wrapping the incoming reader (mirrors internal/cfgparser.DefaultMaxInputSize)
• Charset handling: delegate to internal/cfgparser.charsetReader or replicate its logic
• Entity map: set dec.Entity = map[string]string{} on the XML decoder

Backward Compatibility:

• All existing OPNsense tests must continue to pass without modification
• The low-level internal/cfgparser.XMLParser is unchanged; pfSense uses its own XML decoder

Related Issues & PRs

• Blocked by: Refactor model layer to support multi-device configurations (OPNsense, pfSense, and future platforms) #196 (model restructuring for multi-device support) — Phase 1 now complete
• Related: feat: configuration data models and processing #20 (configuration data models)
• Related: feat: implement proper ISO-8859-1 and Windows-1252 XML encoding support #169 (XML encoding / charset support)
• Milestone phase: v1.3.0 Phase 4 — Platform Expansion

[unclesp1d3r]

Dependency: This issue is blocked by #196 (model restructuring for multi-device support).

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Related PRs

#20 - feat: configuration data models and processing [merged]
#74 - fix(templates): resolve comprehensive report structural inconsistencies with summary report [merged]
#77 - feat(NAT): prominently display NAT mode and forwarding rules with enhanced security information [merged]
#169 - feat: implement proper ISO-8859-1 and Windows-1252 XML encoding support [merged]
#181 - feat(compliance): add extended checks for password policy and audit logging [merged]

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[unclesp1d3r]

@coderabbitai Enhance this issue body with additional context and a proposed solution. Improve the issue title and assign the proper labels and other metadata.

[coderabbitai]

Coding Plan

Approach

Add support for parsing pfSense config.xml configuration files by creating a pfSense-specific parser, establishing a device-agnostic abstraction layer, and integrating auto-detection into the CLI so that opnDossier can analyze both OPNsense and pfSense firewalls using the same commands and output formats.

Observations

The project is a CLI tool for processing OPNsense configuration files. The parser layer (internal/parser/xml.go) implements a Parser interface with Parse() and Validate() methods, using streaming XML decoding. The model layer (internal/schema/, internal/model/) defines OpnSenseDocument with accessor methods (SystemConfig(), NetworkConfig(), etc.) that the converter layer uses. The display layer is already device-agnostic, operating on converted strings. Currently, the entire codebase is tightly coupled to OPNsense, with hardcoded root element checks for <opnsense> and OPNsense-specific type names throughout.

Assumptions

Assumption 1: Schema Organization Strategy

Options Considered:

1. Create completely separate pfSense schema with shared interface contract
2. Create shared base types with device-specific extensions and embedding

Chosen Option: 1

Rationale: Separate schemas with a common interface provide clearer boundaries, easier maintenance, and avoid coupling formats that may continue to diverge.

Assumption 2: Parser Package Structure

Options Considered:

1. Create new internal/parser/pfsense/ package as specified in ticket
2. Add pfSense parsing to existing internal/parser/ with file-based separation

Chosen Option: 1

Rationale: Following the ticket's explicit guidance, a separate package provides clear separation and allows each parser to evolve independently.

Assumption 3: Detection Integration Point

Options Considered:

1. Create a detection layer that runs before parsing and returns device type
2. Create a unified parser entry point that peeks at the root element and delegates to the appropriate parser

Chosen Option: 2

Rationale: A unified entry point keeps the API simple for callers—they call one function and get back the appropriate document type without managing detection separately.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Multi-Device Abstraction Layer

Establish the foundational abstractions that enable both OPNsense and pfSense configurations to be handled uniformly. This includes defining a common interface contract, refactoring the parser interface to be device-agnostic, and updating the model layer to support multiple document types.

Task 1: Create Device Document Interface

Define a common interface that both OPNsense and pfSense document types will implement, enabling polymorphic handling throughout the converter and CLI layers.

• Create new file internal/model/device.go defining DeviceDocument interface with methods: GetDeviceType() string, GetSystemConfig(), GetNetworkConfig(), GetSecurityConfig(), GetServiceConfig()
• Add DeviceType constants (e.g., DeviceTypeOPNsense, DeviceTypePfSense) for consistent identification
• Define common grouped config interfaces or types that both device documents return (can be the existing SystemConfig, NetworkConfig, etc. structures)
• Update internal/schema/opnsense.go to add GetDeviceType() string method returning "opnsense" to implement the new interface

Task 2: Refactor Parser Interface for Multi-Device Support

Update the parser interface and factory pattern to support returning different document types while maintaining backward compatibility.

• Create internal/parser/parser.go with a new generic ConfigParser interface: Parse(ctx, reader) (model.DeviceDocument, error) and Validate(doc model.DeviceDocument) error
• Rename existing XMLParser to OpnSenseParser or keep as internal implementation detail
• Create ParseConfig() factory function in internal/parser/ that accepts an io.Reader, detects config type by peeking at root element, and delegates to the appropriate parser
• Maintain backward compatibility by keeping NewXMLParser() working for OPNsense-specific usage
• Add DetectConfigType(r io.Reader) (string, error) helper that reads enough XML to identify root element without consuming the full stream

Task 3: Update Error Types for Multi-Device Context

Extend error handling to be device-agnostic while retaining useful context.

• Update internal/parser/errors.go to rename ErrMissingOpnSenseDocumentRoot to a more generic error or add ErrUnsupportedConfigType for unknown root elements
• Ensure ParseError and ValidationError can carry device type context when relevant
• Add helper functions like IsUnsupportedConfigError(err) for CLI error handling

🤖 Prompt for AI agents

Establish foundational abstractions that enable uniform handling of both
OPNsense and pfSense configurations through a common interface contract and
device-agnostic parser interface.

**Device Document Interface:**
- Create `internal/model/device.go` with a `DeviceDocument` interface containing
methods: `GetDeviceType() string`, `GetSystemConfig()`, `GetNetworkConfig()`,
`GetSecurityConfig()`, `GetServiceConfig()`
- Define `DeviceType` string constants: `DeviceTypeOPNsense` and
`DeviceTypePfSense`
- Define or reuse common grouped config types/interfaces returned by the
accessor methods (existing `SystemConfig`, `NetworkConfig`, etc.)
- Update `internal/schema/opnsense.go`: Add `GetDeviceType()` method to the
OPNsense document type that returns `"opnsense"` to satisfy the interface

**Parser Interface Refactoring:**
- Create `internal/parser/parser.go` with a new `ConfigParser` interface having
methods: `Parse(ctx context.Context, reader io.Reader) (model.DeviceDocument,
error)` and `Validate(doc model.DeviceDocument) error`
- Rename or refactor existing `XMLParser` to `OpnSenseParser` (or keep as
internal implementation)
- Implement `ParseConfig(reader io.Reader) (model.DeviceDocument, error)`
factory function that detects config type and delegates to appropriate parser
- Keep `NewXMLParser()` functional for backward compatibility
- Implement `DetectConfigType(r io.Reader) (string, error)` helper that peeks at
the XML root element without consuming the stream

**Error Type Updates:**
- In `internal/parser/errors.go`, rename `ErrMissingOpnSenseDocumentRoot` to a
generic equivalent or add `ErrUnsupportedConfigType` for unknown root elements
- Ensure `ParseError` and `ValidationError` types can optionally carry device
type context
- Add helper function `IsUnsupportedConfigError(err error) bool` for checking
unsupported config errors

Phase 2: pfSense Parser Implementation

Create the pfSense-specific schema and parser, implementing the same interface contract as OPNsense to enable seamless integration.

Task 1: Create pfSense Schema Structures

Define the Go structs representing pfSense's XML configuration format, mirroring the organization of the OPNsense schema.

• Create internal/schema/pfsense/ directory for pfSense-specific types
• Create document.go with PfSenseDocument struct having xml:"pfsense" root tag
• Implement the DeviceDocument interface on PfSenseDocument with GetDeviceType() returning "pfsense"
• Define core sections: System, Interfaces, Filter, Nat matching pfSense's XML structure
• Note key differences from OPNsense: password field is bcrypt-hash not passwd, default user is admin not root
• Add accessor methods (SystemConfig(), NetworkConfig(), etc.) that return the common grouped config types
• Create internal/model/pfsense.go to re-export pfSense types following the existing pattern

Task 2: Implement pfSense XML Parser

Create the streaming XML parser for pfSense configurations following the established patterns from the OPNsense parser.

• Create internal/parser/pfsense/parser.go implementing the ConfigParser interface
• Follow the same streaming token-based approach as the OPNsense parser for memory efficiency
• Implement Parse(ctx, reader) that expects <pfsense> root element and populates PfSenseDocument
• Implement element handlers following the handleStartElement pattern: route elements to appropriate decoders based on name
• Include the same security measures: XML bomb protection, XXE prevention, charset handling
• Create internal/parser/pfsense/parser_test.go with basic parsing tests

Task 3: Implement pfSense Validation

Add validation logic for pfSense configurations, reusing common validation rules where applicable.

• Create internal/validator/pfsense.go with ValidatePfSenseDocument() function
• Reuse existing validation helpers from internal/validator/ for common checks (IP validation, CIDR, MTU ranges)
• Add pfSense-specific validation rules where the format differs
• Wire validation into the pfSense parser's Validate() method

🤖 Prompt for AI agents

Create pfSense-specific schema structures and parser implementation that
conforms to the same interface contract as OPNsense, enabling seamless
integration.

**pfSense Schema Structures:**
- Create directory `internal/schema/pfsense/`
- Create `document.go` with `PfSenseDocument` struct tagged with `xml:"pfsense"`
as root element
- Implement `DeviceDocument` interface on `PfSenseDocument`: add
`GetDeviceType()` method returning `"pfsense"`
- Define core section structs: `System`, `Interfaces`, `Filter`, `Nat` matching
pfSense XML structure
- Key pfSense-specific differences to implement: password field uses
`bcrypt-hash` instead of `passwd`, default user is `admin` not `root`
- Implement accessor methods (`SystemConfig()`, `NetworkConfig()`,
`GetSecurityConfig()`, `GetServiceConfig()`) that return common grouped config
types
- Create `internal/model/pfsense.go` to re-export pfSense types following
existing pattern

**pfSense XML Parser:**
- Create `internal/parser/pfsense/parser.go` with a type implementing the
`ConfigParser` interface
- Use streaming token-based XML parsing (matching OPNsense parser approach) for
memory efficiency
- Implement `Parse(ctx context.Context, reader io.Reader)` expecting `<pfsense>`
root element, populating `PfSenseDocument`
- Implement element handler functions using `handleStartElement` pattern: route
XML elements to appropriate decoders by element name
- Include security measures: XML bomb protection, XXE prevention, charset
handling
- Create `internal/parser/pfsense/parser_test.go` with basic parsing tests

**pfSense Validation:**
- Create `internal/validator/pfsense.go` with `ValidatePfSenseDocument(doc
*pfsense.PfSenseDocument) error` function
- Reuse existing validation helper functions from `internal/validator/` for
common checks: IP validation, CIDR validation, MTU range checks
- Implement pfSense-specific validation rules where formats differ
- Wire the validation function into the pfSense parser's `Validate()` method

Phase 3: CLI and Converter Integration

Update the CLI commands and converter layer to work with the device-agnostic interface, enabling auto-detection and unified output handling.

Task 1: Update Converter Layer for Multi-Device Support

Modify converters to accept the DeviceDocument interface and produce appropriate output for either device type.

• Update internal/converter/markdown.go: Change ToMarkdown() signature to accept model.DeviceDocument instead of *model.OpnSenseDocument
• Parameterize the document title (currently hardcoded "OPNsense Configuration") to use doc.GetDeviceType() for dynamic headers
• Update internal/converter/json.go and internal/converter/yaml.go similarly—these should work with minimal changes since they use marshaling
• Update internal/converter/builder/builder.go to accept the interface type
• Ensure accessor method calls work through the interface (doc.GetSystemConfig(), etc.)

Task 2: Update CLI Commands

Integrate auto-detection into the main CLI commands so users get seamless support for both config types.

• Update cmd/convert.go: Replace parser.NewXMLParser() calls with parser.ParseConfig() unified entry point
• Update cmd/validate.go and cmd/display.go similarly
• Add optional --device-type flag (values: auto, opnsense, pfsense) to allow explicit override, defaulting to auto
• Update error handling to provide helpful messages when config type cannot be detected
• Ensure progress/status messages indicate detected device type

Task 3: Update Output Formatting

Ensure output clearly indicates the source device type and handles device-specific presentation appropriately.

• Update markdown output header to show device type (e.g., "pfSense Configuration" or "OPNsense Configuration")
• Add device_type field to JSON/YAML output root for programmatic consumers
• Update any OPNsense-specific error messages in internal/converter/markdown.go (e.g., ErrNilOpnSenseDocument) to be device-agnostic

🤖 Prompt for AI agents

Update CLI commands and converter layer to work with the device-agnostic
`DeviceDocument` interface, enabling auto-detection and unified output handling
for both OPNsense and pfSense configs.

**Converter Layer Updates:**
- Update `internal/converter/markdown.go`: Change `ToMarkdown()` function
signature to accept `model.DeviceDocument` instead of `*model.OpnSenseDocument`
- Parameterize the document title: replace hardcoded "OPNsense Configuration"
with dynamic title using `doc.GetDeviceType()` to generate "pfSense
Configuration" or "OPNsense Configuration"
- Update `internal/converter/json.go` and `internal/converter/yaml.go` to accept
`model.DeviceDocument` (minimal changes expected since these use marshaling)
- Update `internal/converter/builder/builder.go` to accept the `DeviceDocument`
interface type
- Verify accessor method calls (`doc.GetSystemConfig()`,
`doc.GetNetworkConfig()`, etc.) work through the interface

**CLI Command Updates:**
- Update `cmd/convert.go`: Replace `parser.NewXMLParser()` calls with
`parser.ParseConfig()` unified entry point
- Update `cmd/validate.go` and `cmd/display.go` similarly to use
`parser.ParseConfig()`
- Add `--device-type` flag to commands with allowed values: `auto`, `opnsense`,
`pfsense`, defaulting to `auto`
- Implement error handling that provides helpful messages when config type
cannot be auto-detected
- Update progress and status messages to display detected device type (e.g.,
"Detected pfSense configuration")

**Output Formatting Updates:**
- Update markdown output header generation to display device-specific titles:
"pfSense Configuration" or "OPNsense Configuration" based on device type
- Add `device_type` field to the root of JSON/YAML output for programmatic
consumers
- Update device-specific error messages in `internal/converter/markdown.go`
(like `ErrNilOpnSenseDocument`) to be device-agnostic

Phase 4: Testing and Documentation

Add comprehensive test coverage for pfSense parsing and update documentation to reflect multi-device support.

Task 1: Add pfSense Test Data

Create sample pfSense configuration files for testing different versions and configurations.

• Add testdata/pfsense/ directory for pfSense-specific test fixtures
• Create sample configs for pfSense 2.6.x and 2.7.x versions
• Include minimal config, full-featured config, and edge case configs
• Add corresponding XSD/DTD schema files for pfSense if available

Task 2: Add Parser Integration Tests

Create comprehensive tests covering pfSense parsing, auto-detection, and multi-device scenarios.

• Create internal/parser/pfsense/parser_test.go with unit tests for pfSense parsing
• Add tests to internal/parser/ for the unified ParseConfig() function testing auto-detection
• Test detection with both OPNsense and pfSense configs
• Test error cases: invalid XML, unknown root elements, malformed configs
• Add converter tests verifying output works correctly with pfSense documents

Task 3: Update Documentation

Document the new multi-device support for users and contributors.

• Update README.md to indicate pfSense support
• Add usage examples showing pfSense config processing
• Document the --device-type flag and auto-detection behavior
• Update docs/dev-guide/architecture.md to describe the multi-device abstraction layer
• Add a section documenting known differences between OPNsense and pfSense config handling

🤖 Prompt for AI agents

Add comprehensive test coverage for pfSense parsing, auto-detection, and
multi-device scenarios, and update documentation to reflect the new multi-device
support.

**pfSense Test Data:**
- Create `testdata/pfsense/` directory for pfSense-specific test fixtures
- Add sample configuration files for pfSense versions 2.6.x and 2.7.x
- Include test configs covering: minimal config, full-featured config, and edge
cases
- Add XSD/DTD schema files for pfSense if available

**Parser Integration Tests:**
- In `internal/parser/pfsense/parser_test.go`, create unit tests for pfSense
parsing: test parsing valid configs, extracting system/network/security configs,
handling malformed pfSense XML
- Add tests in `internal/parser/` for unified `ParseConfig()` function: test
auto-detection with OPNsense configs, test auto-detection with pfSense configs,
verify correct parser delegation
- Add error case tests: invalid XML, unknown root elements, malformed configs
- Add converter tests in `internal/converter/` verifying output generation works
correctly with pfSense documents

**Documentation Updates:**
- Update `README.md`: Add section indicating pfSense support, include usage
examples showing pfSense config file processing
- Document `--device-type` flag: explain allowed values (`auto`, `opnsense`,
`pfsense`), describe auto-detection behavior
- Update `docs/dev-guide/architecture.md`: describe the multi-device abstraction
layer, explain `DeviceDocument` interface and parser factory pattern
- Add documentation section listing known differences between OPNsense and
pfSense configuration handling (e.g., password fields, default users, structural
differences)

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Establish foundational abstractions that enable uniform handling of both
OPNsense and pfSense configurations through a common interface contract and
device-agnostic parser interface.

**Device Document Interface:**
- Create `internal/model/device.go` with a `DeviceDocument` interface containing
methods: `GetDeviceType() string`, `GetSystemConfig()`, `GetNetworkConfig()`,
`GetSecurityConfig()`, `GetServiceConfig()`
- Define `DeviceType` string constants: `DeviceTypeOPNsense` and
`DeviceTypePfSense`
- Define or reuse common grouped config types/interfaces returned by the
accessor methods (existing `SystemConfig`, `NetworkConfig`, etc.)
- Update `internal/schema/opnsense.go`: Add `GetDeviceType()` method to the
OPNsense document type that returns `"opnsense"` to satisfy the interface

**Parser Interface Refactoring:**
- Create `internal/parser/parser.go` with a new `ConfigParser` interface having
methods: `Parse(ctx context.Context, reader io.Reader) (model.DeviceDocument,
error)` and `Validate(doc model.DeviceDocument) error`
- Rename or refactor existing `XMLParser` to `OpnSenseParser` (or keep as
internal implementation)
- Implement `ParseConfig(reader io.Reader) (model.DeviceDocument, error)`
factory function that detects config type and delegates to appropriate parser
- Keep `NewXMLParser()` functional for backward compatibility
- Implement `DetectConfigType(r io.Reader) (string, error)` helper that peeks at
the XML root element without consuming the stream

**Error Type Updates:**
- In `internal/parser/errors.go`, rename `ErrMissingOpnSenseDocumentRoot` to a
generic equivalent or add `ErrUnsupportedConfigType` for unknown root elements
- Ensure `ParseError` and `ValidationError` types can optionally carry device
type context
- Add helper function `IsUnsupportedConfigError(err error) bool` for checking
unsupported config errors
===============================================================================

Task: 2

Create pfSense-specific schema structures and parser implementation that
conforms to the same interface contract as OPNsense, enabling seamless
integration.

**pfSense Schema Structures:**
- Create directory `internal/schema/pfsense/`
- Create `document.go` with `PfSenseDocument` struct tagged with `xml:"pfsense"`
as root element
- Implement `DeviceDocument` interface on `PfSenseDocument`: add
`GetDeviceType()` method returning `"pfsense"`
- Define core section structs: `System`, `Interfaces`, `Filter`, `Nat` matching
pfSense XML structure
- Key pfSense-specific differences to implement: password field uses
`bcrypt-hash` instead of `passwd`, default user is `admin` not `root`
- Implement accessor methods (`SystemConfig()`, `NetworkConfig()`,
`GetSecurityConfig()`, `GetServiceConfig()`) that return common grouped config
types
- Create `internal/model/pfsense.go` to re-export pfSense types following
existing pattern

**pfSense XML Parser:**
- Create `internal/parser/pfsense/parser.go` with a type implementing the
`ConfigParser` interface
- Use streaming token-based XML parsing (matching OPNsense parser approach) for
memory efficiency
- Implement `Parse(ctx context.Context, reader io.Reader)` expecting `<pfsense>`
root element, populating `PfSenseDocument`
- Implement element handler functions using `handleStartElement` pattern: route
XML elements to appropriate decoders by element name
- Include security measures: XML bomb protection, XXE prevention, charset
handling
- Create `internal/parser/pfsense/parser_test.go` with basic parsing tests

**pfSense Validation:**
- Create `internal/validator/pfsense.go` with `ValidatePfSenseDocument(doc
*pfsense.PfSenseDocument) error` function
- Reuse existing validation helper functions from `internal/validator/` for
common checks: IP validation, CIDR validation, MTU range checks
- Implement pfSense-specific validation rules where formats differ
- Wire the validation function into the pfSense parser's `Validate()` method
===============================================================================

Task: 3

Update CLI commands and converter layer to work with the device-agnostic
`DeviceDocument` interface, enabling auto-detection and unified output handling
for both OPNsense and pfSense configs.

**Converter Layer Updates:**
- Update `internal/converter/markdown.go`: Change `ToMarkdown()` function
signature to accept `model.DeviceDocument` instead of `*model.OpnSenseDocument`
- Parameterize the document title: replace hardcoded "OPNsense Configuration"
with dynamic title using `doc.GetDeviceType()` to generate "pfSense
Configuration" or "OPNsense Configuration"
- Update `internal/converter/json.go` and `internal/converter/yaml.go` to accept
`model.DeviceDocument` (minimal changes expected since these use marshaling)
- Update `internal/converter/builder/builder.go` to accept the `DeviceDocument`
interface type
- Verify accessor method calls (`doc.GetSystemConfig()`,
`doc.GetNetworkConfig()`, etc.) work through the interface

**CLI Command Updates:**
- Update `cmd/convert.go`: Replace `parser.NewXMLParser()` calls with
`parser.ParseConfig()` unified entry point
- Update `cmd/validate.go` and `cmd/display.go` similarly to use
`parser.ParseConfig()`
- Add `--device-type` flag to commands with allowed values: `auto`, `opnsense`,
`pfsense`, defaulting to `auto`
- Implement error handling that provides helpful messages when config type
cannot be auto-detected
- Update progress and status messages to display detected device type (e.g.,
"Detected pfSense configuration")

**Output Formatting Updates:**
- Update markdown output header generation to display device-specific titles:
"pfSense Configuration" or "OPNsense Configuration" based on device type
- Add `device_type` field to the root of JSON/YAML output for programmatic
consumers
- Update device-specific error messages in `internal/converter/markdown.go`
(like `ErrNilOpnSenseDocument`) to be device-agnostic
===============================================================================

Task: 4

Add comprehensive test coverage for pfSense parsing, auto-detection, and
multi-device scenarios, and update documentation to reflect the new multi-device
support.

**pfSense Test Data:**
- Create `testdata/pfsense/` directory for pfSense-specific test fixtures
- Add sample configuration files for pfSense versions 2.6.x and 2.7.x
- Include test configs covering: minimal config, full-featured config, and edge
cases
- Add XSD/DTD schema files for pfSense if available

**Parser Integration Tests:**
- In `internal/parser/pfsense/parser_test.go`, create unit tests for pfSense
parsing: test parsing valid configs, extracting system/network/security configs,
handling malformed pfSense XML
- Add tests in `internal/parser/` for unified `ParseConfig()` function: test
auto-detection with OPNsense configs, test auto-detection with pfSense configs,
verify correct parser delegation
- Add error case tests: invalid XML, unknown root elements, malformed configs
- Add converter tests in `internal/converter/` verifying output generation works
correctly with pfSense documents

**Documentation Updates:**
- Update `README.md`: Add section indicating pfSense support, include usage
examples showing pfSense config file processing
- Document `--device-type` flag: explain allowed values (`auto`, `opnsense`,
`pfsense`), describe auto-detection behavior
- Update `docs/dev-guide/architecture.md`: describe the multi-device abstraction
layer, explain `DeviceDocument` interface and parser factory pattern
- Add documentation section listing known differences between OPNsense and
pfSense configuration handling (e.g., password fields, default users, structural
differences)

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For assumption 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[unclesp1d3r]

@coderabbitai Enhance this issue body with additional context and a proposed solution. Improve the issue title and assign the proper labels and other metadata.