pyddock 0.2.4__tar.gz → 0.3.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.
Files changed (87) hide show
  1. {pyddock-0.2.4 → pyddock-0.3.0}/PKG-INFO +28 -2
  2. {pyddock-0.2.4 → pyddock-0.3.0}/README.md +27 -1
  3. {pyddock-0.2.4 → pyddock-0.3.0}/pyproject.toml +1 -1
  4. pyddock-0.3.0/src/pyddock/_audit_enforcement.py +597 -0
  5. pyddock-0.3.0/src/pyddock/_base.py +133 -0
  6. {pyddock-0.2.4 → pyddock-0.3.0}/src/pyddock/_enforcement.py +94 -13
  7. {pyddock-0.2.4 → pyddock-0.3.0}/src/pyddock/_fs_enforcement.py +78 -5
  8. {pyddock-0.2.4 → pyddock-0.3.0}/src/pyddock/_process_utils.py +9 -0
  9. {pyddock-0.2.4 → pyddock-0.3.0}/src/pyddock/_proxies.py +59 -13
  10. {pyddock-0.2.4 → pyddock-0.3.0}/src/pyddock/_subprocess_patch.py +94 -180
  11. {pyddock-0.2.4 → pyddock-0.3.0}/src/pyddock/ast_validator.py +79 -0
  12. {pyddock-0.2.4 → pyddock-0.3.0}/src/pyddock/cli.py +19 -4
  13. {pyddock-0.2.4 → pyddock-0.3.0}/src/pyddock/config.py +143 -0
  14. pyddock-0.3.0/src/pyddock/default_config.toml +503 -0
  15. {pyddock-0.2.4 → pyddock-0.3.0}/src/pyddock/executor.py +40 -4
  16. {pyddock-0.2.4 → pyddock-0.3.0}/src/pyddock/server.py +11 -3
  17. pyddock-0.3.0/src/pyddock/shell_executor.py +838 -0
  18. pyddock-0.3.0/tests/_config_helpers.py +53 -0
  19. pyddock-0.3.0/tests/test_attr_reflection_hardening.py +137 -0
  20. pyddock-0.3.0/tests/test_audit_hook_backstop.py +755 -0
  21. pyddock-0.3.0/tests/test_config.py +252 -0
  22. pyddock-0.3.0/tests/test_deny_always_wins.py +204 -0
  23. {pyddock-0.2.4 → pyddock-0.3.0}/tests/test_deny_messages.py +13 -34
  24. pyddock-0.3.0/tests/test_env_policy.py +321 -0
  25. {pyddock-0.2.4 → pyddock-0.3.0}/tests/test_file_tools.py +6 -0
  26. {pyddock-0.2.4 → pyddock-0.3.0}/tests/test_filesystem_guards.py +2 -0
  27. {pyddock-0.2.4 → pyddock-0.3.0}/tests/test_runtime.py +78 -7
  28. pyddock-0.3.0/tests/test_sandbox_escape_hardening.py +455 -0
  29. {pyddock-0.2.4 → pyddock-0.3.0}/tests/test_security_guards.py +230 -0
  30. {pyddock-0.2.4 → pyddock-0.3.0}/tests/test_workspace_imports.py +19 -31
  31. {pyddock-0.2.4 → pyddock-0.3.0}/uv.lock +1 -1
  32. pyddock-0.2.4/src/pyddock/_base.py +0 -45
  33. pyddock-0.2.4/src/pyddock/default_config.toml +0 -271
  34. pyddock-0.2.4/src/pyddock/shell_executor.py +0 -428
  35. pyddock-0.2.4/tests/test_config.py +0 -414
  36. {pyddock-0.2.4 → pyddock-0.3.0}/.gitignore +0 -0
  37. {pyddock-0.2.4 → pyddock-0.3.0}/.hypothesis/.gitignore +0 -0
  38. {pyddock-0.2.4 → pyddock-0.3.0}/.hypothesis/constants/106d94c8123c0256 +0 -0
  39. {pyddock-0.2.4 → pyddock-0.3.0}/.hypothesis/constants/1685e03b3aa38c02 +0 -0
  40. {pyddock-0.2.4 → pyddock-0.3.0}/.hypothesis/constants/1deca112ec6f2f3c +0 -0
  41. {pyddock-0.2.4 → pyddock-0.3.0}/.hypothesis/constants/2488a3a95c48acfb +0 -0
  42. {pyddock-0.2.4 → pyddock-0.3.0}/.hypothesis/constants/2a94d83a13979745 +0 -0
  43. {pyddock-0.2.4 → pyddock-0.3.0}/.hypothesis/constants/499f1d5a639a382a +0 -0
  44. {pyddock-0.2.4 → pyddock-0.3.0}/.hypothesis/constants/4ee6f24fa151b65d +0 -0
  45. {pyddock-0.2.4 → pyddock-0.3.0}/.hypothesis/constants/5b1b2189b70f5ef2 +0 -0
  46. {pyddock-0.2.4 → pyddock-0.3.0}/.hypothesis/constants/5d6f8b26b2137fe1 +0 -0
  47. {pyddock-0.2.4 → pyddock-0.3.0}/.hypothesis/constants/61f9b905d7da14e0 +0 -0
  48. {pyddock-0.2.4 → pyddock-0.3.0}/.hypothesis/constants/67a7f4ab2d372f23 +0 -0
  49. {pyddock-0.2.4 → pyddock-0.3.0}/.hypothesis/constants/6c6f5083ece3f86b +0 -0
  50. {pyddock-0.2.4 → pyddock-0.3.0}/.hypothesis/constants/827e18b40f235443 +0 -0
  51. {pyddock-0.2.4 → pyddock-0.3.0}/.hypothesis/constants/8401e4039d635fbc +0 -0
  52. {pyddock-0.2.4 → pyddock-0.3.0}/.hypothesis/constants/8490e7baefc8c8c3 +0 -0
  53. {pyddock-0.2.4 → pyddock-0.3.0}/.hypothesis/constants/a7c132b836381d0d +0 -0
  54. {pyddock-0.2.4 → pyddock-0.3.0}/.hypothesis/constants/b395547bc71e5c52 +0 -0
  55. {pyddock-0.2.4 → pyddock-0.3.0}/.hypothesis/constants/ca50661510a40488 +0 -0
  56. {pyddock-0.2.4 → pyddock-0.3.0}/.hypothesis/tmp/tmpl8oe65gb +0 -0
  57. {pyddock-0.2.4 → pyddock-0.3.0}/.hypothesis/tmp/tmpqwper0dp +0 -0
  58. {pyddock-0.2.4 → pyddock-0.3.0}/.hypothesis/unicode_data/15.1.0/charmap.json.gz +0 -0
  59. {pyddock-0.2.4 → pyddock-0.3.0}/.hypothesis/unicode_data/15.1.0/codec-utf-8.json.gz +0 -0
  60. {pyddock-0.2.4 → pyddock-0.3.0}/LICENSE +0 -0
  61. {pyddock-0.2.4 → pyddock-0.3.0}/publish-to-pypi.ps1 +0 -0
  62. {pyddock-0.2.4 → pyddock-0.3.0}/src/pyddock/__init__.py +0 -0
  63. {pyddock-0.2.4 → pyddock-0.3.0}/src/pyddock/_import_hook.py +0 -0
  64. {pyddock-0.2.4 → pyddock-0.3.0}/src/pyddock/_prewarm.py +0 -0
  65. {pyddock-0.2.4 → pyddock-0.3.0}/src/pyddock/_runtime.py +0 -0
  66. {pyddock-0.2.4 → pyddock-0.3.0}/src/pyddock/script_registry.py +0 -0
  67. {pyddock-0.2.4 → pyddock-0.3.0}/src/pyddock/tools/__init__.py +0 -0
  68. {pyddock-0.2.4 → pyddock-0.3.0}/src/pyddock/tools/fs_append.py +0 -0
  69. {pyddock-0.2.4 → pyddock-0.3.0}/src/pyddock/tools/fs_delete.py +0 -0
  70. {pyddock-0.2.4 → pyddock-0.3.0}/src/pyddock/tools/read_file.py +0 -0
  71. {pyddock-0.2.4 → pyddock-0.3.0}/src/pyddock/tools/stat_file.py +0 -0
  72. {pyddock-0.2.4 → pyddock-0.3.0}/src/pyddock/tools/str_replace.py +0 -0
  73. {pyddock-0.2.4 → pyddock-0.3.0}/src/pyddock/venv_manager.py +0 -0
  74. {pyddock-0.2.4 → pyddock-0.3.0}/tests/__init__.py +0 -0
  75. {pyddock-0.2.4 → pyddock-0.3.0}/tests/test_ast_properties.py +0 -0
  76. {pyddock-0.2.4 → pyddock-0.3.0}/tests/test_chmod_integration.py +0 -0
  77. {pyddock-0.2.4 → pyddock-0.3.0}/tests/test_executor.py +0 -0
  78. {pyddock-0.2.4 → pyddock-0.3.0}/tests/test_proxy_properties.py +0 -0
  79. {pyddock-0.2.4 → pyddock-0.3.0}/tests/test_realistic.py +0 -0
  80. {pyddock-0.2.4 → pyddock-0.3.0}/tests/test_server.py +0 -0
  81. {pyddock-0.2.4 → pyddock-0.3.0}/tests/test_shell_arg_paths.py +0 -0
  82. {pyddock-0.2.4 → pyddock-0.3.0}/tests/test_shell_executor.py +0 -0
  83. {pyddock-0.2.4 → pyddock-0.3.0}/tests/test_shell_properties.py +0 -0
  84. {pyddock-0.2.4 → pyddock-0.3.0}/tests/test_subprocess_enforcement.py +0 -0
  85. {pyddock-0.2.4 → pyddock-0.3.0}/tests/test_subprocess_properties.py +0 -0
  86. {pyddock-0.2.4 → pyddock-0.3.0}/tests/test_subst_trusted_path.py +0 -0
  87. {pyddock-0.2.4 → pyddock-0.3.0}/tests/test_venv_stamp.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: pyddock
3
- Version: 0.2.4
3
+ Version: 0.3.0
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
- **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.
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
- **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.
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
  ```
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "pyddock"
3
- version = "0.2.4"
3
+ version = "0.3.0"
4
4
  description = "MCP server that gives AI agents pre-approved Python, shell, and file I/O tools with declarative policy controls"
5
5
  requires-python = ">=3.11"
6
6
  license = "MIT"