rules

package
v0.54.2 Latest Latest
Warning

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

Go to latest
Published: Nov 2, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package rules contains the approval-rule model and matcher.

Rule decisions are deterministic; path matching only examines the target's filesystem metadata and never reads configuration.

Index

Constants

View Source
const (
	// Shell names mirror the executable categories selected by native.resolveShell.
	// They are untyped so callers can pass native.ShellName results directly.
	ShellSh         = "sh"
	ShellBash       = "bash"
	ShellPowerShell = "powershell"
	ShellCmd        = "cmd"
)
View Source
const (
	Allow Action = "allow"
	Ask   Action = "ask"
	Deny  Action = "deny"

	// The prefixed names make call sites that already use an Action namespace
	// explicit while the short names keep rule construction readable.
	ActionAllow = Allow
	ActionAsk   = Ask
	ActionDeny  = Deny
)

Variables

This section is empty.

Functions

func IsProtectedPath

func IsProtectedPath(target Target, workspace, sugaHome string, ruleFiles ...string) bool

IsProtectedPath reports whether a file target is inside an internal control path. This is intentionally owned by the rules package so every entry point applies the same protection list instead of maintaining local copies.

Types

type Action

type Action string

Action is the result of an approval decision.

func ClampAllow

func ClampAllow(action Action, target Target, workspace, sugaHome string, ruleFiles ...string) Action

ClampAllow prevents an approval rule from granting access to suga's own control-plane files. The entry point still decides whether a protected path is askable: chat and ACP can ask, while non-interactive run/sub-agents deny.

type Mode

type Mode string

Mode limits a rule to one entry point. An empty Modes list means all modes.

const (
	ModeChat Mode = "chat"
	ModeRun  Mode = "run"
	ModeACP  Mode = "acp"
)

type Policy

type Policy struct {
	Rules   []Rule
	Default Action
}

Policy is an ordered set of rules and the action used when none matches. Rules are evaluated together: deny is stronger than ask, which is stronger than allow. Order is used only to choose a representative among equal strength matches, so adding a later deny cannot be hidden by an earlier allow.

func (Policy) Decide

func (p Policy) Decide(target Target) (Action, *Rule)

Decide returns the strongest matching action and its representative rule. When no rule matches, the policy default is returned and the rule is nil. An unset default is deliberately fail-closed as deny.

func (Policy) Validate

func (p Policy) Validate() error

Validate checks every rule and the policy default action.

type Rule

type Rule struct {
	Source  Source
	Index   int
	Tool    string
	Command []string
	Path    []string
	Root    string
	Modes   []Mode
	Action  Action
}

Rule is one declarative approval rule. Command and Path are slices because the configuration format permits either one pattern or a list; the loader normalizes both forms before constructing a Rule.

func (Rule) MatchesCommand

func (r Rule) MatchesCommand(target Target) bool

MatchesCommand reports whether one of the rule's command patterns applies to target. Command rules are restricted to the native shell_exec identity. An allow additionally requires the command to pass the selected shell's conservative ASCII whitelist; ask and deny can still match an unsafe command so a rule can deliberately make it more restrictive.

func (Rule) MatchesPath

func (r Rule) MatchesPath(target Target) bool

MatchesPath applies a file rule to a resolved tool target. Allow rules are deliberately stricter than deny rules: the lexical path and the path after resolving its existing ancestors must both match, and the target must not be a link, hard link, or special file. A deny rule is conservative in the other direction and matches either spelling, including a failed resolution.

func (Rule) MatchesTool

func (r Rule) MatchesTool(target Target) bool

MatchesTool reports whether the rule's tool glob applies to target. It is exported separately because later specialized matchers need to retain this identity check before inspecting commands or paths.

func (Rule) Summary

func (r Rule) Summary() string

Summary returns the stable human-readable form used by approval reports.

func (Rule) Validate

func (r Rule) Validate() error

Validate checks the schema-level invariants that are independent of a host's configuration or filesystem. Detailed command and path semantics belong to the command/path matcher tasks, but malformed rule shapes fail here so the wiring layer can return an actionable startup error.

type Source

type Source string

Source identifies where a rule came from. The values are kept as strings so they can be written directly to reports and trace attributes.

const (
	SourceUser    Source = "user"
	SourceProject Source = "project"
	SourceSession Source = "session"
	SourceLegacy  Source = "legacy"
)

type Target

type Target struct {
	Tool      string
	MCP       bool
	MCPServer string
	Mode      Mode
	// Shell is the resolved shell name used by shell_exec (for example sh,
	// bash, pwsh, powershell, or cmd). An unknown name is fail-closed for
	// command allows. Windows controls case and .exe normalization explicitly
	// because the rules package is also used by non-Windows hosts.
	Shell   string
	Windows bool
	Command string
	Path    string
	Root    string
	// Protected roots are supplied by wiring; keeping them on the target lets
	// Policy.Decide apply the same allow clamp for every entry point.
	Workspace string
	SugaHome  string
	RuleFiles []string
}

Target is the identity and optional call data used by Policy.Decide.

MCP targets must set MCP and use the server/tool form in Tool. MCPServer is accepted as a convenience for callers that keep the server and tool name separately; Tool is still the canonical identity used by glob matching. Command and Path are intentionally part of the value now so command and filesystem matchers can be added without changing the Policy API.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL