gemara

package module
v0.18.0 Latest Latest
Warning

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

 Go to latest Published: Dec 29, 2025 License: Apache-2.0 Imports: 10 Imported by: 0

README

Gemara: GRC Engineering Model for Automated Risk Assessment Go Reference

Pronounced: Juh-MAH-ruh (think 💎)

Overview

Gemara (The GRC Engineering Model for Automated Risk Assessment) provides a logical model to describe the categories of compliance activities, how they interact, and the schemas to enable automated interoperability between them.

In order to better facilitate cross-functional communication, the Gemara Model seeks to outline the categorical layers of activities related to automated governance.

We will begin by establishing the overall model, and then the following sections will contain detailed breakdowns of each categorical layer, with examples.

This document assumes that the reader is trained in governance, risk, compliance, or cybersecurity and therefore understands or can find definitions of concepts or terms that are infrequently used herein.

For the purpose of this document, "organization" may refer to a business or an organizational unit within it.

The Model

Each layer in the model builds upon the lower layer, though in higher-level use cases you may find examples where multiple lower layers are brought into a higher level together. Examples and clarifications can be found in the respective sections below.

Layer Name Description
1 Guidance High-level guidance on cybersecurity measures
2 Controls Technology-specific, threat-informed security controls
3 Policy Risk-informed guidance tailored to an organization
4 Evaluation Inspection of code, configurations, and deployments
5 Enforcement Prevention or remediation based on assessment findings
6 Audit Review of organizational policy and conformance
Layer 1: Guidance

The Guidance layer is the lowest level of the Gemara Model. Activities in this layer provide high-level rules pertaining to cybersecurity measures. Guidance is typically developed by industry groups, government agencies, or international standards bodies. Examples include the NIST Cybersecurity Framework, ISO 27001, PCI DSS, HIPPA, GDPR, and CRA. They are intended to be used as a starting point for organizations to develop their own cybersecurity programs.

Guidance frameworks or standards occasionally express their rules using the term "controls" — these should be understood as Layer 1 Controls in the event that the term appears to conflict with Layer 2.

These guidance documents are high-level, abstract controls that may be referenced in the development of other Layer 1 or Layer 2 assets.

Layer 1 Schema

The Gemara Layer 1 Schema describes the machine-readable format of Layer 1 guidelines.

Both simple and more complex, multipart guidelines can be expressed with associated recommendations. Guideline mappings or "crosswalk references" can be expressed, allowing correlation between multiple Layer 1 guidance documents.

Layer 2: Controls

Activities in the Control layer produce technology-specific, threat-informed security controls. Controls are the specific guardrails that organizations put in place to protect their information systems. They are typically informed by the best practices and industry standards which are produced in Layer 1.

Layer 2 controls are typically developed by an organization for its own purposes, or for general use by industry groups, government agencies, or international standards bodies. Examples include CIS Benchmarks, FINOS Common Cloud Controls, and the Open Source Project Security (OSPS) Baseline.

Assets in this category may be refined into more specific Layer 2 controls, or combined with organizational risk considerations to form Layer 3 policies.

The recommended process for developing Layer 2 controls is to first assess the technology's capabilities, then identify threats to those capabilities, and finally develop controls to mitigate those threats.

Layer 2 Schema

The Gemara Layer 2 Schema describes the machine-readable format of Layer 2 controls.

The schema allows controls to be mapped to threats or Layer 1 controls by their unique identifiers. Threats may also be expressed in the schema, with mappings to the technology-specific capabilities which may be vulnerable to the threat.

The Gemara go module provides Layer 2 support for ingesting YAML and JSON documents that follow this schema.

The cue CLI can be used to validate YAML data containing a Layer 2 control catalog.

Layer 3: Policy

Activities in the Policy layer provide risk-informed governance rules that — while based on best practices and industry standards — are tailored to an organization.

Layer 3 controls are typically developed by an organization to compile into organizational policies. Policies cannot be properly developed without consideration for organization-specific risk appetite and risk-acceptance.

These policy documents may be referenced by other policy documents, or used as a starting point for Layer 4 assessments.

Layer 3 Schema

The Gemara Layer 3 Schema describes the machine-readable format of Layer 3 policies. This allows for the programmatic validation and processing of policy documents, ensuring they adhere to a defined structure.

Layer 4: Evaluation

Activities in the Evaluation layer provide inspection of code, configurations, and deployments. Those elements are part of the software development lifecycle which is not represented in this model.

Evaluation activities may be built based on outputs from layers 2 or 3. While automated assessments are often developed by vendors or industry groups, robust evaluation should be informed by organizational policies in order to custom-tailor the assessment to the needs of the compliance program.

Layer 4 Schema

The Gemara Layer 4 Schema describes the machine-readable format of Layer 4 evaluation results.

The schema allows evaluations to be mapped to Layer 2 controls by their unique identifiers.

The Gemara go module provides Layer 4 support for writing and executing assessments, which can produce results conforming to this schema.

Layer 5: Enforcement

Activities in the Enforcement layer provide prevention or remediation. These enforcement actions should be guided by Layer 3 policies and based on assessment findings from Layer 4 evaluations.

This layer ensures that the organization is complying with policy when evidence of noncompliance is found, such as by blocking the deployment of a resource that does not meet the organization's policies.

Layer 6: Audit

Activities in the Audit layer provide a review of organizational policy and conformance.

Audits consider information from all of the lower layers. These activities are typically performed by internal or external auditors to ensure that the organization has designed and enforced effective policies based on the organization's requirements.

Usage

Install the go module with go get github.com/ossf/gemara and consult our go docs

Use the schemas directly with cue for validating Gemara data payloads against the schemas and more.

Projects and tooling using Gemara

Some Gemara use cases include:

Contributing

We're so glad you asked - see CONTRIBUTING.md and if you have any questions or feedback head over to the OpenSSF Slack in #gemara

You can also join the biweekly meeting on alternate Thursdays.
See Gemara Bi-Weekly Meeting on the OpenSSF calendar for details.

Documentation

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AcceptedMethod 

type AcceptedMethod struct {
	Type string `json:"type" yaml:"type"`

	Description string `json:"description,omitempty" yaml:"description,omitempty"`

	Actor Actor `json:"actor,omitempty" yaml:"actor,omitempty"`
}

AcceptedMethod defines a method for evaluation or enforcement.

type AcceptedRisk 

type AcceptedRisk struct {
	Risk SingleMapping `json:"risk" yaml:"risk"`

	// Scope and justification are only required for accepted risks (e.g., risk is accepted for TLP:Green and TLP:Clear because they contain non-sensitive data)
	Scope Scope `json:"scope,omitempty" yaml:"scope,omitempty"`

	Justification string `json:"justification,omitempty" yaml:"justification,omitempty"`
}

RiskMapping maps a risk to a reference and optionally includes scope and justification.

type Actor 

type Actor struct {
	// Id uniquely identifies the actor.
	Id string `json:"id" yaml:"id"`

	// Name provides the name of the actor.
	Name string `json:"name" yaml:"name"`

	// Type specifies the type of entity interacting in the workflow.
	Type ActorType `json:"type" yaml:"type"`

	// Version specifies the version of the actor (if applicable, e.g., for tools).
	Version string `json:"version,omitempty" yaml:"version,omitempty"`

	// Description provides additional context about the actor.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`

	// Uri provides a general URI for the actor information.
	Uri string `json:"uri,omitempty" yaml:"uri,omitempty"`

	// Contact provides contact information for the actor.
	Contact Contact `json:"contact,omitempty" yaml:"contact,omitempty"`
}

Actor represents an entity (human or tool) that can perform actions in evaluations.

type ActorType 

type ActorType int

ActorType specifies type of actor interacting in the workflow (human/software) 

const (
	// Software indicates the actor creates outputs without human intervention.
	Software ActorType = iota
	// Human indicates the actor creates outputs as a result of human review or judgment.
	Human
	// SoftwareAssisted indicates the actor creates outputs with software assistance but requires human oversight or judgment.
	SoftwareAssisted
)

func (*ActorType) MarshalJSON 

func (e *ActorType) MarshalJSON() ([]byte, error)

MarshalJSON ensures that ActorType is serialized as a string in JSON

func (*ActorType) MarshalYAML 

func (e *ActorType) MarshalYAML() (interface{}, error)

MarshalYAML ensures that ActorType is serialized as a string in YAML

func (*ActorType) String 

func (e *ActorType) String() string

func (*ActorType) UnmarshalJSON 

func (e *ActorType) UnmarshalJSON(data []byte) error

UnmarshalJSON ensures that ActorType can be deserialized from a JSON string

func (*ActorType) UnmarshalYAML 

func (e *ActorType) UnmarshalYAML(data []byte) error

UnmarshalYAML ensures that ActorType can be deserialized from a YAML string

type Adherence 

type Adherence struct {
	EvaluationMethods []AcceptedMethod `json:"evaluation-methods,omitempty" yaml:"evaluation-methods,omitempty"`

	AssessmentPlans []AssessmentPlan `json:"assessment-plans,omitempty" yaml:"assessment-plans,omitempty"`

	EnforcementMethods []AcceptedMethod `json:"enforcement-methods,omitempty" yaml:"enforcement-methods,omitempty"`

	NonCompliance string `json:"non-compliance,omitempty" yaml:"non-compliance,omitempty"`
}

Adherence defines evaluation methods, assessment plans, enforcement methods, and non-compliance notifications.

type AssessmentLog 

type AssessmentLog struct {
	// Requirement should map to the assessment requirement for this assessment.
	Requirement SingleMapping `json:"requirement" yaml:"requirement"`

	// Plan maps to the policy assessment plan being executed.
	Plan *SingleMapping `json:"plan,omitempty" yaml:"plan,omitempty"`

	// Description provides a summary of the assessment procedure.
	Description string `json:"description" yaml:"description"`

	// Result is the overall outcome of the assessment procedure, matching the result of the last step that was run.
	Result Result `json:"result" yaml:"result"`

	// Message provides additional context about the assessment result.
	Message string `json:"message" yaml:"message"`

	// Applicability is elevated from the Layer 2 Assessment Requirement to aid in execution and reporting.
	Applicability []string `json:"applicability" yaml:"applicability"`

	// Steps are sequential actions taken as part of the assessment, which may halt the assessment if a failure occurs.
	Steps []AssessmentStep `json:"steps" yaml:"steps"`

	// Steps-executed is the number of steps that were executed as part of the assessment.
	StepsExecuted int64 `json:"steps-executed,omitempty" yaml:"steps-executed,omitempty"`

	// Start is the timestamp when the assessment began.
	Start Datetime `json:"start" yaml:"start"`

	// End is the timestamp when the assessment concluded.
	End Datetime `json:"end,omitempty" yaml:"end,omitempty"`

	// Recommendation provides guidance on how to address a failed assessment.
	Recommendation string `json:"recommendation,omitempty" yaml:"recommendation,omitempty"`

	// ConfidenceLevel indicates the evaluator's confidence level in this specific assessment result.
	ConfidenceLevel ConfidenceLevel `json:"confidence-level,omitempty" yaml:"confidence-level,omitempty"`
}

AssessmentLog contains the results of executing a single assessment procedure for a control requirement.

func NewAssessment 

func NewAssessment(requirementId string, description string, applicability []string, steps []AssessmentStep) (*AssessmentLog, error)

NewAssessment creates a new AssessmentLog object and returns a pointer to it.

func (*AssessmentLog) AddStep 

func (a *AssessmentLog) AddStep(step AssessmentStep)

AddStep queues a new step in the AssessmentLog

func (*AssessmentLog) Run 

func (a *AssessmentLog) Run(targetData interface{}) Result

Run will execute all steps, halting if any step does not return Passed.

type AssessmentPlan 

type AssessmentPlan struct {
	Id string `json:"id" yaml:"id"`

	RequirementId string `json:"requirement-id" yaml:"requirement-id"`

	Frequency string `json:"frequency" yaml:"frequency"`

	EvaluationMethods []AcceptedMethod `json:"evaluation-methods" yaml:"evaluation-methods"`

	EvidenceRequirements string `json:"evidence-requirements,omitempty" yaml:"evidence-requirements,omitempty"`

	Parameters []Parameter `json:"parameters,omitempty" yaml:"parameters,omitempty"`
}

AssessmentPlan defines how a specific assessment requirement is evaluated.

type AssessmentRequirement 

type AssessmentRequirement struct {
	Id string `json:"id" yaml:"id"`

	Text string `json:"text" yaml:"text"`

	Applicability []string `json:"applicability" yaml:"applicability"`

	Recommendation string `json:"recommendation,omitempty" yaml:"recommendation,omitempty"`
}

type AssessmentRequirementModifier 

type AssessmentRequirementModifier struct {
	Id string `json:"id" yaml:"id"`

	TargetId string `json:"target-id" yaml:"target-id"`

	ModificationType ModType `json:"modification-type" yaml:"modification-type"`

	ModificationRationale string `json:"modification-rationale" yaml:"modification-rationale"`

	// The updated text of the assessment requirement
	Text string `json:"text,omitempty" yaml:"text,omitempty"`

	// The updated applicability of the assessment requirement
	Applicability []string `json:"applicability,omitempty" yaml:"applicability,omitempty"`

	// The updated recommendation for the assessment requirement
	Recommendation string `json:"recommendation,omitempty" yaml:"recommendation,omitempty"`
}

AssessmentRequirementModifier allows organizations to customize assessment requirements based on how an organization wants to gather evidence for the objective.

type AssessmentStep 

type AssessmentStep func(payload interface{}) (Result, string, ConfidenceLevel)

AssessmentStep is a function type that inspects the provided targetData and returns a Result with a message and confidence level. The message may be an error string or other descriptive text.

func (AssessmentStep) MarshalJSON 

func (as AssessmentStep) MarshalJSON() ([]byte, error)

func (AssessmentStep) MarshalYAML 

func (as AssessmentStep) MarshalYAML() (interface{}, error)

func (AssessmentStep) String 

func (as AssessmentStep) String() string

type Capability 

type Capability struct {
	Id string `json:"id" yaml:"id"`

	Title string `json:"title" yaml:"title"`

	Description string `json:"description" yaml:"description"`
}

type Catalog 

type Catalog struct {
	Metadata Metadata `json:"metadata,omitempty" yaml:"metadata,omitempty"`

	Title string `json:"title" yaml:"title"`

	ControlFamilies []ControlFamily `json:"control-families,omitempty" yaml:"control-families,omitempty"`

	Threats []Threat `json:"threats,omitempty" yaml:"threats,omitempty"`

	Capabilities []Capability `json:"capabilities,omitempty" yaml:"capabilities,omitempty"`

	ImportedControls []MultiMapping `json:"imported-controls,omitempty" yaml:"imported-controls,omitempty"`

	ImportedThreats []MultiMapping `json:"imported-threats,omitempty" yaml:"imported-threats,omitempty"`

	ImportedCapabilities []MultiMapping `json:"imported-capabilities,omitempty" yaml:"imported-capabilities,omitempty"`
}

func (*Catalog) LoadFile 

func (c *Catalog) LoadFile(sourcePath string) error

LoadFile loads data from a single YAML or JSON file at the provided path. sourcePath is expected to be a file or https URI in the form file:///path/to/file.yaml or https://example.com/file.yaml. If run multiple times for the same data type, this method will override previous data.

func (*Catalog) LoadFiles 

func (c *Catalog) LoadFiles(sourcePaths []string) error

LoadFiles loads data from any number of YAML or JSON files at the provided paths. sourcePath are expected to be file or https URIs in the form file:///path/to/file.yaml or https://example.com/file.yaml. If run multiple times, this method will append new data to previous data.

func (*Catalog) LoadNestedCatalog 

func (c *Catalog) LoadNestedCatalog(sourcePath, fieldName string) error

LoadNestedCatalog loads a YAML file containing a nested catalog. Only supports a single layer of nesting. Accepts file URIs with the 'file:///' prefix. Throws an error if the URL is not https. TODO: Consider validating/sanitizing inputs to reduce injection risks.

type CatalogImport 

type CatalogImport struct {
	ReferenceId string `json:"reference-id,omitempty" yaml:"reference-id,omitempty"`

	Exclusions []string `json:"exclusions,omitempty" yaml:"exclusions,omitempty"`

	Constraints []Constraint `json:"constraints,omitempty" yaml:"constraints,omitempty"`

	AssessmentRequirementModifications []AssessmentRequirementModifier `json:"assessment-requirement-modifications,omitempty" yaml:"assessment-requirement-modifications,omitempty"`
}

CatalogImport defines how to import control catalogs with optional exclusions, constraints, and assessment requirement modifications.

type Category 

type Category struct {
	Id string `json:"id" yaml:"id"`

	Title string `json:"title" yaml:"title"`

	Description string `json:"description" yaml:"description"`

	Guidelines []Guideline `json:"guidelines,omitempty" yaml:"guidelines,omitempty"`
}

Category represents a category used for applicability or classification

Category represents a logical group of guidelines (i.e. control family)

type Checklist 

type Checklist struct {
	// PolicyId identifies the policy.
	PolicyId string
	// PolicyTitle is the title of the policy.
	PolicyTitle string
	// Author is the name of the policy author.
	Author string
	// AuthorVersion is the version of the authoring tool or system.
	AuthorVersion string
	// Sections are the requirement sections
	Sections []RequirementSection
}

Checklist represents the structured checklist data.

type ChecklistItem 

type ChecklistItem struct {
	// PlanId is the assessment plan identifier this item belongs to.
	PlanId string
	// MethodDescription provides additional context or a summary about the method.
	MethodDescription string
	// MethodType defines the category the method falls into.
	MethodType string
	// Frequency indicates how often this assessment should be performed.
	Frequency string
	// EvidenceRequirements describes what evidence is required for this assessment.
	EvidenceRequirements string
}

ChecklistItem represents a single checklist item.

type ConfidenceLevel 

type ConfidenceLevel int

ConfidenceLevel indicates the evaluator's confidence level in an assessment result. This is designed to restrict the possible confidence level values to a set of known levels. 

const (
	// NotSet indicates the confidence level has not been set yet (initial/default state).
	NotSet ConfidenceLevel = iota
	// Undetermined indicates the confidence level could not be determined (sticky, like Unknown result).
	Undetermined
	// Low indicates the evaluator has low confidence in this result.
	Low
	// Medium indicates the evaluator has moderate confidence in this result.
	Medium
	// High indicates the evaluator has high confidence in this result.
	High
)

func (ConfidenceLevel) MarshalJSON 

func (c ConfidenceLevel) MarshalJSON() ([]byte, error)

MarshalJSON ensures that ConfidenceLevel is serialized as a string in JSON

func (ConfidenceLevel) MarshalYAML 

func (c ConfidenceLevel) MarshalYAML() (interface{}, error)

MarshalYAML ensures that ConfidenceLevel is serialized as a string in YAML

func (ConfidenceLevel) String 

func (c ConfidenceLevel) String() string

type Constraint 

type Constraint struct {
	// Unique ID for this constraint to enable Layer 4/5 tracking
	Id string `json:"id" yaml:"id"`

	// Links to the specific Guidance or Control being constrained
	TargetId string `json:"target-id" yaml:"target-id"`

	// The prescriptive requirement/constraint text
	Text string `json:"text" yaml:"text"`
}

Constraint defines a prescriptive requirement that applies to a specific guidance or control.

type Contact 

type Contact struct {
	// The contact person's name.
	Name string `json:"name" yaml:"name"`

	// The entity with which the contact is affiliated, such as a school or employer.
	Affiliation *string `json:"affiliation,omitempty" yaml:"affiliation,omitempty"`

	// A preferred email address to reach the contact.
	Email *Email `json:"email,omitempty" yaml:"email,omitempty"`

	// A social media handle or profile for the contact.
	Social *string `json:"social,omitempty" yaml:"social,omitempty"`
}

Contact represents contact information used across multiple layers

type Contacts 

type Contacts struct {
	// responsible is the person or group responsible for implementing controls for technical requirements
	Responsible []Contact `json:"responsible" yaml:"responsible"`

	// accountable is the person or group accountable for evaluating and enforcing the efficacy of technical controls
	Accountable []Contact `json:"accountable" yaml:"accountable"`

	// consulted is an optional person or group who may be consulted for more information about the technical requirements
	Consulted []Contact `json:"consulted,omitempty" yaml:"consulted,omitempty"`

	// informed is an optional person or group who must receive updates about compliance with this policy
	Informed []Contact `json:"informed,omitempty" yaml:"informed,omitempty"`
}

Contacts defines RACI roles for policy compliance and notification.

type Control 

type Control struct {
	Id string `json:"id" yaml:"id"`

	Title string `json:"title" yaml:"title"`

	Objective string `json:"objective" yaml:"objective"`

	AssessmentRequirements []AssessmentRequirement `json:"assessment-requirements" yaml:"assessment-requirements"`

	GuidelineMappings []MultiMapping `json:"guideline-mappings,omitempty" yaml:"guideline-mappings,omitempty"`

	ThreatMappings []MultiMapping `json:"threat-mappings,omitempty" yaml:"threat-mappings,omitempty"`
}

type ControlEvaluation 

type ControlEvaluation struct {
	Name string `json:"name" yaml:"name"`

	Result Result `json:"result" yaml:"result"`

	Message string `json:"message" yaml:"message"`

	Control SingleMapping `json:"control" yaml:"control"`

	// Enforce that control reference and the assessments' references match
	// This formulation uses the control's reference if the assessment doesn't include a reference
	AssessmentLogs []*AssessmentLog `json:"assessment-logs" yaml:"assessment-logs"`
}

ControlEvaluation contains the results of evaluating a single Layer 4 control.

func (*ControlEvaluation) AddAssessment 

func (c *ControlEvaluation) AddAssessment(requirementId string, description string, applicability []string, steps []AssessmentStep) (assessment *AssessmentLog)

AddAssessment creates a new AssessmentLog object and adds it to the ControlEvaluation.

func (*ControlEvaluation) Evaluate 

func (c *ControlEvaluation) Evaluate(targetData interface{}, userApplicability []string)

Evaluate runs each step in each assessment, updating the relevant fields on the control evaluation. It will halt if a step returns a failed result. The targetData is the data that the assessment will be run against. The userApplicability is a slice of strings that determine when the assessment is applicable. The changesAllowed determines whether the assessment is allowed to execute its changes.

type ControlFamily 

type ControlFamily struct {
	Id string `json:"id" yaml:"id"`

	Title string `json:"title" yaml:"title"`

	Description string `json:"description" yaml:"description"`

	Controls []Control `json:"controls" yaml:"controls"`
}

type Date 

type Date string

Date represents a date string (ISO 8601 date format)

type Datetime 

type Datetime string

Datetime represents an ISO 8601 formatted datetime string

type Dimensions 

type Dimensions struct {
	// technologies is an optional list of technology categories or services
	Technologies []string `json:"technologies,omitempty" yaml:"technologies,omitempty"`

	// geopolitical is an optional list of geopolitical regions
	Geopolitical []string `json:"geopolitical,omitempty" yaml:"geopolitical,omitempty"`

	// sensitivity is an optional list of data classification levels
	Sensitivity []string `json:"sensitivity,omitempty" yaml:"sensitivity,omitempty"`

	// users is an optional list of user roles
	Users []string `json:"users,omitempty" yaml:"users,omitempty"`

	Groups []string `json:"groups,omitempty" yaml:"groups,omitempty"`
}

Dimensions specify the applicability criteria for a policy

type DocumentType 

type DocumentType string

type Email 

type Email string

Email represents a validated email address pattern

type EvaluationLog 

type EvaluationLog struct {
	Evaluations []*ControlEvaluation `json:"evaluations" yaml:"evaluations"`

	Metadata Metadata `json:"metadata,omitempty" yaml:"metadata,omitempty"`
}

EvaluationLog contains the results of evaluating a set of Layer 2 controls.

type Exemption 

type Exemption struct {
	Reason string `json:"reason" yaml:"reason"`

	Redirect MultiMapping `json:"redirect,omitempty" yaml:"redirect,omitempty"`
}

Exemption represents an exemption with a reason and optional redirect

type GuidanceDocument 

type GuidanceDocument struct {
	Metadata Metadata `json:"metadata,omitempty" yaml:"metadata,omitempty"`

	Title string `json:"title" yaml:"title"`

	DocumentType DocumentType `json:"document-type" yaml:"document-type"`

	Exemptions []Exemption `json:"exemptions,omitempty" yaml:"exemptions,omitempty"`

	// Introductory text for the document to be used during rendering
	FrontMatter string `json:"front-matter,omitempty" yaml:"front-matter,omitempty"`

	Categories []Category `json:"categories,omitempty" yaml:"categories,omitempty"`

	// For inheriting from other guidance documents to create tailored documents/baselines
	ImportedGuidelines []MultiMapping `json:"imported-guidelines,omitempty" yaml:"imported-guidelines,omitempty"`

	ImportedPrinciples []MultiMapping `json:"imported-principles,omitempty" yaml:"imported-principles,omitempty"`
}
Example 
package main

import (
	"fmt"
	"os"
	"text/template"

	"github.com/goccy/go-yaml"
)

// Adapted from: https://github.com/finos/ai-governance-framework/blob/main/docs/_mitigations/mi-11_human-feedback-loop-for-ai-systems.md

func main() {
	tmpl := `
# {{ .Title }} ({{ .Metadata.Id }})
---
**Front Matter:** {{ .FrontMatter }}
---
{{ range .Categories }}
### {{ .Title }} ({{ .Id }})
{{ .Description }}
#### Guidelines:
{{ range .Guidelines }}
##### {{ .Title }} ({{ .Id }})
**Objective:** {{ .Objective }}
{{ if .SeeAlso }}
**See Also:** {{ range .SeeAlso }}{{ . }} {{ end }}
{{ end }}
{{ end }}
{{ end }}
`

	l1Docs, err := goodAIGFExample()
	if err != nil {
		fmt.Printf("error getting testdata: %v\n", err)
		return
	}
	t, err := template.New("guidance").Parse(tmpl)
	if err != nil {
		fmt.Printf("error parsing template: %v\n", err)
		return
	}

	err = t.Execute(os.Stdout, l1Docs)
	if err != nil {
		fmt.Printf("error executing template: %v\n", err)
	}
}

func goodAIGFExample() (GuidanceDocument, error) {
	testdataPath := "./test-data/good-aigf.yaml"
	data, err := os.ReadFile(testdataPath)
	if err != nil {
		return GuidanceDocument{}, err
	}
	var l1Docs GuidanceDocument
	if err := yaml.Unmarshal(data, &l1Docs); err != nil {
		return GuidanceDocument{}, err
	}
	return l1Docs, nil
}

Output:

# AI Governance Framework (FINOS-AIR)
---
**Front Matter:** The following framework has been developed by FINOS (Fintech Open Source Foundation).
---

### Detective (DET)
Detection and Continuous Improvement
#### Guidelines:

##### Human Feedback Loop for AI Systems (AIR-DET-011)
**Objective:** A Human Feedback Loop is a critical detective and continuous improvement mechanism that involves systematically collecting, analyzing, and acting upon feedback provided by human users, subject matter experts (SMEs), or reviewers regarding an AI system's performance, outputs, or behavior.

**See Also:** AIR-DET-015 AIR-DET-004 AIR-PREV-005

func (*GuidanceDocument) LoadFile 

func (g *GuidanceDocument) LoadFile(sourcePath string) error

LoadFile loads data from a YAML or JSON file at the provided path into the GuidanceDocument. sourcePath is expected to be a file or https URI in the form file:///path/to/file.yaml or https://example.com/file.yaml. If run multiple times for the same data type, this method will override previous data.

func (*GuidanceDocument) LoadFiles 

func (g *GuidanceDocument) LoadFiles(sourcePaths []string) error

LoadFiles loads data from any number of YAML or JSON files at the provided paths. sourcePath are expected to be file or https URIs in the form file:///path/to/file.yaml or https://example.com/file.yaml. If run multiple times, this method will append new data to previous data.

type GuidanceImport 

type GuidanceImport struct {
	ReferenceId string `json:"reference-id,omitempty" yaml:"reference-id,omitempty"`

	Exclusions []string `json:"exclusions,omitempty" yaml:"exclusions,omitempty"`

	// Constraints allow policy authors to define ad hoc minimum requirements (e.g., "review at least annually").
	Constraints []Constraint `json:"constraints,omitempty" yaml:"constraints,omitempty"`
}

GuidanceImport defines how to import guidance documents with optional exclusions and constraints.

type Guideline 

type Guideline struct {
	Id string `json:"id" yaml:"id"`

	Title string `json:"title" yaml:"title"`

	Objective string `json:"objective,omitempty" yaml:"objective,omitempty"`

	// Maps to fields commonly seen in controls with implementation guidance
	Recommendations []string `json:"recommendations,omitempty" yaml:"recommendations,omitempty"`

	// For control enhancements (ex. AC-2(1) in 800-53)
	// The base-guideline-id is needed to achieve full context for the enhancement
	BaseGuidelineID string `json:"base-guideline-id,omitempty" yaml:"base-guideline-id,omitempty"`

	Rationale *Rationale `json:"rationale,omitempty" yaml:"rationale,omitempty"`

	// Represents individual guideline parts/statements
	GuidelineParts []Part `json:"guideline-parts,omitempty" yaml:"guideline-parts,omitempty"`

	// Crosswalking this guideline to other guidelines in other documents
	GuidelineMappings []MultiMapping `json:"guideline-mappings,omitempty" yaml:"guideline-mappings,omitempty"`

	// A list for associated key principle ids
	PrincipleMappings []MultiMapping `json:"principle-mappings,omitempty" yaml:"principle-mappings,omitempty"`

	// This is akin to related controls, but using more explicit terminology
	SeeAlso []string `json:"see-also,omitempty" yaml:"see-also,omitempty"`
}

type ImplementationDetails 

type ImplementationDetails struct {
	Start Datetime `json:"start" yaml:"start"`

	End Datetime `json:"end,omitempty" yaml:"end,omitempty"`

	Notes string `json:"notes" yaml:"notes"`
}

ImplementationDetails specifies the timeline for policy implementation.

type ImplementationPlan 

type ImplementationPlan struct {
	NotificationProcess string `json:"notification-process,omitempty" yaml:"notification-process,omitempty"`

	EvaluationTimeline ImplementationDetails `json:"evaluation-timeline" yaml:"evaluation-timeline"`

	EnforcementTimeline ImplementationDetails `json:"enforcement-timeline" yaml:"enforcement-timeline"`
}

ImplementationPlan defines when and how the policy becomes active.

type Imports 

type Imports struct {
	Policies []string `json:"policies,omitempty" yaml:"policies,omitempty"`

	Catalogs []CatalogImport `json:"catalogs,omitempty" yaml:"catalogs,omitempty"`

	Guidance []GuidanceImport `json:"guidance,omitempty" yaml:"guidance,omitempty"`
}

Imports defines external policies, controls, and guidelines required by this policy.

type MappingEntry 

type MappingEntry struct {
	ReferenceId string `json:"reference-id" yaml:"reference-id"`

	Strength int64 `json:"strength" yaml:"strength"`

	Remarks string `json:"remarks,omitempty" yaml:"remarks,omitempty"`
}

MappingEntry represents a single entry within a mapping

type MappingReference 

type MappingReference struct {
	Id string `json:"id" yaml:"id"`

	Title string `json:"title" yaml:"title"`

	Version string `json:"version" yaml:"version"`

	Description string `json:"description,omitempty" yaml:"description,omitempty"`

	Url string `json:"url,omitempty" yaml:"url,omitempty"`
}

MappingReference represents a reference to an external document with full metadata.

type Metadata 

type Metadata struct {
	Id string `json:"id" yaml:"id"`

	Version string `json:"version,omitempty" yaml:"version,omitempty"`

	Date Date `json:"date,omitempty" yaml:"date,omitempty"`

	Description string `json:"description" yaml:"description"`

	Author Actor `json:"author" yaml:"author"`

	MappingReferences []MappingReference `json:"mapping-references,omitempty" yaml:"mapping-references,omitempty"`

	ApplicabilityCategories []Category `json:"applicability-categories,omitempty" yaml:"applicability-categories,omitempty"`

	Draft bool `json:"draft,omitempty" yaml:"draft,omitempty"`

	Lexicon string `json:"lexicon,omitempty" yaml:"lexicon,omitempty"`
}

Metadata represents common metadata fields shared across all layers

type MethodType 

type MethodType string

type ModType 

type ModType string

ModType defines the type of modification to the assessment requirement.

type MultiMapping 

type MultiMapping struct {
	// ReferenceId should reference the corresponding MappingReference id from metadata
	ReferenceId string `json:"reference-id" yaml:"reference-id"`

	Entries []MappingEntry `json:"entries" yaml:"entries"`

	Remarks string `json:"remarks,omitempty" yaml:"remarks,omitempty"`
}

MultiMapping represents a mapping to an external reference with one or more entries.

type Outcome 

type Outcome struct {
	Title string `json:"title" yaml:"title"`

	Description string `json:"description" yaml:"description"`
}

type Parameter 

type Parameter struct {
	Id string `json:"id" yaml:"id"`

	Label string `json:"label" yaml:"label"`

	Description string `json:"description" yaml:"description"`

	AcceptedValues []string `json:"accepted-values,omitempty" yaml:"accepted-values,omitempty"`
}

Parameter defines a configurable parameter for assessment or enforcement activities.

type Part 

type Part struct {
	Id string `json:"id" yaml:"id"`

	Title string `json:"title,omitempty" yaml:"title,omitempty"`

	Text string `json:"text" yaml:"text"`

	Recommendations []string `json:"recommendations,omitempty" yaml:"recommendations,omitempty"`
}

Parts include sub-statements of a guideline that can be assessed individually

type Policy 

type Policy struct {
	Title string `json:"title" yaml:"title"`

	Metadata Metadata `json:"metadata" yaml:"metadata"`

	Contacts Contacts `json:"contacts" yaml:"contacts"`

	Scope Scope `json:"scope" yaml:"scope"`

	Imports Imports `json:"imports" yaml:"imports"`

	ImplementationPlan ImplementationPlan `json:"implementation-plan,omitempty" yaml:"implementation-plan,omitempty"`

	Risks Risks `json:"risks,omitempty" yaml:"risks,omitempty"`

	Adherence Adherence `json:"adherence" yaml:"adherence"`
}

Policy represents a policy document with metadata, contacts, scope, imports, implementation plan, risks, and adherence requirements.

func (*Policy) LoadFile 

func (p *Policy) LoadFile(sourcePath string) error

LoadFile loads data from a YAML or JSON file at the provided path. If run multiple times for the same data type, this method will override previous data.

func (*Policy) ToMarkdownChecklist 

func (p *Policy) ToMarkdownChecklist() (string, error)

ToMarkdownChecklist converts a policy into a markdown checklist.

Example 
policy := &Policy{
	Metadata: Metadata{
		Id:      "security-policy-v2.1",
		Version: "2.1.0",
		Author: Actor{
			Name:    "Security Team",
			Version: "1.0.0",
		},
	},
	Title: "Information Security Policy",
	Adherence: Adherence{
		AssessmentPlans: []AssessmentPlan{
			{
				Id:            "plan-access-control-monthly",
				RequirementId: "AC-01.01",
				Frequency:     "monthly",
				EvaluationMethods: []AcceptedMethod{
					{
						Type:        "automated",
						Description: "Run automated access control audit script",
					},
					{
						Type:        "manual",
						Description: "Review access control logs for anomalies",
					},
				},
				EvidenceRequirements: "Access logs, audit report, and review notes",
			},
			{
				Id:            "plan-encryption-quarterly",
				RequirementId: "SC-02.01",
				Frequency:     "quarterly",
				EvaluationMethods: []AcceptedMethod{
					{
						Type:        "automated",
						Description: "Verify encryption is enabled on all data stores",
					},
				},
				EvidenceRequirements: "Configuration scan results and compliance report",
			},
			{
				Id:            "plan-backup-automated",
				RequirementId: "CP-01.01",
				Frequency:     "weekly",
				EvaluationMethods: []AcceptedMethod{
					{
						Type:        "automated",
						Description: "Verify backup jobs completed successfully",
					},
				},
				EvidenceRequirements: "Backup job logs and success reports",
			},
			{
				Id:            "plan-backup-manual",
				RequirementId: "CP-01.01",
				Frequency:     "monthly",
				EvaluationMethods: []AcceptedMethod{
					{
						Type:        "manual",
						Description: "Test restore procedure from backup",
					},
				},
				EvidenceRequirements: "Restore test results and documentation",
			},
		},
	},
}

checklist, err := policy.ToMarkdownChecklist()
if err != nil {
	fmt.Printf("Error generating checklist: %v\n", err)
	return
}

// Print the generated checklist
fmt.Println(checklist)

Output:

# Policy Checklist: Information Security Policy (security-policy-v2.1)

**Author:** Security Team (v1.0.0)

## Assessment Requirement: AC-01.01

- [ ] Run automated access control audit script (monthly) [Plan: plan-access-control-monthly]
    > **Evidence Required:** Access logs, audit report, and review notes
- [ ] Review access control logs for anomalies (monthly) [Plan: plan-access-control-monthly]
    > **Evidence Required:** Access logs, audit report, and review notes

---

## Assessment Requirement: SC-02.01

- [ ] Verify encryption is enabled on all data stores (quarterly) [Plan: plan-encryption-quarterly]
    > **Evidence Required:** Configuration scan results and compliance report

---

## Assessment Requirement: CP-01.01

- [ ] Verify backup jobs completed successfully (weekly) [Plan: plan-backup-automated]
    > **Evidence Required:** Backup job logs and success reports
- [ ] Test restore procedure from backup (monthly) [Plan: plan-backup-manual]
    > **Evidence Required:** Restore test results and documentation

type Rationale 

type Rationale struct {
	// Negative results expected from the guideline's lack of implementation
	Risks []Risk `json:"risks" yaml:"risks"`

	// Positive results expected from the guideline's implementation
	Outcomes []Outcome `json:"outcomes" yaml:"outcomes"`
}

Rationale provides contextual information to help with development and understanding of guideline intent.

type RequirementSection 

type RequirementSection struct {
	// RequirementId is the assessment requirement identifier (e.g., "OSPS-AC-01.01")
	RequirementId string
	// Items are the checklist items for this requirement
	Items []ChecklistItem
}

RequirementSection organizes checklist items by assessment requirement.

type Result 

type Result int

Result is an enum representing the result of a control evaluation This is designed to restrict the possible result values to a set of known states 

const (
	NotRun Result = iota
	Passed
	Failed
	NeedsReview
	NotApplicable
	Unknown
)

func UpdateAggregateResult 

func UpdateAggregateResult(previous Result, new Result) Result

UpdateAggregateResult compares the current result with the new result and returns the most severe of the two.

func (Result) MarshalJSON 

func (r Result) MarshalJSON() ([]byte, error)

MarshalJSON ensures that Result is serialized as a string in JSON

func (Result) MarshalYAML 

func (r Result) MarshalYAML() (interface{}, error)

MarshalYAML ensures that Result is serialized as a string in YAML

func (Result) String 

func (r Result) String() string

type Risk 

type Risk struct {
	Title string `json:"title" yaml:"title"`

	Description string `json:"description" yaml:"description"`
}

type Risks 

type Risks struct {
	// Mitigated risks only need reference-id and risk-id (no justification required)
	Mitigated []MultiMapping `json:"mitigated,omitempty" yaml:"mitigated,omitempty"`

	// Accepted risks require rationale (justification) and may include scope. Controls addressing these risks are implicitly identified through threat mappings.
	Accepted []AcceptedRisk `json:"accepted,omitempty" yaml:"accepted,omitempty"`
}

Risks defines mitigated and accepted risks addressed by this policy.

type Scope 

type Scope struct {
	In Dimensions `json:"in" yaml:"in"`

	Out Dimensions `json:"out,omitempty" yaml:"out,omitempty"`
}

Scope defines what is included and excluded from policy applicability.

type SingleMapping 

type SingleMapping struct {
	// ReferenceId should reference the corresponding MappingReference id from metadata
	ReferenceId string `json:"reference-id,omitempty" yaml:"reference-id,omitempty"`

	EntryId string `json:"entry-id" yaml:"entry-id"`

	Remarks string `json:"remarks,omitempty" yaml:"remarks,omitempty"`
}

SingleMapping represents how a specific entry (control/requirement/procedure) maps to a MappingReference.

type Threat 

type Threat struct {
	Id string `json:"id" yaml:"id"`

	Title string `json:"title" yaml:"title"`

	Description string `json:"description" yaml:"description"`

	Capabilities []MultiMapping `json:"capabilities" yaml:"capabilities"`

	ExternalMappings []MultiMapping `json:"external-mappings,omitempty" yaml:"external-mappings,omitempty"`
}

Source Files

View all Source files

Directories

Path Synopsis
cmd
oscal_export command
oscal_export/export
types_tagger command
internal
loaders
oscal
Package oscal provides conversion functions to transform Gemara documents into OSCAL (Open Security Controls Assessment Language) format.
 Package oscal provides conversion functions to transform Gemara documents into OSCAL (Open Security Controls Assessment Language) format.
Package sarif provides conversion functions to transform Gemara evaluation results into SARIF (Static Analysis Results Interchange Format) format.
 Package sarif provides conversion functions to transform Gemara evaluation results into SARIF (Static Analysis Results Interchange Format) format.

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.