Documentation
¶
Overview ¶
Package commandtool provides a secure, streaming command execution tool.
Security Features:
- AllowedCommands: Whitelist of permitted base commands
- DeniedCommands: Blacklist of dangerous commands (applied first)
- DeniedPatterns: Regex patterns for dangerous patterns (rm -rf, etc.)
- WorkingDirectory: Restricted execution directory
- MaxExecutionTime: Timeout to prevent runaway processes
- RequireApproval: HITL approval before execution
Streaming:
- Uses iter.Seq2 pattern matching LLM.GenerateContent
- Real-time stdout/stderr streaming for UI feedback
Example usage:
tool := commandtool.New(commandtool.Config{
AllowedCommands: []string{"docker", "npm", "go", "ls", "cat"},
DeniedCommands: []string{"rm", "sudo", "chmod"},
WorkingDir: "/project",
RequireApproval: true, // HITL approval required
})
Package commandtool provides a secure, streaming command execution tool.
Sandbox Enforcement:
By default, Hector is compiled with SandboxEnforced = true, which means:
- DefaultDeniedCommands are ALWAYS applied (cannot be emptied via config)
- DefaultDeniedPatterns are ALWAYS applied (cannot be removed via config)
- Config can ADD to deny lists, but not remove default protections
To compile an unrestricted version (for advanced users who understand the risks):
go build -tags=unrestricted ./cmd/hector
This should only be used in controlled environments where the operator explicitly wants to allow all commands.
Index ¶
- Constants
- Variables
- type CommandTool
- func (t *CommandTool) CallStreaming(ctx tool.Context, args map[string]any) iter.Seq2[*tool.Result, error]
- func (t *CommandTool) Cancel(callID string) bool
- func (t *CommandTool) Description() string
- func (t *CommandTool) IsLongRunning() bool
- func (t *CommandTool) Name() string
- func (t *CommandTool) RequiresApproval() bool
- func (t *CommandTool) Schema() map[string]any
- func (t *CommandTool) SupportsCancellation() bool
- type Config
Constants ¶
const SandboxEnforced = true
SandboxEnforced indicates whether sandbox protections are permanently enabled. When true (the default), DefaultDeniedCommands and DefaultDeniedPatterns cannot be bypassed via configuration.
Variables ¶
var DefaultDeniedCommands = []string{
"rm", "rmdir", "sudo", "su", "chmod", "chown",
"dd", "mkfs", "fdisk", "mount", "umount",
"kill", "killall", "pkill", "reboot", "shutdown",
"passwd", "useradd", "userdel", "groupadd",
}
DefaultDeniedCommands are commands that are blocked by default for security.
var DefaultDeniedPatterns = []*regexp.Regexp{ regexp.MustCompile(`rm\s+(-rf|-fr|--recursive)`), regexp.MustCompile(`>\s*/dev/`), regexp.MustCompile(`:\(\)\s*\{\s*:\|:\s*&\s*\}\s*;`), regexp.MustCompile(`wget.*\|\s*sh`), regexp.MustCompile(`curl.*\|\s*sh`), regexp.MustCompile(`eval\s*\$`), regexp.MustCompile(`\$\(.*\)\s*>\s*/`), regexp.MustCompile(`>\s*/etc/`), regexp.MustCompile(`chmod\s+777`), regexp.MustCompile(`--no-preserve-root`), }
DefaultDeniedPatterns are regex patterns blocked by default.
Functions ¶
This section is empty.
Types ¶
type CommandTool ¶
type CommandTool struct {
// contains filtered or unexported fields
}
CommandTool executes shell commands with security controls and streaming output.
func (*CommandTool) CallStreaming ¶
func (t *CommandTool) CallStreaming(ctx tool.Context, args map[string]any) iter.Seq2[*tool.Result, error]
CallStreaming executes the command and yields output using iter.Seq2. Note: The approval flow is handled externally by the agent flow via RequiresApproval(). When CallStreaming is invoked, approval has already been granted (if configured).
func (*CommandTool) Cancel ¶
func (t *CommandTool) Cancel(callID string) bool
Cancel terminates a running command execution by callID. Returns true if cancellation was initiated.
func (*CommandTool) Description ¶
func (t *CommandTool) Description() string
Description returns the tool description.
func (*CommandTool) IsLongRunning ¶
func (t *CommandTool) IsLongRunning() bool
IsLongRunning returns false - command execution is not async.
func (*CommandTool) RequiresApproval ¶
func (t *CommandTool) RequiresApproval() bool
RequiresApproval returns true if approval is enabled (HITL pattern). This causes the task to transition to INPUT_REQUIRED state before execution.
func (*CommandTool) Schema ¶
func (t *CommandTool) Schema() map[string]any
Schema returns the JSON schema for the tool parameters.
func (*CommandTool) SupportsCancellation ¶
func (t *CommandTool) SupportsCancellation() bool
SupportsCancellation returns true - command execution can be cancelled.
type Config ¶
type Config struct {
// Name overrides the default tool name.
Name string
// AllowedCommands is a whitelist of base commands that can be executed.
// If empty and DenyByDefault is false, all non-denied commands are allowed.
// If empty and DenyByDefault is true, no commands are allowed.
AllowedCommands []string
// DeniedCommands is a blacklist of base commands (checked before allowed).
// Defaults to DefaultDeniedCommands if nil.
DeniedCommands []string
// DeniedPatterns are regex patterns that block dangerous command patterns.
// Defaults to DefaultDeniedPatterns if nil.
DeniedPatterns []*regexp.Regexp
// DenyByDefault requires explicit AllowedCommands whitelist.
// When true, only commands in AllowedCommands are permitted.
// When false, all commands except denied ones are permitted.
DenyByDefault bool
// WorkingDir sets the default working directory.
// Commands cannot escape this directory.
WorkingDir string
// Timeout for command execution. Default: 5 minutes.
Timeout time.Duration
// RequireApproval triggers HITL approval before command execution.
// When true, IsLongRunning() returns true and the tool uses the
// approval flow instead of direct execution.
RequireApproval bool
// ApprovalPrompt customizes the approval message shown to users.
ApprovalPrompt string
}
Config configures the command tool with security settings.
Source Files