refactor: updates AssessmentMethod to AssessmentProcedure

This change refactors the work in the previous commits to allow for
top-level metadata to support different types of assessment procedures
and move the AssessmentSteps under AssessmentProcedure struct. The concept of
"method" is updated to describe the procedure categorically for tools that run
automated procedures.

Signed-off-by: Jennifer Power <[email protected]>

Author: jpower432

layer4/assessment.go

@@ -6,7 +6,7 @@ import (
 	"time"
 )
 
-// Assessment is a struct that contains the results of a single method within a ControlEvaluation.
+// Assessment is a struct that contains the results of a single Procedure within a ControlEvaluation.
 type Assessment struct {
 	// RequirementID is the unique identifier for the requirement being tested
 	RequirementId string `yaml:"requirement-id"`
@@ -18,10 +18,8 @@ type Assessment struct {
 	Result Result `yaml:"result"`
 	// Message is the human-readable result of the test
 	Message string `yaml:"message"`
-	// Methods is a slice of assessment methods that were executed during the test
-	Methods []*AssessmentMethod `yaml:"methods"`
-	// MethodsExecuted is the number of assessment methods that were executed during the test
-	MethodsExecuted int `yaml:"methods-executed,omitempty"`
+	// Procedures is a slice of assessment procedures that were executed during the test
+	Procedures []*AssessmentProcedure `yaml:"procedures"`
 	// RunDuration is the time it took to run the test
 	RunDuration string `yaml:"run-duration,omitempty"`
 	// Value is the object that was returned during the test
@@ -31,32 +29,24 @@ type Assessment struct {
 }
 
 // NewAssessment creates a new Assessment object and returns a pointer to it.
-func NewAssessment(requirementId string, description string, applicability []string, methods []*AssessmentMethod) (*Assessment, error) {
+func NewAssessment(requirementId string, description string, applicability []string, procedures []*AssessmentProcedure) (*Assessment, error) {
 	a := &Assessment{
 		RequirementId: requirementId,
 		Description:   description,
 		Applicability: applicability,
 		Result:        NotRun,
-		Methods:       methods,
+		Procedures:    procedures,
 	}
 	err := a.precheck()
 	return a, err
 }
 
-// AddMethod queues a new method in the Assessment
-func (a *Assessment) AddMethod(method AssessmentMethod) {
-	a.Methods = append(a.Methods, &method)
+// AddProcedure queues a new Procedure in the Assessment
+func (a *Assessment) AddProcedure(Procedure AssessmentProcedure) {
+	a.Procedures = append(a.Procedures, &Procedure)
 }
 
-func (a *Assessment) runMethod(targetData interface{}, method *AssessmentMethod) Result {
-	a.MethodsExecuted++
-	result, message := method.RunMethod(targetData, a.Changes)
-	a.Result = UpdateAggregateResult(a.Result, result)
-	a.Message = message
-	return result
-}
-
-// Run will execute all steps, halting if any method does not return layer4.Passed.
+// Run executes all automated assessment procedures.
 func (a *Assessment) Run(targetData interface{}, changesAllowed bool) Result {
 	if a.Result != NotRun {
 		return a.Result
@@ -73,11 +63,15 @@ func (a *Assessment) Run(targetData interface{}, changesAllowed bool) Result {
 			change.Allow()
 		}
 	}
-	for _, method := range a.Methods {
-		if a.runMethod(targetData, method) == Failed {
-			return Failed
+
+	for _, procedure := range a.Procedures {
+		if procedure.Method == TestMethod {
+			result := procedure.RunProcedure(targetData, a.Changes)
+			a.Result = UpdateAggregateResult(a.Result, result)
+			a.Message = procedure.Message
 		}
 	}
+
 	a.RunDuration = time.Since(startTime).String()
 	return a.Result
 }
@@ -118,10 +112,10 @@ func (a *Assessment) RevertChanges() (corrupted bool) {
 // precheck verifies that the assessment has all the required fields.
 // It returns an error if the assessment is not valid.
 func (a *Assessment) precheck() error {
-	if a.RequirementId == "" || a.Description == "" || a.Applicability == nil || a.Methods == nil || len(a.Applicability) == 0 || len(a.Methods) == 0 {
+	if a.RequirementId == "" || a.Description == "" || a.Applicability == nil || a.Procedures == nil || len(a.Applicability) == 0 || len(a.Procedures) == 0 {
 		message := fmt.Sprintf(
-			"expected all Assessment fields to have a value, but got: requirementId=len(%v), description=len=(%v), applicability=len(%v), methods=len(%v)",
-			len(a.RequirementId), len(a.Description), len(a.Applicability), len(a.Methods),
+			"expected all Assessment fields to have a value, but got: requirementId=len(%v), description=len=(%v), applicability=len(%v), procedures=len(%v)",
+			len(a.RequirementId), len(a.Description), len(a.Applicability), len(a.Procedures),
 		)
 		a.Result = Unknown
 		a.Message = message

layer4/assessment_method.go

@@ -0,0 +1,117 @@
+package layer4
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"reflect"
+	"runtime"
+)
+
+// AssessmentProcedure defines a specific assessment for assessing a Layer 2 control requirement.
+type AssessmentProcedure struct {
+	// Id is the unique identifier of the assessment Procedure being executed
+	Id string `json:"id" yaml:"id"`
+	// Name is the human-readable name of the Procedure.
+	Name string `json:"name" yaml:"name"`
+	// Description is a detailed explanation of the Procedure.
+	Description string `json:"description" yaml:"description"`
+
+	// Method describe the high-level method used to determine the results of the procedure
+	Method Method `yaml:"method"`
+	// Remediation guide is a URL to remediation guidance associated with the control's assessment requirement and this specific assessment Procedure.
+	RemediationGuide string `json:"remediation-guide,omitempty" yaml:"remediation-guide,omitempty"`
+	// URL to documentation that describes how the assessment Procedure evaluates the control requirement.
+	Documentation string `json:"documentation,omitempty" yaml:"documentation,omitempty"`
+
+	// Run is a boolean indicating whether the procedure was run or not. When run is true, result is expected to be present.
+	Run bool `json:"run" yaml:"run"`
+	// Message is the human-readable result of the test
+	Message string `json:"message,omitempty" yaml:"message,omitempty"`
+	// Result is the outcome of the assessment Procedure.
+	// This field must be present if Run is true.
+	Result Result `json:"result,omitempty" yaml:"result,omitempty"`
+	// StepsExecuted is the number of steps that were executed during the assessment execution
+	StepsExecuted int `json:"-" yaml:"-"`
+
+	// Steps define logical steps to inspect the provided targetData and returns a Result with a message.
+	// The message may be an error string or other descriptive text.
+	Steps []AssessmentStep
+}
+
+// NewProcedure creates a new AssessmentProcedure object and returns a pointer to it.
+func NewProcedure(id, name, description string, steps []AssessmentStep) (*AssessmentProcedure, error) {
+	a := &AssessmentProcedure{
+		Id:          id,
+		Name:        name,
+		Description: description,
+		Result:      NotRun,
+		Steps:       steps,
+	}
+	err := a.precheck()
+	return a, err
+}
+
+// AssessmentStep is a function type that inspects the provided targetData and returns a Result with a message.
+// The message may be an error string or other descriptive text.
+type AssessmentStep func(payload interface{}, c map[string]*Change) (Result, string)
+
+func (as AssessmentStep) String() string {
+	// Get the function pointer correctly
+	fn := runtime.FuncForPC(reflect.ValueOf(as).Pointer())
+	if fn == nil {
+		return "<unknown function>"
+	}
+	return fn.Name()
+}
+
+func (as AssessmentStep) MarshalJSON() ([]byte, error) {
+	return json.Marshal(as.String())
+}
+
+func (as AssessmentStep) MarshalYAML() (interface{}, error) {
+	return as.String(), nil
+}
+
+// AddStep queues a new step in the Assessment Procedure
+func (a *AssessmentProcedure) AddStep(step AssessmentStep) {
+	a.Steps = append(a.Steps, step)
+}
+
+// RunProcedure executes all assessment steps, halting if any assessment does not return layer4.Passed.
+func (a *AssessmentProcedure) RunProcedure(targetData interface{}, changes map[string]*Change) Result {
+	a.Run = true
+
+	err := a.precheck()
+	if err != nil {
+		a.Result = Unknown
+		return a.Result
+	}
+	for _, steps := range a.Steps {
+		if a.runStep(targetData, changes, steps) == Failed {
+			return Failed
+		}
+	}
+	return a.Result
+}
+
+func (a *AssessmentProcedure) runStep(targetData interface{}, changes map[string]*Change, step AssessmentStep) Result {
+	a.StepsExecuted++
+	result, message := step(targetData, changes)
+	a.Result = UpdateAggregateResult(a.Result, result)
+	a.Message = message
+	return result
+}
+
+// precheck verifies that the assessment procedure has step fields.
+// It returns an error if the assessment is not valid.
+func (a *AssessmentProcedure) precheck() error {
+	if len(a.Steps) == 0 {
+		message := fmt.Sprintf(
+			"expected all Assessment Procedure fields steps=len(%v)",
+			len(a.Steps),
+		)
+		return errors.New(message)
+	}
+	return nil
+}