shellguard

Documentation

Overview

Package shellguard provides shell command security checking with a two-step pipeline: deterministic denylist checks followed by optional LLM-based analysis.

Index

• Variables
• type BannedSubcommand
• type Gate
  • func New(shell Shell, workspace string, allowedDirs, userDeniedCommands []string, ...) *Gate
  • func (g *Gate) Check(ctx context.Context, args tools.Args) (err error)
  • func (g *Gate) CheckDeterministic(command string) (bool, string)
• type Result
• type Shell
  • func Bash() Shell
  • func Fish() Shell
  • func Posix() Shell

Variables

var BannedCommands = []string{

	"alias", "aria2c", "axel", "chrome", "curl", "curlie", "firefox",
	"http-prompt", "httpie", "links", "lynx", "nc", "netcat", "ncat",
	"safari", "scp", "sftp", "ssh", "telnet", "w3m", "wget", "xh",

	"doas", "su", "sudo", "pkexec", "gksudo", "kdesudo",

	"apk", "apt", "apt-cache", "apt-get", "dnf", "dpkg", "emerge",
	"home-manager", "makepkg", "opkg", "pacman", "paru", "pkg",
	"pkg_add", "pkg_delete", "portage", "rpm", "yay", "yum", "zypper",
	"snap", "flatpak", "nix-env",

	"at", "batch", "chkconfig", "crontab", "fdisk", "mkfs", "mount",
	"parted", "service", "systemctl", "umount", "shutdown", "reboot",
	"poweroff", "init", "telinit",

	"firewall-cmd", "ifconfig", "ip", "iptables", "ip6tables", "nft",
	"netstat", "pfctl", "route", "ufw", "nmcli", "networkctl",

	"useradd", "userdel", "usermod", "groupadd", "groupdel", "groupmod",
	"passwd", "chpasswd", "adduser", "deluser",

	"shred", "wipe", "dd", "losetup",

	"setcap", "getcap", "chroot", "unshare", "nsenter",
}

BannedCommands is the hardcoded list of commands that are always blocked.

var BannedSubcommandPatterns = []BannedSubcommand{
	{Command: "brew", Args: []string{"install"}},
	{Command: "cargo", Args: []string{"install"}},
	{Command: "gem", Args: []string{"install"}},
	{Command: "go", Args: []string{"install"}},
	{Command: "npm", Args: []string{"install"}, Flags: []string{"--global", "-g"}},
	{Command: "pip", Args: []string{"install"}, Flags: []string{"--user", "--system"}},
	{Command: "pip3", Args: []string{"install"}, Flags: []string{"--user", "--system"}},
	{Command: "pnpm", Args: []string{"add"}, Flags: []string{"--global", "-g"}},
	{Command: "yarn", Args: []string{"global", "add"}},
	{Command: "go", Args: []string{"test"}, Flags: []string{"-exec"}},
	{Command: "git", Args: []string{"config", "--global"}},
	{Command: "git", Args: []string{"config", "--system"}},
	{Command: "docker", Args: []string{"run"}, Flags: []string{"--privileged"}},
	{Command: "docker", Args: []string{"run"}, Flags: []string{"-v", "/:/"}},
	{Command: "podman", Args: []string{"run"}, Flags: []string{"--privileged"}},
}

BannedSubcommandPatterns blocks specific subcommand patterns even if the base command is allowed.

var DangerousPipePatterns = []*regexp.Regexp{
	regexp.MustCompile(`(?i)curl\s+.+\|\s*(ba)?sh`),
	regexp.MustCompile(`(?i)wget\s+.+\|\s*(ba)?sh`),
	regexp.MustCompile(`(?i)curl\s+.+\|\s*python`),
	regexp.MustCompile(`(?i)wget\s+.+\|\s*python`),
	regexp.MustCompile(`(?i)\|\s*sudo\b`),
	regexp.MustCompile(`(?i)\|\s*su\b`),
	regexp.MustCompile(`(?i)\|\s*base64\s+-d\s*\|\s*(ba)?sh`),
}

DangerousPipePatterns detects dangerous command chaining.

Types

type BannedSubcommand

type BannedSubcommand struct {
	Command string
	Args    []string
	Flags   []string
}

BannedSubcommand defines specific subcommand patterns to block.

type Gate

type Gate struct {

	// OnDecision is called after each security decision for logging/auditing.
	OnDecision func(command, step string, allowed bool, reason string, durationMs int64, inputTokens, outputTokens int)
	// contains filtered or unexported fields
}

Gate is the security gate for shell commands. Commands pass through deterministic checks (banned commands, patterns, pipes) and optionally LLM-based analysis before being allowed to execute.

func New

func New(shell Shell, workspace string, allowedDirs, userDeniedCommands []string, model llm.Model, securityScope string) *Gate

New creates a new shell command security gate. shell determines how commands are parsed (use BashShell{}, FishShell{}, or PosixShell{}). model is optional (nil for deterministic-only checks). securityScope is optional ("" for normal mode).

func (*Gate) Check

func (g *Gate) Check(ctx context.Context, args tools.Args) (err error)

Check implements tools.Guard. It extracts "command" from args and runs the security pipeline.

func (*Gate) CheckDeterministic

func (g *Gate) CheckDeterministic(command string) (bool, string)

CheckDeterministic performs only the fast deterministic checks (for testing/preview).

type Result

type Result struct {
	Allowed      bool
	Reason       string
	InputTokens  int
	OutputTokens int
}

Result contains the outcome of a command security check.

type Shell

type Shell interface {
	// HasChainedCommands returns true if the command contains shell metacharacters
	// that chain multiple commands (pipes, &&, ||, ;, etc.).
	HasChainedCommands(command string) bool

	// SplitSegments splits a compound command into individual segments
	// by pipes, semicolons, and logical operators.
	SplitSegments(command string) []string

	// ExtractCommand returns the base command name from a single segment,
	// stripping path prefixes, env prefixes, etc.
	ExtractCommand(segment string) string
}

Shell defines shell-specific command parsing behavior. Different shells have different metacharacters, quoting rules, and chaining syntax.

func Bash

func Bash() Shell

Bash returns a Shell for bash and zsh (identical parsing rules).

func Fish

func Fish() Shell

Fish returns a Shell for the fish shell. Fish has different syntax: no $() (uses ()), no &&/|| (uses "; and"/"; or"), and single quotes don't escape backslashes.

func Posix

func Posix() Shell

Posix returns a Shell for POSIX sh. POSIX sh is a subset of bash — same metacharacters but no $() or ${}.