Documentation
¶
Overview ¶
Package services contains domain services that encapsulate business logic spanning multiple entities. These services are stateless and can be called from engine, executor, or future workers.
Index ¶
- type AndSpecification
- type CapabilityAnalyzer
- type ControlEnv
- type ControlFilter
- func (f *ControlFilter) ShouldRun(ctrl entities.Control) (bool, string)
- func (f *ControlFilter) WithExcludedControls(controlIDs []string) *ControlFilter
- func (f *ControlFilter) WithExcludedTags(tags []string) *ControlFilter
- func (f *ControlFilter) WithExclusiveControls(controlIDs []string) *ControlFilter
- func (f *ControlFilter) WithFilterExpression(program *vm.Program) *ControlFilter
- func (f *ControlFilter) WithIncludedSeverities(severities []string) *ControlFilter
- func (f *ControlFilter) WithIncludedTags(tags []string) *ControlFilter
- type ControlLevel
- type ControlSpecification
- type DependencyResolver
- type ExcludedControlsSpecification
- type ExcludedTagsSpecification
- type ExclusiveControlsSpecification
- type ExpressionSpecification
- type IncludedSeveritiesSpecification
- type IncludedTagsSpecification
- type ProfileCompiler
- type StatusAggregator
- func (s *StatusAggregator) AggregateControlStatus(observationStatuses []values.Status) values.Status
- func (s *StatusAggregator) DetermineObservationStatus(_ context.Context, evidence *execution.Evidence, expects []string) (values.Status, []execution.ExpectationResult)
- func (s *StatusAggregator) StatusFromEvidenceStatus(evidenceStatus bool) values.Status
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AndSpecification ¶
type AndSpecification struct {
// contains filtered or unexported fields
}
AndSpecification combines multiple specifications with logical AND.
func NewAndSpecification ¶
func NewAndSpecification(specs ...ControlSpecification) *AndSpecification
NewAndSpecification creates a new AndSpecification.
func (*AndSpecification) IsSatisfiedBy ¶
func (s *AndSpecification) IsSatisfiedBy(ctrl entities.Control) (bool, string)
IsSatisfiedBy checks if all specifications are satisfied.
type CapabilityAnalyzer ¶
type CapabilityAnalyzer struct {
// contains filtered or unexported fields
}
CapabilityAnalyzer extracts specific capability requirements from profiles. This is a pure domain service with no infrastructure dependencies.
func NewCapabilityAnalyzer ¶
func NewCapabilityAnalyzer(registry *capabilities.Registry) *CapabilityAnalyzer
NewCapabilityAnalyzer creates a new capability analyzer.
func (*CapabilityAnalyzer) ExtractCapabilities ¶
func (a *CapabilityAnalyzer) ExtractCapabilities(profile entities.ProfileReader) map[string][]capabilities.Capability
ExtractCapabilities analyzes profile observations to extract specific capability requirements. This enables principle of least privilege by requesting only the resources actually used, rather than the plugin's full declared capabilities.
Returns a map of plugin name to required capabilities, deduplicated.
type ControlEnv ¶
type ControlEnv struct {
ID string `expr:"id"`
Name string `expr:"name"`
Severity string `expr:"severity"`
Owner string `expr:"owner"`
Tags []string `expr:"tags"`
}
ControlEnv defines the variables available during filter expression evaluation.
type ControlFilter ¶
type ControlFilter struct {
// contains filtered or unexported fields
}
ControlFilter implements policy selection logic based on tags, severity, and IDs.
func NewControlFilter ¶
func NewControlFilter() *ControlFilter
NewControlFilter initializes a new empty filter.
func (*ControlFilter) ShouldRun ¶
func (f *ControlFilter) ShouldRun(ctrl entities.Control) (bool, string)
ShouldRun evaluates whether a control matches the filter criteria. It returns true if the control should execute, along with a reason if skipped.
func (*ControlFilter) WithExcludedControls ¶
func (f *ControlFilter) WithExcludedControls(controlIDs []string) *ControlFilter
WithExcludedControls excludes specific control IDs.
func (*ControlFilter) WithExcludedTags ¶
func (f *ControlFilter) WithExcludedTags(tags []string) *ControlFilter
WithExcludedTags excludes controls with any of these tags.
func (*ControlFilter) WithExclusiveControls ¶
func (f *ControlFilter) WithExclusiveControls(controlIDs []string) *ControlFilter
WithExclusiveControls restricts execution to ONLY the specified control IDs. If set, all other filters are ignored.
func (*ControlFilter) WithFilterExpression ¶
func (f *ControlFilter) WithFilterExpression(program *vm.Program) *ControlFilter
WithFilterExpression applies a compiled Expr program for advanced filtering.
func (*ControlFilter) WithIncludedSeverities ¶
func (f *ControlFilter) WithIncludedSeverities(severities []string) *ControlFilter
WithIncludedSeverities includes only controls with these severities.
func (*ControlFilter) WithIncludedTags ¶
func (f *ControlFilter) WithIncludedTags(tags []string) *ControlFilter
WithIncludedTags includes only controls with any of these tags.
type ControlLevel ¶
ControlLevel represents controls at a specific dependency level
type ControlSpecification ¶
type ControlSpecification interface {
// IsSatisfiedBy checks if the control meets the specification.
// Returns true if satisfied, along with a reason if not (or empty if satisfied).
IsSatisfiedBy(ctrl entities.Control) (bool, string)
}
ControlSpecification defines a condition that a control must meet.
type DependencyResolver ¶
type DependencyResolver struct{}
DependencyResolver handles control dependency graph operations
func NewDependencyResolver ¶
func NewDependencyResolver() *DependencyResolver
NewDependencyResolver creates a new dependency resolver service
func (*DependencyResolver) BuildControlDAG ¶
func (r *DependencyResolver) BuildControlDAG(controls []entities.Control) ([]ControlLevel, error)
BuildControlDAG builds a dependency graph using Kahn's algorithm. Returns controls grouped by level for parallel execution within levels.
Algorithm: 1. Build adjacency list and in-degree map 2. Find all controls with no dependencies (in-degree 0) 3. Process controls level by level, decrementing in-degrees 4. Detect cycles (remaining controls with in-degree > 0)
func (*DependencyResolver) ResolveDependencies ¶
func (r *DependencyResolver) ResolveDependencies(controls []entities.Control) (map[string]map[string]bool, error)
ResolveDependencies calculates transitive dependencies for each control. Returns map of controlID → set of all dependencies (direct + transitive).
Used by --include-dependencies flag to include all controls in dependency chain.
type ExcludedControlsSpecification ¶
type ExcludedControlsSpecification struct {
// contains filtered or unexported fields
}
ExcludedControlsSpecification excludes specified control IDs.
func NewExcludedControlsSpecification ¶
func NewExcludedControlsSpecification(ids map[string]bool) *ExcludedControlsSpecification
NewExcludedControlsSpecification creates a new ExcludedControlsSpecification.
func (*ExcludedControlsSpecification) IsSatisfiedBy ¶
func (s *ExcludedControlsSpecification) IsSatisfiedBy(ctrl entities.Control) (bool, string)
IsSatisfiedBy checks if the control ID is NOT in the excluded list.
type ExcludedTagsSpecification ¶
type ExcludedTagsSpecification struct {
// contains filtered or unexported fields
}
ExcludedTagsSpecification excludes controls with any of the specified tags.
func NewExcludedTagsSpecification ¶
func NewExcludedTagsSpecification(tags map[string]bool) *ExcludedTagsSpecification
NewExcludedTagsSpecification creates a new ExcludedTagsSpecification.
func (*ExcludedTagsSpecification) IsSatisfiedBy ¶
func (s *ExcludedTagsSpecification) IsSatisfiedBy(ctrl entities.Control) (bool, string)
IsSatisfiedBy checks if the control has NONE of the excluded tags.
type ExclusiveControlsSpecification ¶
type ExclusiveControlsSpecification struct {
// contains filtered or unexported fields
}
ExclusiveControlsSpecification includes only specified control IDs.
func NewExclusiveControlsSpecification ¶
func NewExclusiveControlsSpecification(ids map[string]bool) *ExclusiveControlsSpecification
NewExclusiveControlsSpecification creates a new ExclusiveControlsSpecification.
func (*ExclusiveControlsSpecification) IsSatisfiedBy ¶
func (s *ExclusiveControlsSpecification) IsSatisfiedBy(ctrl entities.Control) (bool, string)
IsSatisfiedBy checks if the control ID is in the exclusive list.
type ExpressionSpecification ¶
type ExpressionSpecification struct {
// contains filtered or unexported fields
}
ExpressionSpecification filters controls using an expr program.
func NewExpressionSpecification ¶
func NewExpressionSpecification(program *vm.Program) *ExpressionSpecification
NewExpressionSpecification creates a new ExpressionSpecification.
func (*ExpressionSpecification) IsSatisfiedBy ¶
func (s *ExpressionSpecification) IsSatisfiedBy(ctrl entities.Control) (bool, string)
IsSatisfiedBy evaluates the expr program against the control.
type IncludedSeveritiesSpecification ¶
type IncludedSeveritiesSpecification struct {
// contains filtered or unexported fields
}
IncludedSeveritiesSpecification includes only controls with specified severities.
func NewIncludedSeveritiesSpecification ¶
func NewIncludedSeveritiesSpecification(severities map[string]bool) *IncludedSeveritiesSpecification
NewIncludedSeveritiesSpecification creates a new IncludedSeveritiesSpecification.
func (*IncludedSeveritiesSpecification) IsSatisfiedBy ¶
func (s *IncludedSeveritiesSpecification) IsSatisfiedBy(ctrl entities.Control) (bool, string)
IsSatisfiedBy checks if the control severity is in the included list.
type IncludedTagsSpecification ¶
type IncludedTagsSpecification struct {
// contains filtered or unexported fields
}
IncludedTagsSpecification includes only controls with any of the specified tags.
func NewIncludedTagsSpecification ¶
func NewIncludedTagsSpecification(tags map[string]bool) *IncludedTagsSpecification
NewIncludedTagsSpecification creates a new IncludedTagsSpecification.
func (*IncludedTagsSpecification) IsSatisfiedBy ¶
func (s *IncludedTagsSpecification) IsSatisfiedBy(ctrl entities.Control) (bool, string)
IsSatisfiedBy checks if the control has ANY of the included tags.
type ProfileCompiler ¶
type ProfileCompiler struct{}
ProfileCompiler transforms raw profiles into validated, immutable profiles. This is a domain service that encapsulates the compilation process.
Compilation steps: 1. Deep copy the raw profile (prevent mutation) 2. Apply default values to controls 3. Validate invariants 4. Return immutable ValidatedProfile
func NewProfileCompiler ¶
func NewProfileCompiler() *ProfileCompiler
NewProfileCompiler creates a new profile compiler service.
func (*ProfileCompiler) Compile ¶
func (c *ProfileCompiler) Compile(raw *entities.Profile) (*entities.ValidatedProfile, error)
Compile transforms a raw profile into a validated, immutable profile. The input profile is NOT modified (immutability guarantee).
Returns an error if the profile fails validation.
type StatusAggregator ¶
type StatusAggregator struct {
// contains filtered or unexported fields
}
StatusAggregator determines status at different levels of the execution hierarchy. It caches compiled expressions to avoid redundant compilation overhead.
func NewStatusAggregator ¶
func NewStatusAggregator() *StatusAggregator
NewStatusAggregator creates a new status aggregator service with initialized cache.
func (*StatusAggregator) AggregateControlStatus ¶
func (s *StatusAggregator) AggregateControlStatus(observationStatuses []values.Status) values.Status
AggregateControlStatus determines control status from observation statuses.
Business Rule: Failure precedence for compliance reporting - If ANY observation is StatusFail → Control is StatusFail (proven non-compliance) - If ANY observation is StatusError (but no failures) → Control is StatusError (inconclusive) - If ALL observations are StatusPass → Control is StatusPass
Rationale: If 9 observations FAIL and 1 errors, the control FAILED (not errored). A proven compliance violation is more important than a technical error. Auditors need to see definitive failures, not have them masked by errors.
func (*StatusAggregator) DetermineObservationStatus ¶
func (s *StatusAggregator) DetermineObservationStatus( _ context.Context, evidence *execution.Evidence, expects []string, ) (values.Status, []execution.ExpectationResult)
DetermineObservationStatus evaluates expect expressions against evidence data.
Evaluation Rules: - ALL expect expressions must evaluate to true for observation to PASS - ANY false expression → observation FAILS - Non-boolean result or compilation error → observation ERRORS
Security: - Expression length limited to 1000 chars (DoS prevention) - Only explicitly provided variables accessible (no probing) - expr-lang prevents code execution, filesystem, network access
Performance: - Compiled expressions are cached to avoid redundant compilation - Thread-safe caching with read/write locks for concurrent execution
Returns: Status and list of expectation results
func (*StatusAggregator) StatusFromEvidenceStatus ¶
func (s *StatusAggregator) StatusFromEvidenceStatus(evidenceStatus bool) values.Status
StatusFromEvidenceStatus converts evidence boolean status to observation status
Source Files