policy

package
v0.7.2 Latest Latest
Warning

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

 Go to latest Published: Apr 8, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package policy implements a unified trust rules engine for agent tool access control. It supports both Claude Code (settings.json) and ratchet (config.yaml) rule formats, mode presets, scoped rules, and integrates with the existing ToolPolicyEngine.

Index

Examples

Constants

This section is empty.

Variables

View Source 
var ModePresets = map[string][]TrustRule{
	"conservative": {
		{Pattern: "file_read", Action: Allow},
		{Pattern: "blackboard_*", Action: Allow},
		{Pattern: "send_message", Action: Allow},
		{Pattern: "bash:git *", Action: Allow},
		{Pattern: "bash:go *", Action: Allow},
		{Pattern: "file_write", Action: Ask},
		{Pattern: "bash:*", Action: Ask},
		{Pattern: "path:~/.ssh/*", Action: Deny},
		{Pattern: "path:~/.aws/*", Action: Deny},
	},
	"permissive": {
		{Pattern: "*", Action: Allow},
		{Pattern: "bash:rm -rf /*", Action: Deny},
		{Pattern: "bash:sudo *", Action: Deny},
		{Pattern: "path:~/.ssh/*", Action: Deny},
	},
	"locked": {
		{Pattern: "file_read", Action: Allow},
		{Pattern: "blackboard_*", Action: Allow},
		{Pattern: "*", Action: Ask},
	},
	"sandbox": {
		{Pattern: "*", Action: Allow},
	},
}

ModePresets defines the built-in trust modes.

Functions

This section is empty.

Types

type Action 

type Action string

Action defines the trust decision for a tool/path/command. 

const (
	Allow Action = "allow"
	Deny  Action = "deny"
	Ask   Action = "ask"
)

type GlobMatcher 

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

GlobMatcher evaluates file paths against allow/deny glob patterns. Deny patterns are checked first (deny wins). Unmatched paths return Ask. Supports standard glob wildcards (*) and doublestar (**) for recursive matching. Patterns starting with ~/ are expanded to the user's home directory.

Example 
gm := NewGlobMatcher(
	[]string{"/workspace/**", "/tmp/*"},
	[]string{"**/.git/**", "**/*.secret"},
)
fmt.Println(gm.Check("/workspace/main.go"))   // Allow
fmt.Println(gm.Check("/workspace/.git/HEAD")) // Deny
fmt.Println(gm.Check("/etc/passwd"))          // Ask

Output:
allow
deny
ask

func NewGlobMatcher 

func NewGlobMatcher(allow, deny []string) *GlobMatcher

NewGlobMatcher creates a GlobMatcher from allow and deny glob lists. Tilde (~) in patterns is expanded to the user's home directory at construction time.

func (*GlobMatcher) Check 

func (gm *GlobMatcher) Check(path string) Action

Check returns Allow, Deny, or Ask for the given path. Deny patterns are evaluated first so deny wins over allow. An unmatched path returns Ask (not Deny), allowing the caller to prompt the user.

type PermissionGrant 

type PermissionGrant struct {
	ID        int64
	Pattern   string
	Action    Action
	Scope     string
	GrantedBy string
	CreatedAt time.Time
}

PermissionGrant is a persisted trust decision.

type PermissionStore 

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

PermissionStore persists "always allow/deny" trust decisions in SQLite.

func NewPermissionStore 

func NewPermissionStore(db *sql.DB) (*PermissionStore, error)

NewPermissionStore creates a PermissionStore and initializes the table.

func (*PermissionStore) Check 

func (ps *PermissionStore) Check(toolName, scope string) (Action, bool)

Check returns the persisted action for a toolName+scope using glob matching. Stored patterns (e.g. "blackboard_*") are matched against the incoming toolName using the same logic as TrustEngine rule evaluation. Deny wins across all matches. Scope-specific grants are checked alongside global grants.

func (*PermissionStore) Grant 

func (ps *PermissionStore) Grant(pattern string, action Action, scope, grantedBy string) error

Grant persists an allow/deny decision. Upserts by pattern+scope atomically.

func (*PermissionStore) List 

func (ps *PermissionStore) List() ([]PermissionGrant, error)

List returns all persisted grants.

func (*PermissionStore) Revoke 

func (ps *PermissionStore) Revoke(pattern, scope string) error

Revoke removes a persisted grant.

type PolicyEngine 

type PolicyEngine interface {
	IsAllowed(ctx context.Context, toolName, agentID, teamID string) (bool, string)
}

PolicyEngine is an optional backing store for SQL-based policies. Matches the existing orchestrator.ToolPolicyEngine.IsAllowed signature.

type RatchetPromptPattern 

type RatchetPromptPattern struct {
	Name   string `yaml:"name" json:"name"`
	Match  string `yaml:"match" json:"match"`
	Action string `yaml:"action" json:"action"`
}

RatchetPromptPattern is a user-defined screen prompt auto-response pattern.

type RatchetTrustConfig 

type RatchetTrustConfig struct {
	Mode         string                 `yaml:"mode" json:"mode"`
	Rules        []RatchetTrustRule     `yaml:"rules" json:"rules"`
	ProviderArgs map[string][]string    `yaml:"provider_args" json:"provider_args"`
	Prompts      []RatchetPromptPattern `yaml:"prompts" json:"prompts"`
}

RatchetTrustConfig is the trust section from ~/.ratchet/config.yaml.

type RatchetTrustRule 

type RatchetTrustRule struct {
	Pattern string `yaml:"pattern" json:"pattern"`
	Action  string `yaml:"action" json:"action"`
}

RatchetTrustRule is a single rule in ratchet format.

type TrustEngine 

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

TrustEngine evaluates trust rules for tool calls, paths, and commands.

func NewTrustEngine 

func NewTrustEngine(mode string, rules []TrustRule, policyDB PolicyEngine) *TrustEngine

NewTrustEngine creates a TrustEngine with the given mode and explicit rules. If mode is a known preset, the preset rules are loaded into presetRules. policyDB is optional (may be nil).

func (*TrustEngine) AddRule 

func (te *TrustEngine) AddRule(rule TrustRule)

AddRule appends an explicit rule dynamically. These are preserved across SetMode calls.

func (*TrustEngine) Evaluate 

func (te *TrustEngine) Evaluate(ctx context.Context, toolName string, args map[string]any) Action

Evaluate checks whether a tool call is allowed. Scope defaults to "global".

func (*TrustEngine) EvaluateCommand 

func (te *TrustEngine) EvaluateCommand(cmd string) Action

EvaluateCommand checks whether a bash command is allowed. Matches rules with "bash:" prefix patterns.

func (*TrustEngine) EvaluatePath 

func (te *TrustEngine) EvaluatePath(path string) Action

EvaluatePath checks whether a file path is accessible. Matches rules with "path:" prefix patterns.

func (*TrustEngine) EvaluateScoped 

func (te *TrustEngine) EvaluateScoped(ctx context.Context, toolName string, args map[string]any, scope string) Action

EvaluateScoped checks whether a tool call is allowed in the given scope. Resolution order: deny-wins across all matching rules.

  1. Per-scope rules matching the tool name
  2. Global rules matching the tool name
  3. PermissionStore persistent grants
  4. ToolPolicyEngine (SQL)
  5. Default: Deny

func (*TrustEngine) GrantPersistent 

func (te *TrustEngine) GrantPersistent(pattern string, action Action, scope, grantedBy string) error

GrantPersistent stores an "always allow/deny" decision for future sessions.

func (*TrustEngine) Mode 

func (te *TrustEngine) Mode() string

Mode returns the current operating mode.

func (*TrustEngine) Rules 

func (te *TrustEngine) Rules() []TrustRule

Rules returns a copy of all active rules (preset + explicit).

func (*TrustEngine) SetMode 

func (te *TrustEngine) SetMode(mode string) []TrustRule

SetMode switches the active mode preset. Returns the new preset rules that were loaded. Explicit rules added via AddRule or the constructor are preserved. If mode is unknown, returns nil and mode is unchanged.

func (*TrustEngine) SetPermissionStore 

func (te *TrustEngine) SetPermissionStore(ps *PermissionStore)

SetPermissionStore attaches a persistent permission store for "always" grants.

type TrustRule 

type TrustRule struct {
	Pattern string // "file_read", "bash:git *", "path:~/.ssh/*", "Bash(rm:*)"
	Action  Action
	Scope   string // "global", "provider:claude_code", "agent:coder"
}

TrustRule is a single trust policy entry.

func ParseClaudeCodeSettings 

func ParseClaudeCodeSettings(data []byte) ([]TrustRule, error)

ParseClaudeCodeSettings parses a .claude/settings.json file into TrustRules. allowedTools → Allow, disallowedTools → Deny. Bash(cmd:*) is normalized to bash:cmd *.

func ParseRatchetTrustConfig 

func ParseRatchetTrustConfig(cfg RatchetTrustConfig) []TrustRule

ParseRatchetTrustConfig converts ratchet YAML trust config into TrustRules.

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.