engine

Documentation

Overview

Package engine evaluates gatekeeper rules against canonical tool calls.

The engine is harness-agnostic: it consumes a canonical.ToolCall and returns a canonical.Verdict. All harness-specific wire parsing/encoding lives in the adapters (internal/adapter/*); the PCRE2 rule matching, deny-wins policy, preconditions, and Bash cd-prefix/heredoc handling live here.

Index

• Constants
• func ExtractCDPrefix(command string) string
• func StripHeredocs(command string) string
• type CompiledRule
• type Engine
  • func New(cfg *config.Config, debug bool) (*Engine, error)
  • func (e *Engine) Evaluate(tc *canonical.ToolCall) (canonical.Verdict, error)
  • func (e *Engine) SetExecCommand(fn func(ctx context.Context, cwd, command, toolInput string) (string, error))

Constants

const EnvGatekeeperInput = "GATEKEEPER_INPUT"

EnvGatekeeperInput is the environment variable set for every precondition shell. Value is the (heredoc-stripped) tool input string under evaluation.

Functions

func ExtractCDPrefix

func ExtractCDPrefix(command string) string

ExtractCDPrefix returns any leading "cd <path> &&" from a Bash command, including the "&&". Returns "" if no cd prefix is found. This allows preconditions to run in the same directory the command targets.

func StripHeredocs

func StripHeredocs(command string) string

StripHeredocs removes heredoc bodies from a Bash command string. This prevents deny rules from matching against data content such as commit messages or PR descriptions that happen to contain denied patterns. However, heredocs fed as stdin to shell interpreters (bash, sh, python, etc.) are preserved because they contain executable code that deny rules must check.

Types

type CompiledRule

type CompiledRule struct {
	ToolRegex         *regexp2.Regexp
	InputRegex        *regexp2.Regexp
	PreconditionCmd   string
	PreconditionRegex *regexp2.Regexp
	Decision          canonical.Decision
	Reason            string
}

CompiledRule is a rule with pre-compiled regex patterns.

type Engine

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

Engine evaluates rules and returns permission decisions.

func New

func New(cfg *config.Config, debug bool) (*Engine, error)

New compiles all rules and returns an Engine.

func (*Engine) Evaluate

func (e *Engine) Evaluate(tc *canonical.ToolCall) (canonical.Verdict, error)

Evaluate checks all rules against a canonical tool call and returns a verdict. Returns a Verdict with Decision == canonical.Abstain when no rule matches.

func (*Engine) SetExecCommand

func (e *Engine) SetExecCommand(fn func(ctx context.Context, cwd, command, toolInput string) (string, error))

SetExecCommand overrides the shell executor (used in tests).