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 safety evaluator in structured.go is compile-gated behind the "safety_scaffolded" build tag. It is not included in default builds. The stable operator path uses blocker.go (Check) instead.

Index

• type BlockResult
  • func Check(k *knowledge.ClusterKnowledge, desc string, isKnownBad func(string) bool) BlockResult
• type Category
• type Decision
• type Evaluator
  • func NewEvaluator(_ RuleSet) *Evaluator
  • func (e *Evaluator) Evaluate(rawCmd string, _ 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(k *knowledge.ClusterKnowledge, 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{}

Evaluator is a no-op stub when safety_scaffolded is not set.

func NewEvaluator

func NewEvaluator(_ RuleSet) *Evaluator

NewEvaluator creates a no-op safety evaluator stub.

func (*Evaluator) Evaluate

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

Evaluate returns a permissive decision (always allow).

func (*Evaluator) LearnAllow

func (e *Evaluator) LearnAllow(_ string)

LearnAllow is a no-op stub.

func (*Evaluator) LearnDeny

func (e *Evaluator) LearnDeny(_ string)

LearnDeny is a no-op stub.

type Rule

type Rule struct {
	Name        string   `yaml:"name" json:"name"`
	Description string   `yaml:"description" json:"description"`
	Programs    []string `yaml:"programs" json:"programs"`
	ArgPatterns []string `yaml:"arg_patterns" json:"arg_patterns"`
	Category    Category `yaml:"category" json:"category"`
	Verdict     Verdict  `yaml:"verdict" json:"verdict"`
	Priority    int      `yaml:"priority" json:"priority"`
	Surfaces    []string `yaml:"surfaces" json:"surfaces,omitempty"`
}

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 an empty rule set stub.

type Verdict

type Verdict string

Verdict is the outcome of a safety evaluation.

const (
	VerdictAllow  Verdict = "allow"
	VerdictDeny   Verdict = "deny"
	VerdictPrompt Verdict = "prompt"
)