Documentation
¶
Overview ¶
Package pfsense provides a pfSense-specific parser and converter that transforms pfsense.Document (pkg/schema/pfsense, imported without an alias and therefore not usable as a doc-link target within this package) into the platform-agnostic common.CommonDevice (pkg/model). The bracketed name matches the import alias used in this file.
Registration ¶
This package self-registers its Parser with the global parser.DefaultRegistry under the device type name "pfsense" from an init() function. Consumers that want the pfSense parser available through parser.Factory must add a blank import:
import _ "github.com/EvilBit-Labs/opnDossier/pkg/parser/pfsense"
See parser for the full registration contract.
Self-managed XML decoding ¶
Unlike the OPNsense parser, this package does not use the injected parser.OPNsenseXMLDecoder because that interface returns *opnsense.OpnSenseDocument (pkg/schema/opnsense), which is incompatible with pfsense.Document. The OPNsenseXMLDecoder parameter on NewParser is accepted but ignored — it exists so that NewParserFactory (the function registered with parser.DefaultRegistry) matches the parser.ConstructorFunc signature. pfSense input is decoded internally with the shared security-hardened decoder from parser.NewSecureXMLDecoder.
Validation injection ¶
Semantic validation lives in internal/validator, which pkg/ cannot import directly. SetValidator is the injection point: call it once at startup from cmd/ (or an equivalent composition root) to wire validation into Parser.ParseAndValidate. The installed validator is locked in by a sync.Once — subsequent calls are silently ignored, which prevents a dynamically loaded plugin's init() from overwriting the CLI-installed validator (see GOTCHAS.md §20). When no validator has been installed, ParseAndValidate falls back to structural parsing only, which is the safe default for library consumers that do not want to couple to opnDossier's validator.
Dependencies ¶
This package has no internal/ dependencies in production code; it depends only on other public pkg/ packages (pkg/model, pkg/parser, pkg/schema/pfsense, and pkg/schema/opnsense — the latter supplies shared DHCP/Unbound types reused by the converters) plus the standard library.
Index ¶
- Constants
- Variables
- func ConvertDocument(doc *pfsense.Document) (*common.CommonDevice, []common.ConversionWarning, error)
- func IsKnownGap(field string) bool
- func KnownGaps() []string
- func NewParserFactory(decoder parser.OPNsenseXMLDecoder) parser.DeviceParser
- func SetValidator(fn func(doc *pfsense.Document) error)
- type Parser
Constants ¶
const PfsenseKnownGapMessage = "not yet implemented in pfSense converter"
PfsenseKnownGapMessage is the stable message text emitted for every CommonDevice subsystem listed in [pfsenseKnownGaps]. Consumers (compliance plugins, audit filters) can match on this exact substring to identify warnings that report "this subsystem is not yet implemented by the pfSense converter" rather than "the XML configuration omits the subsystem". The wording is part of the public contract and will remain stable across minor releases.
Variables ¶
var ErrNilDocument = errors.New("pfsense converter: received nil document")
ErrNilDocument is returned when ToCommonDevice receives a nil document.
Functions ¶
func ConvertDocument ¶
func ConvertDocument(doc *pfsense.Document) (*common.CommonDevice, []common.ConversionWarning, error)
ConvertDocument transforms a parsed pfSense Document into a platform-agnostic CommonDevice along with any non-fatal conversion warnings. This is a convenience function that creates a fresh converter internally.
func IsKnownGap ¶ added in v1.5.0
IsKnownGap reports whether field names a CommonDevice subsystem that the pfSense converter knowingly does not populate. The comparison is case-sensitive and matches the exact CommonDevice field name (e.g. "HighAvailability", "KeaDHCP"). Callers outside the parser use this to avoid false-PASS results when reasoning about pfSense coverage — see docs/user-guide/device-support-matrix.md for the human-readable table.
IsKnownGap is safe for concurrent use; the underlying slice is never mutated after package init.
func KnownGaps ¶ added in v1.5.0
func KnownGaps() []string
KnownGaps returns a fresh copy of [pfsenseKnownGaps] so callers can iterate the full list (e.g. in tests that assert one warning per gap) without risking mutation of the package-level slice.
func NewParserFactory ¶
func NewParserFactory(decoder parser.OPNsenseXMLDecoder) parser.DeviceParser
NewParserFactory returns a new DeviceParser configured for pfSense devices. It satisfies the factory function signature required by DeviceParserRegistry.
func SetValidator ¶ added in v1.5.0
SetValidator installs fn as the pfSense semantic validator used by Parser.ParseAndValidate. Only the first call per process has any effect; subsequent calls are silently ignored. This one-shot semantics is the enforcement point against a dynamically loaded plugin's init() stomping the CLI-installed validator (see GOTCHAS.md §20).
Passing a nil fn locks the slot in the "no validator" state — equivalent to never calling SetValidator, except that future SetValidator calls are still ignored. Parser.ParseAndValidate falls back to structural parsing only when no validator is installed.
SetValidator is safe to call from any goroutine; concurrent callers race to be the one the sync.Once picks, but only one wins and the others are silently dropped.
Types ¶
type Parser ¶
type Parser struct {
// contains filtered or unexported fields
}
Parser implements the DeviceParser interface for pfSense configuration files. It manages its own XML decoding because the shared OPNsenseXMLDecoder returns *schema.OpnSenseDocument which is incompatible with pfsense.Document.
func NewParser ¶
func NewParser(_ parser.OPNsenseXMLDecoder) *Parser
NewParser returns a new pfSense Parser. The decoder parameter is accepted for compatibility with the ConstructorFunc signature but is not used because pfSense requires its own XML decoding pipeline.
func (*Parser) Parse ¶
func (p *Parser) Parse(ctx context.Context, r io.Reader) (*common.CommonDevice, []common.ConversionWarning, error)
Parse reads a pfSense XML configuration from r (structural parsing only, no semantic validation) and returns a platform-agnostic CommonDevice along with any non-fatal conversion warnings.
func (*Parser) ParseAndValidate ¶
func (p *Parser) ParseAndValidate( ctx context.Context, r io.Reader, ) (*common.CommonDevice, []common.ConversionWarning, error)
ParseAndValidate reads a pfSense XML configuration from r, runs structural parsing and semantic validation, and returns a platform-agnostic CommonDevice along with any non-fatal conversion warnings. If no validator has been installed via SetValidator (e.g., by cmd/root.go), falls back to structural parsing only.
Source Files