framework

Documentation

Overview

Package framework groups the corpus's per-rule framework reference keys (host_rule_state.framework_refs) into user-facing FAMILIES and lists them for the "default compliance lens" picker.

Corpus keys are either OS-specific baselines (stig_rhel9, cis_ubuntu22, …) or OS-agnostic catalogs (nist_800_53, pci_dss_4, srg). A FAMILY is the coarse grouping an operator picks (STIG, CIS, …): the key with a trailing _<os><version> segment stripped. An OS-agnostic key is its own family.

The score-filter queries (fleet score, hosts list) match a family in SQL with the SAME regexp as FamilyOf below — see osSuffixSQL. Keep the two in sync: a rule-state is "in family F" when any of its framework_refs keys, with the OS suffix stripped, equals F.

Index

• Constants
• func BenchmarkFamily(osFamily string) string
• func FamilyOf(key string) string
• func Label(id string) string
• func MatchSQL(paramRef string) string
• func OSResolvedMatchSQL(famRef, osFamilyExpr, osVersionExpr string) string
• type Family
• type Service
  • func NewService(pool *pgxpool.Pool) *Service
  • func (s *Service) EffectiveTarget(ctx context.Context, hostID uuid.UUID, orgDefault string) (string, error)
  • func (s *Service) Families(ctx context.Context) ([]Family, error)

Constants

const OSSuffixSQL = `_(rhel|ubuntu)[0-9]+$`

OSSuffixSQL is the Postgres regexp literal mirroring osSuffix, for the score-filter queries. MUST match osSuffix.

Functions

func BenchmarkFamily

func BenchmarkFamily(osFamily string) string

BenchmarkFamily normalizes a hosts.os_family value to the distro whose corpus keys apply to it. Unknown or empty input is returned lower-cased and unchanged.

func FamilyOf

func FamilyOf(key string) string

FamilyOf returns the family id for a corpus framework key by stripping a trailing OS suffix. A key with no OS suffix is its own family:

stig_rhel9 -> stig ; cis_ubuntu22 -> cis ; nist_800_53 -> nist_800_53

func Label

func Label(id string) string

Label renders a family id for display, with Kensa's label for it. There is no OpenWatch label map: it disagreed with Kensa's ("PCI DSS 4" against "PCI DSS 4.0") and with the frontend's, so one framework read three ways (D-2 S-7). An id Kensa does not know is returned as it is.

func MatchSQL

func MatchSQL(paramRef string) string

MatchSQL returns a SQL boolean fragment (for a WHERE clause on a table with a framework_refs JSONB column) that is TRUE when:

• the bind parameter is NULL (all-rules, no filter), OR
• framework_refs has a key equal to the parameter (a specific corpus key, e.g. "stig_rhel9"), OR
• framework_refs has a key whose family (OS suffix stripped) equals the parameter (a family id, e.g. "stig" matches stig_rhel9/stig_rhel10/…).

paramRef is the placeholder to use (e.g. "$1", "$2"); it must be a fixed literal, never user input. The family regexp mirrors FamilyOf.

func OSResolvedMatchSQL

func OSResolvedMatchSQL(famRef, osFamilyExpr, osVersionExpr string) string

OSResolvedMatchSQL returns a SQL boolean fragment (for a WHERE clause on a table with a framework_refs JSONB column) that is TRUE when framework_refs matches the family in famRef RESOLVED to the host's OWN OS-specific corpus key — NOT the union of every OS variant.

This is the correct filter for a PER-HOST compliance score. MatchSQL is family-aware and matches ANY key in a family (stig -> stig_rhel9 + stig_rhel10 + …); that over-counts a single host, which carries mapped rules for several OS benchmarks at once (a RHEL 9 host has stig_rhel9 AND stig_rhel10 refs). Grading a RHEL 9 host partly against the RHEL 10 STIG is wrong. OSResolvedMatchSQL instead scopes a family to `<family>_<osfamily><major>` (stig on a rhel 9.6 host -> stig_rhel9), so the list/summary/fleet score matches the host-detail tile.

It is TRUE when:

• famRef IS NULL (all rules, no filter), OR
• framework_refs has the OS-resolved key `famRef || '_' || <osfamily><major>` (a family scoped to this host's OS: stig -> stig_rhel9), OR
• framework_refs has a key equal to famRef itself — which covers an OS-neutral family (nist_800_53, pci_dss_4, srg, whose key carries no OS suffix) and an explicitly-passed specific key (stig_rhel9).

famRef, osFamilyExpr, osVersionExpr are SQL expressions (a bind placeholder like "$2", or a column reference like "eff.fam"/"hh.os_family"); they must be fixed literals in code, never user input. The OS token mirrors the corpus key suffix: the BENCHMARK family concatenated with the major version (split_part(os_version,'.',1)) — e.g. rhel+9 = rhel9, ubuntu+22 = ubuntu22.

The family goes through benchmarkFamilySQL rather than a bare lower(), so an EL rebuild resolves to its upstream: an almalinux 9.8 host asks for stig_rhel9 (391 of its rules carry that ref) instead of stig_almalinux9 (which no rule carries). See benchmarkFamily for why that mapping is a stand-in.

Types

type Family

type Family struct {
	ID    string   `json:"id"`
	Label string   `json:"label"`
	Keys  []string `json:"keys"`
}

Family is a user-facing framework grouping with the corpus keys it spans.

type Service

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

Service resolves families from the live corpus (host_rule_state).

func NewService

func NewService(pool *pgxpool.Pool) *Service

NewService builds the resolver.

func (*Service) EffectiveTarget

func (s *Service) EffectiveTarget(ctx context.Context, hostID uuid.UUID, orgDefault string) (string, error)

EffectiveTarget returns the host's effective compliance-target family: its host_effective_target value (the host override, else the oldest site-group target — migration 0051), falling back to orgDefault when neither is set. An empty result means All rules. This is the per-host default lens: a host's score defaults to its target instead of the org default.

func (*Service) Families

func (s *Service) Families(ctx context.Context) ([]Family, error)

Families groups every framework key present in the corpus into families, sorted by id. Empty when no host has been scanned yet.

"The corpus" means the CURRENT corpora (internal/corpus): the rows each host's most recent completed scan evaluated. A framework surviving only on retired rows drops off the list, which is the point. It would otherwise stay selectable as a lens forever, scoring hosts on rules nothing evaluates.