Documentation
¶
Overview ¶
Package shell 提供安全的 Shell 脚本执行功能 基于 mvdan/sh interp 实现，替代 os/exec
Index ¶
- func GetAvailableCommandsDescription(ctx context.Context) string
- func IsCommandAvailable(ctx context.Context, cmd string, allowedCommands []string) bool
- func IsShellScript(ctx context.Context, script string) (bool, error)
- func SafeExecute(ctx context.Context, script string) (string, error)
- func SimpleExecute(ctx context.Context, script string) (string, error)
- func SimpleExecuteSeparate(ctx context.Context, script string) (stdout, stderr string, err error)
- type CommandCategory
- type CommandInfo
- type Config
- type Executor
- type Result
- type SandboxConfig
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func GetAvailableCommandsDescription ¶ added in v0.7.5
GetAvailableCommandsDescription 返回系统可用命令的 Markdown 描述
仅包含允许列表中存在且系统中真实存在的命令，按分类组织。 返回格式适合嵌入 Shell 工具的系统提示词（tool call description）：
### 命令分类1 命令名1 - 版本信息1 命令名2 - 版本信息2 ... ### 命令分类2 ...
参数:
ctx: 上下文（用于命令验证的超时控制，整体可能耗时数秒）
返回值:
string: Markdown 格式的命令描述（无可用命令时返回提示信息）
func IsCommandAvailable ¶ added in v0.7.5
IsCommandAvailable 判断命令是否可用（在允许列表中且系统中真实存在）
安全策略：系统中存在但不在允许列表中的命令，统一判为不可用。 此设计确保：
- 沙箱执行时不会意外放行未授权的命令
- 不泄露系统已安装命令的信息（不区分"不存在"与"存在但不允许"）
参数:
ctx: 上下文 cmd: 命令名 allowedCommands: 允许的命令列表（如 getAllowedCommands() 的返回值）
返回值:
bool: 命令可用返回 true
func IsShellScript ¶
IsShellScript 判断给定的脚本是否是有效的Shell脚本
该函数使用mvdan.cc/sh/v3/syntax包来解析脚本，如果能够成功解析为有效的Shell语法， 则返回true。这比简单的shebang检测更准确，因为： 1. 不依赖shebang（shebang可能缺失或错误） 2. 能够检测语法错误 3. 能够处理复杂的Shell脚本结构
参数:
ctx: 上下文，目前未使用，为未来扩展保留 script: 要检查的脚本内容
返回值:
bool: 如果是有效的Shell脚本返回true，否则返回false error: 解析过程中的错误信息（如果脚本不是有效的Shell脚本，会返回具体的语法错误）
func SafeExecute ¶
SafeExecute 安全执行 Shell 脚本（启用沙箱模式）
func SimpleExecute ¶
SimpleExecute 简单执行 Shell 脚本（使用默认配置）
func SimpleExecuteSeparate ¶ added in v0.7.6
SimpleExecuteSeparate 与 SimpleExecute 类似，但分别返回 stdout 和 stderr。
对于像 staticcheck 这样通过 stdout 输出检查结果、通过非零退出码表示发现问题的工具， 调用方可以区分 stdout（有用输出）和 stderr（错误信息），做出更精确的判断。
Types ¶
type CommandCategory ¶ added in v0.7.5
CommandCategory 命令分类，用于组织和描述允许的命令
type CommandInfo ¶ added in v0.7.5
type CommandInfo struct {
Name string // 命令名
Path string // 命令路径（空表示未找到）
Version string // 版本信息首行（通过 --version/version 等获取）
Exists bool // 系统中是否存在（exec.LookPath 成功）
Verified bool // 是否经过版本验证（确认为真实命令，非同名包装脚本）
Error string // 验证过程中的错误信息
}
CommandInfo 系统命令验证信息
func VerifySystemCommand ¶ added in v0.7.5
func VerifySystemCommand(ctx context.Context, cmd string) (*CommandInfo, error)
VerifySystemCommand 验证命令在系统中真实存在且为期望的命令
使用 exec.LookPath 查找命令路径，然后通过尝试多种版本查询方式 （--version、-version、version 子命令等）获取版本信息来验证命令身份。
某些命令（如 rg）可能被用户同名脚本覆盖，此方法通过版本输出检测此类情况。 版本输出非空即认为命令身份已经过验证——真实的命令行工具都会响应版本查询， 而简单的包装脚本通常不会正确处理 --version 参数。
验证流程：
- exec.LookPath 查找命令路径（2s 超时）
- 依次尝试 --version、-version、version、-V、--help 获取版本信息
- 版本信息非空 → Verified=true
参数:
ctx: 上下文（用于超时控制） cmd: 命令名
返回值:
*CommandInfo: 命令验证信息（始终非 nil） error: 系统级错误（如超时），命令不存在不会返回 error
type Config ¶
type Config struct {
// 工作目录
WorkingDir string
// 环境变量（如果为空则使用系统环境变量）
EnvVars []string
// 默认执行超时
Timeout time.Duration
// 最大输出大小（字节）
MaxOutputSize int
// 是否启用严格模式（-e -u 参数）
StrictMode bool
// 是否启用沙箱模式
SandboxMode bool
// 沙箱配置（仅在 SandboxMode=true 时生效）
SandboxConfig *SandboxConfig
}
Config 执行器配置
type Executor ¶
type Executor struct {
// contains filtered or unexported fields
}
Executor Shell 脚本执行器
func NewExecutor ¶
NewExecutor 创建新的执行器
type Result ¶
type Result struct {
// 标准输出
Stdout string
// 标准错误
Stderr string
// 退出码
ExitCode int
// 执行耗时
Duration time.Duration
// 执行错误（如果有）
Err error
// 输出是否被截断
Truncated bool
}
Result 执行结果
type SandboxConfig ¶
type SandboxConfig struct {
// 允许的命令列表（如果为空则允许所有命令）
AllowedCommands []string
// 允许访问的路径列表（如果为空则允许所有路径）
AllowedPaths []string
// 允许的环境变量列表（如果为空则允许所有环境变量）
AllowedEnvVars []string
// 是否允许网络访问
AllowNetwork bool
// 是否允许执行外部程序
AllowExternalExec bool
}
SandboxConfig 沙箱配置
func DefaultSandboxConfig ¶
func DefaultSandboxConfig(ctx context.Context) *SandboxConfig
DefaultSandboxConfig 返回默认沙箱配置
Source Files
¶
- executor.go
- validator.go