policy

package
v0.0.0-...-1a28f28 Latest Latest
Warning

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

 Go to latest Published: Jan 22, 2026 License: MIT Imports: 35 Imported by: 0

Documentation

Overview

Package policy provides the CEL-based policy evaluation engine for Deputy.

Policies are defined in YAML with CEL expressions that evaluate against typed proto inputs like vulnerabilities, packages, and container images.

The package provides:

  • Parsing and compiling policy bundles (YAML + CEL)
  • Pre-compiled policy execution via Engine
  • Entrypoint-based routing for different evaluation contexts
  • Custom CEL helper functions for security analysis

Example usage: 

engine, err := policy.NewEngineFromPaths([]string{"policy.yaml"})
actions, err := engine.EvaluateAll(ctx, payload, "scan", "scan_vulnerability")

Index

Constants

View Source 
const (
	// ActionDeny blocks the operation and returns an error to the caller.
	ActionDeny = "deny"

	// ActionWarn allows the operation but emits a warning message.
	ActionWarn = "warn"

	// ActionAllow explicitly permits the operation (no effect if other rules deny).
	ActionAllow = "allow"
)

Action type constants represent the standard policy decision types. These are case-insensitive when compared (use ActionTypeIs for comparison).

Variables

View Source 
var (
	// EntrypointsProxy lists all entrypoints related to the artifact proxy.
	EntrypointsProxy = []Entrypoint{
		EntrypointGoArtifactRequest,
		EntrypointNpmArtifactRequest,
		EntrypointPypiArtifactRequest,
		EntrypointRubygemsArtifactRequest,
		EntrypointOCIArtifactRequest,
	}
	// EntrypointsScan lists all entrypoints related to the scan command.
	EntrypointsScan = []Entrypoint{
		EntrypointScanReport,
		EntrypointScanVulnerability,
	}
	// EntrypointsDiff lists all entrypoints related to the diff command (git repositories).
	EntrypointsDiff = []Entrypoint{
		EntrypointDiffReport,
		EntrypointDiffDependencyChange,
		EntrypointDiffVulnerability,
	}
	// EntrypointsContainerDiff lists all entrypoints related to container image diff.
	EntrypointsContainerDiff = []Entrypoint{
		EntrypointContainerDiffReport,
		EntrypointContainerDiffChange,
		EntrypointContainerDiffVulnerability,
		EntrypointContainerDiffLayer,
		EntrypointContainerDiffConfig,
	}
	// EntrypointsSBOM lists all entrypoints related to the sbom command.
	EntrypointsSBOM = []Entrypoint{
		EntrypointSBOMReport,
		EntrypointSBOMComponent,
	}
	// EntrypointsFix lists all entrypoints related to the fix command.
	EntrypointsFix = []Entrypoint{
		EntrypointFixPlan,
		EntrypointFixPlanStep,
	}
	// EntrypointsTriage lists all entrypoints related to the triage command.
	EntrypointsTriage = []Entrypoint{
		EntrypointTriageReport,
		EntrypointTriageCluster,
	}
	// EntrypointsDockerfile lists all entrypoints related to Dockerfile analysis.
	EntrypointsDockerfile = []Entrypoint{
		EntrypointDockerfileReport,
		EntrypointDockerfileStage,
	}
	// EntrypointsSecrets lists all entrypoints related to secret detection.
	EntrypointsSecrets = []Entrypoint{
		EntrypointSecretsReport,
		EntrypointSecretsFinding,
	}
	// EntrypointsGraph lists all entrypoints related to dependency graph analysis.
	EntrypointsGraph = []Entrypoint{
		EntrypointGraphReport,
		EntrypointGraphNode,
		EntrypointGraphEdge,
	}
	// EntrypointsService lists all entrypoints related to API request authorization.
	// These enable RBAC/ABAC when Deputy runs as a shared service (server mode).
	EntrypointsService = []Entrypoint{
		EntrypointServiceScanRequest,
		EntrypointServiceListRequest,
		EntrypointServiceSBOMRequest,
		EntrypointServiceDiffRequest,
		EntrypointServiceSecretsRequest,
		EntrypointServiceGraphRequest,
	}
	// EntrypointsSandbox lists all entrypoints related to sandbox execution control.
	// These enable policies to control what runs in sandboxes and with what permissions.
	EntrypointsSandbox = []Entrypoint{
		EntrypointSandboxExecution,
		EntrypointSandboxCommand,
		EntrypointSandboxNetwork,
	}

	// AllEntrypoints contains every canonical entrypoint defined in Deputy.
	AllEntrypoints = slices.Concat(EntrypointsProxy, EntrypointsScan, EntrypointsDiff, EntrypointsContainerDiff, EntrypointsSBOM, EntrypointsFix, EntrypointsTriage, EntrypointsDockerfile, EntrypointsSecrets, EntrypointsGraph, EntrypointsService, EntrypointsSandbox)
)
View Source 
var BindingProfiles = map[Entrypoint]BindingProfile{

	EntrypointGoArtifactRequest: {
		Entrypoint:  EntrypointGoArtifactRequest,
		Required:    []string{"request", "env"},
		Optional:    append([]string{"vulnerabilities", "licenses"}, jwtVars...),
		Description: "Triggers when the proxy handles a Go module request",
	},
	EntrypointNpmArtifactRequest: {
		Entrypoint:  EntrypointNpmArtifactRequest,
		Required:    []string{"request", "env"},
		Optional:    append([]string{"vulnerabilities", "licenses"}, jwtVars...),
		Description: "Triggers when the proxy handles an NPM package request",
	},
	EntrypointPypiArtifactRequest: {
		Entrypoint:  EntrypointPypiArtifactRequest,
		Required:    []string{"request", "env"},
		Optional:    append([]string{"vulnerabilities", "licenses"}, jwtVars...),
		Description: "Triggers when the proxy handles a PyPI package request",
	},
	EntrypointRubygemsArtifactRequest: {
		Entrypoint:  EntrypointRubygemsArtifactRequest,
		Required:    []string{"request", "env"},
		Optional:    append([]string{"vulnerabilities", "licenses"}, jwtVars...),
		Description: "Triggers when the proxy handles a RubyGems package request",
	},
	EntrypointOCIArtifactRequest: {
		Entrypoint:  EntrypointOCIArtifactRequest,
		Required:    []string{"request", "env"},
		Optional:    append(append([]string{"vulnerabilities"}, imageVars...), jwtVars...),
		Description: "Triggers when the proxy handles an OCI image request",
	},

	EntrypointScanReport: {
		Entrypoint:  EntrypointScanReport,
		Required:    append([]string{"vulnerabilities", "packages"}, envVars...),
		Optional:    append(targetVars, imageVars...),
		Description: "Triggers after a scan completes with the full report",
	},
	EntrypointScanVulnerability: {
		Entrypoint:  EntrypointScanVulnerability,
		Required:    append(singleVulnerabilityVars, envVars...),
		Optional:    append(targetVars, imageVars...),
		Description: "Triggers for each vulnerability found during a scan",
	},

	EntrypointDiffReport: {
		Entrypoint:  EntrypointDiffReport,
		Required:    append([]string{"changes", "vulnerabilities"}, envVars...),
		Optional:    targetVars,
		Description: "Triggers after a dependency diff completes",
	},
	EntrypointDiffDependencyChange: {
		Entrypoint:  EntrypointDiffDependencyChange,
		Required:    append([]string{"change", "dependency", "pkg"}, envVars...),
		Optional:    targetVars,
		Description: "Triggers for each dependency change in a diff",
	},
	EntrypointDiffVulnerability: {
		Entrypoint:  EntrypointDiffVulnerability,
		Required:    append(singleVulnerabilityVars, envVars...),
		Optional:    targetVars,
		Description: "Triggers for each vulnerability found in a diff",
	},

	EntrypointContainerDiffReport: {
		Entrypoint:  EntrypointContainerDiffReport,
		Required:    append(containerDiffVars, envVars...),
		Optional:    nil,
		Description: "Triggers after a container image diff completes",
	},
	EntrypointContainerDiffChange: {
		Entrypoint:  EntrypointContainerDiffChange,
		Required:    append([]string{"change"}, envVars...),
		Optional:    []string{"base_image", "target_image"},
		Description: "Triggers for each package change between container images",
	},
	EntrypointContainerDiffVulnerability: {
		Entrypoint:  EntrypointContainerDiffVulnerability,
		Required:    append(singleVulnerabilityVars, envVars...),
		Optional:    []string{"base_image", "target_image"},
		Description: "Triggers for each vulnerability difference between images",
	},
	EntrypointContainerDiffLayer: {
		Entrypoint:  EntrypointContainerDiffLayer,
		Required:    append([]string{"layer"}, envVars...),
		Optional:    []string{"base_image", "target_image"},
		Description: "Triggers for each layer difference analysis",
	},
	EntrypointContainerDiffConfig: {
		Entrypoint:  EntrypointContainerDiffConfig,
		Required:    append([]string{"config_changes"}, envVars...),
		Optional:    []string{"base_image", "target_image"},
		Description: "Triggers for configuration changes between images",
	},

	EntrypointSBOMReport: {
		Entrypoint:  EntrypointSBOMReport,
		Required:    append([]string{"sbom", "packages"}, envVars...),
		Optional:    targetVars,
		Description: "Triggers after an SBOM is generated",
	},
	EntrypointSBOMComponent: {
		Entrypoint:  EntrypointSBOMComponent,
		Required:    append([]string{"component", "pkg"}, envVars...),
		Optional:    nil,
		Description: "Triggers for each component in an SBOM",
	},

	EntrypointGraphReport: {
		Entrypoint:  EntrypointGraphReport,
		Required:    append([]string{"graph", "nodes", "edges", "stats", "roots"}, envVars...),
		Optional:    targetVars,
		Description: "Triggers after a dependency graph is built with full graph data",
	},
	EntrypointGraphNode: {
		Entrypoint:  EntrypointGraphNode,
		Required:    append([]string{"node"}, envVars...),
		Optional:    append([]string{"nodes", "edges", "stats", "ancestors", "descendants"}, targetVars...),
		Description: "Triggers for each node in the dependency graph",
	},
	EntrypointGraphEdge: {
		Entrypoint:  EntrypointGraphEdge,
		Required:    append([]string{"edge", "from_node", "to_node"}, envVars...),
		Optional:    append([]string{"nodes", "edges", "stats"}, targetVars...),
		Description: "Triggers for each edge in the dependency graph",
	},

	EntrypointFixPlan: {
		Entrypoint:  EntrypointFixPlan,
		Required:    append([]string{"plan"}, envVars...),
		Optional:    []string{"vulnerabilities", "repo"},
		Description: "Triggers after a remediation plan is generated",
	},
	EntrypointFixPlanStep: {
		Entrypoint:  EntrypointFixPlanStep,
		Required:    append([]string{"step"}, envVars...),
		Optional:    []string{"plan"},
		Description: "Triggers for each step in a remediation plan",
	},

	EntrypointTriageReport: {
		Entrypoint:  EntrypointTriageReport,
		Required:    append([]string{"findings", "vulnerabilities"}, envVars...),
		Optional:    []string{"repo"},
		Description: "Triggers after a triage report is generated",
	},
	EntrypointTriageCluster: {
		Entrypoint:  EntrypointTriageCluster,
		Required:    append([]string{"cluster"}, envVars...),
		Optional:    nil,
		Description: "Triggers for each cluster in a triage report",
	},

	EntrypointDockerfileReport: {
		Entrypoint:  EntrypointDockerfileReport,
		Required:    append(dockerfileVars, envVars...),
		Optional:    targetVars,
		Description: "Triggers after a Dockerfile is parsed",
	},
	EntrypointDockerfileStage: {
		Entrypoint:  EntrypointDockerfileStage,
		Required:    append([]string{"stage"}, envVars...),
		Optional:    dockerfileVars,
		Description: "Triggers for each stage in a multi-stage Dockerfile",
	},

	EntrypointSecretsReport: {
		Entrypoint:  EntrypointSecretsReport,
		Required:    append([]string{"secrets", "report"}, envVars...),
		Optional:    targetVars,
		Description: "Triggers after a secrets scan completes with all findings",
	},
	EntrypointSecretsFinding: {
		Entrypoint:  EntrypointSecretsFinding,
		Required:    append([]string{"secret"}, envVars...),
		Optional:    append([]string{"report"}, targetVars...),
		Description: "Triggers for each secret found during a scan",
	},

	EntrypointServiceScanRequest: {
		Entrypoint:  EntrypointServiceScanRequest,
		Required:    append([]string{"request"}, envVars...),
		Optional:    append(targetVars, jwtVars...),
		Description: "Triggers before a scan is executed via the API",
	},
	EntrypointServiceListRequest: {
		Entrypoint:  EntrypointServiceListRequest,
		Required:    append([]string{"request"}, envVars...),
		Optional:    append(targetVars, jwtVars...),
		Description: "Triggers before a list operation via the API",
	},
	EntrypointServiceSBOMRequest: {
		Entrypoint:  EntrypointServiceSBOMRequest,
		Required:    append([]string{"request"}, envVars...),
		Optional:    append(targetVars, jwtVars...),
		Description: "Triggers before SBOM generation via the API",
	},
	EntrypointServiceDiffRequest: {
		Entrypoint:  EntrypointServiceDiffRequest,
		Required:    append([]string{"request"}, envVars...),
		Optional:    append(targetVars, jwtVars...),
		Description: "Triggers before a diff operation via the API",
	},
	EntrypointServiceSecretsRequest: {
		Entrypoint:  EntrypointServiceSecretsRequest,
		Required:    append([]string{"request"}, envVars...),
		Optional:    append(targetVars, jwtVars...),
		Description: "Triggers before a secrets scan via the API",
	},
	EntrypointServiceGraphRequest: {
		Entrypoint:  EntrypointServiceGraphRequest,
		Required:    append([]string{"request"}, envVars...),
		Optional:    append(targetVars, jwtVars...),
		Description: "Triggers before a graph operation via the API",
	},

	EntrypointSandboxExecution: {
		Entrypoint:  EntrypointSandboxExecution,
		Required:    append([]string{"command", "workspace_dir", "requested_config"}, envVars...),
		Optional:    []string{"context", "source"},
		Description: "Triggers before any sandbox execution begins",
	},
	EntrypointSandboxCommand: {
		Entrypoint:  EntrypointSandboxCommand,
		Required:    append([]string{"command", "sandbox_config"}, envVars...),
		Optional:    []string{"context"},
		Description: "Triggers for each command executed within a sandbox session",
	},
	EntrypointSandboxNetwork: {
		Entrypoint:  EntrypointSandboxNetwork,
		Required:    append([]string{"host", "port", "protocol", "sandbox_config"}, envVars...),
		Optional:    []string{"context"},
		Description: "Triggers when a sandbox requests network access",
	},
}

BindingProfiles maps each entrypoint to its variable bindings. This is the authoritative source for what's available where.

View Source 
var ExampleCategories = []ExampleCategory{
	{
		Name:        "scan",
		Description: "Vulnerability scanning policies",
		Entrypoints: []Entrypoint{
			EntrypointScanVulnerability,
			EntrypointScanReport,
		},
	},
	{
		Name:        "proxy",
		Description: "Package proxy request policies",
		Entrypoints: []Entrypoint{
			EntrypointGoArtifactRequest,
			EntrypointNpmArtifactRequest,
			EntrypointPypiArtifactRequest,
			EntrypointRubygemsArtifactRequest,
			EntrypointOCIArtifactRequest,
		},
	},
	{
		Name:        "diff",
		Description: "Dependency diff policies",
		Entrypoints: []Entrypoint{
			EntrypointDiffReport,
			EntrypointDiffVulnerability,
			EntrypointDiffDependencyChange,
		},
	},
	{
		Name:        "container",
		Description: "Container image policies",
		Entrypoints: []Entrypoint{
			EntrypointContainerDiffReport,
			EntrypointContainerDiffChange,
			EntrypointContainerDiffVulnerability,
		},
	},
	{
		Name:        "dockerfile",
		Description: "Dockerfile analysis policies",
		Entrypoints: []Entrypoint{
			EntrypointDockerfileReport,
			EntrypointDockerfileStage,
		},
	},
	{
		Name:        "sbom",
		Description: "SBOM generation policies",
		Entrypoints: []Entrypoint{
			EntrypointSBOMReport,
			EntrypointSBOMComponent,
		},
	},
	{
		Name:        "graph",
		Description: "Dependency graph policies",
		Entrypoints: []Entrypoint{
			EntrypointGraphReport,
			EntrypointGraphNode,
			EntrypointGraphEdge,
		},
	},
	{
		Name:        "secrets",
		Description: "Secret scanning policies",
		Entrypoints: []Entrypoint{
			EntrypointSecretsReport,
			EntrypointSecretsFinding,
		},
	},
	{
		Name:        "service",
		Description: "API authorization policies",
		Entrypoints: []Entrypoint{
			EntrypointServiceScanRequest,
			EntrypointServiceListRequest,
			EntrypointServiceSBOMRequest,
		},
	},
}

ExampleCategories organizes entrypoints into logical groups.

Functions

func ActionTypeIs 

func ActionTypeIs(actionType, expected string) bool

ActionTypeIs returns true if the action type matches the expected type (case-insensitive).

func Compile 

func Compile(source string, extraVars []string) error

Compile verifies that the CEL source parses and type-checks using the provided extra variable names (in addition to the default policy variables).

func DefaultVariableNames 

func DefaultVariableNames() []string

DefaultVariableNames returns the identifiers that Deputy injects into CEL environments for policies. Tooling (e.g., LSP) uses this to stay aligned with the runtime without duplicating the list.

func Evaluate 

func Evaluate(ctx context.Context, source string, input map[string]any) (any, error)

Evaluate compiles the provided CEL source and evaluates it against the input document. Input keys are exposed to the CEL program as top-level identifiers. This is a low-level function for ad-hoc CEL evaluation; prefer Engine.EvaluateAll with typed PolicyInput protos for policy evaluation.

func IsAllowedCommand 

func IsAllowedCommand(cmd string) bool

IsAllowedCommand reports whether the command is one of the known CLI/proxy commands.

func IsAllowedEntrypoint 

func IsAllowedEntrypoint(name string) bool

IsAllowedEntrypoint reports whether the name matches a canonical entrypoint.

func NewFilterEnv 

func NewFilterEnv() (*cel.Env, error)

NewFilterEnv creates a CEL environment suitable for filter expressions. It includes the vulnerability variable and severity constants.

func OptionalVariablesForEntrypoint 

func OptionalVariablesForEntrypoint(ep Entrypoint) []string

OptionalVariablesForEntrypoint returns variables that may be available.

func ProtoToMap 

func ProtoToMap(msg proto.Message) (map[string]any, error)

ProtoToMap converts a proto message to map[string]any for CEL evaluation. Uses protojson with UseProtoNames to preserve snake_case field names, UseEnumNumbers so enums serialize as integers for CEL comparison, and EmitUnpopulated to ensure empty arrays and zero values are present (required for policies that check size() on potentially empty lists). Returns an error if serialization fails; use protoToMap for internal use where errors can be safely ignored (e.g., example generation).

func RequiredVariablesForEntrypoint 

func RequiredVariablesForEntrypoint(ep Entrypoint) []string

RequiredVariablesForEntrypoint returns variables that are always available.

func SeverityConstants 

func SeverityConstants() map[string]any

SeverityConstants returns the severity constants map for CEL expressions. This allows external packages to use the same constants (severity.critical, etc.)

func TryParseStructuredBundleBytes 

func TryParseStructuredBundleBytes(data []byte) (*structuredBundle, bool, error)

TryParseStructuredBundleBytes parses data into a structuredBundle and returns it plus a parsed flag.

func VariablesForEntrypoint 

func VariablesForEntrypoint(ep Entrypoint) []string

VariablesForEntrypoint returns all variables available at the given entrypoint. This is useful for LSP autocompletion and documentation generation.

Types

type Action 

type Action struct {
	Source      string            // Source is the name of the policy that generated this action.
	Type        string            // Type is the action type (e.g., "deny", "warn", "allow").
	Reason      string            // Reason is a human-readable explanation for the action.
	Message     string            // Message is an optional additional message.
	Remediation string            // Remediation suggests how to resolve the issue.
	Code        string            // Code is a machine-readable error code.
	Status      *int              // Status is an optional HTTP status code to return.
	Headers     map[string]string // Headers are HTTP headers to set in the response.
	Annotations map[string]any    // Annotations are arbitrary metadata attached to the action.
	Raw         map[string]any    // Raw is the original map returned by the policy.
}

Action represents a normalized policy decision emitted by a CEL program.

func EvaluateAll 

func EvaluateAll(ctx context.Context, sources []Source, input proto.Message) ([]Action, error)

EvaluateAll executes every policy source against the provided input proto and aggregates the resulting actions.

func EvaluateMap 

func EvaluateMap(ctx context.Context, sources []Source, input map[string]any) ([]Action, error)

EvaluateMap executes policies against a raw map[string]any input. This is intended for CLI testing scenarios where the input is arbitrary JSON rather than a typed proto message. For production use, prefer EvaluateAll with typed proto inputs.

type BindingProfile 

type BindingProfile struct {
	// Entrypoint is the canonical entrypoint this profile applies to.
	Entrypoint Entrypoint

	// Required lists variables that are always available at this entrypoint.
	// Policy authors can rely on these without null checks.
	Required []string

	// Optional lists variables that may be available depending on context.
	// Policy authors should use CEL optional syntax (?.field.orValue()) for these.
	Optional []string

	// Description briefly explains when this entrypoint triggers.
	Description string
}

BindingProfile describes the variables available at a specific entrypoint. This enables compile-time documentation and runtime validation of policy contexts.

func GetBindingProfile 

func GetBindingProfile(ep Entrypoint) *BindingProfile

GetBindingProfile returns the binding profile for an entrypoint. Returns nil if the entrypoint is not recognized.

func (BindingProfile) IsRequired 

func (p BindingProfile) IsRequired(name string) bool

IsRequired reports whether the named variable is always available.

func (BindingProfile) Variables 

func (p BindingProfile) Variables() []string

Variables returns all variable names (required + optional) for this profile.

type Bundle 

type Bundle struct {
	SchemaVersion string         `json:"schemaVersion"`      // SchemaVersion is the bundle format version.
	Generated     string         `json:"generated"`          // Generated is the timestamp when the bundle was built.
	Policies      []BundlePolicy `json:"policies"`           // Policies is the list of compiled policies.
	Metadata      map[string]any `json:"metadata,omitempty"` // Metadata contains arbitrary bundle metadata.
}

Bundle is the on-disk representation produced by `deputy policy bundle`.

func BuildBundle 

func BuildBundle(paths []string) (*Bundle, error)

BuildBundle compiles all provided policy sources and returns a bundle structure.

func LoadBundle 

func LoadBundle(path string) (*Bundle, error)

LoadBundle reads a compiled JSON bundle file from disk. For structured YAML policies, use LoadSources instead.

func ParseBundle 

func ParseBundle(data []byte) (*Bundle, bool)

ParseBundle attempts to parse the provided bytes as a policy bundle.

type BundlePolicy 

type BundlePolicy struct {
	Name   string `json:"name"`   // Name is the policy name.
	Source string `json:"source"` // Source is the compiled CEL source code.
}

BundlePolicy contains the CEL program for a single entry in a bundle.

type Engine 

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

Engine holds compiled CEL programs and evaluates them without per-request recompilation.

func NewEngine 

func NewEngine(sources []Source) (*Engine, error)

NewEngine builds a compiled engine from already loaded sources.

func NewEngineFromPaths 

func NewEngineFromPaths(paths []string) (*Engine, error)

NewEngineFromPaths loads sources from disk and builds a compiled engine.

func (*Engine) Evaluate 

func (e *Engine) Evaluate(ctx context.Context, entrypoint string, input proto.Message) ([]Action, error)

Evaluate implements the Evaluator interface. It evaluates all policies against the input proto using the provided entrypoint, with command inferred from the input's env.command field (if present).

func (*Engine) EvaluateAll 

func (e *Engine) EvaluateAll(ctx context.Context, input proto.Message, command, entrypoint string) ([]Action, error)

EvaluateAll runs all compiled policies against the input proto and returns aggregated actions.

The input should be a typed PolicyInput proto message (e.g., *policyv1.ScanVulnerabilityPolicyInput). The proto is converted to a map[string]any for CEL evaluation using protojson serialization, which preserves snake_case field names as defined in the proto schema.

Policy execution order: Policies are evaluated in the order they were loaded (typically the order they appear in source files). Each policy may return zero or more actions. All actions from all matching policies are collected and returned.

Filtering behavior: Policies can declare entrypoint and/or command restrictions via metadata. A policy is skipped if EITHER:

  • The policy declares specific entrypoints AND the request entrypoint doesn't match any
  • The policy declares specific commands AND the request command doesn't match any

This means both filters must pass (AND logic) for a policy to run. Policies without restrictions always run.

Advisory mode: Policies with mode="advisory" have their "deny" actions downgraded to "warn", allowing observation without blocking.

func (*Engine) EvaluateAllMap 

func (e *Engine) EvaluateAllMap(ctx context.Context, payload map[string]any, command, entrypoint string) ([]Action, error)

EvaluateAllMap runs all compiled policies against a raw map[string]any input. This is for CLI testing scenarios where the input is arbitrary JSON rather than a typed proto. For production use, prefer EvaluateAll with typed proto inputs.

type Entrypoint 

type Entrypoint string

Entrypoint represents a canonical policy evaluation entrypoint. Using a distinct type provides compile-time safety and makes entrypoint usage explicit throughout the codebase. 

const (
	// EntrypointGoArtifactRequest triggers when the proxy handles a Go module request.
	EntrypointGoArtifactRequest Entrypoint = "go_artifact_request"
	// EntrypointNpmArtifactRequest triggers when the proxy handles an NPM package request.
	EntrypointNpmArtifactRequest Entrypoint = "npm_artifact_request"
	// EntrypointPypiArtifactRequest triggers when the proxy handles a PyPI package request.
	EntrypointPypiArtifactRequest Entrypoint = "pypi_artifact_request"
	// EntrypointRubygemsArtifactRequest triggers when the proxy handles a RubyGems package request.
	EntrypointRubygemsArtifactRequest Entrypoint = "rubygems_artifact_request"
	// EntrypointOCIArtifactRequest triggers when the proxy handles an OCI image request.
	EntrypointOCIArtifactRequest Entrypoint = "oci_artifact_request"

	// EntrypointScanReport triggers after a scan completes, providing the full report.
	EntrypointScanReport Entrypoint = "scan_report"
	// EntrypointScanVulnerability triggers for each vulnerability found during a scan.
	EntrypointScanVulnerability Entrypoint = "scan_vulnerability"

	// EntrypointDiffReport triggers after a diff completes, providing the full report.
	EntrypointDiffReport Entrypoint = "diff_report"
	// EntrypointDiffDependencyChange triggers for each dependency change found during a diff.
	EntrypointDiffDependencyChange Entrypoint = "diff_dependency_change"
	// EntrypointDiffVulnerability triggers for each vulnerability found during a diff.
	EntrypointDiffVulnerability Entrypoint = "diff_vulnerability"

	// Container image diff entrypoints - for comparing two container images
	// EntrypointContainerDiffReport triggers after a container image diff completes.
	EntrypointContainerDiffReport Entrypoint = "container_diff_report"
	// EntrypointContainerDiffChange triggers for each package change between container images.
	EntrypointContainerDiffChange Entrypoint = "container_diff_change"
	// EntrypointContainerDiffVulnerability triggers for each vulnerability difference.
	EntrypointContainerDiffVulnerability Entrypoint = "container_diff_vulnerability"
	// EntrypointContainerDiffLayer triggers for each layer difference analysis.
	EntrypointContainerDiffLayer Entrypoint = "container_diff_layer"
	// EntrypointContainerDiffConfig triggers for configuration changes between images.
	EntrypointContainerDiffConfig Entrypoint = "container_diff_config"

	// EntrypointSBOMReport triggers after an SBOM is generated.
	EntrypointSBOMReport Entrypoint = "sbom_report"
	// EntrypointSBOMComponent triggers for each component in an SBOM.
	EntrypointSBOMComponent Entrypoint = "sbom_component"

	// EntrypointFixPlan triggers after a remediation plan is generated.
	EntrypointFixPlan Entrypoint = "fix_plan"
	// EntrypointFixPlanStep triggers for each step in a remediation plan.
	EntrypointFixPlanStep Entrypoint = "fix_plan_step"

	// EntrypointTriageReport triggers after a triage report is generated.
	EntrypointTriageReport Entrypoint = "triage_report"
	// EntrypointTriageCluster triggers for each cluster of issues in a triage report.
	EntrypointTriageCluster Entrypoint = "triage_cluster"

	// Dockerfile entrypoints - for analyzing Dockerfiles
	// EntrypointDockerfileReport triggers after a Dockerfile is parsed.
	EntrypointDockerfileReport Entrypoint = "dockerfile_report"
	// EntrypointDockerfileStage triggers for each stage in a multi-stage Dockerfile.
	EntrypointDockerfileStage Entrypoint = "dockerfile_stage"

	// Secrets entrypoints - for secret detection policies
	// EntrypointSecretsReport triggers after a secrets scan completes.
	EntrypointSecretsReport Entrypoint = "secrets_report"
	// EntrypointSecretsFinding triggers for each secret found during a scan.
	EntrypointSecretsFinding Entrypoint = "secrets_finding"

	// Graph entrypoints - for dependency graph analysis and policies
	// EntrypointGraphReport triggers after a graph is built, providing the full graph.
	EntrypointGraphReport Entrypoint = "graph_report"
	// EntrypointGraphNode triggers for each node in the dependency graph.
	// Available variables: node (with purl, name, version, ecosystem, direct, depth, etc.)
	EntrypointGraphNode Entrypoint = "graph_node"
	// EntrypointGraphEdge triggers for each edge in the dependency graph.
	// Available variables: edge (with from, to PURLs), from_node, to_node
	EntrypointGraphEdge Entrypoint = "graph_edge"

	// EntrypointServiceScanRequest triggers before a scan is executed via the API.
	// Use this to authorize which targets a user/service can scan.
	EntrypointServiceScanRequest Entrypoint = "service_scan_request"
	// EntrypointServiceListRequest triggers before a list operation via the API.
	EntrypointServiceListRequest Entrypoint = "service_list_request"
	// EntrypointServiceSBOMRequest triggers before SBOM generation via the API.
	EntrypointServiceSBOMRequest Entrypoint = "service_sbom_request"
	// EntrypointServiceDiffRequest triggers before a diff operation via the API.
	EntrypointServiceDiffRequest Entrypoint = "service_diff_request"
	// EntrypointServiceSecretsRequest triggers before a secrets scan via the API.
	EntrypointServiceSecretsRequest Entrypoint = "service_secrets_request"
	// EntrypointServiceGraphRequest triggers before a graph operation via the API.
	EntrypointServiceGraphRequest Entrypoint = "service_graph_request"

	// EntrypointSandboxExecution triggers before any sandbox execution begins.
	// Use this to authorize sandbox executions based on source, command, and config.
	// Available variables: command, workspace_dir, requested_config, context
	EntrypointSandboxExecution Entrypoint = "sandbox_execution"
	// EntrypointSandboxCommand triggers for each command executed within a sandbox session.
	// Use this for fine-grained command-level control within ongoing sandboxes.
	// Available variables: command, sandbox_config, context
	EntrypointSandboxCommand Entrypoint = "sandbox_command"
	// EntrypointSandboxNetwork triggers when a sandbox requests network access.
	// Use this to implement network allowlists or block specific destinations.
	// Available variables: host, port, protocol, sandbox_config, context
	EntrypointSandboxNetwork Entrypoint = "sandbox_network"
)

Canonical entrypoint constants. Use these typed values instead of raw strings.

func ListEntrypoints 

func ListEntrypoints() []Entrypoint

ListEntrypoints returns all available entrypoints sorted alphabetically.

func (Entrypoint) Category 

func (e Entrypoint) Category() string

Category returns which command category this entrypoint belongs to.

func (Entrypoint) IsValid 

func (e Entrypoint) IsValid() bool

IsValid reports whether this is a known canonical entrypoint.

func (Entrypoint) String 

func (e Entrypoint) String() string

String returns the entrypoint name.

type Evaluator 

type Evaluator interface {
	Evaluate(ctx context.Context, entrypoint string, input proto.Message) ([]Action, error)
}

Evaluator is the interface for evaluating policies against a payload. It abstracts the policy engine for consumers that only need evaluation capability.

type ExampleCategory 

type ExampleCategory struct {
	Name        string
	Description string
	Entrypoints []Entrypoint
}

ExampleCategory groups related entrypoints for discovery.

func GetCategoryForEntrypoint 

func GetCategoryForEntrypoint(ep Entrypoint) *ExampleCategory

GetCategoryForEntrypoint returns the category containing this entrypoint.

type ExampleInput 

type ExampleInput struct {
	Entrypoint  Entrypoint
	Level       ExampleLevel
	Description string
	Input       map[string]any
	JSON        string // Pretty-printed JSON
	Comments    []string
}

ExampleInput contains a generated example for policy testing.

func GenerateExample 

func GenerateExample(ep Entrypoint, level ExampleLevel) (*ExampleInput, error)

GenerateExample creates a canonical example input for the given entrypoint.

type ExampleLevel 

type ExampleLevel string

ExampleLevel describes how much detail to include in generated examples. 

const (
	// ExampleLevelMinimal includes only required fields with simplest values.
	ExampleLevelMinimal ExampleLevel = "minimal"
	// ExampleLevelTypical includes common fields users will encounter.
	ExampleLevelTypical ExampleLevel = "typical"
	// ExampleLevelComprehensive includes all fields with rich examples.
	ExampleLevelComprehensive ExampleLevel = "comprehensive"
)

type HelperFunction 

type HelperFunction struct {
	Name      string // Name is the function name as it appears in CEL.
	Signature string // Signature is the function signature for documentation/hover.
	Doc       string // Doc is the documentation string for the function.
}

HelperFunction describes a CEL helper exposed in the Deputy environment. It is used both by the runtime (for registration) and by tooling (LSP, docs) to keep completions/hovers in sync with the functions actually available.

func HelperCatalog 

func HelperCatalog() []HelperFunction

HelperCatalog returns the CEL helper catalog.

type Source 

type Source struct {
	Name string // Name is the identifier for the policy source.
	Body string // Body is the CEL source code.
}

Source represents an individual CEL policy ready for evaluation.

func LoadSources 

func LoadSources(paths []string) ([]Source, error)

LoadSources reads a list of file paths and returns the flattened list of policy sources.

Supported formats:

  • Structured YAML bundle (policies: [...]) - recommended for authoring
  • JSON bundle with schemaVersion field - for compiled/distributed bundles

The function tries to parse each file in order of preference:

  1. JSON bundle format (compiled bundles from `deputy policy bundle`)
  2. Structured YAML format (human-authored policy files)

If neither format matches, an error is returned with guidance on valid formats.

func ParseStructuredSources 

func ParseStructuredSources(data []byte, virtualPath string) ([]Source, error)

ParseStructuredSources parses a structured YAML bundle (same format accepted by `deputy policy` commands) into a slice of policy sources. The virtualPath is used only for error context and source naming; callers can provide an in-memory pseudo path such as "buffer" or a real file path.

Source Files

View all Source files

Directories

Path Synopsis
Package celconv provides type conversion utilities for CEL (Common Expression Language).
 Package celconv provides type conversion utilities for CEL (Common Expression Language).
Package lsp implements a lightweight, high-performance Language Server Protocol (LSP) server tailored for Deputy policy bundles.
 Package lsp implements a lightweight, high-performance Language Server Protocol (LSP) server tailored for Deputy policy bundles.

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.