builder

package
v1.6.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 17, 2026 License: Apache-2.0 Imports: 14 Imported by: 0

Documentation

Overview

Package builder provides programmatic report building functionality for device configurations.

Package builder constructs the markdown sections that make up an opnDossier report. This file centralizes the column-header strings that the report tables share — every builder_*.go assembles tables whose headers reuse the same vocabulary ("Description", "Status", "Interface", etc.) and goconst flagged them as repeated literals.

These constants are deliberately scoped to package builder. They are presentation strings (markdown table headers seen by report readers), not part of any external contract; we may freely rename them as the report design evolves so long as the strings stay in sync across all tables that share a column.

Package builder provides programmatic report building functionality for device configurations.

Index

Constants

View Source 
const MaxDescriptionLength = 80

MaxDescriptionLength is the maximum rune length for table cell descriptions.

View Source 
const TruncationEllipsisLen = 3

TruncationEllipsisLen is the length of the "..." ellipsis used in truncation.

Variables

View Source 
var ErrNilDevice = errors.New("device configuration is nil")

ErrNilDevice is returned when the input device configuration is nil.

Functions

func BuildDHCPStaticLeasesTableSet 

func BuildDHCPStaticLeasesTableSet(leases []common.DHCPStaticLease) *markdown.TableSet

BuildDHCPStaticLeasesTableSet builds the table data for static DHCP leases.

func BuildDHCPSummaryTableSet 

func BuildDHCPSummaryTableSet(scopes []common.DHCPScope) *markdown.TableSet

BuildDHCPSummaryTableSet builds the table data for DHCP scope summary.

func BuildFirewallRulesTableSet 

func BuildFirewallRulesTableSet(rules []common.FirewallRule) *markdown.TableSet

BuildFirewallRulesTableSet builds the table data for firewall rules.

func BuildGroupTableSet 

func BuildGroupTableSet(groups []common.Group) *markdown.TableSet

BuildGroupTableSet builds the table data for system groups.

func BuildInboundNATTableSet 

func BuildInboundNATTableSet(rules []common.InboundNATRule) *markdown.TableSet

BuildInboundNATTableSet builds the table data for inbound NAT rules.

func BuildInterfaceTableSet 

func BuildInterfaceTableSet(interfaces []common.Interface) *markdown.TableSet

BuildInterfaceTableSet builds the table data for network interfaces.

func BuildOutboundNATTableSet 

func BuildOutboundNATTableSet(rules []common.NATRule) *markdown.TableSet

BuildOutboundNATTableSet builds the table data for outbound NAT rules.

func BuildStaticRoutesTableSet 

func BuildStaticRoutesTableSet(routes []common.StaticRoute) *markdown.TableSet

BuildStaticRoutesTableSet builds the table data for static routes.

func BuildSysctlTableSet 

func BuildSysctlTableSet(sysctl []common.SysctlItem) *markdown.TableSet

BuildSysctlTableSet builds the table data for system tunables.

func BuildUserTableSet 

func BuildUserTableSet(users []common.User) *markdown.TableSet

BuildUserTableSet builds the table data for system users.

func BuildVLANTableSet 

func BuildVLANTableSet(vlans []common.VLAN) *markdown.TableSet

BuildVLANTableSet builds the table data for VLAN configurations.

func EscapePipeForMarkdown added in v1.3.0 

func EscapePipeForMarkdown(s string) string

EscapePipeForMarkdown escapes pipe characters for safe display in markdown table cells. Unlike formatters.EscapeTableContent which escapes all markdown special characters, this function only escapes pipes for table cell safety when content is already partially formatted.

func FormatLeaseTime 

func FormatLeaseTime(seconds string) string

FormatLeaseTime converts DHCP lease time seconds to human-readable format. Empty string or "0" returns "-". Invalid input returns the original string. Examples:

  • "" → "-"
  • "0" → "-"
  • "3600" → "1 hour"
  • "7200" → "2 hours"
  • "86400" → "1 day"
  • "172800" → "2 days"
  • "604800" → "1 week"
  • "1209600" → "2 weeks"
  • "5400" → "1 hour, 30 minutes"

func HasAdvancedDHCPConfig 

func HasAdvancedDHCPConfig(dhcp common.DHCPScope) bool

HasAdvancedDHCPConfig checks if any advanced DHCPv4 fields are populated in a DHCPScope.

func HasDHCPv6Config 

func HasDHCPv6Config(dhcp common.DHCPScope) bool

HasDHCPv6Config checks if any DHCPv6 fields are populated in a DHCPScope.

func TruncateString added in v1.3.0 

func TruncateString(s string, maxLen int) string

TruncateString truncates a string to the specified maximum rune length. It is rune-aware to avoid splitting multi-byte UTF-8 characters. Unlike formatters.TruncateDescription which truncates at word boundaries, this function truncates at exact rune positions.

Types

type MarkdownBuilder 

type MarkdownBuilder struct {
	// contains filtered or unexported fields
}

MarkdownBuilder implements the ReportBuilder interface with comprehensive programmatic markdown generation capabilities. MarkdownBuilder is not safe for concurrent use. Create a new instance per goroutine.

func NewMarkdownBuilder 

func NewMarkdownBuilder(opts ...Option) *MarkdownBuilder

NewMarkdownBuilder creates a new MarkdownBuilder instance.

By default the generated timestamp is time.Now() and the tool version is constants.Version. Pass WithGeneratedTime and/or WithVersion to override these defaults (typically for deterministic test output).

func NewMarkdownBuilderWithConfig 

func NewMarkdownBuilderWithConfig(
	config *common.CommonDevice,
	logger *logging.Logger,
	opts ...Option,
) *MarkdownBuilder

NewMarkdownBuilderWithConfig creates a new MarkdownBuilder instance with configuration.

By default the generated timestamp is time.Now() and the tool version is constants.Version. Pass WithGeneratedTime and/or WithVersion to override these defaults (typically for deterministic test output).

func (*MarkdownBuilder) AggregatePackageStats 

func (b *MarkdownBuilder) AggregatePackageStats(packages []common.Package) map[string]int

AggregatePackageStats aggregates statistics about packages.

func (*MarkdownBuilder) AssessRiskLevel 

func (b *MarkdownBuilder) AssessRiskLevel(severity string) string

AssessRiskLevel returns a consistent emoji + text representation.

func (*MarkdownBuilder) AssessServiceRisk 

func (b *MarkdownBuilder) AssessServiceRisk(serviceName string) string

AssessServiceRisk maps common services to risk levels.

func (*MarkdownBuilder) BoolToString 

func (b *MarkdownBuilder) BoolToString(val bool) string

BoolToString converts a boolean value to a standardized string representation with emojis.

func (*MarkdownBuilder) BuildAuditSection added in v1.3.0 

func (b *MarkdownBuilder) BuildAuditSection(data *common.CommonDevice) string

BuildAuditSection builds the compliance audit section from the device's ComplianceResults. If ComplianceResults is nil, it returns an empty string.

When Controls data is available for a plugin, a unified "Plugin Results" table is rendered with a Status column (PASS/FAIL). When b.failuresOnly is true, only FAIL rows are included. When Controls is empty but Findings exist, the legacy findings table is rendered as a fallback.

func (*MarkdownBuilder) BuildComprehensiveReport 

func (b *MarkdownBuilder) BuildComprehensiveReport(data *common.CommonDevice) (string, error)

BuildComprehensiveReport builds a comprehensive markdown report.

func (*MarkdownBuilder) BuildHASection 

func (b *MarkdownBuilder) BuildHASection(data *common.CommonDevice) string

BuildHASection builds the High Availability and CARP configuration section.

func (*MarkdownBuilder) BuildIDSSection added in v1.2.0 

func (b *MarkdownBuilder) BuildIDSSection(data *common.CommonDevice) string

BuildIDSSection builds the IDS/Suricata configuration section.

func (*MarkdownBuilder) BuildIPsecSection 

func (b *MarkdownBuilder) BuildIPsecSection(data *common.CommonDevice) string

BuildIPsecSection builds the IPsec VPN configuration section.

func (*MarkdownBuilder) BuildNetworkSection 

func (b *MarkdownBuilder) BuildNetworkSection(data *common.CommonDevice) string

BuildNetworkSection builds the network configuration section.

func (*MarkdownBuilder) BuildOpenVPNSection 

func (b *MarkdownBuilder) BuildOpenVPNSection(data *common.CommonDevice) string

BuildOpenVPNSection builds the OpenVPN configuration section with servers and clients.

func (*MarkdownBuilder) BuildSecuritySection 

func (b *MarkdownBuilder) BuildSecuritySection(data *common.CommonDevice) string

BuildSecuritySection builds the security configuration section.

func (*MarkdownBuilder) BuildServicesSection 

func (b *MarkdownBuilder) BuildServicesSection(data *common.CommonDevice) string

BuildServicesSection builds the service configuration section.

func (*MarkdownBuilder) BuildStandardReport 

func (b *MarkdownBuilder) BuildStandardReport(data *common.CommonDevice) (string, error)

BuildStandardReport builds a standard markdown report.

func (*MarkdownBuilder) BuildSystemSection 

func (b *MarkdownBuilder) BuildSystemSection(data *common.CommonDevice) string

BuildSystemSection builds the system configuration section.

func (*MarkdownBuilder) CalculateSecurityScore 

func (b *MarkdownBuilder) CalculateSecurityScore(data *common.CommonDevice) int

CalculateSecurityScore computes an overall score (0-100).

func (*MarkdownBuilder) DefaultValue 

func (b *MarkdownBuilder) DefaultValue(value, defaultVal any) any

DefaultValue returns the default value if the primary value is empty.

func (*MarkdownBuilder) EscapeTableContent 

func (b *MarkdownBuilder) EscapeTableContent(content any) string

EscapeTableContent escapes content for safe display in markdown tables.

func (*MarkdownBuilder) ExtractUniqueValues 

func (b *MarkdownBuilder) ExtractUniqueValues(items []string) []string

ExtractUniqueValues extracts unique values from a slice of strings.

func (*MarkdownBuilder) FilterRulesByType 

func (b *MarkdownBuilder) FilterRulesByType(
	rules []common.FirewallRule,
	ruleType common.FirewallRuleType,
) []common.FirewallRule

FilterRulesByType filters firewall rules by their type.

func (*MarkdownBuilder) FilterSystemTunables 

func (b *MarkdownBuilder) FilterSystemTunables(tunables []common.SysctlItem, includeTunables bool) []common.SysctlItem

FilterSystemTunables filters system tunables based on security-related prefixes.

func (*MarkdownBuilder) FormatBytes 

func (b *MarkdownBuilder) FormatBytes(bytes int64) string

FormatBytes formats a byte count as a human-readable string.

func (*MarkdownBuilder) IsEmpty 

func (b *MarkdownBuilder) IsEmpty(value any) bool

IsEmpty checks if a value is considered empty according to Go conventions.

func (*MarkdownBuilder) IsLastInSlice 

func (b *MarkdownBuilder) IsLastInSlice(index int, slice any) bool

IsLastInSlice checks if the given index is the last element in a slice or array.

func (*MarkdownBuilder) SanitizeID 

func (b *MarkdownBuilder) SanitizeID(s string) string

SanitizeID converts a string to a valid HTML/markdown anchor ID.

func (*MarkdownBuilder) SetFailuresOnly added in v1.4.0 

func (b *MarkdownBuilder) SetFailuresOnly(v bool)

SetFailuresOnly configures whether only non-compliant controls are shown in audit reports. When true, passing controls are filtered out of the plugin results table. Not safe for concurrent use — call in the same goroutine as Build/Write methods.

func (*MarkdownBuilder) SetIncludeTunables added in v1.3.0 

func (b *MarkdownBuilder) SetIncludeTunables(v bool)

SetIncludeTunables configures whether all system tunables are included in the report. When false, only security-relevant tunables are shown (filtered by formatters.FilterSystemTunables). Not safe for concurrent use — call in the same goroutine as Build/Write methods.

func (*MarkdownBuilder) ToLower 

func (b *MarkdownBuilder) ToLower(s string) string

ToLower converts a string to lowercase.

func (*MarkdownBuilder) ToUpper 

func (b *MarkdownBuilder) ToUpper(s string) string

ToUpper converts a string to uppercase.

func (*MarkdownBuilder) TrimSpace 

func (b *MarkdownBuilder) TrimSpace(s string) string

TrimSpace removes leading and trailing whitespace from a string.

func (*MarkdownBuilder) TruncateDescription 

func (b *MarkdownBuilder) TruncateDescription(description string, maxLength int) string

TruncateDescription truncates a description to the specified maximum length.

func (*MarkdownBuilder) WriteAuditSection added in v1.3.0 

func (b *MarkdownBuilder) WriteAuditSection(w io.Writer, data *common.CommonDevice) error

WriteAuditSection writes the compliance audit section directly to the writer.

func (*MarkdownBuilder) WriteComprehensiveReport 

func (b *MarkdownBuilder) WriteComprehensiveReport(w io.Writer, data *common.CommonDevice) error

WriteComprehensiveReport writes a complete comprehensive report directly to the writer. This provides the same content as BuildComprehensiveReport but with streaming output.

func (*MarkdownBuilder) WriteDHCPStaticLeasesTable 

func (b *MarkdownBuilder) WriteDHCPStaticLeasesTable(
	md *markdown.Markdown,
	leases []common.DHCPStaticLease,
) *markdown.Markdown

WriteDHCPStaticLeasesTable writes a static DHCP leases table and returns md for chaining.

func (*MarkdownBuilder) WriteDHCPSummaryTable 

func (b *MarkdownBuilder) WriteDHCPSummaryTable(md *markdown.Markdown, scopes []common.DHCPScope) *markdown.Markdown

WriteDHCPSummaryTable writes a DHCP scope summary table and returns md for chaining.

func (*MarkdownBuilder) WriteFirewallRulesTable 

func (b *MarkdownBuilder) WriteFirewallRulesTable(
	md *markdown.Markdown,
	rules []common.FirewallRule,
) *markdown.Markdown

WriteFirewallRulesTable writes a firewall rules table and returns md for chaining.

func (*MarkdownBuilder) WriteGroupTable 

func (b *MarkdownBuilder) WriteGroupTable(md *markdown.Markdown, groups []common.Group) *markdown.Markdown

WriteGroupTable writes a groups table and returns md for chaining.

func (*MarkdownBuilder) WriteInboundNATTable 

func (b *MarkdownBuilder) WriteInboundNATTable(
	md *markdown.Markdown,
	rules []common.InboundNATRule,
) *markdown.Markdown

WriteInboundNATTable writes an inbound NAT rules table and returns md for chaining.

func (*MarkdownBuilder) WriteInterfaceTable 

func (b *MarkdownBuilder) WriteInterfaceTable(md *markdown.Markdown, interfaces []common.Interface) *markdown.Markdown

WriteInterfaceTable writes an interfaces table and returns md for chaining.

func (*MarkdownBuilder) WriteNetworkSection 

func (b *MarkdownBuilder) WriteNetworkSection(w io.Writer, data *common.CommonDevice) error

WriteNetworkSection writes the network configuration section directly to the writer.

func (*MarkdownBuilder) WriteOutboundNATTable 

func (b *MarkdownBuilder) WriteOutboundNATTable(md *markdown.Markdown, rules []common.NATRule) *markdown.Markdown

WriteOutboundNATTable writes an outbound NAT rules table and returns md for chaining.

func (*MarkdownBuilder) WriteSecuritySection 

func (b *MarkdownBuilder) WriteSecuritySection(w io.Writer, data *common.CommonDevice) error

WriteSecuritySection writes the security configuration section directly to the writer.

func (*MarkdownBuilder) WriteServicesSection 

func (b *MarkdownBuilder) WriteServicesSection(w io.Writer, data *common.CommonDevice) error

WriteServicesSection writes the services configuration section directly to the writer.

func (*MarkdownBuilder) WriteStandardReport 

func (b *MarkdownBuilder) WriteStandardReport(w io.Writer, data *common.CommonDevice) error

WriteStandardReport writes a complete standard report directly to the writer. Unlike BuildStandardReport which returns a string, this method streams output section-by-section, reducing peak memory usage for large configurations.

func (*MarkdownBuilder) WriteStaticRoutesTable 

func (b *MarkdownBuilder) WriteStaticRoutesTable(
	md *markdown.Markdown,
	routes []common.StaticRoute,
) *markdown.Markdown

WriteStaticRoutesTable writes a static routes table and returns md for chaining.

func (*MarkdownBuilder) WriteSysctlTable 

func (b *MarkdownBuilder) WriteSysctlTable(md *markdown.Markdown, sysctl []common.SysctlItem) *markdown.Markdown

WriteSysctlTable writes a sysctl tunables table and returns md for chaining.

func (*MarkdownBuilder) WriteSystemSection 

func (b *MarkdownBuilder) WriteSystemSection(w io.Writer, data *common.CommonDevice) error

WriteSystemSection writes the system configuration section directly to the writer.

func (*MarkdownBuilder) WriteUserTable 

func (b *MarkdownBuilder) WriteUserTable(md *markdown.Markdown, users []common.User) *markdown.Markdown

WriteUserTable writes a users table and returns md for chaining.

func (*MarkdownBuilder) WriteVLANTable 

func (b *MarkdownBuilder) WriteVLANTable(md *markdown.Markdown, vlans []common.VLAN) *markdown.Markdown

WriteVLANTable writes a VLAN configurations table and returns md for chaining.

type Option added in v1.5.0 

type Option func(*MarkdownBuilder)

Option configures a MarkdownBuilder at construction time.

Options are applied after the default values are set and override them. Use WithGeneratedTime and WithVersion in tests to produce deterministic, byte-for-byte reproducible output (for golden files, for example).

func WithGeneratedTime added in v1.5.0 

func WithGeneratedTime(t time.Time) Option

WithGeneratedTime sets the "Generated On" timestamp used in report headers.

When the zero time is supplied the default (time.Now at construction) is retained. Tests should pass a fixed UTC time to make report output deterministic and avoid post-hoc regex normalization of golden files.

func WithVersion added in v1.5.0 

func WithVersion(v string) Option

WithVersion sets the tool version string used in the "Parsed By" header line.

When an empty string is supplied the default (constants.Version) is retained. Tests should pass a fixed version to decouple golden files from the build-time -ldflags -X injection of constants.Version.

type ReportBuilder 

type ReportBuilder interface {
	SectionBuilder
	TableWriter
	ReportComposer
}

ReportBuilder defines the contract for programmatic report generation. It composes SectionBuilder, TableWriter, and ReportComposer to provide type-safe, compile-time guaranteed markdown generation.

type ReportComposer added in v1.3.0 

type ReportComposer interface {
	// SetIncludeTunables configures whether all system tunables are included in the report.
	// When false, only tunables matching the security prefixes used by
	// formatters.FilterSystemTunables are shown.
	SetIncludeTunables(v bool)
	// SetFailuresOnly configures whether only non-compliant controls are shown in audit reports.
	SetFailuresOnly(v bool)
	// BuildStandardReport generates a standard configuration report.
	BuildStandardReport(data *common.CommonDevice) (string, error)
	// BuildComprehensiveReport generates a comprehensive configuration report.
	BuildComprehensiveReport(data *common.CommonDevice) (string, error)
}

ReportComposer defines methods for composing full configuration reports. Each method assembles multiple sections into a complete markdown document. SetIncludeTunables and SetFailuresOnly configure rendering behavior before composition.

type SectionBuilder added in v1.3.0 

type SectionBuilder interface {
	// BuildSystemSection builds the system configuration section.
	BuildSystemSection(data *common.CommonDevice) string
	// BuildNetworkSection builds the network configuration section.
	BuildNetworkSection(data *common.CommonDevice) string
	// BuildSecuritySection builds the security configuration section.
	BuildSecuritySection(data *common.CommonDevice) string
	// BuildServicesSection builds the services configuration section.
	BuildServicesSection(data *common.CommonDevice) string
	// BuildIPsecSection builds the IPsec VPN configuration section.
	BuildIPsecSection(data *common.CommonDevice) string
	// BuildOpenVPNSection builds the OpenVPN configuration section.
	BuildOpenVPNSection(data *common.CommonDevice) string
	// BuildHASection builds the High Availability and CARP configuration section.
	BuildHASection(data *common.CommonDevice) string
	// BuildIDSSection builds the IDS/Suricata configuration section.
	BuildIDSSection(data *common.CommonDevice) string
	// BuildAuditSection builds the compliance audit section from the device's ComplianceResults.
	BuildAuditSection(data *common.CommonDevice) string
}

SectionBuilder defines methods for building individual report sections. Each method renders a specific configuration domain into a markdown string or returns an empty string when the section has no data.

type SectionWriter 

type SectionWriter interface {
	// WriteSystemSection writes the system configuration section to the writer.
	WriteSystemSection(w io.Writer, data *common.CommonDevice) error

	// WriteNetworkSection writes the network configuration section to the writer.
	WriteNetworkSection(w io.Writer, data *common.CommonDevice) error

	// WriteSecuritySection writes the security configuration section to the writer.
	WriteSecuritySection(w io.Writer, data *common.CommonDevice) error

	// WriteServicesSection writes the services configuration section to the writer.
	WriteServicesSection(w io.Writer, data *common.CommonDevice) error

	// WriteAuditSection writes the compliance audit section to the writer.
	WriteAuditSection(w io.Writer, data *common.CommonDevice) error

	// WriteStandardReport writes a complete standard report to the writer.
	WriteStandardReport(w io.Writer, data *common.CommonDevice) error

	// WriteComprehensiveReport writes a complete comprehensive report to the writer.
	WriteComprehensiveReport(w io.Writer, data *common.CommonDevice) error
}

SectionWriter defines the interface for streaming report generation. This interface enables memory-efficient output by writing sections directly to an io.Writer instead of accumulating strings in memory.

Implementations should write each section immediately, allowing for: - Lower memory footprint for large configurations - Faster time-to-first-byte for output - Better support for piping to other tools.

type TableWriter added in v1.3.0 

type TableWriter interface {
	// WriteFirewallRulesTable writes a firewall rules table and returns md for chaining.
	WriteFirewallRulesTable(md *markdown.Markdown, rules []common.FirewallRule) *markdown.Markdown
	// WriteInterfaceTable writes an interfaces table and returns md for chaining.
	WriteInterfaceTable(md *markdown.Markdown, interfaces []common.Interface) *markdown.Markdown
	// WriteUserTable writes a users table and returns md for chaining.
	WriteUserTable(md *markdown.Markdown, users []common.User) *markdown.Markdown
	// WriteGroupTable writes a groups table and returns md for chaining.
	WriteGroupTable(md *markdown.Markdown, groups []common.Group) *markdown.Markdown
	// WriteSysctlTable writes a sysctl tunables table and returns md for chaining.
	WriteSysctlTable(md *markdown.Markdown, sysctl []common.SysctlItem) *markdown.Markdown
	// WriteOutboundNATTable writes an outbound NAT rules table and returns md for chaining.
	WriteOutboundNATTable(md *markdown.Markdown, rules []common.NATRule) *markdown.Markdown
	// WriteInboundNATTable writes an inbound NAT/port forward rules table and returns md for chaining.
	WriteInboundNATTable(md *markdown.Markdown, rules []common.InboundNATRule) *markdown.Markdown
	// WriteVLANTable writes a VLAN configurations table and returns md for chaining.
	WriteVLANTable(md *markdown.Markdown, vlans []common.VLAN) *markdown.Markdown
	// WriteStaticRoutesTable writes a static routes table and returns md for chaining.
	WriteStaticRoutesTable(md *markdown.Markdown, routes []common.StaticRoute) *markdown.Markdown
	// WriteDHCPSummaryTable writes a DHCP summary table and returns md for chaining.
	WriteDHCPSummaryTable(md *markdown.Markdown, scopes []common.DHCPScope) *markdown.Markdown
	// WriteDHCPStaticLeasesTable writes a static leases table and returns md for chaining.
	WriteDHCPStaticLeasesTable(md *markdown.Markdown, leases []common.DHCPStaticLease) *markdown.Markdown
}

TableWriter defines methods for writing data tables into a markdown instance. Each method appends a formatted table and returns the markdown for chaining.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.