safety

Documentation

Overview

Package safety is EXPERIMENTAL — execution safety blocker with structured analysis. It is subordinate to observed state and emits warnings automatically.

The structured evaluator is included in default builds. blocker.go uses it through Check, and guarded execution evaluates commands through the same default rule set. Learned approvals remain disabled.

Package safety is EXPERIMENTAL — structured safety evaluation and execution blocker. It is subordinate to observed state and emits warnings automatically.

• Category-based rules (destructive, network, privilege-escalation, etc.)
• Surface-aware rule matching
• Explicit safety reasoning per decision

Learned approvals are intentionally disabled in this branch because program-name-only overrides are too broad to be treated as operator-safe.

Index

• type BlockResult
  • func Check(snap *models.ClusterSnapshot, desc string, isKnownBad func(string) bool) BlockResult
• type Category
• type Decision
• type Evaluator
  • func NewEvaluator(rs RuleSet) *Evaluator
  • func (e *Evaluator) Evaluate(rawCmd string, surface string) Decision
  • func (e *Evaluator) LearnAllow(_ string)
  • func (e *Evaluator) LearnDeny(_ string)
• type Rule
• type RuleSet
  • func DefaultRuleSet() RuleSet
• type Verdict

Types

type BlockResult

type BlockResult struct {
	Blocked bool   `json:"blocked"`
	Reason  string `json:"reason"`
	Score   int    `json:"dumb_score"` // 0-100
}

BlockResult is final verdict. Score >= 80 = instant block.

func Check

func Check(snap *models.ClusterSnapshot, desc string, isKnownBad func(string) bool) BlockResult

Check is the single gatekeeper. Call this first, always.

type Category

type Category string

Category classifies the risk level of a command.

const (
	CategorySafe              Category = "safe"
	CategoryReadOnly          Category = "read-only"
	CategoryModify            Category = "modify"
	CategoryDestructive       Category = "destructive"
	CategoryNetworkMutating   Category = "network-mutating"
	CategoryPrivilegeEscalate Category = "privilege-escalate"
	CategorySystemCritical    Category = "system-critical"
	CategoryUnknown           Category = "unknown"
)

type Decision

type Decision struct {
	Verdict     Verdict   `json:"verdict"`
	Category    Category  `json:"category"`
	Program     string    `json:"program"`
	Args        []string  `json:"args"`
	RawCmd      string    `json:"raw_cmd"`
	Reasons     []string  `json:"reasons"`
	MatchedRule string    `json:"matched_rule,omitempty"`
	EvalAt      time.Time `json:"evaluated_at"`
}

Decision captures the full reasoning for a safety evaluation.

type Evaluator

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

Evaluator applies static rules to commands. Program-wide learned overrides are intentionally disabled until they can be scoped more narrowly than a binary name alone.

func NewEvaluator

func NewEvaluator(rs RuleSet) *Evaluator

NewEvaluator creates a safety evaluator from a rule set.

func (*Evaluator) Evaluate

func (e *Evaluator) Evaluate(rawCmd string, surface string) Decision

Evaluate assesses a command string and returns a safety decision.

func (*Evaluator) LearnAllow

func (e *Evaluator) LearnAllow(_ string)

LearnAllow is intentionally disabled until approvals can be scoped more narrowly than a program name alone.

func (*Evaluator) LearnDeny

func (e *Evaluator) LearnDeny(_ string)

LearnDeny is intentionally disabled until approvals can be scoped more narrowly than a program name alone.

type Rule

type Rule struct {
	Name        string   `yaml:"name" json:"name"`
	Description string   `yaml:"description" json:"description"`
	Programs    []string `yaml:"programs" json:"programs,omitempty"`         // glob patterns for program name
	ArgPatterns []string `yaml:"arg_patterns" json:"arg_patterns,omitempty"` // glob patterns matched against joined args
	RawPatterns []string `yaml:"raw_patterns" json:"raw_patterns,omitempty"` // substring match against raw command
	Category    Category `yaml:"category" json:"category"`
	Verdict     Verdict  `yaml:"verdict" json:"verdict"`
	Priority    int      `yaml:"priority" json:"priority"`           // higher = evaluated first
	Surfaces    []string `yaml:"surfaces" json:"surfaces,omitempty"` // restrict to surfaces (empty = all)
}

Rule defines a single safety rule.

type RuleSet

type RuleSet struct {
	Rules   []Rule `yaml:"rules" json:"rules"`
	Version string `yaml:"version" json:"version"`
}

RuleSet is an ordered collection of safety rules.

func DefaultRuleSet

func DefaultRuleSet() RuleSet

DefaultRuleSet returns the built-in safety rules.

type Verdict

type Verdict string

Verdict is the outcome of a safety evaluation.

const (
	VerdictAllow  Verdict = "allow"
	VerdictDeny   Verdict = "deny"
	VerdictPrompt Verdict = "prompt" // ask the operator
)