README
¶
rshell
A default-deny shell interpreter for Go, built for AI agents that need a bounded Bash/POSIX-like command surface.
[!IMPORTANT] The CLI is a development and local-validation tool, not a production security boundary. Production integrations should embed the Go package and explicitly configure commands, paths, environment, timeouts, and execution mode.
Install
go get github.com/DataDog/rshell/interp
For the optional development CLI:
go install github.com/DataDog/rshell/cmd/rshell@latest
Quick start
A minimal embedded runner (imports omitted):
func runScript(ctx context.Context) error {
program, err := interp.ParseScript(`echo "hello from rshell"`, "")
if err != nil {
return err
}
runner, err := interp.New(
interp.StdIO(nil, os.Stdout, os.Stderr),
interp.AllowedCommands([]string{"rshell:echo"}),
interp.MaxExecutionTime(5*time.Second),
)
if err != nil {
return err
}
defer runner.Close()
return runner.Run(ctx, program)
}
See the Go API reference for runner options and lifecycle details.
The same command through the development CLI:
rshell --allowed-commands rshell:echo --timeout 5s -c 'echo "hello from rshell"'
Security model
Policy is layered and default-deny:
| Surface | Default | Explicit opt-in |
|---|---|---|
| Commands | Denied | AllowedCommands with namespaced entries such as rshell:cat |
| Filesystem | Denied | AllowedPaths roots, optionally suffixed with :ro or :rw |
| Environment | Empty; the host environment is not inherited | Env |
| Writes and remediation commands | Disabled | WithMode(ModeRemediation) plus a matching :rw path or capability grant |
| Systemd | All units and actions denied | Exact unit/action grants through AllowedSystemServices; systemctl also requires remediation mode |
Only registered rshell builtins are executable through the public API; host binaries and unknown commands are rejected. Read-only mode is the default; remediation mode enables only the separately authorized write and host-remediation surfaces.
Some inspection builtins read fixed kernel interfaces outside AllowedPaths, and trusted systemd target paths intentionally bypass the filesystem sandbox. Their platform limits, data exposure, and authorization rules are documented in the feature reference.
Features and platforms
Allow rshell:help, then run help for the commands and policy active on a runner, or help <command> for command-specific details. See SHELL_FEATURES.md for the complete supported and blocked feature matrix.
The interpreter supports Linux, macOS, and Windows. Some host-inspection builtins are platform-specific; the feature reference calls those out individually.
Development
See CONTRIBUTING.md for setup, testing, and pull request guidance. Security-sensitive builtin implementation rules live in docs/RULES.md.
License
Directories
¶
| Path | Synopsis |
|---|---|
|
Package allowedpaths implements a filesystem sandbox that restricts access to a set of allowed directories using os.Root (Go 1.24+).
|
Package allowedpaths implements a filesystem sandbox that restricts access to a set of allowed directories using os.Root (Go 1.24+). |
|
internal/fsstat
Package fsstat reads filesystem metadata for a path opened through os.Root.
|
Package fsstat reads filesystem metadata for a path opened through os.Root. |
|
Package analysis provides a go/analysis.Analyzer that enforces symbol-level import restrictions on Go source files.
|
Package analysis provides a go/analysis.Analyzer that enforces symbol-level import restrictions on Go source files. |
|
break
Package breakcmd implements the break builtin command.
|
Package breakcmd implements the break builtin command. |
|
cat
Package cat implements the cat builtin command.
|
Package cat implements the cat builtin command. |
|
cd
Package cd implements the cd builtin command.
|
Package cd implements the cd builtin command. |
|
continue
Package continuecmd implements the continue builtin command.
|
Package continuecmd implements the continue builtin command. |
|
cut
Package cut implements the cut builtin command.
|
Package cut implements the cut builtin command. |
|
df
Package df implements the df builtin command.
|
Package df implements the df builtin command. |
|
du
Package du implements the du builtin command.
|
Package du implements the du builtin command. |
|
echo
Package echo implements the echo builtin command.
|
Package echo implements the echo builtin command. |
|
exit
Package exit implements the exit builtin command.
|
Package exit implements the exit builtin command. |
|
false
Package falsecmd implements the false builtin command.
|
Package falsecmd implements the false builtin command. |
|
find
Package find implements the find builtin command.
|
Package find implements the find builtin command. |
|
free
Package free implements the free builtin command.
|
Package free implements the free builtin command. |
|
grep
Package grep implements the grep builtin command.
|
Package grep implements the grep builtin command. |
|
head
Package head implements the head builtin command.
|
Package head implements the head builtin command. |
|
help
Package help implements the help builtin command.
|
Package help implements the help builtin command. |
|
internal/diskstats
Package diskstats reads mounted-filesystem usage information from the kernel and presents it as a normalised cross-platform Mount struct.
|
Package diskstats reads mounted-filesystem usage information from the kernel and presents it as a normalised cross-platform Mount struct. |
|
internal/flagparser
Package flagparser bridges between pflag and the GNU-getopt wording that rshell builtins are expected to match.
|
Package flagparser bridges between pflag and the GNU-getopt wording that rshell builtins are expected to match. |
|
internal/meminfo
Package meminfo reads host memory and swap usage from the kernel and presents it as a normalised cross-platform Info struct.
|
Package meminfo reads host memory and swap usage from the kernel and presents it as a normalised cross-platform Info struct. |
|
internal/procfd
Package procfd provides Linux open-file-descriptor enumeration for the lsof builtin.
|
Package procfd provides Linux open-file-descriptor enumeration for the lsof builtin. |
|
internal/procinfo
Package procinfo provides OS-specific process information for the ps builtin.
|
Package procinfo provides OS-specific process information for the ps builtin. |
|
internal/procmaps
Package procmaps reads per-process virtual memory mappings for the pmap builtin and presents them as a normalised cross-platform slice of Mapping.
|
Package procmaps reads per-process virtual memory mappings for the pmap builtin and presents them as a normalised cross-platform slice of Mapping. |
|
internal/procnetroute
Package procnetroute reads the Linux IPv4 routing table from /proc/net/route.
|
Package procnetroute reads the Linux IPv4 routing table from /proc/net/route. |
|
internal/procnetsocket
Package procnetsocket reads Linux socket state from /proc/net/.
|
Package procnetsocket reads Linux socket state from /proc/net/. |
|
internal/procpath
Package procpath provides the single canonical default path to the Linux proc filesystem.
|
Package procpath provides the single canonical default path to the Linux proc filesystem. |
|
internal/procsyskernel
Package procsyskernel reads Linux kernel information from /proc/sys/kernel/.
|
Package procsyskernel reads Linux kernel information from /proc/sys/kernel/. |
|
internal/sizeparse
Package sizeparse parses coreutils-style non-negative byte sizes.
|
Package sizeparse parses coreutils-style non-negative byte sizes. |
|
internal/sysinfo
Package sysinfo provides cross-platform access to system uptime and load average data.
|
Package sysinfo provides cross-platform access to system uptime and load average data. |
|
internal/vmstat
Package vmstat reads virtual-memory, swap, IO-paging, and CPU pressure counters from the kernel and presents them as a normalised cross-platform Stats struct.
|
Package vmstat reads virtual-memory, swap, IO-paging, and CPU pressure counters from the kernel and presents them as a normalised cross-platform Stats struct. |
|
internal/winnet
Package winnet provides socket enumeration for Windows via iphlpapi.dll.
|
Package winnet provides socket enumeration for Windows via iphlpapi.dll. |
|
internal/winpoll
Package winpoll provides a non-consuming readability probe for Windows file handles.
|
Package winpoll provides a non-consuming readability probe for Windows file handles. |
|
ip
Package ip implements the ip builtin command.
|
Package ip implements the ip builtin command. |
|
journalctl
Package journalctl implements a bounded systemd journal query builtin.
|
Package journalctl implements a bounded systemd journal query builtin. |
|
logrotate
Package logrotate implements a remediation-mode log truncation builtin.
|
Package logrotate implements a remediation-mode log truncation builtin. |
|
ls
Package ls implements the ls builtin command.
|
Package ls implements the ls builtin command. |
|
lsof
Package lsof implements the lsof builtin command.
|
Package lsof implements the lsof builtin command. |
|
ping
Package ping implements the ping builtin command.
|
Package ping implements the ping builtin command. |
|
pmap
Package pmap implements the pmap builtin command.
|
Package pmap implements the pmap builtin command. |
|
printf
Package printf implements the printf builtin command.
|
Package printf implements the printf builtin command. |
|
ps
Package ps implements the ps builtin command.
|
Package ps implements the ps builtin command. |
|
pwd
Package pwd implements the pwd builtin command.
|
Package pwd implements the pwd builtin command. |
|
read
Package read implements the read builtin command.
|
Package read implements the read builtin command. |
|
rm
Package rm implements the rm builtin command.
|
Package rm implements the rm builtin command. |
|
sed
Package sed implements the sed builtin command.
|
Package sed implements the sed builtin command. |
|
sort
Package sort implements the sort builtin command.
|
Package sort implements the sort builtin command. |
|
ss
Package ss implements the ss builtin command.
|
Package ss implements the ss builtin command. |
|
stat
Package stat implements the stat filesystem-status builtin.
|
Package stat implements the stat filesystem-status builtin. |
|
strings_cmd
Package strings_cmd implements the strings builtin command.
|
Package strings_cmd implements the strings builtin command. |
|
systemctl
Package systemctl implements a capability-bounded systemd unit manager.
|
Package systemctl implements a capability-bounded systemd unit manager. |
|
tail
Package tail implements the tail builtin command.
|
Package tail implements the tail builtin command. |
|
testcmd
Package testcmd implements the POSIX test and [ builtin commands.
|
Package testcmd implements the POSIX test and [ builtin commands. |
|
testutil
Package testutil provides shared test helpers for builtin command tests.
|
Package testutil provides shared test helpers for builtin command tests. |
|
tr
Package tr implements the tr builtin command.
|
Package tr implements the tr builtin command. |
|
true
Package truecmd implements the true builtin command.
|
Package truecmd implements the true builtin command. |
|
truncate
Package truncate implements the truncate builtin command.
|
Package truncate implements the truncate builtin command. |
|
uname
Package uname implements the uname builtin command.
|
Package uname implements the uname builtin command. |
|
uniq
Package uniq implements the uniq builtin command.
|
Package uniq implements the uniq builtin command. |
|
uptime
Package uptime implements the uptime builtin command.
|
Package uptime implements the uptime builtin command. |
|
vmstat
Package vmstat implements the vmstat builtin command.
|
Package vmstat implements the vmstat builtin command. |
|
wc
Package wc implements the wc builtin command.
|
Package wc implements the wc builtin command. |
|
xargs
Package xargs implements the xargs builtin command.
|
Package xargs implements the xargs builtin command. |
|
cmd
|
|
|
rshell
command
Package main provides the rshell development CLI.
|
Package main provides the rshell development CLI. |
|
internal
|
|
|
interpoption
Package interpoption provides internal-only interpreter options that are not part of the public API.
|
Package interpoption provides internal-only interpreter options that are not part of the public API. |
|
systemd
Package systemd contains the trusted target and transport implementation used by systemd-aware builtins.
|
Package systemd contains the trusted target and transport implementation used by systemd-aware builtins. |
|
version
Package version exposes the build version of rshell.
|
Package version exposes the build version of rshell. |
|
Package interp implements a restricted shell interpreter designed for safe, sandboxed execution.
|
Package interp implements a restricted shell interpreter designed for safe, sandboxed execution. |
Click to show internal directories.
Click to hide internal directories.