pyddock 0.2.4__tar.gz → 0.3.1__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.2.4 → pyddock-0.3.1}/PKG-INFO +28 -2
- {pyddock-0.2.4 → pyddock-0.3.1}/README.md +27 -1
- {pyddock-0.2.4 → pyddock-0.3.1}/pyproject.toml +1 -1
- pyddock-0.3.1/src/pyddock/_audit_enforcement.py +606 -0
- pyddock-0.3.1/src/pyddock/_base.py +166 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/src/pyddock/_enforcement.py +116 -13
- {pyddock-0.2.4 → pyddock-0.3.1}/src/pyddock/_fs_enforcement.py +172 -32
- {pyddock-0.2.4 → pyddock-0.3.1}/src/pyddock/_process_utils.py +9 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/src/pyddock/_proxies.py +158 -19
- {pyddock-0.2.4 → pyddock-0.3.1}/src/pyddock/_subprocess_patch.py +111 -179
- {pyddock-0.2.4 → pyddock-0.3.1}/src/pyddock/ast_validator.py +79 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/src/pyddock/cli.py +19 -4
- {pyddock-0.2.4 → pyddock-0.3.1}/src/pyddock/config.py +143 -0
- pyddock-0.3.1/src/pyddock/default_config.toml +545 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/src/pyddock/executor.py +50 -5
- {pyddock-0.2.4 → pyddock-0.3.1}/src/pyddock/server.py +11 -3
- pyddock-0.3.1/src/pyddock/shell_executor.py +877 -0
- pyddock-0.3.1/tests/_config_helpers.py +53 -0
- pyddock-0.3.1/tests/test_attr_reflection_hardening.py +137 -0
- pyddock-0.3.1/tests/test_audit_hook_backstop.py +755 -0
- pyddock-0.3.1/tests/test_config.py +252 -0
- pyddock-0.3.1/tests/test_deny_always_wins.py +204 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/tests/test_deny_messages.py +13 -34
- pyddock-0.3.1/tests/test_env_policy.py +373 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/tests/test_executor.py +30 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/tests/test_file_tools.py +6 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/tests/test_filesystem_guards.py +2 -0
- pyddock-0.3.1/tests/test_jailbreak_regression.py +440 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/tests/test_runtime.py +78 -7
- pyddock-0.3.1/tests/test_sandbox_escape_hardening.py +455 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/tests/test_security_guards.py +308 -0
- pyddock-0.3.1/tests/test_trusted_prefixes_uv_cache.py +166 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/tests/test_workspace_imports.py +19 -31
- {pyddock-0.2.4 → pyddock-0.3.1}/uv.lock +1 -1
- pyddock-0.2.4/src/pyddock/_base.py +0 -45
- pyddock-0.2.4/src/pyddock/default_config.toml +0 -271
- pyddock-0.2.4/src/pyddock/shell_executor.py +0 -428
- pyddock-0.2.4/tests/test_config.py +0 -414
- {pyddock-0.2.4 → pyddock-0.3.1}/.gitignore +0 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/.hypothesis/.gitignore +0 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/.hypothesis/constants/106d94c8123c0256 +0 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/.hypothesis/constants/1685e03b3aa38c02 +0 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/.hypothesis/constants/1deca112ec6f2f3c +0 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/.hypothesis/constants/2488a3a95c48acfb +0 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/.hypothesis/constants/2a94d83a13979745 +0 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/.hypothesis/constants/499f1d5a639a382a +0 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/.hypothesis/constants/4ee6f24fa151b65d +0 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/.hypothesis/constants/5b1b2189b70f5ef2 +0 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/.hypothesis/constants/5d6f8b26b2137fe1 +0 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/.hypothesis/constants/61f9b905d7da14e0 +0 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/.hypothesis/constants/67a7f4ab2d372f23 +0 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/.hypothesis/constants/6c6f5083ece3f86b +0 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/.hypothesis/constants/827e18b40f235443 +0 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/.hypothesis/constants/8401e4039d635fbc +0 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/.hypothesis/constants/8490e7baefc8c8c3 +0 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/.hypothesis/constants/a7c132b836381d0d +0 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/.hypothesis/constants/b395547bc71e5c52 +0 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/.hypothesis/constants/ca50661510a40488 +0 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/.hypothesis/tmp/tmpl8oe65gb +0 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/.hypothesis/tmp/tmpqwper0dp +0 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/.hypothesis/unicode_data/15.1.0/charmap.json.gz +0 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/.hypothesis/unicode_data/15.1.0/codec-utf-8.json.gz +0 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/LICENSE +0 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/publish-to-pypi.ps1 +0 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/src/pyddock/__init__.py +0 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/src/pyddock/_import_hook.py +0 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/src/pyddock/_prewarm.py +0 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/src/pyddock/_runtime.py +0 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/src/pyddock/script_registry.py +0 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/src/pyddock/tools/__init__.py +0 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/src/pyddock/tools/fs_append.py +0 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/src/pyddock/tools/fs_delete.py +0 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/src/pyddock/tools/read_file.py +0 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/src/pyddock/tools/stat_file.py +0 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/src/pyddock/tools/str_replace.py +0 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/src/pyddock/venv_manager.py +0 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/tests/__init__.py +0 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/tests/test_ast_properties.py +0 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/tests/test_chmod_integration.py +0 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/tests/test_proxy_properties.py +0 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/tests/test_realistic.py +0 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/tests/test_server.py +0 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/tests/test_shell_arg_paths.py +0 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/tests/test_shell_executor.py +0 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/tests/test_shell_properties.py +0 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/tests/test_subprocess_enforcement.py +0 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/tests/test_subprocess_properties.py +0 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/tests/test_subst_trusted_path.py +0 -0
- {pyddock-0.2.4 → pyddock-0.3.1}/tests/test_venv_stamp.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: pyddock
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.3.1
|
|
4
4
|
Summary: MCP server that gives AI agents pre-approved Python, shell, and file I/O tools with declarative policy controls
|
|
5
5
|
Project-URL: Homepage, https://github.com/portablestew/pyddock
|
|
6
6
|
Project-URL: Repository, https://github.com/portablestew/pyddock
|
|
@@ -119,6 +119,7 @@ Pyddock also exposes file I/O tools that execute through the same sandbox as `ru
|
|
|
119
119
|
|
|
120
120
|
- **AST validation** (pre-execution) — rejects disallowed imports, blocked calls (`eval`, `exec`, `compile`), and blocked attribute access (`__globals__`, `__subclasses__`, etc.)
|
|
121
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
|
+
- **Audit-hook policy engine** (in-subprocess) — a `sys.addaudithook` that enforces the `[audit]` disposition table at the CPython audit-event layer, *beneath* the Python name bindings. This is the authoritative backstop for the name-based monkeypatches above: it catches operations that reach a real primitive through a live-object leak (e.g. `type(sys.stdout.buffer.raw)(...)` → the genuine `_io.FileIO`) or low-level `os.open`/`os.replace`. See [Audit policy](#audit-policy).
|
|
122
123
|
|
|
123
124
|
`run_shell` and subprocess enforcement:
|
|
124
125
|
|
|
@@ -129,9 +130,25 @@ Pyddock also exposes file I/O tools that execute through the same sandbox as `ru
|
|
|
129
130
|
- **Write protection** — path-like shell command regexes automatically generate write-deny rules for `run_python`, preventing write-then-execute privilege escalation
|
|
130
131
|
- **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
|
|
|
133
|
+
**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), `"read-only"` (writes not allowed), 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, while `.git/` is read-only.
|
|
134
|
+
|
|
132
135
|
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
136
|
|
|
134
|
-
|
|
137
|
+
## Audit policy
|
|
138
|
+
|
|
139
|
+
The `[audit]` section maps CPython audit events (see the [Audit events table](https://docs.python.org/3/library/audit_events.html)) to a **disposition**. It is enforced by a `sys.addaudithook` that fires beneath the Python name bindings, so it cannot be bypassed by re-deriving a real primitive from a live object. Each key is an audit event name; a key ending in `*` is a prefix match (e.g. `"ctypes.*"`). Dispositions:
|
|
140
|
+
|
|
141
|
+
- **`fs`** — `open()`: path-scoped read/write check (by mode/flags).
|
|
142
|
+
- **`fs-write`** — single-path mutation (`os.remove`, `os.mkdir`, …): check the target.
|
|
143
|
+
- **`fs-write-pair`** — two-path mutation (`os.rename`/`replace`, `os.link`, …): check both.
|
|
144
|
+
- **`agent-deny`** — deny when the caller is agent code; allow trusted libraries, stdlib, and import machinery. For primitives with no sanctioned agent use (`ctypes.*`, `marshal.loads`, `code.__new__`, `sys.settrace`, …). Defense-in-depth behind the import allowlist.
|
|
145
|
+
- **`network`** — network egress (`socket.connect`/`bind`/`sendto`, `urllib.Request`): same caller-scoped deny as `agent-deny` (agents have no socket path; trusted libraries are allowed).
|
|
146
|
+
- **`observe`** — log only under `serve --debug`; no enforcement.
|
|
147
|
+
- **`allow`** — explicit no-op (override a default to permit).
|
|
148
|
+
|
|
149
|
+
`[audit]` is the single source of truth — events not listed are ignored, and a config that omits the section entirely runs without the audit backstop. The five policy-bearing sections (`[execution]`, `[imports]`, `[filesystem]`, `[ast]`, `[audit]`) are **required**: pyddock halts at startup if any is absent (a present-but-empty section is a valid explicit opt-out).
|
|
150
|
+
|
|
151
|
+
**Debug logging:** `pyddock serve --debug` (or `pyddock run --debug`) records every observed event — filesystem, process, and network — as JSONL to `.pyddock/tmp/audit.jsonl`, with the allow/deny decision and a caller classification (`AGENT` / `TRUSTED` / `IMPORT`). Useful for auditing what agent code and dependencies actually do. Off by default with no overhead.
|
|
135
152
|
|
|
136
153
|
## Configuration
|
|
137
154
|
|
|
@@ -173,6 +190,14 @@ readable_paths = ["*"]
|
|
|
173
190
|
block_calls = ["eval", "exec", "compile", "breakpoint", "__import__"]
|
|
174
191
|
block_attributes = ["__subclasses__", "__globals__", "__code__", "__bases__", "__mro__", "__closure__"]
|
|
175
192
|
|
|
193
|
+
[audit] # audit event → disposition (see "Audit policy" below)
|
|
194
|
+
"open" = "fs"
|
|
195
|
+
"os.rename" = "fs-write-pair"
|
|
196
|
+
"ctypes.*" = "agent-deny"
|
|
197
|
+
"marshal.loads" = "agent-deny"
|
|
198
|
+
"socket.connect" = "network"
|
|
199
|
+
"subprocess.Popen" = "observe"
|
|
200
|
+
|
|
176
201
|
[restrictions.polars]
|
|
177
202
|
mode = "allow"
|
|
178
203
|
module_deny = ["write_.*", "sink_.*"]
|
|
@@ -274,6 +299,7 @@ When `subprocess` is enabled in `[imports]`, `run_python` code can call `subproc
|
|
|
274
299
|
|
|
275
300
|
```sh
|
|
276
301
|
pyddock serve --workspace /path/to/project # MCP server (stdio)
|
|
302
|
+
pyddock serve --workspace /path/to/project --debug # + JSONL audit trail to .pyddock/tmp/audit.jsonl
|
|
277
303
|
pyddock run "2 + 2" # Direct execution
|
|
278
304
|
pyddock run script.py -- arg1 arg2 # File execution with args
|
|
279
305
|
```
|
|
@@ -95,6 +95,7 @@ Pyddock also exposes file I/O tools that execute through the same sandbox as `ru
|
|
|
95
95
|
|
|
96
96
|
- **AST validation** (pre-execution) — rejects disallowed imports, blocked calls (`eval`, `exec`, `compile`), and blocked attribute access (`__globals__`, `__subclasses__`, etc.)
|
|
97
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
|
+
- **Audit-hook policy engine** (in-subprocess) — a `sys.addaudithook` that enforces the `[audit]` disposition table at the CPython audit-event layer, *beneath* the Python name bindings. This is the authoritative backstop for the name-based monkeypatches above: it catches operations that reach a real primitive through a live-object leak (e.g. `type(sys.stdout.buffer.raw)(...)` → the genuine `_io.FileIO`) or low-level `os.open`/`os.replace`. See [Audit policy](#audit-policy).
|
|
98
99
|
|
|
99
100
|
`run_shell` and subprocess enforcement:
|
|
100
101
|
|
|
@@ -105,9 +106,25 @@ Pyddock also exposes file I/O tools that execute through the same sandbox as `ru
|
|
|
105
106
|
- **Write protection** — path-like shell command regexes automatically generate write-deny rules for `run_python`, preventing write-then-execute privilege escalation
|
|
106
107
|
- **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
|
|
|
109
|
+
**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), `"read-only"` (writes not allowed), 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, while `.git/` is read-only.
|
|
110
|
+
|
|
108
111
|
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
112
|
|
|
110
|
-
|
|
113
|
+
## Audit policy
|
|
114
|
+
|
|
115
|
+
The `[audit]` section maps CPython audit events (see the [Audit events table](https://docs.python.org/3/library/audit_events.html)) to a **disposition**. It is enforced by a `sys.addaudithook` that fires beneath the Python name bindings, so it cannot be bypassed by re-deriving a real primitive from a live object. Each key is an audit event name; a key ending in `*` is a prefix match (e.g. `"ctypes.*"`). Dispositions:
|
|
116
|
+
|
|
117
|
+
- **`fs`** — `open()`: path-scoped read/write check (by mode/flags).
|
|
118
|
+
- **`fs-write`** — single-path mutation (`os.remove`, `os.mkdir`, …): check the target.
|
|
119
|
+
- **`fs-write-pair`** — two-path mutation (`os.rename`/`replace`, `os.link`, …): check both.
|
|
120
|
+
- **`agent-deny`** — deny when the caller is agent code; allow trusted libraries, stdlib, and import machinery. For primitives with no sanctioned agent use (`ctypes.*`, `marshal.loads`, `code.__new__`, `sys.settrace`, …). Defense-in-depth behind the import allowlist.
|
|
121
|
+
- **`network`** — network egress (`socket.connect`/`bind`/`sendto`, `urllib.Request`): same caller-scoped deny as `agent-deny` (agents have no socket path; trusted libraries are allowed).
|
|
122
|
+
- **`observe`** — log only under `serve --debug`; no enforcement.
|
|
123
|
+
- **`allow`** — explicit no-op (override a default to permit).
|
|
124
|
+
|
|
125
|
+
`[audit]` is the single source of truth — events not listed are ignored, and a config that omits the section entirely runs without the audit backstop. The five policy-bearing sections (`[execution]`, `[imports]`, `[filesystem]`, `[ast]`, `[audit]`) are **required**: pyddock halts at startup if any is absent (a present-but-empty section is a valid explicit opt-out).
|
|
126
|
+
|
|
127
|
+
**Debug logging:** `pyddock serve --debug` (or `pyddock run --debug`) records every observed event — filesystem, process, and network — as JSONL to `.pyddock/tmp/audit.jsonl`, with the allow/deny decision and a caller classification (`AGENT` / `TRUSTED` / `IMPORT`). Useful for auditing what agent code and dependencies actually do. Off by default with no overhead.
|
|
111
128
|
|
|
112
129
|
## Configuration
|
|
113
130
|
|
|
@@ -149,6 +166,14 @@ readable_paths = ["*"]
|
|
|
149
166
|
block_calls = ["eval", "exec", "compile", "breakpoint", "__import__"]
|
|
150
167
|
block_attributes = ["__subclasses__", "__globals__", "__code__", "__bases__", "__mro__", "__closure__"]
|
|
151
168
|
|
|
169
|
+
[audit] # audit event → disposition (see "Audit policy" below)
|
|
170
|
+
"open" = "fs"
|
|
171
|
+
"os.rename" = "fs-write-pair"
|
|
172
|
+
"ctypes.*" = "agent-deny"
|
|
173
|
+
"marshal.loads" = "agent-deny"
|
|
174
|
+
"socket.connect" = "network"
|
|
175
|
+
"subprocess.Popen" = "observe"
|
|
176
|
+
|
|
152
177
|
[restrictions.polars]
|
|
153
178
|
mode = "allow"
|
|
154
179
|
module_deny = ["write_.*", "sink_.*"]
|
|
@@ -250,6 +275,7 @@ When `subprocess` is enabled in `[imports]`, `run_python` code can call `subproc
|
|
|
250
275
|
|
|
251
276
|
```sh
|
|
252
277
|
pyddock serve --workspace /path/to/project # MCP server (stdio)
|
|
278
|
+
pyddock serve --workspace /path/to/project --debug # + JSONL audit trail to .pyddock/tmp/audit.jsonl
|
|
253
279
|
pyddock run "2 + 2" # Direct execution
|
|
254
280
|
pyddock run script.py -- arg1 arg2 # File execution with args
|
|
255
281
|
```
|