bash

Documentation

Index

• func Register(registry *tool.Registry, opts ...Option) error
• type BashTool
  • func New(opts ...Option) *BashTool
  • func (bt *BashTool) Handler() tool.ToolHandler
  • func (bt *BashTool) ToolDef() schema.ToolDef
• type Classification
• type Classifier
  • func NewClassifier(rules []Rule) *Classifier
  • func (c *Classifier) Classify(command string) Classification
• type Option
  • func WithMaxOutput(n int) Option
  • func WithPathGuardian(g *PathGuardian) Option
  • func WithTimeout(d time.Duration) Option
  • func WithWorkingDir(dir string) Option
• type PathGuardian
  • func NewPathGuardian(allowedDirs []string, workingDir string) *PathGuardian
  • func (g *PathGuardian) Classify(command string) Classification
• type Rule
  • func DefaultRules() []Rule
• type Tier
  • func (t Tier) String() string

Functions

func Register

func Register(registry *tool.Registry, opts ...Option) error

Register creates a BashTool and registers it in the given registry. Returns an error if a tool named "bash" is already registered.

Types

type BashTool

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

BashTool holds configuration for the built-in bash command executor.

func New

func New(opts ...Option) *BashTool

New creates a BashTool with the given options. Defaults: timeout=30s, maxOutputBytes=256KB.

func (*BashTool) Handler

func (bt *BashTool) Handler() tool.ToolHandler

Handler returns the ToolHandler closure for this bash tool.

func (*BashTool) ToolDef

func (bt *BashTool) ToolDef() schema.ToolDef

ToolDef returns the schema.ToolDef for registration.

type Classification

type Classification struct {
	Tier       Tier
	Rule       string // matched rule name; empty when Tier == TierCaution and nothing matched
	Reason     string
	SubCommand string // the sub-command that determined the tier
}

Classification is the outcome for a single command.

type Classifier

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

Classifier matches a command string against a rule library and returns the highest-tier match across all sub-commands.

func NewClassifier

func NewClassifier(rules []Rule) *Classifier

NewClassifier returns a Classifier over the given rules. Rules are evaluated in order; on ties the first matching rule of the highest tier wins.

func (*Classifier) Classify

func (c *Classifier) Classify(command string) Classification

Classify returns the worst-case classification across the command's sub-commands (split on `;`, `&&`, `||`, and extracted from `$(...)` / backticks).

type Option

type Option func(*BashTool)

Option is a functional option for configuring a BashTool.

func WithMaxOutput

func WithMaxOutput(n int) Option

WithMaxOutput sets the maximum output size in bytes.

func WithPathGuardian

func WithPathGuardian(g *PathGuardian) Option

WithPathGuardian installs a path guardian that hard-blocks commands classified as TierBlocked before execution.

func WithTimeout

func WithTimeout(d time.Duration) Option

WithTimeout sets the command execution timeout.

func WithWorkingDir

func WithWorkingDir(dir string) Option

WithWorkingDir sets the working directory for command execution.

type PathGuardian

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

PathGuardian inspects a shell command for path-based escapes relative to a set of allowed directories. It classifies each sub-command (reusing the classifier's splitter) and returns the worst-case Classification.

PathGuardian is additive to Classifier: callers typically take the higher Tier of both.

func NewPathGuardian

func NewPathGuardian(allowedDirs []string, workingDir string) *PathGuardian

NewPathGuardian returns a guardian bound to canonical allowed directories and the bash tool's working directory (used for resolving relative path arguments). Passing an empty allowedDirs disables the guardian.

func (*PathGuardian) Classify

func (g *PathGuardian) Classify(command string) Classification

Classify returns the worst-case Classification across a command's sub-commands.

type Rule

type Rule struct {
	Name    string
	Tier    Tier
	Pattern *regexp.Regexp
	Reason  string
}

Rule is one entry in the classifier's rule library.

func DefaultRules

func DefaultRules() []Rule

DefaultRules returns the hard-coded baseline rule library. Callers typically combine these with user-configured extensions.

The list is intentionally short and conservative: only well-known, high-confidence patterns are blocked or marked dangerous, and the safe list covers the most common read-only operations in this project's workflow.

type Tier

type Tier int

Tier classifies how a bash command should be gated.

const (
	// TierSafe: no confirmation required.
	TierSafe Tier = iota
	// TierCaution: default tier for unmatched commands; prompt with standard three-state dialog.
	TierCaution
	// TierDangerous: prompt per-invocation; the caller should not offer an "allow always" option.
	TierDangerous
	// TierBlocked: hard reject; never execute regardless of permission mode.
	TierBlocked
)

func (Tier) String

func (t Tier) String() string

String returns a stable lowercase identifier for the tier.