opa

Documentation

Overview

Package opa wraps the Open Policy Agent runtime for Plumber's rule engine. Each policy is a Rego module evaluated against an ir.NormalizedPipeline and emits violations through the shared "deny" rule.

This is the Phase 0 scaffold: it can load in-memory modules and return findings. Embedded policy discovery, user-policy overrides, and reporter integration land in later phases.

Index

• type Engine
  • func New() *Engine
  • func (e *Engine) Evaluate(ctx context.Context, pipeline *ir.NormalizedPipeline, config map[string]any) ([]Finding, error)
  • func (e *Engine) LoadFromFS(fsys fs.FS) error
  • func (e *Engine) LoadFromFSFiltered(fsys fs.FS, skip func(filename string, content []byte) bool) error
  • func (e *Engine) LoadModule(name, source string)
• type Finding
  • func (f Finding) MarshalJSON() ([]byte, error)
  • func (f *Finding) UnmarshalJSON(b []byte) error

Types

type Engine

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

Engine evaluates Rego policies against an IR pipeline.

func New

func New() *Engine

New returns an Engine with no policies loaded.

func (*Engine) Evaluate

func (e *Engine) Evaluate(ctx context.Context, pipeline *ir.NormalizedPipeline, config map[string]any) ([]Finding, error)

Evaluate runs every loaded policy against pipeline and returns the aggregated findings. Policies see a two-field input:

input.pipeline  — the NormalizedPipeline
input.config    — an arbitrary map forwarded from .plumber.yaml

config may be nil. Pipeline must not be nil.

func (*Engine) LoadFromFS

func (e *Engine) LoadFromFS(fsys fs.FS) error

LoadFromFS loads every .rego file at the root of fsys. The module's logical name is the file's base name without its extension. Nested subdirectories are ignored for now; the concern-based layout lands with the first real policies in Phase 2.

func (*Engine) LoadFromFSFiltered

func (e *Engine) LoadFromFSFiltered(fsys fs.FS, skip func(filename string, content []byte) bool) error

LoadFromFSFiltered is LoadFromFS with an optional skip predicate. When skip is non-nil and returns true for a (filename, content) pair, that file is excluded from the engine — it never executes, never produces findings, never costs evaluation time. Used to gate dev-side benched policies out of production runs without touching the policy files themselves.

func (*Engine) LoadModule

func (e *Engine) LoadModule(name, source string)

LoadModule registers a Rego module under the given logical name. The name must match the module's package path (the "deny" rule is queried at data.<name>.deny).

type Finding

type Finding struct {
	Code     string         `json:"-"`
	Severity string         `json:"-"`
	Message  string         `json:"-"`
	Job      string         `json:"-"`
	File     string         `json:"-"`
	Line     int            `json:"-"`
	Data     map[string]any `json:"-"`
}

Finding is a single rule violation emitted by a policy. File and Line, when populated, point at the exact location of the offending job in the source workflow/pipeline file so editors and terminals can render a clickable file:line link.

Data carries policy-specific structured payload (variable name, affected image link, location, …) emitted by the Rego rule next to the canonical fields. It serialises inline at the top level so downstream consumers can read both the human message and the machine-parseable evidence on the same finding object.

func (Finding) MarshalJSON

func (f Finding) MarshalJSON() ([]byte, error)

MarshalJSON flattens the canonical fields and the Data payload into a single object so structured keys appear at the top level (the shape pre-Rego consumers parsed). Empty canonical fields are omitted, mirroring the previous `omitempty` tags.

func (*Finding) UnmarshalJSON

func (f *Finding) UnmarshalJSON(b []byte) error

UnmarshalJSON splits an incoming flat object into the canonical fields and the Data bag. Unknown keys land in Data so they survive a round-trip even when added by future rules.