audit

Documentation

Overview

Package audit provides SOC 2 Type I audit tooling including readiness assessment, evidence collection automation, gap analysis, and report generation. It ties together the compliance and security packages to produce a complete audit picture.

Index

• func CollectAllEvidence(policies []compliance.PolicyDocument) (*compliance.EvidenceCollector, int, []error)
• func SortGapsBySeverity(gaps []Gap)
• type ControlReadiness
• type Gap
• type GapAnalysis
  • func AnalyzeGaps(mapping *compliance.ControlMapping, collector *compliance.EvidenceCollector) *GapAnalysis
  • func (ga *GapAnalysis) GapRate() float64
  • func (ga *GapAnalysis) GapsByCategory(cat compliance.Category) []Gap
  • func (ga *GapAnalysis) GapsBySeverity(sev GapSeverity) []Gap
• type GapSeverity
• type PolicyEvidenceSource
  • func (p *PolicyEvidenceSource) Collect(controlID compliance.ControlID) ([]compliance.Evidence, error)
  • func (p *PolicyEvidenceSource) Name() string
  • func (p *PolicyEvidenceSource) SupportedControls() []compliance.ControlID
• type ReadinessAssessment
  • func AssessReadiness(mapping *compliance.ControlMapping, collector *compliance.EvidenceCollector) *ReadinessAssessment
  • func (ra *ReadinessAssessment) NotReady() []ControlReadiness
  • func (ra *ReadinessAssessment) Partial() []ControlReadiness
  • func (ra *ReadinessAssessment) ReadinessRate() float64
  • func (ra *ReadinessAssessment) Ready() []ControlReadiness
• type ReadinessLevel
• type Report
  • func GenerateReport(cfg ReportConfig, mapping *compliance.ControlMapping, ...) *Report
  • func (r *Report) Render() string
• type ReportConfig
• type SecurityControlSource
  • func (s *SecurityControlSource) Collect(controlID compliance.ControlID) ([]compliance.Evidence, error)
  • func (s *SecurityControlSource) Name() string
  • func (s *SecurityControlSource) SupportedControls() []compliance.ControlID
• type TestingProcedure

Functions

func CollectAllEvidence

func CollectAllEvidence(policies []compliance.PolicyDocument) (*compliance.EvidenceCollector, int, []error)

CollectAllEvidence creates an EvidenceCollector pre-configured with all audit evidence sources: security controls, policies, CI/CD, and code review.

func SortGapsBySeverity

func SortGapsBySeverity(gaps []Gap)

SortGapsBySeverity sorts gaps with critical first, low last.

Types

type ControlReadiness

type ControlReadiness struct {
	Control       compliance.Control
	Level         ReadinessLevel
	EvidenceIDs   []string
	Assessment    compliance.ControlAssessment
	HasAssessment bool
	Notes         string
}

ControlReadiness captures the readiness state of a single control.

type Gap

type Gap struct {
	Control        compliance.Control
	Severity       GapSeverity
	MissingItems   []string // What is missing (e.g., "assessment", "evidence", "policy")
	Recommendation string
}

Gap represents a single control that is missing or incomplete.

type GapAnalysis

type GapAnalysis struct {
	TotalControls       int
	ImplementedControls int
	GapCount            int
	Gaps                []Gap
}

GapAnalysis is the result of comparing implemented controls against the full set of required SOC 2 Trust Services Criteria.

func AnalyzeGaps

func AnalyzeGaps(mapping *compliance.ControlMapping, collector *compliance.EvidenceCollector) *GapAnalysis

AnalyzeGaps examines the control mapping and evidence collector to identify controls that are missing assessments, evidence, or both. It returns a GapAnalysis with prioritized findings.

func (*GapAnalysis) GapRate

func (ga *GapAnalysis) GapRate() float64

GapRate returns the percentage of controls that have gaps.

func (*GapAnalysis) GapsByCategory

func (ga *GapAnalysis) GapsByCategory(cat compliance.Category) []Gap

GapsByCategory returns gaps filtered by TSC category.

func (*GapAnalysis) GapsBySeverity

func (ga *GapAnalysis) GapsBySeverity(sev GapSeverity) []Gap

GapsBySeverity returns gaps filtered by severity.

type GapSeverity

type GapSeverity string

GapSeverity indicates the severity of a missing control.

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

type PolicyEvidenceSource

type PolicyEvidenceSource struct {
	Policies []compliance.PolicyDocument
}

PolicyEvidenceSource collects evidence from compliance policy documents.

func (*PolicyEvidenceSource) Collect

func (p *PolicyEvidenceSource) Collect(controlID compliance.ControlID) ([]compliance.Evidence, error)

Collect returns evidence for a control based on matching policy documents.

func (*PolicyEvidenceSource) Name

func (p *PolicyEvidenceSource) Name() string

Name returns the source name.

func (*PolicyEvidenceSource) SupportedControls

func (p *PolicyEvidenceSource) SupportedControls() []compliance.ControlID

SupportedControls returns the control IDs covered by the registered policies.

type ReadinessAssessment

type ReadinessAssessment struct {
	AssessedAt time.Time
	Controls   []ControlReadiness
}

ReadinessAssessment maps all implemented controls to Trust Services Criteria and evaluates audit readiness.

func AssessReadiness

func AssessReadiness(mapping *compliance.ControlMapping, collector *compliance.EvidenceCollector) *ReadinessAssessment

AssessReadiness performs a readiness assessment using the control mapping and evidence collector. A control is "ready" if it has both an assessment (compliant or partially compliant) and at least one piece of evidence. It is "partial" if it has either an assessment or evidence, but not both. It is "not ready" if it has neither.

func (*ReadinessAssessment) NotReady

func (ra *ReadinessAssessment) NotReady() []ControlReadiness

NotReady returns controls that are not ready for audit.

func (*ReadinessAssessment) Partial

func (ra *ReadinessAssessment) Partial() []ControlReadiness

Partial returns controls that are partially ready.

func (*ReadinessAssessment) ReadinessRate

func (ra *ReadinessAssessment) ReadinessRate() float64

ReadinessRate returns the percentage of controls that are fully ready.

func (*ReadinessAssessment) Ready

func (ra *ReadinessAssessment) Ready() []ControlReadiness

Ready returns controls that are fully ready for audit.

type ReadinessLevel

type ReadinessLevel string

ReadinessLevel indicates how ready a control is for audit.

const (
	ReadinessReady    ReadinessLevel = "ready"
	ReadinessPartial  ReadinessLevel = "partial"
	ReadinessNotReady ReadinessLevel = "not_ready"
)

type Report

type Report struct {
	Config      ReportConfig
	Readiness   *ReadinessAssessment
	Gaps        *GapAnalysis
	GeneratedAt time.Time
}

Report is a complete SOC 2 Type I audit report.

func GenerateReport

func GenerateReport(cfg ReportConfig, mapping *compliance.ControlMapping, collector *compliance.EvidenceCollector) *Report

GenerateReport creates a complete SOC 2 Type I audit report from the control mapping and evidence collector.

func (*Report) Render

func (r *Report) Render() string

Render formats the audit report as a markdown document.

type ReportConfig

type ReportConfig struct {
	Organization string
	Auditor      string
	PeriodStart  time.Time
	PeriodEnd    time.Time
}

ReportConfig configures the audit report generation.

type SecurityControlSource

type SecurityControlSource struct{}

SecurityControlSource collects evidence from the security package's implemented controls. It maps security features (API key management, encryption, network security, secrets management, vulnerability scanning, incident response) to the SOC 2 controls they satisfy.

func (*SecurityControlSource) Collect

func (s *SecurityControlSource) Collect(controlID compliance.ControlID) ([]compliance.Evidence, error)

Collect returns evidence for a specific control based on security package capabilities.

func (*SecurityControlSource) Name

func (s *SecurityControlSource) Name() string

Name returns the source name.

func (*SecurityControlSource) SupportedControls

func (s *SecurityControlSource) SupportedControls() []compliance.ControlID

SupportedControls returns the SOC 2 control IDs that the security package provides evidence for.

type TestingProcedure

type TestingProcedure struct {
	ControlID        compliance.ControlID
	Category         compliance.Category
	Title            string
	Objective        string
	Procedure        string
	ExpectedEvidence string
}

TestingProcedure defines how to test a specific control.