provider

package
v1.0.0 Latest Latest
Warning

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

 Go to latest Published: Jul 28, 2026 License: Apache-2.0 Imports: 12 Imported by: 0

Documentation

Index

Constants

View Source 
const WorkspaceDir = ".complytime"

WorkspaceDir is the workspace-local directory complyctl uses for all per-project artifacts (generated configs, scan output, state). Provider authors should use this constant when constructing paths under the workspace rather than hard-coding the directory name.

Variables

View Source 
var Handshake = goplugin.HandshakeConfig{
	ProtocolVersion: 1,
	MagicCookieKey:  "COMPLYCTL_PLUGIN",

	MagicCookieValue: "ddff478d-578e-4d9d-8253-35e8ebf548d2",
}

Handshake is the shared config that providers must match to connect. Wire values are frozen — do not change MagicCookieKey, MagicCookieValue, or ProtocolVersion.

View Source 
var SupportedProviders = map[string]goplugin.Plugin{
	"evaluator": &GRPCEvaluatorPlugin{},
}

SupportedProviders is the provider type map used when creating go-plugin clients.

Functions

func Serve 

func Serve(impl Provider)

Serve starts the provider process. Provider authors call this from main(). A JSON logger is created at Trace level so every message reaches the client; the client-side logger level controls what is actually written.

Types

type AssessmentConfiguration 

type AssessmentConfiguration struct {
	PlanID        string
	RequirementID string
	Parameters    map[string]string
	// EvaluatorID is used for routing to the correct provider. It is not
	// serialized over gRPC — routing is handled by the provider manager.
	EvaluatorID string
}

AssessmentConfiguration carries one Gemara assessment plan selected for provider generation. PlanID is the assessment plan id used by providers for matching provider content. RequirementID is the Gemara requirement-id used later for report output.

func (AssessmentConfiguration) MatchID 

func (c AssessmentConfiguration) MatchID() string

MatchID returns the identifier providers should use to match generated content. Assessment plan IDs take precedence when present; global evaluator configurations can fall back to requirement IDs.

type AssessmentLog 

type AssessmentLog struct {
	// PlanID carries the provider-returned match ID before scan output resolves
	// it to the Gemara requirement-id.
	PlanID string
	// RequirementID carries the final Gemara requirement-id after scan output
	// resolution. Output/reporting code should use this field.
	RequirementID  string
	Steps          []Step
	Message        string
	Confidence     ConfidenceLevel
	Evidence       []Evidence
	Recommendation string
}

AssessmentLog holds the evaluation result for one provider assessment.

type Client 

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

Client provides gRPC communication with a provider subprocess managed by hashicorp/go-plugin.

func NewClient 

func NewClient(executablePath string, logger hclog.Logger) (*Client, error)

func (*Client) Close 

func (c *Client) Close()

func (*Client) Describe 

func (c *Client) Describe(ctx context.Context, req *DescribeRequest) (*DescribeResponse, error)

func (*Client) Generate 

func (c *Client) Generate(ctx context.Context, req *GenerateRequest) (*GenerateResponse, error)

func (*Client) Scan 

func (c *Client) Scan(ctx context.Context, req *ScanRequest) (*ScanResponse, error)

type ConfidenceLevel 

type ConfidenceLevel int32

ConfidenceLevel indicates the evaluator's confidence in an assessment result. Mirrors go-gemara ConfidenceLevel enum values (1:1 mapping). 

const (
	ConfidenceLevelNotSet       ConfidenceLevel = 0
	ConfidenceLevelUndetermined ConfidenceLevel = 1
	ConfidenceLevelLow          ConfidenceLevel = 2
	ConfidenceLevelMedium       ConfidenceLevel = 3
	ConfidenceLevelHigh         ConfidenceLevel = 4
)

type DescribeRequest 

type DescribeRequest struct{}

DescribeRequest is sent to discover provider identity and requirements.

type DescribeResponse 

type DescribeResponse struct {
	Healthy                      bool
	Version                      string
	ErrorMessage                 string
	RequiredGlobalVariables      []string
	RequiredTargetVariables      []string
	OptionalTargetVariableGroups []string
}

DescribeResponse reports provider identity, health, version, and declared variable requirements used by doctor diagnostics (R51).

type Discovery 

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

Discovery scans a directory for provider executables matching the naming convention.

func NewDiscovery 

func NewDiscovery(providerDir string) *Discovery

func (*Discovery) DiscoverProviders 

func (d *Discovery) DiscoverProviders() ([]ProviderInfo, error)

DiscoverProviders scans the user provider directory and the system-wide provider directory for executables matching the naming convention. User-directory providers take precedence over system-installed ones.

type Evidence 

type Evidence struct {
	ID          string
	Type        string
	Description string
	Payload     []byte
	CollectedAt string
}

Evidence records a piece of data collected during assessment.

type GRPCEvaluatorPlugin 

type GRPCEvaluatorPlugin struct {
	goplugin.Plugin
	Impl Provider
}

GRPCEvaluatorPlugin implements hashicorp/go-plugin.GRPCPlugin for the evaluator service.

func (*GRPCEvaluatorPlugin) GRPCClient 

func (p *GRPCEvaluatorPlugin) GRPCClient(_ context.Context, _ *goplugin.GRPCBroker, c *grpc.ClientConn) (interface{}, error)

func (*GRPCEvaluatorPlugin) GRPCServer 

func (p *GRPCEvaluatorPlugin) GRPCServer(_ *goplugin.GRPCBroker, s *grpc.Server) error

type GenerateRequest 

type GenerateRequest struct {
	GlobalVariables       map[string]string
	Configuration         []AssessmentConfiguration
	TargetVariables       map[string]string
	ComplypackContentPath string
}

GenerateRequest carries assessment plan configuration to a provider. See R48: three-tier variable model.

type GenerateResponse 

type GenerateResponse struct {
	Success      bool
	ErrorMessage string
}

GenerateResponse confirms whether policy preparation succeeded.

type LoadedProvider 

type LoadedProvider struct {
	Info   ProviderInfo
	Client Provider
}

LoadedProvider pairs discovery metadata with a live gRPC client.

func (*LoadedProvider) GetClient 

func (p *LoadedProvider) GetClient() Provider

type Manager 

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

Manager handles provider discovery, lifecycle, and request routing.

func NewManager 

func NewManager(providerDir string, logger hclog.Logger) (*Manager, error)

func (*Manager) Cleanup 

func (m *Manager) Cleanup()

Cleanup kills all managed provider subprocesses. Call via defer after LoadProviders.

func (*Manager) GetProvider 

func (m *Manager) GetProvider(evaluatorID string) (*LoadedProvider, error)

func (*Manager) ListProviders 

func (m *Manager) ListProviders() []*LoadedProvider

func (*Manager) LoadProviders 

func (m *Manager) LoadProviders() error

LoadProviders discovers providers via executable naming convention and verifies each via Describe RPC before registering.

func (*Manager) RouteGenerate 

func (m *Manager) RouteGenerate(ctx context.Context, evaluatorID string, globalVars, targetVars map[string]string, configs []AssessmentConfiguration, complypackContentPath string) error

RouteGenerate dispatches a GenerateRequest to the provider matching evaluatorID. globalVars carries workspace-level variables; targetVars carries per-target variables from the three-tier model (R48). complypackContentPath is the path to a cached complypack content archive for the evaluator; pass "" when no complypack is available (backward compatible).

func (*Manager) RouteScan 

func (m *Manager) RouteScan(ctx context.Context, evaluatorID string, targets []Target) ([]AssessmentLog, error)

RouteScan dispatches a ScanRequest to the provider matching evaluatorID. The provider evaluates all requirements from Generate-time state — no requirement IDs are sent over the wire. See R47: specs/001-gemara-native-workflow/research.md

Backward-compat: injects synthetic error assessments for operational failures so callers that only consume the assessment stream still see error entries. New callers should prefer RouteScanResult.

func (*Manager) RouteScanResult 

func (m *Manager) RouteScanResult(ctx context.Context, evaluatorID string, targets []Target) (*ScanResult, error)

RouteScanResult dispatches a ScanRequest and returns the full ScanResult including both assessments and operational errors. Callers that need to distinguish evaluation results from infrastructure failures should use this method instead of RouteScan.

type Provider 

type Provider interface {
	Describe(ctx context.Context, req *DescribeRequest) (*DescribeResponse, error)
	Generate(ctx context.Context, req *GenerateRequest) (*GenerateResponse, error)
	Scan(ctx context.Context, req *ScanRequest) (*ScanResponse, error)
}

Provider is the interface that provider authors implement for evaluation RPCs.

type ProviderInfo 

type ProviderInfo struct {
	ProviderID     string
	EvaluatorID    string
	ExecutablePath string
}

ProviderInfo holds the identity and filesystem path of a discovered provider.

type Result 

type Result int32

Result is the outcome of a single assessment step. Each value has a 1:1 mapping to a proto Result enum value and a corresponding Gemara result state used in report generation. 

const (
	// ResultUnspecified indicates the step was never executed.
	// Maps to proto RESULT_UNSPECIFIED / Gemara NotRun.
	ResultUnspecified Result = 0

	// ResultPassed indicates the requirement was evaluated and met.
	// Maps to proto RESULT_PASSED / Gemara Passed.
	ResultPassed Result = 1

	// ResultFailed indicates the requirement was evaluated and not met.
	// Maps to proto RESULT_FAILED / Gemara Failed.
	ResultFailed Result = 2

	// ResultSkipped indicates the requirement was evaluated but does
	// not apply to the target. Providers MUST report not-applicable
	// results with this value rather than omitting the assessment.
	// Maps to proto RESULT_SKIPPED / Gemara NotApplicable.
	ResultSkipped Result = 3

	// ResultError indicates the evaluation could not complete due to
	// a tool or configuration error. Compliance posture is unknown.
	// Maps to proto RESULT_ERROR / Gemara Unknown.
	ResultError Result = 4
)

type ScanRequest 

type ScanRequest struct {
	Targets []Target
}

ScanRequest carries targets to evaluate. The scanning provider evaluates all requirements from Generate-time state. See R47: specs/001-gemara-native-workflow/research.md

type ScanResponse 

type ScanResponse struct {
	Assessments []AssessmentLog
	Errors      []string
}

ScanResponse carries assessment results from a provider scan. Errors holds operational/infrastructure failures (coverage gaps). Assessments holds actual evaluation results (compliance posture known).

type ScanResult 

type ScanResult struct {
	Assessments []AssessmentLog
	Errors      []string
	// contains filtered or unexported fields
}

ScanResult holds the combined output of a RouteScanResult call, separating evaluation results (Assessments) from operational failures (Errors).

func (*ScanResult) HasErrors 

func (r *ScanResult) HasErrors() bool

HasErrors reports whether the scan encountered operational failures.

type Step 

type Step struct {
	Name    string
	Result  Result
	Message string
}

Step is one discrete check within an assessment.

type Target 

type Target struct {
	TargetID  string
	Variables map[string]string
}

Target identifies a system or environment to scan, with provider-specific variables.

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.