lints and tests

Signed-off-by: Eddie Knight <knight@linux.com>

Author: eddie-knight

control_catalog_yaml.go

@@ -0,0 +1,41 @@
+package gemara
+
+import "github.com/goccy/go-yaml"
+
+// UnmarshalYAML allows decoding control catalogs from older/alternate YAML schemas.
+// It supports mapping `families` -> `groups`.
+func (c *ControlCatalog) UnmarshalYAML(data []byte) error {
+	type controlCatalogYAML struct {
+		Groups   []Group `yaml:"groups,omitempty"`
+		Families []Group `yaml:"families,omitempty"`
+
+		Title    string  `yaml:"title"`
+		Metadata Metadata `yaml:"metadata"`
+
+		Extends []ArtifactMapping `yaml:"extends,omitempty"`
+		Imports []MultiEntryMapping `yaml:"imports,omitempty"`
+
+		Controls []Control `yaml:"controls,omitempty"`
+	}
+
+	var tmp controlCatalogYAML
+	if err := yaml.Unmarshal(data, &tmp); err != nil {
+		return err
+	}
+
+	c.Groups = tmp.Groups
+	if len(c.Groups) == 0 {
+		c.Groups = tmp.Families
+	}
+	c.Controls = tmp.Controls
+
+	c.Title = tmp.Title
+	c.Metadata = tmp.Metadata
+	c.Extends = tmp.Extends
+
+	// Keep imports exactly as decoded (nil vs empty can matter to tests).
+	c.Imports = tmp.Imports
+
+	return nil
+}
+

document_example_test.go

@@ -15,12 +15,12 @@ func ExampleGuidanceCatalog() {
 ---
 **Front Matter:** {{ .FrontMatter }}
 ---
-{{- $doc := . }}{{ range .Families }}
+{{- $doc := . }}{{ range .Groups }}
 
 ### {{ .Title }} ({{ .Id }})
 {{ .Description }}
 #### Guidelines:
-{{- $familyId := .Id }}{{ range $doc.Guidelines }}{{ if eq .Family $familyId }}
+{{- $familyId := .Id }}{{ range $doc.Guidelines }}{{ if eq .Group $familyId }}
 
 ##### {{ .Title }} ({{ .Id }})
 **Objective:** {{ .Objective }}

enums.go

@@ -33,6 +33,15 @@ type RelationshipType int
 // MethodType enumerates the category of evaluation or enforcement method.
 type MethodType int
 
+// ModeType enumerates whether enforcement/evaluation is manual or automated.
+type ModeType int
+
+// Disposition enumerates the possible enforcement outcomes.
+type Disposition int
+
+// EnforcementStep is a reference to the code path that performed an enforcement action.
+type EnforcementStep string
+
 // Severity defines the allowed impact levels for a risk.
 type Severity int
 
@@ -112,6 +121,17 @@ const (
 	MethodGate
 )
 
+const (
+	ModeManual ModeType = iota
+	ModeAutomated
+)
+
+const (
+	DispositionEnforced Disposition = iota
+	DispositionTolerated
+	DispositionClear
+)
+
 const (
 	SeverityLow Severity = iota
 	SeverityMedium
@@ -276,6 +296,28 @@ var (
 		"Gate":            MethodGate,
 	}
 
+	modeTypeToString = map[ModeType]string{
+		ModeManual:    "Manual",
+		ModeAutomated: "Automated",
+	}
+
+	stringToModeType = map[string]ModeType{
+		"Manual":    ModeManual,
+		"Automated": ModeAutomated,
+	}
+
+	dispositionToString = map[Disposition]string{
+		DispositionEnforced: "Enforced",
+		DispositionTolerated: "Tolerated",
+		DispositionClear:    "Clear",
+	}
+
+	stringToDisposition = map[string]Disposition{
+		"Enforced":  DispositionEnforced,
+		"Tolerated": DispositionTolerated,
+		"Clear":     DispositionClear,
+	}
+
 	severityToString = map[Severity]string{
 		SeverityLow:      "Low",
 		SeverityMedium:   "Medium",
@@ -598,6 +640,60 @@ func (m *MethodType) UnmarshalJSON(data []byte) error {
 	return unmarshalJSONEnum(data, stringToMethodType, "MethodType", m)
 }
 
+func (m ModeType) String() string {
+	if s, ok := modeTypeToString[m]; ok {
+		return s
+	}
+	return fmt.Sprintf("ModeType(%d)", m)
+}
+
+// MarshalYAML ensures that ModeType is serialized as a string in YAML
+func (m ModeType) MarshalYAML() (interface{}, error) {
+	return marshalYAMLString(m)
+}
+
+// MarshalJSON ensures that ModeType is serialized as a string in JSON
+func (m ModeType) MarshalJSON() ([]byte, error) {
+	return marshalJSONString(m)
+}
+
+// UnmarshalYAML ensures that ModeType can be deserialized from a YAML string
+func (m *ModeType) UnmarshalYAML(data []byte) error {
+	return unmarshalYAMLEnum(data, stringToModeType, "ModeType", m)
+}
+
+// UnmarshalJSON ensures that ModeType can be deserialized from a JSON string
+func (m *ModeType) UnmarshalJSON(data []byte) error {
+	return unmarshalJSONEnum(data, stringToModeType, "ModeType", m)
+}
+
+func (d Disposition) String() string {
+	if s, ok := dispositionToString[d]; ok {
+		return s
+	}
+	return fmt.Sprintf("Disposition(%d)", d)
+}
+
+// MarshalYAML ensures that Disposition is serialized as a string in YAML
+func (d Disposition) MarshalYAML() (interface{}, error) {
+	return marshalYAMLString(d)
+}
+
+// MarshalJSON ensures that Disposition is serialized as a string in JSON
+func (d Disposition) MarshalJSON() ([]byte, error) {
+	return marshalJSONString(d)
+}
+
+// UnmarshalYAML ensures that Disposition can be deserialized from a YAML string
+func (d *Disposition) UnmarshalYAML(data []byte) error {
+	return unmarshalYAMLEnum(data, stringToDisposition, "Disposition", d)
+}
+
+// UnmarshalJSON ensures that Disposition can be deserialized from a JSON string
+func (d *Disposition) UnmarshalJSON(data []byte) error {
+	return unmarshalJSONEnum(data, stringToDisposition, "Disposition", d)
+}
+
 func (s Severity) String() string {
 	if str, ok := severityToString[s]; ok {
 		return str

enums_test.go

@@ -232,6 +232,43 @@ func TestMethodTypeString(t *testing.T) {
 	}
 }
 
+func TestModeTypeString(t *testing.T) {
+	tests := []struct {
+		v        ModeType
+		expected string
+	}{
+		{ModeManual, "Manual"},
+		{ModeAutomated, "Automated"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.expected, func(t *testing.T) {
+			if got := tt.v.String(); got != tt.expected {
+				t.Errorf("String() = %q, want %q", got, tt.expected)
+			}
+		})
+	}
+}
+
+func TestDispositionString(t *testing.T) {
+	tests := []struct {
+		v        Disposition
+		expected string
+	}{
+		{DispositionEnforced, "Enforced"},
+		{DispositionTolerated, "Tolerated"},
+		{DispositionClear, "Clear"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.expected, func(t *testing.T) {
+			if got := tt.v.String(); got != tt.expected {
+				t.Errorf("String() = %q, want %q", got, tt.expected)
+			}
+		})
+	}
+}
+
 func TestSeverityString(t *testing.T) {
 	tests := []struct {
 		v        Severity

gemaraconv/catalog.go

@@ -35,19 +35,19 @@ func CatalogToOSCAL(catalog *gemara.ControlCatalog, opts ...GenerateOption) (osc
 	}
 
 	familyMap := make(map[string]gemara.Group)
-	for _, family := range catalog.Families {
+	for _, family := range catalog.Groups {
 		familyMap[family.Id] = family
 	}
 
-	controlsByFamily := make(map[string][]gemara.Control)
+	controlsByGroup := make(map[string][]gemara.Control)
 	for _, control := range catalog.Controls {
-		controlsByFamily[control.Family] = append(controlsByFamily[control.Family], control)
+		controlsByGroup[control.Group] = append(controlsByGroup[control.Group], control)
 	}
 
 	catalogGroups := []oscal.Group{}
 
-	for _, family := range catalog.Families {
-		controls := controlsByFamily[family.Id]
+	for _, family := range catalog.Groups {
+		controls := controlsByGroup[family.Id]
 		if len(controls) == 0 {
 			continue
 		}

gemaraconv/catalog_test.go

@@ -25,7 +25,7 @@ var testCases = []struct {
 				Version: "devel",
 			},
 			Title: "Test Catalog",
-			Families: []gemara.Group{
+			Groups: []gemara.Group{
 				{
 					Id:          "AC",
 					Title:       "access-control",
@@ -34,9 +34,9 @@ var testCases = []struct {
 			},
 			Controls: []gemara.Control{
 				{
-					Id:     "AC-01",
-					Family: "AC",
-					Title:  "Access Control Policy",
+					Id:    "AC-01",
+					Group: "AC",
+					Title: "Access Control Policy",
 					AssessmentRequirements: []gemara.AssessmentRequirement{
 						{
 							Id:   "AC-01.1",
@@ -58,7 +58,7 @@ var testCases = []struct {
 				Version: "devel",
 			},
 			Title: "Test Catalog Multiple",
-			Families: []gemara.Group{
+			Groups: []gemara.Group{
 				{
 					Id:          "AC",
 					Title:       "access-control",
@@ -72,9 +72,9 @@ var testCases = []struct {
 			},
 			Controls: []gemara.Control{
 				{
-					Id:     "AC-01",
-					Family: "AC",
-					Title:  "Access Control Policy",
+					Id:    "AC-01",
+					Group: "AC",
+					Title: "Access Control Policy",
 					AssessmentRequirements: []gemara.AssessmentRequirement{
 						{
 							Id:   "AC-01.1",
@@ -83,9 +83,9 @@ var testCases = []struct {
 					},
 				},
 				{
-					Id:     "BR-01",
-					Family: "BR",
-					Title:  "Business Requirements Policy",
+					Id:    "BR-01",
+					Group: "BR",
+					Title: "Business Requirements Policy",
 					AssessmentRequirements: []gemara.AssessmentRequirement{
 						{
 							Id:   "BR-01.1",
@@ -128,10 +128,10 @@ func TestFromCatalog(t *testing.T) {
 			assert.NotEmpty(t, oscalCatalog.UUID)
 			assert.Equal(t, tt.expectedTitle, oscalCatalog.Metadata.Title)
 			assert.Equal(t, tt.catalog.Metadata.Version, oscalCatalog.Metadata.Version)
-			assert.Equal(t, len(tt.catalog.Families), len(*oscalCatalog.Groups))
+			assert.Equal(t, len(tt.catalog.Groups), len(*oscalCatalog.Groups))
 
 			// Compare each control family
-			for i, family := range tt.catalog.Families {
+			for i, family := range tt.catalog.Groups {
 				groups := (*oscalCatalog.Groups)
 				group := groups[i]
 				assert.Equal(t, family.Id, group.ID)

gemaraconv/guidance.go

@@ -30,7 +30,7 @@ func GuidanceToOSCAL(g *gemara.GuidanceCatalog, guidanceDocHref string, opts ...
 
 	// Create catalog
 	// Return early for empty documents
-	if len(g.Families) == 0 {
+	if len(g.Groups) == 0 {
 		return oscal.Catalog{}, oscal.Profile{}, fmt.Errorf("document %s does not have defined families", g.Metadata.Id)
 	}
 
@@ -53,18 +53,18 @@ func GuidanceToOSCAL(g *gemara.GuidanceCatalog, guidanceDocHref string, opts ...
 	}
 
 	// Group guidelines by family
-	guidelinesByFamily := make(map[string][]gemara.Guideline)
+	guidelinesByGroup := make(map[string][]gemara.Guideline)
 	for _, guideline := range g.Guidelines {
 		// Skip guidelines that extend external controls - these belong only in the profile as alterations
 		if guideline.Extends != nil && guideline.Extends.ReferenceId != "" {
 			continue
 		}
-		guidelinesByFamily[guideline.Family] = append(guidelinesByFamily[guideline.Family], guideline)
+		guidelinesByGroup[guideline.Group] = append(guidelinesByGroup[guideline.Group], guideline)
 	}
 
 	var groups []oscal.Group
-	for _, family := range g.Families {
-		guidelines := guidelinesByFamily[family.Id]
+	for _, family := range g.Groups {
+		guidelines := guidelinesByGroup[family.Id]
 		if len(guidelines) > 0 {
 			groups = append(groups, createControlGroup(g, family, guidelines, resourcesMap))
 		}

gemaraconv/sarif_test.go

@@ -326,16 +326,16 @@ func makeAssessmentLog(entryID, description string, result gemara.Result, messag
 
 func makeCatalog(controlID, controlTitle, controlObjective, reqID, reqText, reqRecommendation string) *gemara.ControlCatalog {
 	return &gemara.ControlCatalog{
-		Families: []gemara.Group{
+		Groups: []gemara.Group{
 			{
 				Id:    "test-family",
-				Title: "Test Family",
+				Title: "Test Group",
 			},
 		},
 		Controls: []gemara.Control{
 			{
 				Id:        controlID,
-				Family:    "test-family",
+				Group:     "test-family",
 				Title:     controlTitle,
 				Objective: controlObjective,
 				AssessmentRequirements: []gemara.AssessmentRequirement{