exectool

Documentation

Index

• type ExecTool
  • func NewExecTool(opts ...ExecToolOption) (*ExecTool, error)
  • func (et *ExecTool) AllowedRoots() []string
  • func (et *ExecTool) RunScript(ctx context.Context, args RunScriptArgs) (*RunScriptOut, error)
  • func (et *ExecTool) RunScriptTool() spec.Tool
  • func (et *ExecTool) SetAllowedRoots(roots []string) error
  • func (et *ExecTool) SetWorkBaseDir(base string) error
  • func (et *ExecTool) ShellCommand(ctx context.Context, args ShellCommandArgs) (*ShellCommandOut, error)
  • func (et *ExecTool) ShellCommandTool() spec.Tool
  • func (et *ExecTool) Tools() []spec.Tool
  • func (et *ExecTool) WorkBaseDir() string
• type ExecToolOption
  • func WithAllowedRoots(roots []string) ExecToolOption
  • func WithBlockedCommands(cmds []string) ExecToolOption
  • func WithExecutionPolicy(p ExecutionPolicy) ExecToolOption
  • func WithMaxSessions(maxSessions int) ExecToolOption
  • func WithRunScriptPolicy(p RunScriptPolicy) ExecToolOption
  • func WithSessionTTL(ttl time.Duration) ExecToolOption
  • func WithWorkBaseDir(base string) ExecToolOption
• type ExecutionPolicy
  • func DefaultExecutionPolicy() ExecutionPolicy
• type RunScriptArgs
• type RunScriptInterpreter
• type RunScriptMode
• type RunScriptOut
• type RunScriptPolicy
  • func DefaultRunScriptPolicy() RunScriptPolicy
  • func NormalizeRunScriptPolicy(in RunScriptPolicy) (RunScriptPolicy, error)
• type ShellCommandArgs
• type ShellCommandExecResult
• type ShellCommandOut
• type ShellName

Types

type ExecTool

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

ExecTool is an instance-owned execution tool runner (modeled after fstool.FSTool). It centralizes:

• workBaseDir: base for resolving relative paths
• allowedRoots: optional sandbox roots; if empty, allow all
• execution policy (timeouts/output/limits)
• session store for shellcommand
• runscript policy (optional tool)

func NewExecTool

func NewExecTool(opts ...ExecToolOption) (*ExecTool, error)

func (*ExecTool) AllowedRoots

func (et *ExecTool) AllowedRoots() []string

func (*ExecTool) RunScript

func (et *ExecTool) RunScript(ctx context.Context, args RunScriptArgs) (*RunScriptOut, error)

func (*ExecTool) RunScriptTool

func (et *ExecTool) RunScriptTool() spec.Tool

func (*ExecTool) SetAllowedRoots

func (et *ExecTool) SetAllowedRoots(roots []string) error

SetAllowedRoots updates allowed roots at runtime (best-effort). If the current workBaseDir is not within the new roots, this returns an error and leaves state unchanged.

func (*ExecTool) SetWorkBaseDir

func (et *ExecTool) SetWorkBaseDir(base string) error

SetWorkBaseDir updates the work base directory at runtime (best-effort).

func (*ExecTool) ShellCommand

func (et *ExecTool) ShellCommand(ctx context.Context, args ShellCommandArgs) (*ShellCommandOut, error)

func (*ExecTool) ShellCommandTool

func (et *ExecTool) ShellCommandTool() spec.Tool

func (*ExecTool) Tools

func (et *ExecTool) Tools() []spec.Tool

func (*ExecTool) WorkBaseDir

func (et *ExecTool) WorkBaseDir() string

type ExecToolOption

type ExecToolOption func(*ExecTool) error

func WithAllowedRoots

func WithAllowedRoots(roots []string) ExecToolOption

func WithBlockedCommands

func WithBlockedCommands(cmds []string) ExecToolOption

WithBlockedCommands adds additional commands to the instance blocklist. Entries must be single command names (not full command lines).

func WithExecutionPolicy

func WithExecutionPolicy(p ExecutionPolicy) ExecToolOption

func WithMaxSessions

func WithMaxSessions(maxSessions int) ExecToolOption

func WithRunScriptPolicy

func WithRunScriptPolicy(p RunScriptPolicy) ExecToolOption

func WithSessionTTL

func WithSessionTTL(ttl time.Duration) ExecToolOption

func WithWorkBaseDir

func WithWorkBaseDir(base string) ExecToolOption

type ExecutionPolicy

type ExecutionPolicy struct {
	// If true, skip heuristic checks (fork-bomb/backgrounding).
	// NOTE: hard-blocked commands are ALWAYS blocked.
	AllowDangerous bool

	Timeout          time.Duration
	MaxOutputBytes   int64
	MaxCommands      int
	MaxCommandLength int
}

ExecutionPolicy provides policy / hardening knobs (host-configured). All limits are clamped to executil hard maximums.

func DefaultExecutionPolicy

func DefaultExecutionPolicy() ExecutionPolicy

type RunScriptArgs

type RunScriptArgs struct {
	Path    string            `json:"path"`
	Args    []string          `json:"args,omitempty"`
	Env     map[string]string `json:"env,omitempty"`
	Workdir string            `json:"workdir,omitempty"`
}

type RunScriptInterpreter

type RunScriptInterpreter struct {
	// Shell selects the wrapper shell used to run the *constructed command string*.
	// This affects quoting dialect and which binary is used for "shell -c" / "-Command".
	Shell ShellName

	Mode RunScriptMode

	// Command is required for ModeInterpreter.
	// Examples: "python3", "python", "node", "ruby".
	Command string
	Args    []string
}

type RunScriptMode

type RunScriptMode string

const (
	// RunScriptModeDirect executes the script path directly (as the "command").
	// This is appropriate for PowerShell scripts executed via "& 'script.ps1' ...".
	RunScriptModeDirect RunScriptMode = "direct"

	// RunScriptModeShell executes the script by invoking the selected wrapper shell as an interpreter:
	//   <shellPath> <script> <args...>
	// This avoids requiring execute bits on Unix shell scripts.
	RunScriptModeShell RunScriptMode = "shell"

	// RunScriptModeInterpreter executes the script via an explicit interpreter command:
	//   <command> <commandArgs...> <script> <args...>
	RunScriptModeInterpreter RunScriptMode = "interpreter"
)

type RunScriptOut

type RunScriptOut struct {
	Path       string `json:"path"`
	ExitCode   int    `json:"exit_code"`
	Stdout     string `json:"stdout,omitempty"`
	Stderr     string `json:"stderr,omitempty"`
	TimedOut   bool   `json:"timed_out,omitempty"`
	DurationMS int64  `json:"duration_ms,omitempty"`

	StdoutTruncated bool `json:"stdout_truncated,omitempty"`
	StderrTruncated bool `json:"stderr_truncated,omitempty"`
}

type RunScriptPolicy

type RunScriptPolicy struct {
	// AllowedExtensions is an optional lowercase allowlist (e.g. [".sh", ".ps1", ".py"]).
	// If empty/nil, extension is allowed iff InterpreterByExtension has a match (or a "" fallback is configured).
	AllowedExtensions []string

	// InterpreterByExtension controls how scripts are executed based on extension.
	// Keys should be lowercase and include the leading dot (".sh", ".ps1", ".py").
	//
	// If no mapping exists for the script extension:
	//   - if a mapping for "" exists, it is used as a fallback
	//   - otherwise runscript fails with "no interpreter mapping for extension"
	InterpreterByExtension map[string]RunScriptInterpreter

	// ExecutionPolicy overrides the ExecTool-wide defaults for runscript.
	// If left zero-valued, ExecTool.execPolicy is used.
	ExecutionPolicy ExecutionPolicy

	// Arg limits (defense-in-depth).
	MaxArgs     int
	MaxArgBytes int
}

func DefaultRunScriptPolicy

func DefaultRunScriptPolicy() RunScriptPolicy

func NormalizeRunScriptPolicy

func NormalizeRunScriptPolicy(in RunScriptPolicy) (RunScriptPolicy, error)

NormalizeRunScriptPolicy deep-clones and normalizes a RunScriptPolicy. This is defensive: it prevents shared map/slice backing storage and makes policy behavior deterministic (lowercased extensions, leading dots, etc).

type ShellCommandArgs

type ShellCommandArgs struct {
	Commands        []string          `json:"commands,omitempty"`
	Workdir         string            `json:"workdir,omitempty"`
	Env             map[string]string `json:"env,omitempty"`
	Shell           ShellName         `json:"shell,omitempty"`
	ExecuteParallel bool              `json:"executeParallel,omitempty"`
	SessionID       string            `json:"sessionID,omitempty"`
}

type ShellCommandExecResult

type ShellCommandExecResult = executil.ShellCommandExecResult

type ShellCommandOut

type ShellCommandOut struct {
	SessionID string                   `json:"sessionID,omitempty"`
	Workdir   string                   `json:"workdir,omitempty"`
	Results   []ShellCommandExecResult `json:"results,omitempty"`
}

type ShellName

type ShellName = executil.ShellName

const (
	ShellNameAuto       ShellName = executil.ShellNameAuto
	ShellNameBash       ShellName = executil.ShellNameBash
	ShellNameZsh        ShellName = executil.ShellNameZsh
	ShellNameSh         ShellName = executil.ShellNameSh
	ShellNameDash       ShellName = executil.ShellNameDash
	ShellNameKsh        ShellName = executil.ShellNameKsh
	ShellNameFish       ShellName = executil.ShellNameFish
	ShellNamePwsh       ShellName = executil.ShellNamePwsh
	ShellNamePowershell ShellName = executil.ShellNamePowershell
	ShellNameCmd        ShellName = executil.ShellNameCmd
)