observation

package
v1.15.1 Latest Latest
Warning

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

 Go to latest Published: Mar 25, 2026 License: Apache-2.0 Imports: 6 Imported by: 0

Documentation

Overview

Package observation implements the SOC 2 Type II observation period framework. It tracks the observation lifecycle (start, monitor, complete), accumulates timestamped evidence, records control deviations, and generates observation period reports with control effectiveness statistics.

Index

Constants

View Source 
const MinimumDuration = 6 * 30 * 24 * time.Hour // ~180 days

MinimumDuration is the minimum observation period required for SOC 2 Type II (6 months).

Variables

This section is empty.

Functions

This section is empty.

Types

type CheckFunc 

type CheckFunc func() (passed bool, details string)

CheckFunc is a function that evaluates whether a control is operating effectively. It returns true if the control passed and an optional description of the result.

type CheckResult 

type CheckResult struct {
	ControlID string
	CheckedAt time.Time
	Passed    bool
	Details   string
}

CheckResult captures the outcome of a single control monitoring check.

type ControlEffectiveness 

type ControlEffectiveness struct {
	ControlID         string
	TotalChecks       int
	PassedChecks      int
	FailedChecks      int
	EffectivenessRate float64 // 0.0 to 1.0
	Deviations        int
	EvidenceCount     int
}

ControlEffectiveness summarizes a control's effectiveness over the observation period.

type Deviation 

type Deviation struct {
	ID          string
	ControlID   string
	Severity    Severity
	Status      DeviationStatus
	Description string
	RootCause   string
	Remediation string
	DetectedAt  time.Time
	ResolvedAt  time.Time
	ResolvedBy  string
}

Deviation records a control failure or exception observed during the observation period.

type DeviationStatus 

type DeviationStatus string

DeviationStatus tracks the remediation state of a deviation. 

const (
	DeviationOpen       DeviationStatus = "open"
	DeviationMitigated  DeviationStatus = "mitigated"
	DeviationRemediated DeviationStatus = "remediated"
	DeviationAccepted   DeviationStatus = "accepted" // risk accepted
)

type DeviationTracker 

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

DeviationTracker records and manages control deviations during the observation period.

func NewDeviationTracker 

func NewDeviationTracker() *DeviationTracker

NewDeviationTracker creates a new deviation tracker.

func (*DeviationTracker) All 

func (t *DeviationTracker) All() []Deviation

All returns all deviations.

func (*DeviationTracker) Count 

func (t *DeviationTracker) Count() int

Count returns the total number of deviations.

func (*DeviationTracker) ForControl 

func (t *DeviationTracker) ForControl(controlID string) []Deviation

ForControl returns deviations for a specific control.

func (*DeviationTracker) Open 

func (t *DeviationTracker) Open() []Deviation

Open returns all deviations that have not been resolved.

func (*DeviationTracker) OpenCount 

func (t *DeviationTracker) OpenCount() int

OpenCount returns the number of open deviations.

func (*DeviationTracker) Record 

func (t *DeviationTracker) Record(d Deviation) error

Record adds a new deviation. Returns an error if the ID or ControlID is empty.

func (*DeviationTracker) Resolve 

func (t *DeviationTracker) Resolve(id string, status DeviationStatus, remediation string, resolvedBy string, resolvedAt time.Time) error

Resolve updates the status and resolution details of a deviation. Returns an error if the deviation is not found.

type EvidenceAccumulator 

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

EvidenceAccumulator collects timestamped evidence over the observation period. Evidence is indexed by control ID for efficient retrieval during report generation.

func NewEvidenceAccumulator 

func NewEvidenceAccumulator() *EvidenceAccumulator

NewEvidenceAccumulator creates an empty evidence accumulator.

func (*EvidenceAccumulator) Add 

func (a *EvidenceAccumulator) Add(e EvidenceItem) error

Add stores a new evidence item. The hash is computed automatically from the content. Returns an error if the ID or ControlID is empty.

func (*EvidenceAccumulator) All 

func (a *EvidenceAccumulator) All() []EvidenceItem

All returns all evidence items in collection order.

func (*EvidenceAccumulator) ControlIDs 

func (a *EvidenceAccumulator) ControlIDs() []string

ControlIDs returns the set of control IDs that have evidence.

func (*EvidenceAccumulator) Count 

func (a *EvidenceAccumulator) Count() int

Count returns the total number of evidence items.

func (*EvidenceAccumulator) CountForControl 

func (a *EvidenceAccumulator) CountForControl(controlID string) int

CountForControl returns the number of evidence items for a given control.

func (*EvidenceAccumulator) ForControl 

func (a *EvidenceAccumulator) ForControl(controlID string) []EvidenceItem

ForControl returns all evidence items for a given control ID.

type EvidenceItem 

type EvidenceItem struct {
	ID          string
	ControlID   string
	Description string
	Collector   string
	CollectedAt time.Time
	Hash        string // SHA-256 of content
	Content     []byte
	Tags        []string
}

EvidenceItem represents a timestamped evidence artifact collected during the observation period. Unlike the base compliance.Evidence, this is specifically scoped to a point in the observation timeline.

type Milestone 

type Milestone struct {
	Name        string
	Description string
	DueDate     time.Time
	CompletedAt time.Time
	Completed   bool
}

Milestone marks a significant event during the observation period.

type Monitor 

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

Monitor performs continuous control monitoring with scheduled checks during the observation period. It records all check results for the observation report.

func NewMonitor 

func NewMonitor() *Monitor

NewMonitor creates a new control monitor.

func (*Monitor) Checks 

func (m *Monitor) Checks() []ScheduledCheck

Checks returns a copy of all registered scheduled checks.

func (*Monitor) Register 

func (m *Monitor) Register(sc ScheduledCheck) error

Register adds a scheduled check for a control. Returns an error if the control ID or check function is nil.

func (*Monitor) Results 

func (m *Monitor) Results() []CheckResult

Results returns all check results recorded so far.

func (*Monitor) ResultsForControl 

func (m *Monitor) ResultsForControl(controlID string) []CheckResult

ResultsForControl returns check results for a specific control.

func (*Monitor) RunAll 

func (m *Monitor) RunAll(now time.Time) []CheckResult

RunAll executes all registered checks regardless of schedule. Returns the results.

func (*Monitor) RunDue 

func (m *Monitor) RunDue(now time.Time) []CheckResult

RunDue executes all checks that are due (i.e., the interval has elapsed since their last run). It returns the results of executed checks.

type Period 

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

Period tracks the SOC 2 Type II observation period lifecycle.

func NewPeriod 

func NewPeriod() *Period

NewPeriod creates a new observation period that has not yet started.

func (*Period) AddMilestone 

func (p *Period) AddMilestone(m Milestone) error

AddMilestone adds a milestone to the observation period. Returns an error if the period is not active.

func (*Period) Complete 

func (p *Period) Complete(now time.Time) error

Complete marks the observation period as completed. It returns an error if the period is not active or the minimum duration has not elapsed.

func (*Period) CompleteMilestone 

func (p *Period) CompleteMilestone(name string, completedAt time.Time) error

CompleteMilestone marks a milestone as completed by name. Returns an error if the milestone is not found.

func (*Period) Elapsed 

func (p *Period) Elapsed(now time.Time) time.Duration

Elapsed returns the time elapsed since the observation period started. Returns zero if the period has not started.

func (*Period) EndDate 

func (p *Period) EndDate() time.Time

EndDate returns the observation end date.

func (*Period) Milestones 

func (p *Period) Milestones() []Milestone

Milestones returns a copy of all milestones.

func (*Period) Phase 

func (p *Period) Phase() Phase

Phase returns the current phase.

func (*Period) RemainingDays 

func (p *Period) RemainingDays(now time.Time) int

RemainingDays returns the number of days remaining until the scheduled end date. Returns 0 if the period is completed or past the end date.

func (*Period) Start 

func (p *Period) Start(start time.Time, duration time.Duration) error

Start begins the observation period. The end date is set to at least MinimumDuration from the start date. If duration is greater than MinimumDuration, the provided duration is used instead. Returns an error if the period has already started.

func (*Period) StartDate 

func (p *Period) StartDate() time.Time

StartDate returns the observation start date.

type Phase 

type Phase string

Phase represents the current phase of the observation period. 

const (
	PhaseNotStarted Phase = "not_started"
	PhaseActive     Phase = "active"
	PhaseCompleted  Phase = "completed"
)

type Report 

type Report struct {
	Title                string
	GeneratedAt          time.Time
	PeriodStart          time.Time
	PeriodEnd            time.Time
	Phase                Phase
	DurationDays         int
	Milestones           []Milestone
	Controls             []ControlEffectiveness
	TotalChecks          int
	TotalPassed          int
	TotalFailed          int
	TotalDeviations      int
	OpenDeviations       int
	TotalEvidence        int
	OverallEffectiveness float64
}

Report captures the full observation period summary, including control effectiveness statistics, deviations, and evidence coverage.

func GenerateReport 

func GenerateReport(period *Period, monitor *Monitor, evidence *EvidenceAccumulator, deviations *DeviationTracker) Report

GenerateReport produces an observation period report from the tracker, monitor, evidence accumulator, and deviation tracker.

func (Report) String 

func (r Report) String() string

String returns a human-readable summary of the observation report.

type ScheduledCheck 

type ScheduledCheck struct {
	ControlID string
	Name      string
	Interval  time.Duration
	Check     CheckFunc
	LastRun   time.Time
}

ScheduledCheck defines a recurring control check.

type Severity 

type Severity string

Severity classifies the impact of a deviation. 

const (
	SeverityCritical Severity = "critical"
	SeverityHigh     Severity = "high"
	SeverityMedium   Severity = "medium"
	SeverityLow      Severity = "low"
)

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.