pyddock 0.1.0__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.
- pyddock-0.1.0/.gitignore +32 -0
- pyddock-0.1.0/LICENSE +21 -0
- pyddock-0.1.0/PKG-INFO +286 -0
- pyddock-0.1.0/README.md +262 -0
- pyddock-0.1.0/pyproject.toml +49 -0
- pyddock-0.1.0/src/pyddock/__init__.py +8 -0
- pyddock-0.1.0/src/pyddock/_process_utils.py +88 -0
- pyddock-0.1.0/src/pyddock/_runtime.py +1975 -0
- pyddock-0.1.0/src/pyddock/ast_validator.py +172 -0
- pyddock-0.1.0/src/pyddock/cli.py +183 -0
- pyddock-0.1.0/src/pyddock/config.py +459 -0
- pyddock-0.1.0/src/pyddock/default_config.toml +219 -0
- pyddock-0.1.0/src/pyddock/executor.py +275 -0
- pyddock-0.1.0/src/pyddock/script_registry.py +172 -0
- pyddock-0.1.0/src/pyddock/server.py +449 -0
- pyddock-0.1.0/src/pyddock/shell_executor.py +414 -0
- pyddock-0.1.0/src/pyddock/tools/__init__.py +10 -0
- pyddock-0.1.0/src/pyddock/tools/fs_append.py +113 -0
- pyddock-0.1.0/src/pyddock/tools/fs_delete.py +97 -0
- pyddock-0.1.0/src/pyddock/tools/read_file.py +114 -0
- pyddock-0.1.0/src/pyddock/tools/stat_file.py +51 -0
- pyddock-0.1.0/src/pyddock/tools/str_replace.py +238 -0
- pyddock-0.1.0/src/pyddock/venv_manager.py +196 -0
- pyddock-0.1.0/tests/__init__.py +0 -0
- pyddock-0.1.0/tests/test_ast_properties.py +178 -0
- pyddock-0.1.0/tests/test_config.py +414 -0
- pyddock-0.1.0/tests/test_executor.py +270 -0
- pyddock-0.1.0/tests/test_file_tools.py +409 -0
- pyddock-0.1.0/tests/test_filesystem_guards.py +162 -0
- pyddock-0.1.0/tests/test_proxy_properties.py +138 -0
- pyddock-0.1.0/tests/test_realistic.py +230 -0
- pyddock-0.1.0/tests/test_runtime.py +692 -0
- pyddock-0.1.0/tests/test_security_guards.py +656 -0
- pyddock-0.1.0/tests/test_server.py +184 -0
- pyddock-0.1.0/tests/test_shell_arg_paths.py +380 -0
- pyddock-0.1.0/tests/test_shell_executor.py +372 -0
- pyddock-0.1.0/tests/test_shell_properties.py +276 -0
- pyddock-0.1.0/tests/test_subprocess_enforcement.py +551 -0
- pyddock-0.1.0/tests/test_subprocess_properties.py +126 -0
- pyddock-0.1.0/tests/test_subst_trusted_path.py +168 -0
- pyddock-0.1.0/tests/test_workspace_imports.py +852 -0
- pyddock-0.1.0/uv.lock +769 -0
pyddock-0.1.0/.gitignore
ADDED
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
# Python
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.py[cod]
|
|
4
|
+
*$py.class
|
|
5
|
+
*.so
|
|
6
|
+
*.egg-info/
|
|
7
|
+
*.egg
|
|
8
|
+
dist/
|
|
9
|
+
build/
|
|
10
|
+
|
|
11
|
+
# Virtual environments
|
|
12
|
+
.venv/
|
|
13
|
+
.pyddock/venv/
|
|
14
|
+
|
|
15
|
+
# IDE
|
|
16
|
+
.idea/
|
|
17
|
+
.kiro/
|
|
18
|
+
.vscode/
|
|
19
|
+
*.swp
|
|
20
|
+
*.swo
|
|
21
|
+
|
|
22
|
+
# OS
|
|
23
|
+
.DS_Store
|
|
24
|
+
Thumbs.db
|
|
25
|
+
|
|
26
|
+
# Testing
|
|
27
|
+
.pytest_cache/
|
|
28
|
+
.coverage
|
|
29
|
+
htmlcov/
|
|
30
|
+
|
|
31
|
+
# Temp
|
|
32
|
+
.pyddock/tmp/
|
pyddock-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Anthony
|
|
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.
|
pyddock-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,286 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: pyddock
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: MCP server that gives AI agents pre-approved Python, shell, and file I/O tools with declarative policy controls
|
|
5
|
+
Project-URL: Homepage, https://github.com/portablestew/pyddock
|
|
6
|
+
Project-URL: Repository, https://github.com/portablestew/pyddock
|
|
7
|
+
Project-URL: Issues, https://github.com/portablestew/pyddock/issues
|
|
8
|
+
Author: portablestew
|
|
9
|
+
License-Expression: MIT
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Keywords: agents,ai,mcp,python,sandbox,shell
|
|
12
|
+
Classifier: Development Status :: 3 - Alpha
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
19
|
+
Classifier: Topic :: Security
|
|
20
|
+
Classifier: Topic :: Software Development :: Libraries
|
|
21
|
+
Requires-Python: >=3.11
|
|
22
|
+
Requires-Dist: mcp>=1.0
|
|
23
|
+
Description-Content-Type: text/markdown
|
|
24
|
+
|
|
25
|
+
# pyddock
|
|
26
|
+
|
|
27
|
+
*py + paddock — an enclosed space where code can run freely within bounds. ([Worked great in Jurassic Park.](https://en.wikipedia.org/wiki/Jurassic_Park))*
|
|
28
|
+
|
|
29
|
+
MCP server that gives AI agents pre-approved `run_python`, `run_shell`, and file i/o tools. Safely replaces shell scripting for data processing, file analysis, computation, and external command execution — no user confirmation needed.
|
|
30
|
+
|
|
31
|
+
## Why
|
|
32
|
+
|
|
33
|
+
Agents write shell snippets for structured tasks. Those snippets require user approval (workflow friction) or blind trust (security risk). Common alternatives each have limitations:
|
|
34
|
+
|
|
35
|
+
- **Trust specific command strings.** Agents produce variations or chain commands into ad-hoc scripts that break naive string matching, causing repeated approval prompts for equivalent operations.
|
|
36
|
+
- **Trust all shell execution.** Unsafe when the environment has access to production resources.
|
|
37
|
+
- **Full containerized sandbox (Docker).** Isolation cuts agents off from the dev workspace, host network, and local tooling. Restoring access requires per-project configuration that is brittle to maintain.
|
|
38
|
+
- **Larger agent framework with granular permissions.** High adoption cost for what should be a drop-in tool.
|
|
39
|
+
|
|
40
|
+
pyddock provides Python execution and shell command access with declarative policy controls. Policies are safe to auto-approve because side effects are scoped to the configured workspace.
|
|
41
|
+
|
|
42
|
+
**Intended use:** Trusted shell replacement for unattended agents in development environments. The full permission policy is reported in the MCP tool description, so agents know what is allowed before writing code. When a snippet does violate a policy, the error includes the specific rule and a recommended workaround. Agents adapt non-interactively rather than blocking on human approval.
|
|
43
|
+
|
|
44
|
+
**Replaces dedicated MCP servers:** A full Python environment means agents can call service APIs directly (boto3, p4python, etc.) under the same policy enforcement. This eliminates the need for separate MCP servers for AWS, Atlassian, Perforce, and similar services, and allows agents to compose multiple API calls in a single `run_python` invocation.
|
|
45
|
+
|
|
46
|
+
**Workspace scripts:** Scripts in a configured directory (e.g. `.kiro/scripts/`) are automatically trusted. Scripts authored for workspace agents require no additional pyddock configuration.
|
|
47
|
+
|
|
48
|
+
**Threat model:** Pyddock's guardrails keep *trustworthy local agents* out of trouble. A determined adversary may discover a jailbreak, or chain with other tools in the workspace for escalation and/or exfiltration. The Python sandbox contains extensive anti-jailbreak protections, but only as a first-line of defense against accidents and casual misuse. Pyddock does not claim to be a security boundary against targeted exploitation or public abuse. In other words, life finds a way.
|
|
49
|
+
|
|
50
|
+
## Setup
|
|
51
|
+
|
|
52
|
+
```json
|
|
53
|
+
{
|
|
54
|
+
"mcpServers": {
|
|
55
|
+
"pyddock": {
|
|
56
|
+
"command": "uvx",
|
|
57
|
+
"args": ["pyddock", "serve", "--workspace", "<path-to-workspace>"],
|
|
58
|
+
"autoApprove": ["run_python","run_shell","fs_read","fs_stat","fs_append","fs_delete","fs_str_replace"]
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## Tool: `run_python`
|
|
65
|
+
|
|
66
|
+
| Parameter | Type | Description |
|
|
67
|
+
|-----------|------|-------------|
|
|
68
|
+
| `code` | string | Inline Python snippet |
|
|
69
|
+
| `file` | string | Path to a .py file (mutually exclusive with `code`) |
|
|
70
|
+
| `args` | string[] | Available as `sys.argv[1:]` |
|
|
71
|
+
| `timeout` | number | Seconds (default: 30) |
|
|
72
|
+
|
|
73
|
+
The last expression in your snippet is captured as RESULT (like a Jupyter cell) when it evaluates to a non-None value. Use `print()` for streaming output or a trailing expression for structured return values.
|
|
74
|
+
|
|
75
|
+
## Tool: `run_shell`
|
|
76
|
+
|
|
77
|
+
| Parameter | Type | Description |
|
|
78
|
+
|-----------|------|-------------|
|
|
79
|
+
| `command` | string | Executable name or script path (must match a shell policy) |
|
|
80
|
+
| `args` | string[] | Arguments passed directly to the command (no shell interpretation) |
|
|
81
|
+
| `timeout` | number | Seconds (default: 30) |
|
|
82
|
+
|
|
83
|
+
Commands are executed directly — no shell interpretation, pipes, redirects, chaining, or variable expansion. Only commands matching a `[shell.*]` policy in your config are permitted. The tool is only registered when at least one `[shell.*]` section exists in the config.
|
|
84
|
+
|
|
85
|
+
Script files get automatic interpreter mapping: `.ps1` → powershell, `.py` → python, `.sh` → bash, `.bat` → cmd /c.
|
|
86
|
+
|
|
87
|
+
## Output format
|
|
88
|
+
|
|
89
|
+
Both `run_python` and `run_shell` return human-readable text sections:
|
|
90
|
+
|
|
91
|
+
```
|
|
92
|
+
--- RESULT ---
|
|
93
|
+
42
|
|
94
|
+
--- STDOUT ---
|
|
95
|
+
Processing 10 files...
|
|
96
|
+
Done.
|
|
97
|
+
--- STDERR ---
|
|
98
|
+
Warning: deprecated API
|
|
99
|
+
--- EXIT CODE: 0 ---
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
- Sections are omitted when empty (except EXIT CODE which is always present)
|
|
103
|
+
- RESULT only appears in `run_python` responses, when the last expression is non-None
|
|
104
|
+
- `run_shell` responses have STDOUT, STDERR, and EXIT CODE only
|
|
105
|
+
|
|
106
|
+
## File Tools
|
|
107
|
+
|
|
108
|
+
Pyddock also exposes file I/O tools that execute through the same sandbox as `run_python` — same filesystem scoping, same protected directories, same policy enforcement. These are convenience shortcuts for common file operations; agents can't do anything they couldn't already do via `run_python` with `pathlib`. On failure, error messages include diagnostic context to guide the agent's next attempt.
|
|
109
|
+
|
|
110
|
+
- **`fs_read`** — Read a text file. Lines are 1-indexed; negative start = tail. Truncates large output with a continuation hint.
|
|
111
|
+
- **`fs_stat`** — File metadata (exists, type, size, line count, modified). Returns `exists: false` for missing paths.
|
|
112
|
+
- **`fs_append`** — Append to a file (creates if missing). Returns a unified diff.
|
|
113
|
+
- **`fs_delete`** — Delete a file or empty directory. Returns a unified diff of removed content.
|
|
114
|
+
- **`fs_str_replace`** — Find-and-replace exact text (unique match required). Returns a unified diff, or match diagnostics on failure.
|
|
115
|
+
|
|
116
|
+
## Security model
|
|
117
|
+
|
|
118
|
+
`run_python` enforcement:
|
|
119
|
+
|
|
120
|
+
- **AST validation** (pre-execution) — rejects disallowed imports, blocked calls (`eval`, `exec`, `compile`), and blocked attribute access (`__globals__`, `__subclasses__`, etc.)
|
|
121
|
+
- **Runtime enforcement** (in-subprocess) — import hook, filesystem scoping, `getattr`/`attrgetter` guards, factory proxies for library method restrictions, safe `sys`/`os`/`subprocess` module proxies
|
|
122
|
+
|
|
123
|
+
`run_shell` and subprocess enforcement:
|
|
124
|
+
|
|
125
|
+
- **Default deny** — any command not matching a `[shell.*]` config section is rejected outright
|
|
126
|
+
- **No shell interpretation** — commands execute via `subprocess.run(shell=False)`, preventing injection, pipes, redirects, and variable expansion
|
|
127
|
+
- **Argument validation** — per-command allow/deny regex patterns control which arguments are permitted
|
|
128
|
+
- **Argument path scanning** — args that look like filesystem paths are validated against protected directories and workspace boundaries (configurable via `arg_paths`)
|
|
129
|
+
- **Write protection** — path-like shell command regexes automatically generate write-deny rules for `run_python`, preventing write-then-execute privilege escalation
|
|
130
|
+
- **subprocess proxy** — `run_python` code has access to `subprocess.run()` and `subprocess.Popen()`, both validated against the same shell policies; `shell=True` and string commands are always rejected; `os.system()` is blocked
|
|
131
|
+
|
|
132
|
+
Writes are restricted to the workspace. The `.pyddock/` directory, pyddock source, and the Python stdlib directory are always write-protected (`.pyddock/tmp/` is the exception, used by tempfile). Reads are unrestricted by default but subject to filesystem guards.
|
|
133
|
+
|
|
134
|
+
**Filesystem guards** (`[filesystem.guards]`) provide regex-based path rules that apply to both reads and writes. Each pattern maps to a disposition: `"deny-agent"` (block agent code; trusted libraries bypass), `"deny-all"` (block unconditionally), `"workspace"` (allow only inside the workspace), or `"allow"` (permit unconditionally). First match listed in the toml wins. Assorted secrets are blocked by default (`~/.ssh/`, `~/.aws/credentials`, `~/.gnupg/`, etc.). `.env` files are restricted to workspace-only access.
|
|
135
|
+
|
|
136
|
+
## Configuration
|
|
137
|
+
|
|
138
|
+
Configuration is resolved in two steps:
|
|
139
|
+
|
|
140
|
+
1. **Base config:** `.pyddock/pyddock.toml` in your workspace (full replacement of the bundled default), or `default_config.toml` if no workspace config exists.
|
|
141
|
+
2. **Overlay (optional):** `.pyddock/pyddock.override.toml` is deep-merged on top of the base. Only include sections/keys you want to change — everything else is inherited.
|
|
142
|
+
|
|
143
|
+
See `default_config.toml` for the full annotated reference. Key sections:
|
|
144
|
+
|
|
145
|
+
```toml
|
|
146
|
+
[execution]
|
|
147
|
+
timeout = 30
|
|
148
|
+
max_timeout = 3600
|
|
149
|
+
|
|
150
|
+
[imports]
|
|
151
|
+
json = true
|
|
152
|
+
csv = true
|
|
153
|
+
pathlib = true
|
|
154
|
+
# ... (see default_config.toml for full list)
|
|
155
|
+
sys = true
|
|
156
|
+
os = true
|
|
157
|
+
subprocess = true
|
|
158
|
+
dateutil = "python-dateutil"
|
|
159
|
+
polars = true
|
|
160
|
+
boto3 = true
|
|
161
|
+
|
|
162
|
+
[filesystem]
|
|
163
|
+
writable_paths = ["."] # "." = workspace directory; "*" = unrestricted
|
|
164
|
+
readable_paths = ["*"]
|
|
165
|
+
|
|
166
|
+
[filesystem.guards] # regex → disposition (first match wins)
|
|
167
|
+
"/\\.ssh/" = "deny-agent"
|
|
168
|
+
"/\\.aws/credentials$" = "deny-agent"
|
|
169
|
+
"/\\.npmrc$" = "deny-all"
|
|
170
|
+
"/\\.env(\\.[^/]*)?$" = "workspace"
|
|
171
|
+
|
|
172
|
+
[ast]
|
|
173
|
+
block_calls = ["eval", "exec", "compile", "breakpoint", "__import__"]
|
|
174
|
+
block_attributes = ["__subclasses__", "__globals__", "__code__", "__bases__", "__mro__", "__closure__"]
|
|
175
|
+
|
|
176
|
+
[restrictions.polars]
|
|
177
|
+
mode = "allow"
|
|
178
|
+
module_deny = ["write_.*", "sink_.*"]
|
|
179
|
+
class_deny = ["write_.*", "sink_.*"]
|
|
180
|
+
|
|
181
|
+
[restrictions.boto3]
|
|
182
|
+
mode = "deny"
|
|
183
|
+
module_allow = ["client"]
|
|
184
|
+
class_allow = ["list_.*", "describe_.*", "get_.*", "head_.*", "scan", "query", "start_query", "stop_query"]
|
|
185
|
+
|
|
186
|
+
[shell.p4]
|
|
187
|
+
mode = "deny"
|
|
188
|
+
allow = ["filelog.*", "files.*", "describe.*", "changes.*", "print.*", "where.*", "info"]
|
|
189
|
+
|
|
190
|
+
[shell.git]
|
|
191
|
+
mode = "deny"
|
|
192
|
+
allow = ["status.*", "log.*", "diff.*", "show.*", "branch.*", "rev-parse.*"]
|
|
193
|
+
|
|
194
|
+
[shell.kiro-scripts]
|
|
195
|
+
command = "\\.kiro/scripts/.*"
|
|
196
|
+
mode = "allow"
|
|
197
|
+
deny = []
|
|
198
|
+
arg_paths = "protected"
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
### Import values
|
|
202
|
+
|
|
203
|
+
Modules are configured in `[imports]` by setting the import name (what you'd write after `import`) to a value:
|
|
204
|
+
|
|
205
|
+
```toml
|
|
206
|
+
[imports]
|
|
207
|
+
json = true
|
|
208
|
+
pathlib = true
|
|
209
|
+
dateutil = "python-dateutil" # pip name differs from import name
|
|
210
|
+
invoice_parser = ".kiro/scripts/invoice-parser" # import invoice_parser
|
|
211
|
+
metrics_client = ".kiro/scripts/reporting/metrics-client" # import metrics_client
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
- `true` — allowed module (import name == pip package name)
|
|
215
|
+
- `false` — revoked module
|
|
216
|
+
- `"<pip-name>"` — allowed module where the PyPI package name differs from the import name (e.g. `dateutil = "python-dateutil"`)
|
|
217
|
+
- `"<path>"` — workspace package installed via `pip install -e` at boot (string containing `/` or `\`, or starting with `.`)
|
|
218
|
+
|
|
219
|
+
Each workspace package must contain a `pyproject.toml`. Dependencies declared in `pyproject.toml` are resolved automatically during installation — transitive deps are available to the package at runtime (including lazy/deferred imports), but not directly importable by agent code unless explicitly listed.
|
|
220
|
+
|
|
221
|
+
Source code changes in workspace packages are picked up immediately (editable install). Metadata changes (e.g. adding new dependencies in `pyproject.toml`) require a server restart.
|
|
222
|
+
|
|
223
|
+
Workspace module directories are automatically write-protected to prevent code modification from within `run_python`.
|
|
224
|
+
|
|
225
|
+
### Configuration override
|
|
226
|
+
|
|
227
|
+
A minimal `.pyddock/pyddock.override.toml` example — only include what you want to change:
|
|
228
|
+
|
|
229
|
+
```toml
|
|
230
|
+
# .pyddock/pyddock.override.toml — only include what you want to change
|
|
231
|
+
[imports]
|
|
232
|
+
requests = true # add a module
|
|
233
|
+
boto3 = false # revoke a module
|
|
234
|
+
|
|
235
|
+
[execution]
|
|
236
|
+
timeout = 120 # override default 30s
|
|
237
|
+
|
|
238
|
+
[shell.npm]
|
|
239
|
+
command = "^npm$"
|
|
240
|
+
mode = "deny"
|
|
241
|
+
allow = ["run build.*", "test.*"]
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
Merge semantics:
|
|
245
|
+
|
|
246
|
+
- **Scalars and lists** (timeout, writable_paths, block_calls): overlay value replaces base value.
|
|
247
|
+
- **Tables** (imports, restrictions, shell): merge by key — new keys are added, existing keys are overwritten, unmentioned keys are inherited.
|
|
248
|
+
|
|
249
|
+
## Restrictions
|
|
250
|
+
|
|
251
|
+
Two modes for per-library restrictions:
|
|
252
|
+
|
|
253
|
+
- **deny** (with `module_allow` and `class_allow`): blocks all module-level access except functions matching `module_allow` patterns. Wraps allowed callables with a proxy so objects they return are restricted to methods matching `class_allow` patterns. Use for client-producing libraries (boto3, botocore).
|
|
254
|
+
- **allow** (with `module_deny` and `class_deny`): blocks specific module-level functions matching `module_deny` patterns and methods on classes matching `class_deny` patterns. Use for libraries where most operations are safe (polars, pandas).
|
|
255
|
+
|
|
256
|
+
## Shell Policies
|
|
257
|
+
|
|
258
|
+
Each `[shell.<name>]` section defines a command execution policy:
|
|
259
|
+
|
|
260
|
+
- **command**: regex pattern matched against the command string (defaults to `^<name>$` if omitted)
|
|
261
|
+
- **mode**: `"deny"` (block all args except those matching `allow`) or `"allow"` (permit all args except those matching `deny`)
|
|
262
|
+
- **allow**: list of regex patterns for permitted argument strings (used with deny mode)
|
|
263
|
+
- **deny**: list of regex patterns for blocked argument strings (used with allow mode)
|
|
264
|
+
- **arg_paths**: controls path scanning for arguments that look like filesystem paths:
|
|
265
|
+
- `"workspace"` (default) — blocks args resolving outside the workspace or into protected dirs (`.pyddock/`, workspace modules, script dirs)
|
|
266
|
+
- `"protected"` — only blocks args targeting protected dirs; allows paths outside the workspace
|
|
267
|
+
- `"none"` — no path scanning (fully trusts the command)
|
|
268
|
+
|
|
269
|
+
Args are space-joined before matching: `["filelog", "//depot/..."]` becomes `"filelog //depot/..."`. All regexes use `re.match()` (implicitly anchored at start).
|
|
270
|
+
|
|
271
|
+
When `subprocess` is enabled in `[imports]`, `run_python` code can call `subprocess.run([...])` with the same policy enforcement and interpreter mapping. This is useful for composing multiple commands, processing output between calls, or passing environment variables dynamically.
|
|
272
|
+
|
|
273
|
+
## CLI
|
|
274
|
+
|
|
275
|
+
```sh
|
|
276
|
+
pyddock serve --workspace /path/to/project # MCP server (stdio)
|
|
277
|
+
pyddock run "2 + 2" # Direct execution
|
|
278
|
+
pyddock run script.py -- arg1 arg2 # File execution with args
|
|
279
|
+
```
|
|
280
|
+
|
|
281
|
+
## Development
|
|
282
|
+
|
|
283
|
+
```sh
|
|
284
|
+
uv sync
|
|
285
|
+
uv run pytest
|
|
286
|
+
```
|
pyddock-0.1.0/README.md
ADDED
|
@@ -0,0 +1,262 @@
|
|
|
1
|
+
# pyddock
|
|
2
|
+
|
|
3
|
+
*py + paddock — an enclosed space where code can run freely within bounds. ([Worked great in Jurassic Park.](https://en.wikipedia.org/wiki/Jurassic_Park))*
|
|
4
|
+
|
|
5
|
+
MCP server that gives AI agents pre-approved `run_python`, `run_shell`, and file i/o tools. Safely replaces shell scripting for data processing, file analysis, computation, and external command execution — no user confirmation needed.
|
|
6
|
+
|
|
7
|
+
## Why
|
|
8
|
+
|
|
9
|
+
Agents write shell snippets for structured tasks. Those snippets require user approval (workflow friction) or blind trust (security risk). Common alternatives each have limitations:
|
|
10
|
+
|
|
11
|
+
- **Trust specific command strings.** Agents produce variations or chain commands into ad-hoc scripts that break naive string matching, causing repeated approval prompts for equivalent operations.
|
|
12
|
+
- **Trust all shell execution.** Unsafe when the environment has access to production resources.
|
|
13
|
+
- **Full containerized sandbox (Docker).** Isolation cuts agents off from the dev workspace, host network, and local tooling. Restoring access requires per-project configuration that is brittle to maintain.
|
|
14
|
+
- **Larger agent framework with granular permissions.** High adoption cost for what should be a drop-in tool.
|
|
15
|
+
|
|
16
|
+
pyddock provides Python execution and shell command access with declarative policy controls. Policies are safe to auto-approve because side effects are scoped to the configured workspace.
|
|
17
|
+
|
|
18
|
+
**Intended use:** Trusted shell replacement for unattended agents in development environments. The full permission policy is reported in the MCP tool description, so agents know what is allowed before writing code. When a snippet does violate a policy, the error includes the specific rule and a recommended workaround. Agents adapt non-interactively rather than blocking on human approval.
|
|
19
|
+
|
|
20
|
+
**Replaces dedicated MCP servers:** A full Python environment means agents can call service APIs directly (boto3, p4python, etc.) under the same policy enforcement. This eliminates the need for separate MCP servers for AWS, Atlassian, Perforce, and similar services, and allows agents to compose multiple API calls in a single `run_python` invocation.
|
|
21
|
+
|
|
22
|
+
**Workspace scripts:** Scripts in a configured directory (e.g. `.kiro/scripts/`) are automatically trusted. Scripts authored for workspace agents require no additional pyddock configuration.
|
|
23
|
+
|
|
24
|
+
**Threat model:** Pyddock's guardrails keep *trustworthy local agents* out of trouble. A determined adversary may discover a jailbreak, or chain with other tools in the workspace for escalation and/or exfiltration. The Python sandbox contains extensive anti-jailbreak protections, but only as a first-line of defense against accidents and casual misuse. Pyddock does not claim to be a security boundary against targeted exploitation or public abuse. In other words, life finds a way.
|
|
25
|
+
|
|
26
|
+
## Setup
|
|
27
|
+
|
|
28
|
+
```json
|
|
29
|
+
{
|
|
30
|
+
"mcpServers": {
|
|
31
|
+
"pyddock": {
|
|
32
|
+
"command": "uvx",
|
|
33
|
+
"args": ["pyddock", "serve", "--workspace", "<path-to-workspace>"],
|
|
34
|
+
"autoApprove": ["run_python","run_shell","fs_read","fs_stat","fs_append","fs_delete","fs_str_replace"]
|
|
35
|
+
}
|
|
36
|
+
}
|
|
37
|
+
}
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
## Tool: `run_python`
|
|
41
|
+
|
|
42
|
+
| Parameter | Type | Description |
|
|
43
|
+
|-----------|------|-------------|
|
|
44
|
+
| `code` | string | Inline Python snippet |
|
|
45
|
+
| `file` | string | Path to a .py file (mutually exclusive with `code`) |
|
|
46
|
+
| `args` | string[] | Available as `sys.argv[1:]` |
|
|
47
|
+
| `timeout` | number | Seconds (default: 30) |
|
|
48
|
+
|
|
49
|
+
The last expression in your snippet is captured as RESULT (like a Jupyter cell) when it evaluates to a non-None value. Use `print()` for streaming output or a trailing expression for structured return values.
|
|
50
|
+
|
|
51
|
+
## Tool: `run_shell`
|
|
52
|
+
|
|
53
|
+
| Parameter | Type | Description |
|
|
54
|
+
|-----------|------|-------------|
|
|
55
|
+
| `command` | string | Executable name or script path (must match a shell policy) |
|
|
56
|
+
| `args` | string[] | Arguments passed directly to the command (no shell interpretation) |
|
|
57
|
+
| `timeout` | number | Seconds (default: 30) |
|
|
58
|
+
|
|
59
|
+
Commands are executed directly — no shell interpretation, pipes, redirects, chaining, or variable expansion. Only commands matching a `[shell.*]` policy in your config are permitted. The tool is only registered when at least one `[shell.*]` section exists in the config.
|
|
60
|
+
|
|
61
|
+
Script files get automatic interpreter mapping: `.ps1` → powershell, `.py` → python, `.sh` → bash, `.bat` → cmd /c.
|
|
62
|
+
|
|
63
|
+
## Output format
|
|
64
|
+
|
|
65
|
+
Both `run_python` and `run_shell` return human-readable text sections:
|
|
66
|
+
|
|
67
|
+
```
|
|
68
|
+
--- RESULT ---
|
|
69
|
+
42
|
|
70
|
+
--- STDOUT ---
|
|
71
|
+
Processing 10 files...
|
|
72
|
+
Done.
|
|
73
|
+
--- STDERR ---
|
|
74
|
+
Warning: deprecated API
|
|
75
|
+
--- EXIT CODE: 0 ---
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
- Sections are omitted when empty (except EXIT CODE which is always present)
|
|
79
|
+
- RESULT only appears in `run_python` responses, when the last expression is non-None
|
|
80
|
+
- `run_shell` responses have STDOUT, STDERR, and EXIT CODE only
|
|
81
|
+
|
|
82
|
+
## File Tools
|
|
83
|
+
|
|
84
|
+
Pyddock also exposes file I/O tools that execute through the same sandbox as `run_python` — same filesystem scoping, same protected directories, same policy enforcement. These are convenience shortcuts for common file operations; agents can't do anything they couldn't already do via `run_python` with `pathlib`. On failure, error messages include diagnostic context to guide the agent's next attempt.
|
|
85
|
+
|
|
86
|
+
- **`fs_read`** — Read a text file. Lines are 1-indexed; negative start = tail. Truncates large output with a continuation hint.
|
|
87
|
+
- **`fs_stat`** — File metadata (exists, type, size, line count, modified). Returns `exists: false` for missing paths.
|
|
88
|
+
- **`fs_append`** — Append to a file (creates if missing). Returns a unified diff.
|
|
89
|
+
- **`fs_delete`** — Delete a file or empty directory. Returns a unified diff of removed content.
|
|
90
|
+
- **`fs_str_replace`** — Find-and-replace exact text (unique match required). Returns a unified diff, or match diagnostics on failure.
|
|
91
|
+
|
|
92
|
+
## Security model
|
|
93
|
+
|
|
94
|
+
`run_python` enforcement:
|
|
95
|
+
|
|
96
|
+
- **AST validation** (pre-execution) — rejects disallowed imports, blocked calls (`eval`, `exec`, `compile`), and blocked attribute access (`__globals__`, `__subclasses__`, etc.)
|
|
97
|
+
- **Runtime enforcement** (in-subprocess) — import hook, filesystem scoping, `getattr`/`attrgetter` guards, factory proxies for library method restrictions, safe `sys`/`os`/`subprocess` module proxies
|
|
98
|
+
|
|
99
|
+
`run_shell` and subprocess enforcement:
|
|
100
|
+
|
|
101
|
+
- **Default deny** — any command not matching a `[shell.*]` config section is rejected outright
|
|
102
|
+
- **No shell interpretation** — commands execute via `subprocess.run(shell=False)`, preventing injection, pipes, redirects, and variable expansion
|
|
103
|
+
- **Argument validation** — per-command allow/deny regex patterns control which arguments are permitted
|
|
104
|
+
- **Argument path scanning** — args that look like filesystem paths are validated against protected directories and workspace boundaries (configurable via `arg_paths`)
|
|
105
|
+
- **Write protection** — path-like shell command regexes automatically generate write-deny rules for `run_python`, preventing write-then-execute privilege escalation
|
|
106
|
+
- **subprocess proxy** — `run_python` code has access to `subprocess.run()` and `subprocess.Popen()`, both validated against the same shell policies; `shell=True` and string commands are always rejected; `os.system()` is blocked
|
|
107
|
+
|
|
108
|
+
Writes are restricted to the workspace. The `.pyddock/` directory, pyddock source, and the Python stdlib directory are always write-protected (`.pyddock/tmp/` is the exception, used by tempfile). Reads are unrestricted by default but subject to filesystem guards.
|
|
109
|
+
|
|
110
|
+
**Filesystem guards** (`[filesystem.guards]`) provide regex-based path rules that apply to both reads and writes. Each pattern maps to a disposition: `"deny-agent"` (block agent code; trusted libraries bypass), `"deny-all"` (block unconditionally), `"workspace"` (allow only inside the workspace), or `"allow"` (permit unconditionally). First match listed in the toml wins. Assorted secrets are blocked by default (`~/.ssh/`, `~/.aws/credentials`, `~/.gnupg/`, etc.). `.env` files are restricted to workspace-only access.
|
|
111
|
+
|
|
112
|
+
## Configuration
|
|
113
|
+
|
|
114
|
+
Configuration is resolved in two steps:
|
|
115
|
+
|
|
116
|
+
1. **Base config:** `.pyddock/pyddock.toml` in your workspace (full replacement of the bundled default), or `default_config.toml` if no workspace config exists.
|
|
117
|
+
2. **Overlay (optional):** `.pyddock/pyddock.override.toml` is deep-merged on top of the base. Only include sections/keys you want to change — everything else is inherited.
|
|
118
|
+
|
|
119
|
+
See `default_config.toml` for the full annotated reference. Key sections:
|
|
120
|
+
|
|
121
|
+
```toml
|
|
122
|
+
[execution]
|
|
123
|
+
timeout = 30
|
|
124
|
+
max_timeout = 3600
|
|
125
|
+
|
|
126
|
+
[imports]
|
|
127
|
+
json = true
|
|
128
|
+
csv = true
|
|
129
|
+
pathlib = true
|
|
130
|
+
# ... (see default_config.toml for full list)
|
|
131
|
+
sys = true
|
|
132
|
+
os = true
|
|
133
|
+
subprocess = true
|
|
134
|
+
dateutil = "python-dateutil"
|
|
135
|
+
polars = true
|
|
136
|
+
boto3 = true
|
|
137
|
+
|
|
138
|
+
[filesystem]
|
|
139
|
+
writable_paths = ["."] # "." = workspace directory; "*" = unrestricted
|
|
140
|
+
readable_paths = ["*"]
|
|
141
|
+
|
|
142
|
+
[filesystem.guards] # regex → disposition (first match wins)
|
|
143
|
+
"/\\.ssh/" = "deny-agent"
|
|
144
|
+
"/\\.aws/credentials$" = "deny-agent"
|
|
145
|
+
"/\\.npmrc$" = "deny-all"
|
|
146
|
+
"/\\.env(\\.[^/]*)?$" = "workspace"
|
|
147
|
+
|
|
148
|
+
[ast]
|
|
149
|
+
block_calls = ["eval", "exec", "compile", "breakpoint", "__import__"]
|
|
150
|
+
block_attributes = ["__subclasses__", "__globals__", "__code__", "__bases__", "__mro__", "__closure__"]
|
|
151
|
+
|
|
152
|
+
[restrictions.polars]
|
|
153
|
+
mode = "allow"
|
|
154
|
+
module_deny = ["write_.*", "sink_.*"]
|
|
155
|
+
class_deny = ["write_.*", "sink_.*"]
|
|
156
|
+
|
|
157
|
+
[restrictions.boto3]
|
|
158
|
+
mode = "deny"
|
|
159
|
+
module_allow = ["client"]
|
|
160
|
+
class_allow = ["list_.*", "describe_.*", "get_.*", "head_.*", "scan", "query", "start_query", "stop_query"]
|
|
161
|
+
|
|
162
|
+
[shell.p4]
|
|
163
|
+
mode = "deny"
|
|
164
|
+
allow = ["filelog.*", "files.*", "describe.*", "changes.*", "print.*", "where.*", "info"]
|
|
165
|
+
|
|
166
|
+
[shell.git]
|
|
167
|
+
mode = "deny"
|
|
168
|
+
allow = ["status.*", "log.*", "diff.*", "show.*", "branch.*", "rev-parse.*"]
|
|
169
|
+
|
|
170
|
+
[shell.kiro-scripts]
|
|
171
|
+
command = "\\.kiro/scripts/.*"
|
|
172
|
+
mode = "allow"
|
|
173
|
+
deny = []
|
|
174
|
+
arg_paths = "protected"
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
### Import values
|
|
178
|
+
|
|
179
|
+
Modules are configured in `[imports]` by setting the import name (what you'd write after `import`) to a value:
|
|
180
|
+
|
|
181
|
+
```toml
|
|
182
|
+
[imports]
|
|
183
|
+
json = true
|
|
184
|
+
pathlib = true
|
|
185
|
+
dateutil = "python-dateutil" # pip name differs from import name
|
|
186
|
+
invoice_parser = ".kiro/scripts/invoice-parser" # import invoice_parser
|
|
187
|
+
metrics_client = ".kiro/scripts/reporting/metrics-client" # import metrics_client
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
- `true` — allowed module (import name == pip package name)
|
|
191
|
+
- `false` — revoked module
|
|
192
|
+
- `"<pip-name>"` — allowed module where the PyPI package name differs from the import name (e.g. `dateutil = "python-dateutil"`)
|
|
193
|
+
- `"<path>"` — workspace package installed via `pip install -e` at boot (string containing `/` or `\`, or starting with `.`)
|
|
194
|
+
|
|
195
|
+
Each workspace package must contain a `pyproject.toml`. Dependencies declared in `pyproject.toml` are resolved automatically during installation — transitive deps are available to the package at runtime (including lazy/deferred imports), but not directly importable by agent code unless explicitly listed.
|
|
196
|
+
|
|
197
|
+
Source code changes in workspace packages are picked up immediately (editable install). Metadata changes (e.g. adding new dependencies in `pyproject.toml`) require a server restart.
|
|
198
|
+
|
|
199
|
+
Workspace module directories are automatically write-protected to prevent code modification from within `run_python`.
|
|
200
|
+
|
|
201
|
+
### Configuration override
|
|
202
|
+
|
|
203
|
+
A minimal `.pyddock/pyddock.override.toml` example — only include what you want to change:
|
|
204
|
+
|
|
205
|
+
```toml
|
|
206
|
+
# .pyddock/pyddock.override.toml — only include what you want to change
|
|
207
|
+
[imports]
|
|
208
|
+
requests = true # add a module
|
|
209
|
+
boto3 = false # revoke a module
|
|
210
|
+
|
|
211
|
+
[execution]
|
|
212
|
+
timeout = 120 # override default 30s
|
|
213
|
+
|
|
214
|
+
[shell.npm]
|
|
215
|
+
command = "^npm$"
|
|
216
|
+
mode = "deny"
|
|
217
|
+
allow = ["run build.*", "test.*"]
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
Merge semantics:
|
|
221
|
+
|
|
222
|
+
- **Scalars and lists** (timeout, writable_paths, block_calls): overlay value replaces base value.
|
|
223
|
+
- **Tables** (imports, restrictions, shell): merge by key — new keys are added, existing keys are overwritten, unmentioned keys are inherited.
|
|
224
|
+
|
|
225
|
+
## Restrictions
|
|
226
|
+
|
|
227
|
+
Two modes for per-library restrictions:
|
|
228
|
+
|
|
229
|
+
- **deny** (with `module_allow` and `class_allow`): blocks all module-level access except functions matching `module_allow` patterns. Wraps allowed callables with a proxy so objects they return are restricted to methods matching `class_allow` patterns. Use for client-producing libraries (boto3, botocore).
|
|
230
|
+
- **allow** (with `module_deny` and `class_deny`): blocks specific module-level functions matching `module_deny` patterns and methods on classes matching `class_deny` patterns. Use for libraries where most operations are safe (polars, pandas).
|
|
231
|
+
|
|
232
|
+
## Shell Policies
|
|
233
|
+
|
|
234
|
+
Each `[shell.<name>]` section defines a command execution policy:
|
|
235
|
+
|
|
236
|
+
- **command**: regex pattern matched against the command string (defaults to `^<name>$` if omitted)
|
|
237
|
+
- **mode**: `"deny"` (block all args except those matching `allow`) or `"allow"` (permit all args except those matching `deny`)
|
|
238
|
+
- **allow**: list of regex patterns for permitted argument strings (used with deny mode)
|
|
239
|
+
- **deny**: list of regex patterns for blocked argument strings (used with allow mode)
|
|
240
|
+
- **arg_paths**: controls path scanning for arguments that look like filesystem paths:
|
|
241
|
+
- `"workspace"` (default) — blocks args resolving outside the workspace or into protected dirs (`.pyddock/`, workspace modules, script dirs)
|
|
242
|
+
- `"protected"` — only blocks args targeting protected dirs; allows paths outside the workspace
|
|
243
|
+
- `"none"` — no path scanning (fully trusts the command)
|
|
244
|
+
|
|
245
|
+
Args are space-joined before matching: `["filelog", "//depot/..."]` becomes `"filelog //depot/..."`. All regexes use `re.match()` (implicitly anchored at start).
|
|
246
|
+
|
|
247
|
+
When `subprocess` is enabled in `[imports]`, `run_python` code can call `subprocess.run([...])` with the same policy enforcement and interpreter mapping. This is useful for composing multiple commands, processing output between calls, or passing environment variables dynamically.
|
|
248
|
+
|
|
249
|
+
## CLI
|
|
250
|
+
|
|
251
|
+
```sh
|
|
252
|
+
pyddock serve --workspace /path/to/project # MCP server (stdio)
|
|
253
|
+
pyddock run "2 + 2" # Direct execution
|
|
254
|
+
pyddock run script.py -- arg1 arg2 # File execution with args
|
|
255
|
+
```
|
|
256
|
+
|
|
257
|
+
## Development
|
|
258
|
+
|
|
259
|
+
```sh
|
|
260
|
+
uv sync
|
|
261
|
+
uv run pytest
|
|
262
|
+
```
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "pyddock"
|
|
3
|
+
version = "0.1.0"
|
|
4
|
+
description = "MCP server that gives AI agents pre-approved Python, shell, and file I/O tools with declarative policy controls"
|
|
5
|
+
requires-python = ">=3.11"
|
|
6
|
+
license = "MIT"
|
|
7
|
+
readme = "README.md"
|
|
8
|
+
authors = [
|
|
9
|
+
{ name = "portablestew" },
|
|
10
|
+
]
|
|
11
|
+
keywords = ["mcp", "ai", "agents", "sandbox", "python", "shell"]
|
|
12
|
+
classifiers = [
|
|
13
|
+
"Development Status :: 3 - Alpha",
|
|
14
|
+
"Intended Audience :: Developers",
|
|
15
|
+
"License :: OSI Approved :: MIT License",
|
|
16
|
+
"Programming Language :: Python :: 3",
|
|
17
|
+
"Programming Language :: Python :: 3.11",
|
|
18
|
+
"Programming Language :: Python :: 3.12",
|
|
19
|
+
"Programming Language :: Python :: 3.13",
|
|
20
|
+
"Topic :: Software Development :: Libraries",
|
|
21
|
+
"Topic :: Security",
|
|
22
|
+
]
|
|
23
|
+
dependencies = [
|
|
24
|
+
"mcp>=1.0",
|
|
25
|
+
]
|
|
26
|
+
|
|
27
|
+
[project.urls]
|
|
28
|
+
Homepage = "https://github.com/portablestew/pyddock"
|
|
29
|
+
Repository = "https://github.com/portablestew/pyddock"
|
|
30
|
+
Issues = "https://github.com/portablestew/pyddock/issues"
|
|
31
|
+
|
|
32
|
+
[project.scripts]
|
|
33
|
+
pyddock = "pyddock.cli:main"
|
|
34
|
+
|
|
35
|
+
[build-system]
|
|
36
|
+
requires = ["hatchling"]
|
|
37
|
+
build-backend = "hatchling.build"
|
|
38
|
+
|
|
39
|
+
[tool.hatch.build.targets.wheel]
|
|
40
|
+
packages = ["src/pyddock"]
|
|
41
|
+
|
|
42
|
+
[tool.pytest.ini_options]
|
|
43
|
+
testpaths = ["tests"]
|
|
44
|
+
|
|
45
|
+
[dependency-groups]
|
|
46
|
+
dev = [
|
|
47
|
+
"pytest",
|
|
48
|
+
"hypothesis",
|
|
49
|
+
]
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
"""pyddock — policy-controlled Python execution via MCP."""
|
|
2
|
+
|
|
3
|
+
__version__ = "0.1.0"
|
|
4
|
+
|
|
5
|
+
# Filename used for compile() when executing agent snippets.
|
|
6
|
+
# Used by executor (compile source), runtime (stack inspection to identify
|
|
7
|
+
# agent code vs trusted library code), and tests.
|
|
8
|
+
SNIPPET_FILENAME = "<snippet>"
|