Documentation
¶
Overview ¶
Package runner provides isolated command execution environments.
Package runner provides isolated command execution environments.
This package defines the Runner interface and implementations for executing commands in various isolation environments including direct execution, firejail (Linux), sandbox-exec (macOS), and Docker containers.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ShouldUseUnixTimeoutCommand ¶
func ShouldUseUnixTimeoutCommand() bool
ShouldUseUnixTimeoutCommand returns whether to use the Unix-style timeout command
Types ¶
type Docker ¶
type Docker struct {
// contains filtered or unexported fields
}
Docker executes commands inside a Docker container.
func (*Docker) CheckImplicitRequirements ¶
CheckImplicitRequirements checks if the runner meets its implicit requirements. Docker runner requires the docker executable and a running daemon.
type DockerOptions ¶
type DockerOptions struct {
// The Docker image to use (required)
Image string `json:"image"`
// Additional Docker run options
DockerRunOpts string `json:"docker_run_opts"`
// Mount points in the format "hostpath:containerpath"
Mounts []string `json:"mounts"`
// Whether to allow networking in the container
AllowNetworking bool `json:"allow_networking"`
// Specific network to connect container to (e.g. "host", "bridge", or custom network name)
Network string `json:"network"`
// User to run as inside the container (defaults to current user)
User string `json:"user"`
// Working directory inside the container
WorkDir string `json:"workdir"`
// PrepareCommand is a command to run before the main command
PrepareCommand string `json:"prepare_command"`
// Memory limit (e.g. "512m", "1g")
Memory string `json:"memory"`
// Memory soft limit (e.g. "256m", "512m")
MemoryReservation string `json:"memory_reservation"`
// Swap limit equal to memory plus swap: '-1' to enable unlimited swap
MemorySwap string `json:"memory_swap"`
// Tune container memory swappiness (0 to 100)
MemorySwappiness int `json:"memory_swappiness"`
// Linux capabilities to add to the container
CapAdd []string `json:"cap_add"`
// Linux capabilities to drop from the container
CapDrop []string `json:"cap_drop"`
// Custom DNS servers for the container
DNS []string `json:"dns"`
// Custom DNS search domains for the container
DNSSearch []string `json:"dns_search"`
// Set platform if server is multi-platform capable (e.g., "linux/amd64", "linux/arm64")
Platform string `json:"platform"`
}
DockerOptions represents configuration options for the Docker runner.
func NewDockerOptions ¶
func NewDockerOptions(genericOpts Options) (DockerOptions, error)
NewDockerOptions extracts Docker-specific options from generic runner options.
func (*DockerOptions) GetBaseDockerCommand ¶
func (o *DockerOptions) GetBaseDockerCommand(env []string) []string
GetBaseDockerCommand creates the common parts of a docker run command with all configured options. It returns a slice of command parts that can be further customized by the calling method.
func (*DockerOptions) GetDirectExecutionCommand ¶
func (o *DockerOptions) GetDirectExecutionCommand(cmd string, env []string) string
GetDirectExecutionCommand constructs the docker run command for direct executable execution. This is used to optimize the case where we're just running a single executable without a temp script.
func (*DockerOptions) GetDockerCommand ¶
func (o *DockerOptions) GetDockerCommand(scriptFile string, env []string) string
GetDockerCommand constructs the docker run command with a script file.
type Exec ¶
type Exec struct {
// contains filtered or unexported fields
}
Exec implements the Runner interface for direct command execution
func NewExec ¶
NewExec creates a new Exec runner with the provided logger. If logger is nil, a default logger is created.
func (*Exec) CheckImplicitRequirements ¶
CheckImplicitRequirements checks if the runner meets its implicit requirements. Exec runner has no special requirements.
func (*Exec) Run ¶
func (r *Exec) Run(ctx context.Context, shell string, command string, env []string, params map[string]interface{}, tmpfile bool, ) (string, error)
Run executes a command with the given shell and returns the output. It implements the Runner interface.
Note: For Windows native shells (cmd, powershell), the 'tmpfile' parameter is ignored and commands are executed directly to avoid issues with output capturing.
type ExecOptions ¶
type ExecOptions struct {
Shell string `json:"shell"`
}
ExecOptions is the options for the Exec runner
func NewExecOptions ¶
func NewExecOptions(options Options) (ExecOptions, error)
NewExecOptions creates a new ExecOptions from Options
type Firejail ¶
type Firejail struct {
// contains filtered or unexported fields
}
Firejail implements the Runner interface using firejail on Linux
func NewFirejail ¶
NewFirejail creates a new Firejail runner with the provided logger. If logger is nil, a default logger is created.
func (*Firejail) CheckImplicitRequirements ¶
CheckImplicitRequirements checks if the runner meets its implicit requirements. Firejail runner requires Linux and the firejail executable.
func (*Firejail) Run ¶
func (r *Firejail) Run(ctx context.Context, shell string, command string, env []string, params map[string]interface{}, tmpfile bool, ) (string, error)
Run executes a command inside the firejail sandbox and returns the output. It implements the Runner interface.
note: tmpfile is ignored for firejail because it's not supported
type FirejailOptions ¶
type FirejailOptions struct {
Shell string `json:"shell"`
AllowNetworking bool `json:"allow_networking"`
AllowUserFolders bool `json:"allow_user_folders"`
AllowReadFolders []string `json:"allow_read_folders"`
AllowWriteFolders []string `json:"allow_write_folders"`
AllowReadFiles []string `json:"allow_read_files"`
AllowWriteFiles []string `json:"allow_write_files"`
CustomProfile string `json:"custom_profile"`
}
FirejailOptions is the options for the Firejail runner
func NewFirejailOptions ¶
func NewFirejailOptions(options Options) (FirejailOptions, error)
NewFirejailOptions creates a new FirejailOptions from Options
type Runner ¶
type Runner interface {
// Run executes a command and returns the output.
//
// Parameters:
// - ctx: Context for cancellation and timeout
// - shell: The shell to use for execution (empty for default)
// - command: The command to execute
// - env: Environment variables in KEY=VALUE format
// - params: Template parameters for variable substitution
// - tmpfile: Whether to use a temporary file for the command
//
// Returns:
// - The command output as a string
// - An error if execution fails
Run(ctx context.Context, shell string, command string, env []string, params map[string]interface{}, tmpfile bool) (string, error)
// CheckImplicitRequirements verifies that the runner's prerequisites are met.
// This includes checking for required executables, OS compatibility, etc.
//
// Returns:
// - nil if all requirements are satisfied
// - An error describing which requirement is not met
CheckImplicitRequirements() error
}
Runner is an interface for running commands in isolated environments
func New ¶
New creates a new Runner based on the given type.
Parameters:
- runnerType: The type of runner to create
- options: Configuration options for the runner
- logger: Logger for debug output (uses global logger if nil)
Returns:
- A Runner instance if successful
- An error if creation fails or requirements are not met
type SandboxExec ¶
type SandboxExec struct {
// contains filtered or unexported fields
}
SandboxExec implements the Runner interface using macOS sandbox-exec
func NewSandboxExec ¶
func NewSandboxExec(options Options, logger *common.Logger) (*SandboxExec, error)
NewSandboxExec creates a new SandboxExec runner with the provided logger. If logger is nil, a default logger is created.
func (*SandboxExec) CheckImplicitRequirements ¶
func (r *SandboxExec) CheckImplicitRequirements() error
CheckImplicitRequirements checks if the runner meets its implicit requirements. SandboxExec runner requires macOS and the sandbox-exec executable.
func (*SandboxExec) Run ¶
func (r *SandboxExec) Run(ctx context.Context, shell string, command string, env []string, params map[string]interface{}, tmpfile bool) (string, error)
Run executes a command inside the macOS sandbox and returns the output. It implements the Runner interface.
note: tmpfile is ignored for sandbox because it's not supported
type SandboxExecOptions ¶
type SandboxExecOptions struct {
Shell string `json:"shell"`
AllowNetworking bool `json:"allow_networking"`
AllowUserFolders bool `json:"allow_user_folders"`
AllowReadFolders []string `json:"allow_read_folders"`
AllowWriteFolders []string `json:"allow_write_folders"`
AllowReadFiles []string `json:"allow_read_files"`
AllowWriteFiles []string `json:"allow_write_files"`
CustomProfile string `json:"custom_profile"`
}
SandboxExecOptions is the options for the SandboxExec runner
func NewSandboxExecOptions ¶
func NewSandboxExecOptions(options Options) (SandboxExecOptions, error)
NewSandboxExecOptions creates a new SandboxExecOptions from Options
type Type ¶
type Type string
Type is an identifier for the type of runner to use. Each runner has its own set of implicit requirements that are checked automatically, so users don't need to explicitly specify common requirements in their tool configurations.
const ( // TypeExec is the standard command execution runner with no additional requirements TypeExec Type = "exec" // TypeSandboxExec is the macOS-specific sandbox-exec runner // Implicit requirements: OS=darwin, executables=[sandbox-exec] TypeSandboxExec Type = "sandbox-exec" // TypeFirejail is the Linux-specific firejail runner // Implicit requirements: OS=linux, executables=[firejail] TypeFirejail Type = "firejail" // TypeDocker is the Docker-based runner // Implicit requirements: executables=[docker] TypeDocker Type = "docker" )
Source Files