proc_jail 0.1.0

Process execution guard for agentic systems
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131

# Risky Binaries

`proc_jail` maintains lists of binaries that are considered high-risk. By default, these are blocked even if explicitly added to the allowlist.

## Categories

### Shells

Binaries that can interpret and execute arbitrary commands.

```rust
pub const RISKY_SHELLS: &[&str] = &[
    "sh", "bash", "zsh", "dash", "ksh", "csh", "tcsh", "fish", "ash", "busybox",
];
```

**Risk**: Any shell can execute arbitrary commands via `-c` or similar.

### Interpreters

Script interpreters that can execute arbitrary code.

```rust
pub const RISKY_INTERPRETERS: &[&str] = &[
    "python", "python2", "python3",
    "perl",
    "ruby",
    "node", "nodejs", "deno", "bun",
    "php",
    "lua", "luajit",
    "tclsh", "wish",
    "awk", "gawk", "nawk", "mawk",
];
```

**Risk**: Interpreters can execute arbitrary code passed via arguments or stdin.

### Spawners

Binaries that can spawn other processes.

```rust
pub const RISKY_SPAWNERS: &[&str] = &[
    "env",       // Can run any command with modified environment
    "xargs",     // Executes commands with input as arguments
    "parallel",  // GNU parallel, runs commands in parallel
    "nohup",     // Runs commands immune to hangups
    "timeout",   // Runs commands with timeout
    "time",      // Times command execution
    "nice",      // Runs with modified priority
    "ionice",    // Runs with modified I/O priority
    "strace",    // Traces system calls of command
    "ltrace",    // Traces library calls of command
    "watch",     // Runs command periodically
    "exec",      // Shell builtin to replace process
];
```

**Risk**: These can be used to execute arbitrary binaries, bypassing the allowlist.

### Privilege Escalation

Binaries that can elevate privileges.

```rust
pub const RISKY_PRIVILEGE: &[&str] = &[
    "sudo",      // Execute as another user
    "su",        // Switch user
    "doas",      // OpenBSD sudo alternative
    "pkexec",    // PolicyKit execution
    "gksudo",    // Graphical sudo
    "kdesudo",   // KDE sudo
    "runuser",   // Run as user (root only)
    "chroot",    // Change root directory
];
```

**Risk**: These can escalate privileges or change security context.

## Policy Options

### DenyByDefault (Recommended)

```rust
.risky_bin_policy(RiskyBinPolicy::DenyByDefault)
```

Even if a risky binary is in your allowlist, it will be denied. This catches mistakes like accidentally allowing `/bin/bash`.

### AllowWithWarning

```rust
.risky_bin_policy(RiskyBinPolicy::AllowWithWarning)
```

Risky binaries are allowed if explicitly in the allowlist, but a warning is logged. Use this if you genuinely need to run interpreters and accept the risks.

### Disabled

```rust
.risky_bin_policy(RiskyBinPolicy::Disabled)
```

No special handling. You're on your own. Only use this if you have external security controls.

## Best Practices

1. **Prefer narrow, single-purpose binaries**:
   ```rust
   // Good
   "/usr/bin/jq", "/usr/bin/grep", "/usr/bin/wc", "/usr/bin/head"
   
   // Risky
   "/usr/bin/python3", "/bin/bash"
   ```

2. **If you must use risky binaries**:
   - Use `AllowWithWarning` to get visibility
   - Pin subcommands where possible
   - Use the most restrictive argument rules
   - Consider container isolation

3. **Don't rely solely on this list**:
   - New risky binaries may not be listed
   - Version-specific variants may be missed
   - Symlinks are resolved before checking, but renamed binaries may be missed

4. **Defense in depth**:
   - Use seccomp/AppArmor/SELinux for kernel-level restrictions
   - Run in containers when possible
   - Limit filesystem access with `path_jail`