fastaudit 0.1.0__tar.gz

fastaudit-0.1.0/CHANGELOG.md

@@ -0,0 +1,12 @@
+<!-- do not remove -->
+
+## 0.1.0
+
+### New Features
+
+- Defer audit hook installation until first `mk_audit`() call ([#6](https://github.com/AnswerDotAI/fastaudit/issues/6))
+- More fully exclude Python-level callables from native-call monitoring ([#4](https://github.com/AnswerDotAI/fastaudit/issues/4))
+- Install audit hook once at import; move per-policy params into ContextVar-scoped config ([#3](https://github.com/AnswerDotAI/fastaudit/issues/3))
+- Support dynamic '.' in allowed roots and audit os.chdir against destination ([#2](https://github.com/AnswerDotAI/fastaudit/issues/2))
+- `monitor_calls`=True ([#1](https://github.com/AnswerDotAI/fastaudit/issues/1))
+

fastaudit-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

fastaudit-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include README.md
+include LICENSE
+include CHANGELOG.md

fastaudit-0.1.0/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: fastaudit
+Version: 0.1.0
+Summary: A lightweight execution guard for running LLM-generated Python in a normal Python process.
+Author: Answer.AI
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/AnswerDotAI/fastaudit
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastcore
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: orjson; extra == "dev"
+Requires-Dist: numpy; extra == "dev"
+Requires-Dist: fastship; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# fastaudit
+
+`fastaudit` is a lightweight execution guard for running LLM-generated Python in a normal Python process.
+
+It is not intended to be a hardened adversarial sandbox. Its purpose is to stop accidental damage from overly broad file operations, unexpected subprocess calls, and tool use that reaches outside approved working directories.
+
+The core mechanism is Python's audit hook system. The first `mk_audit()` call installs one process-wide audit hook. On Python 3.12 and newer, `sys.monitoring` is also used to raise audit events for non-stdlib native calls. `mk_audit()` creates an audit context, then enables permission checks only while that execution context is active.
+
+`fastaudit` requires Python 3.10 or newer. Native call monitoring requires Python 3.12 or newer and is enabled by default. Pass `monitor_calls=False` to use audit-hook-only mode on Python 3.10/3.11 or to avoid monitoring overhead.
+
+## Why this exists
+
+LLM-generated code is usually helpful, but sometimes too determined. If a command fails, an assistant may try another route; if a path is wrong, it may broaden the search; if a tool exists, it may use it without fully understanding its side effects.
+
+`fastaudit` is designed for that case.
+
+It helps with:
+
+- blocking subprocess and process-escape operations unless explicitly allowed
+- allowing writes only under approved roots
+- allowing broad read access where appropriate
+- making permission failures clear and immediate
+- letting host policy callbacks allow trusted tools while ordinary generated code stays checked
+- avoiding global audit state leaks across async tasks
+
+It deliberately does not try to defeat malicious code running in the same interpreter.
+
+## Audit hook categorization
+
+The audit hook is designed as a lightweight guardrail for LLM/tool-generated code, not as a hardened security sandbox against malicious code. The goal is to prevent accidental or over-broad filesystem mutation outside approved working directories: e.g. deleting files in the wrong project, writing into a user’s home directory, or spawning subprocesses unexpectedly. It assumes the surrounding process, user account, and pre-existing filesystem layout are trusted, and that the code being checked is not actively trying to exploit races, pre-planted symlinks, or CPython internals.
+
+The design keeps the common path simple and cheap. Dangerous process-escape events such as subprocess execution are denied outright. Filesystem write/delete events are allowed only when the relevant parent directory is inside a precomputed allowlist, since most mutations are really changes to directory entries. For destination-only operations such as copy, only the destination parent matters; for move/rename/link-style operations, both paths are checked because both filesystem locations may be affected. Read-only operations are generally ignored, and file-descriptor-based truncation is allowed on the assumption that the path policy was enforced when the descriptor was opened. This gives practical protection against accidental damage while avoiding the complexity and cost of pretending to be a fully adversarial sandbox.
+
+Symlinks are treated as part of the trusted filesystem setup. The hook’s path checks focus on the parent directories of mutations, which is the right model for operations that create, remove, or rename directory entries. This means an existing symlink inside an allowed directory may still point outside the allowed roots; that is acceptable under this threat model because the user controls the workspace layout and is assumed not to pre-place hostile links. To avoid making that assumption worse, symlink and hard-link creation should be restricted: the new link’s parent must be allowed, and the link target should either be denied or required to resolve inside an allowed root.
+
+## Threat model
+
+`fastaudit` assumes:
+
+- the user, workspace, and pre-existing filesystem layout are trusted
+- code is LLM-generated or LLM-directed, not actively hostile
+- accidental overreach is the main risk
+- rich user tools may need access that ordinary generated code should not have
+- Solveit or the host application controls the execution wrapper
+
+It does not assume:
+
+- Python introspection is unavailable
+- frames, closures, or modules are impossible to inspect
+- same-process execution can provide a hard security boundary
+- OS-level sandboxing is unnecessary for adversarial workloads
+
+For adversarial code, use a subprocess, container, VM, or OS-level policy.
+
+## Audit scope
+
+Auditing is opt-in per logical task. The audit hook is registered globally when the first audit context is created, and the optional call monitor is registered globally when needed, but permission checks only run while `audit_perms()` is active. This matters for async code. A global boolean or counter would leak audit state between unrelated coroutines whenever one audited task awaits. A `ContextVar` gives logical scoping: child tasks inherit at creation time, nested contexts restore cleanly via tokens, and the guard follows execution flow rather than scheduler order. Threads are denied in the audit sandbox since context variables otherwise are not maintained.
+
+The hook is built once inside a closure rather than read from module globals on every event. Allowed roots and callbacks live in the active context config, the event-classification sets are converted to `frozenset`, and the helpers used in the hot path — `realpath`, `dirname`, `fsdecode`, `os.sep` — are captured as local names. Nothing the hook depends on lives in a mutable global that a generated cell could clear, replace, or reassign. This is not a security barrier against introspection or frame walking; it is a deliberate effort to remove the easy, accidental disabling paths that an enthusiastic LLM is most likely to take when retrying after a `PermissionError`.
+
+## Permission model
+
+The policy classifies audit events into a few groups:
+
+- events denied outright
+- events where the first path argument is checked
+- events where the destination path is checked
+- events where both source and destination paths are checked
+- special cases such as `open`, `os.truncate`, and sensitive `object.__setattr__`
+
+Writes and filesystem mutations are allowed only when the relevant parent directory is inside an approved root.
+
+Reads are generally allowed.
+
+Subprocess creation and similar process escapes are denied by default.
+
+The allowed root `'.'` is dynamic: it means the current directory at the time of each checked operation. This lets a sandbox follow allowed `chdir` calls into child directories. `os.chdir` itself is checked against the destination directory, not the destination's parent.
+
+Non-stdlib native calls raise a `fastaudit.call` audit event while `audit_perms()` is active when `monitor_calls=True`. Python calls and stdlib calls are ignored by the call monitor. The context manager calls `sys.monitoring.restart_events()` on entry so monitored call sites disabled before the context are seen again inside it. With `monitor_calls=False`, only normal Python audit-hook events are checked.
+
+### get/set attr hooks
+
+The `object.__setattr__` audit event fires only for a small fixed set of "sensitive" attribute assignments, not for general attribute setting. On types/classes, it fires when setting `__name__`, `__qualname__`, `__module__`, `__bases__`, `__doc__`, or `__type_params__` — these go through `check_set_special_type_attr` in `Objects/typeobject.c`. The `__class__` reassignment on any object is also audited, via `object_set_class` in the same file. On function objects, assignments to `__code__`, `__defaults__`, and `__kwdefaults__` are audited, via the relevant setters in `Objects/funcobject.c`.
+
+All other attribute assignments — including ordinary `C.x = 1` on a class, instance attribute assignment, and even some dunders like `__abstractmethods__` and `__annotations__` (which write directly via `PyDict_SetItem`) — bypass the audit hook entirely. This is why `@dataclass` triggers an event (it sets `cls.__doc__`) and `namedtuple` triggers one (it sets `cls.__module__`), while `class C: pass; C.x = 1; C.foo = lambda self: None` is silent. The authoritative list lives in the CPython source at [`Objects/typeobject.c`](https://github.com/python/cpython/blob/v3.12.0/Objects/typeobject.c) and [`Objects/funcobject.c`](https://github.com/python/cpython/blob/v3.12.0/Objects/funcobject.c); the public docs only describe the event as firing for "certain sensitive attribute assignments" without enumerating them.
+
+## Host policy
+
+Some user-provided tools need permissions that ordinary generated code should not have. For instance, a search tool may need to call `rg`, or a helper may need to spawn a tightly controlled subprocess.
+
+`fastaudit` does not define that policy itself. Host code can pass `before_deny`, which is called after `fastaudit` decides an operation should be blocked and before `PermissionError` is raised:
+
+```python
+before_deny(event, args, frame, msg, data)
+```
+
+The callback receives the event name, audit arguments, the first non-`fastaudit` stack frame, the error message, and the current host data. Returning a truthy value allows the operation. Returning a falsey value denies it. Exceptions from the callback propagate.
+
+For non-stdlib native calls, host code can also pass `on_call`, which runs before `fastaudit.call` is raised. `on_call` requires `monitor_calls=True`:
+
+```python
+on_call(caller, callee, fn, code, off, data)
+```
+
+It receives the caller, callee, function object, code object, bytecode offset, and current host data. It can return `False` to suppress the audit event for that call, or `sys.monitoring.DISABLE` to disable that monitored call site. Exceptions from the callback propagate.
+
+The optional `data` argument is stored in the audit context config and passed to both callbacks. A host can build mutable policy state outside the sandbox, pass a frozen snapshot to `mk_audit`, and later update that snapshot with `audit_perms.set_data(...)`. Creating or entering a new audit context, or calling `set_data`, raises an internal audit event and is denied while `audit_perms()` is active.
+
+`mk_audit()` uses `sys.monitoring` tool id `3` by default when call monitoring is enabled. Pass `tool_id=...` if the host already uses that id.
+
+## API sketch
+
+```python
+audit_perms = mk_audit(['/tmp', os.getcwd()], before_deny=allow_trusted_tool, data=frozenset(allowed))
+
+with audit_perms():
+    exec(code, restricted_globals)
+
+audit_perms.set_data(frozenset(new_allowed))
+
+audit_perms = mk_audit(['/tmp'], monitor_calls=False)  # audit hooks only
+```
+
+## Implementation notes
+
+The hook should avoid relying on mutable globals during enforcement.
+
+At construction time, bind or freeze:
+
+- approved roots
+- audit event sets
+- write flags
+- path helpers such as `realpath`, `dirname`, and `fsdecode`
+- frame lookup helper
+- call-monitor helpers and callbacks
+
+This prevents the most likely accidental disabling paths, such as clearing a global deny set or replacing a helper function. The implementation still does not claim to be secure against deliberate frame walking or introspection.
+
+## Limitations
+
+`fastaudit` does not provide a hard security boundary.
+
+Known limitations:
+
+- same-process Python code can inspect a lot of runtime state
+- pre-existing writable file descriptors may bypass path-open checks
+- host callbacks can do anything their implementation permits
+- thread support is intentionally restricted unless explicitly designed for
+- The `CALL` event in `sys.monitoring` does not fire for operators invoked via dedicated bytecode opcodes — `BINARY_OP` (`a + b`), `BINARY_SUBSCR` (`a[i]`), comparisons, etc. These dispatch directly to the C-level numeric/subscript/compare slots, which aren't "calls" in PEP 669's model. Explicit dunder invocations (`a.__add__(b)`) do fire CALL normally.
+
+These limitations are acceptable for a guardrail system aimed at LLM-directed execution. They are not acceptable for hostile code.
+
+## Design principle
+
+The goal is not to make escape impossible. The goal is to make the safe path easy, the risky path explicit, and accidental overreach fail early with a useful error.
+
+## Release
+
+1) Ensure your GitHub issues are labeled (`bug`, `enhancement`, `breaking`).
+2) Run:
+
+```bash
+ship-gh
+ship-pypi
+ship-bump
+```

fastaudit-0.1.0/README.md

@@ -0,0 +1,166 @@
+# fastaudit
+
+`fastaudit` is a lightweight execution guard for running LLM-generated Python in a normal Python process.
+
+It is not intended to be a hardened adversarial sandbox. Its purpose is to stop accidental damage from overly broad file operations, unexpected subprocess calls, and tool use that reaches outside approved working directories.
+
+The core mechanism is Python's audit hook system. The first `mk_audit()` call installs one process-wide audit hook. On Python 3.12 and newer, `sys.monitoring` is also used to raise audit events for non-stdlib native calls. `mk_audit()` creates an audit context, then enables permission checks only while that execution context is active.
+
+`fastaudit` requires Python 3.10 or newer. Native call monitoring requires Python 3.12 or newer and is enabled by default. Pass `monitor_calls=False` to use audit-hook-only mode on Python 3.10/3.11 or to avoid monitoring overhead.
+
+## Why this exists
+
+LLM-generated code is usually helpful, but sometimes too determined. If a command fails, an assistant may try another route; if a path is wrong, it may broaden the search; if a tool exists, it may use it without fully understanding its side effects.
+
+`fastaudit` is designed for that case.
+
+It helps with:
+
+- blocking subprocess and process-escape operations unless explicitly allowed
+- allowing writes only under approved roots
+- allowing broad read access where appropriate
+- making permission failures clear and immediate
+- letting host policy callbacks allow trusted tools while ordinary generated code stays checked
+- avoiding global audit state leaks across async tasks
+
+It deliberately does not try to defeat malicious code running in the same interpreter.
+
+## Audit hook categorization
+
+The audit hook is designed as a lightweight guardrail for LLM/tool-generated code, not as a hardened security sandbox against malicious code. The goal is to prevent accidental or over-broad filesystem mutation outside approved working directories: e.g. deleting files in the wrong project, writing into a user’s home directory, or spawning subprocesses unexpectedly. It assumes the surrounding process, user account, and pre-existing filesystem layout are trusted, and that the code being checked is not actively trying to exploit races, pre-planted symlinks, or CPython internals.
+
+The design keeps the common path simple and cheap. Dangerous process-escape events such as subprocess execution are denied outright. Filesystem write/delete events are allowed only when the relevant parent directory is inside a precomputed allowlist, since most mutations are really changes to directory entries. For destination-only operations such as copy, only the destination parent matters; for move/rename/link-style operations, both paths are checked because both filesystem locations may be affected. Read-only operations are generally ignored, and file-descriptor-based truncation is allowed on the assumption that the path policy was enforced when the descriptor was opened. This gives practical protection against accidental damage while avoiding the complexity and cost of pretending to be a fully adversarial sandbox.
+
+Symlinks are treated as part of the trusted filesystem setup. The hook’s path checks focus on the parent directories of mutations, which is the right model for operations that create, remove, or rename directory entries. This means an existing symlink inside an allowed directory may still point outside the allowed roots; that is acceptable under this threat model because the user controls the workspace layout and is assumed not to pre-place hostile links. To avoid making that assumption worse, symlink and hard-link creation should be restricted: the new link’s parent must be allowed, and the link target should either be denied or required to resolve inside an allowed root.
+
+## Threat model
+
+`fastaudit` assumes:
+
+- the user, workspace, and pre-existing filesystem layout are trusted
+- code is LLM-generated or LLM-directed, not actively hostile
+- accidental overreach is the main risk
+- rich user tools may need access that ordinary generated code should not have
+- Solveit or the host application controls the execution wrapper
+
+It does not assume:
+
+- Python introspection is unavailable
+- frames, closures, or modules are impossible to inspect
+- same-process execution can provide a hard security boundary
+- OS-level sandboxing is unnecessary for adversarial workloads
+
+For adversarial code, use a subprocess, container, VM, or OS-level policy.
+
+## Audit scope
+
+Auditing is opt-in per logical task. The audit hook is registered globally when the first audit context is created, and the optional call monitor is registered globally when needed, but permission checks only run while `audit_perms()` is active. This matters for async code. A global boolean or counter would leak audit state between unrelated coroutines whenever one audited task awaits. A `ContextVar` gives logical scoping: child tasks inherit at creation time, nested contexts restore cleanly via tokens, and the guard follows execution flow rather than scheduler order. Threads are denied in the audit sandbox since context variables otherwise are not maintained.
+
+The hook is built once inside a closure rather than read from module globals on every event. Allowed roots and callbacks live in the active context config, the event-classification sets are converted to `frozenset`, and the helpers used in the hot path — `realpath`, `dirname`, `fsdecode`, `os.sep` — are captured as local names. Nothing the hook depends on lives in a mutable global that a generated cell could clear, replace, or reassign. This is not a security barrier against introspection or frame walking; it is a deliberate effort to remove the easy, accidental disabling paths that an enthusiastic LLM is most likely to take when retrying after a `PermissionError`.
+
+## Permission model
+
+The policy classifies audit events into a few groups:
+
+- events denied outright
+- events where the first path argument is checked
+- events where the destination path is checked
+- events where both source and destination paths are checked
+- special cases such as `open`, `os.truncate`, and sensitive `object.__setattr__`
+
+Writes and filesystem mutations are allowed only when the relevant parent directory is inside an approved root.
+
+Reads are generally allowed.
+
+Subprocess creation and similar process escapes are denied by default.
+
+The allowed root `'.'` is dynamic: it means the current directory at the time of each checked operation. This lets a sandbox follow allowed `chdir` calls into child directories. `os.chdir` itself is checked against the destination directory, not the destination's parent.
+
+Non-stdlib native calls raise a `fastaudit.call` audit event while `audit_perms()` is active when `monitor_calls=True`. Python calls and stdlib calls are ignored by the call monitor. The context manager calls `sys.monitoring.restart_events()` on entry so monitored call sites disabled before the context are seen again inside it. With `monitor_calls=False`, only normal Python audit-hook events are checked.
+
+### get/set attr hooks
+
+The `object.__setattr__` audit event fires only for a small fixed set of "sensitive" attribute assignments, not for general attribute setting. On types/classes, it fires when setting `__name__`, `__qualname__`, `__module__`, `__bases__`, `__doc__`, or `__type_params__` — these go through `check_set_special_type_attr` in `Objects/typeobject.c`. The `__class__` reassignment on any object is also audited, via `object_set_class` in the same file. On function objects, assignments to `__code__`, `__defaults__`, and `__kwdefaults__` are audited, via the relevant setters in `Objects/funcobject.c`.
+
+All other attribute assignments — including ordinary `C.x = 1` on a class, instance attribute assignment, and even some dunders like `__abstractmethods__` and `__annotations__` (which write directly via `PyDict_SetItem`) — bypass the audit hook entirely. This is why `@dataclass` triggers an event (it sets `cls.__doc__`) and `namedtuple` triggers one (it sets `cls.__module__`), while `class C: pass; C.x = 1; C.foo = lambda self: None` is silent. The authoritative list lives in the CPython source at [`Objects/typeobject.c`](https://github.com/python/cpython/blob/v3.12.0/Objects/typeobject.c) and [`Objects/funcobject.c`](https://github.com/python/cpython/blob/v3.12.0/Objects/funcobject.c); the public docs only describe the event as firing for "certain sensitive attribute assignments" without enumerating them.
+
+## Host policy
+
+Some user-provided tools need permissions that ordinary generated code should not have. For instance, a search tool may need to call `rg`, or a helper may need to spawn a tightly controlled subprocess.
+
+`fastaudit` does not define that policy itself. Host code can pass `before_deny`, which is called after `fastaudit` decides an operation should be blocked and before `PermissionError` is raised:
+
+```python
+before_deny(event, args, frame, msg, data)
+```
+
+The callback receives the event name, audit arguments, the first non-`fastaudit` stack frame, the error message, and the current host data. Returning a truthy value allows the operation. Returning a falsey value denies it. Exceptions from the callback propagate.
+
+For non-stdlib native calls, host code can also pass `on_call`, which runs before `fastaudit.call` is raised. `on_call` requires `monitor_calls=True`:
+
+```python
+on_call(caller, callee, fn, code, off, data)
+```
+
+It receives the caller, callee, function object, code object, bytecode offset, and current host data. It can return `False` to suppress the audit event for that call, or `sys.monitoring.DISABLE` to disable that monitored call site. Exceptions from the callback propagate.
+
+The optional `data` argument is stored in the audit context config and passed to both callbacks. A host can build mutable policy state outside the sandbox, pass a frozen snapshot to `mk_audit`, and later update that snapshot with `audit_perms.set_data(...)`. Creating or entering a new audit context, or calling `set_data`, raises an internal audit event and is denied while `audit_perms()` is active.
+
+`mk_audit()` uses `sys.monitoring` tool id `3` by default when call monitoring is enabled. Pass `tool_id=...` if the host already uses that id.
+
+## API sketch
+
+```python
+audit_perms = mk_audit(['/tmp', os.getcwd()], before_deny=allow_trusted_tool, data=frozenset(allowed))
+
+with audit_perms():
+    exec(code, restricted_globals)
+
+audit_perms.set_data(frozenset(new_allowed))
+
+audit_perms = mk_audit(['/tmp'], monitor_calls=False)  # audit hooks only
+```
+
+## Implementation notes
+
+The hook should avoid relying on mutable globals during enforcement.
+
+At construction time, bind or freeze:
+
+- approved roots
+- audit event sets
+- write flags
+- path helpers such as `realpath`, `dirname`, and `fsdecode`
+- frame lookup helper
+- call-monitor helpers and callbacks
+
+This prevents the most likely accidental disabling paths, such as clearing a global deny set or replacing a helper function. The implementation still does not claim to be secure against deliberate frame walking or introspection.
+
+## Limitations
+
+`fastaudit` does not provide a hard security boundary.
+
+Known limitations:
+
+- same-process Python code can inspect a lot of runtime state
+- pre-existing writable file descriptors may bypass path-open checks
+- host callbacks can do anything their implementation permits
+- thread support is intentionally restricted unless explicitly designed for
+- The `CALL` event in `sys.monitoring` does not fire for operators invoked via dedicated bytecode opcodes — `BINARY_OP` (`a + b`), `BINARY_SUBSCR` (`a[i]`), comparisons, etc. These dispatch directly to the C-level numeric/subscript/compare slots, which aren't "calls" in PEP 669's model. Explicit dunder invocations (`a.__add__(b)`) do fire CALL normally.
+
+These limitations are acceptable for a guardrail system aimed at LLM-directed execution. They are not acceptable for hostile code.
+
+## Design principle
+
+The goal is not to make escape impossible. The goal is to make the safe path easy, the risky path explicit, and accidental overreach fail early with a useful error.
+
+## Release
+
+1) Ensure your GitHub issues are labeled (`bug`, `enhancement`, `breaking`).
+2) Run:
+
+```bash
+ship-gh
+ship-pypi
+ship-bump
+```

fastaudit-0.1.0/fastaudit/__init__.py

@@ -0,0 +1,2 @@
+__version__ = "0.1.0"
+from .core import *

fastaudit-0.1.0/fastaudit/core.py

@@ -0,0 +1,183 @@
+import os, sys
+from fastcore.utils import *
+from collections import namedtuple
+from contextlib import contextmanager
+from contextvars import ContextVar
+
+_audit_1st = {'os.chmod','os.chown','os.chflags','os.mkdir','os.remove','os.removexattr','os.rmdir','os.setxattr',
+    'shutil.chown','shutil.make_archive','shutil.rmtree','sqlite3.connect','tempfile.mkdtemp','tempfile.mkstemp'}
+_audit_dst = {'shutil.copyfile','shutil.copymode','shutil.copystat','shutil.copytree','sqlite3.load_extension'}
+_audit_both = {'os.link','os.rename','os.symlink','shutil.move','shutil.unpack_archive'}
+
+_audit_proc = {'subprocess.Popen','os.system','os.exec','os.spawn','os.posix_spawn','os.startfile','os.startfile/2',
+    'os.kill','os.killpg','pty.spawn','_posixsubprocess.fork_exec','signal.pthread_kill'}
+_audit_runtime = {'sys.addaudithook','sys.excepthook','sys.unraisablehook','sys.monitoring.register_callback',
+    'cpython.PyConfig_Set','cpython.PyInterpreterState_Clear','cpython.PyInterpreterState_New','cpython._PySys_ClearAuditHooks',
+    'cpython.run_command','cpython.run_file','cpython.run_module','cpython.run_stdin','cpython.run_startup',
+    'cpython.remote_debugger_script','sys.remote_exec','socket.sethostname','os.add_dll_directory','os.putenv','os.unsetenv',
+    '_thread.start_new_thread','_thread.start_joinable_thread'}
+_audit_ctypes = {'ctypes.dlopen','ctypes.dlsym','ctypes.dlsym/handle','ctypes.call_function','ctypes.cdata','ctypes.cdata/buffer',
+    'ctypes.memoryview_at','ctypes.string_at','ctypes.wstring_at','ctypes.addressof','ctypes.PyObj_FromPtr'}
+_audit_win = {'_winapi.CreateFile','_winapi.CreateProcess','_winapi.OpenProcess','_winapi.TerminateProcess','_winapi.CreateJunction',
+    '_winapi.CreateNamedPipe','_winapi.CreatePipe','msvcrt.locking','msvcrt.get_osfhandle','msvcrt.open_osfhandle',
+    'winreg.CreateKey','winreg.DeleteKey','winreg.DeleteValue','winreg.SetValue','winreg.LoadKey','winreg.SaveKey',
+    'winreg.DisableReflectionKey','winreg.EnableReflectionKey'}
+_audit_deny = _audit_proc|_audit_runtime|_audit_ctypes|_audit_win
+_AuditCfg = namedtuple('AuditCfg', 'oks before_deny on_call data monitor_calls')
+_state_attr = '_fastaudit_state'
+
+
+def _new_state():
+    ctx = ContextVar('fastaudit_cfg', default=None)
+    write_flags = os.O_WRONLY|os.O_RDWR|os.O_CREAT|os.O_TRUNC|os.O_APPEND
+    audit_1st,audit_dst,audit_both = map(frozenset, (_audit_1st,_audit_dst,_audit_both))
+    audit_deny = frozenset(_audit_deny|{'fastaudit.call','audit_perms.set_config','audit_perms.set_data'})
+    audit_all = audit_deny|audit_1st|audit_dst|audit_both|{'open','os.chdir','os.truncate','object.__setattr__'}
+    realpath,dirname,fsdecode,sep,getframe = os.path.realpath,os.path.dirname,os.fsdecode,os.sep,sys._getframe
+    mon,audit,stdlib = getattr(sys, 'monitoring', None),sys.audit,frozenset(sys.stdlib_module_names)
+    state = {'tool_id':None}
+
+    def frame_name(f): return f"{f.f_globals.get('__name__')}.{f.f_code.co_qualname}"
+
+    def func_mod(fn):
+        mod = getattr(fn, '__module__', None)
+        cls = getattr(fn, '__objclass__', None)
+        if not mod and cls is not None: mod = getattr(cls, '__module__', None)
+        s = getattr(fn, '__self__', None)
+        if not mod and s is not None: mod = getattr(type(s), '__module__', None)
+        return mod
+
+    def func_name(fn):
+        mod = func_mod(fn)
+        nm = getattr(fn, '__qualname__', getattr(fn, '__name__', None))
+        return f'{mod}.{nm}' if mod and nm else None
+
+    def is_stdlib(fn):
+        mod = func_mod(fn)
+        return bool(mod) and mod.split('.', 1)[0] in stdlib
+
+    def callee_is_python(fn):
+        if hasattr(fn, '__code__') or isinstance(fn, type): return True
+        return hasattr(getattr(type(fn), '__call__', None), '__code__')
+
+    def external_frame():
+        f = getframe()
+        while f:
+            if not frame_name(f).startswith('fastaudit.'): return f
+            f = f.f_back
+
+    def deny(cfg, event, args, msg):
+        if cfg.before_deny and cfg.before_deny(event, args, external_frame(), msg, cfg.data): return
+        raise PermissionError(msg)
+
+    def ok_path(cfg, p, parent=False):
+        try:
+            p = fsdecode(p)
+            if parent: p = dirname(p) or '.'
+            rp = realpath(p or '.')
+        except (OSError,TypeError,ValueError): return False
+        cur = realpath('.')
+        return any(rp==(cur if o=='.' else o) or rp.startswith((cur if o=='.' else o)+sep) for o in cfg.oks)
+
+    def chk(cfg, event, args):
+        if event not in audit_all: return
+        errstr = f"Audit: {event} blocked in sandbox with args: {args}"
+        if event in audit_deny: return deny(cfg, event, args, errstr)
+        if event=='object.__setattr__':
+            if args[1] in ('__doc__','__module__'): return
+            return deny(cfg, event, args, errstr)
+        ps = []
+        if event=='open':
+            path,mode,flags = args
+            if isinstance(mode,str) and not set('wax+') & set(mode): return
+            if mode is None and not flags & write_flags: return
+            ps = [path]
+        elif event=='os.chdir':
+            if not ok_path(cfg, args[0]): return deny(cfg, event, args, f"{event} {args[0]!r} not in {cfg.oks}")
+            return
+        elif event=='os.truncate':
+            if isinstance(args[0],int): return
+            ps = [args[0]]
+        elif event in audit_1st: ps = [args[0]]
+        elif event in audit_dst: ps = [args[1]]
+        elif event in audit_both: ps = args[:2]
+        for p in ps:
+            if not ok_path(cfg, p, parent=True): deny(cfg, event, args, f"{event} {p!r} not in {cfg.oks}")
+
+    def hook(event, args):
+        cfg = ctx.get()
+        if cfg is None: return
+        try: chk(cfg, event, args)
+        except PermissionError as e:
+            e.__traceback__ = None
+            raise
+
+    def call_cb(code, off, fn, arg0):
+        if code is call_cb.__code__ or callee_is_python(fn) or is_stdlib(fn): return mon.DISABLE
+        cfg = ctx.get()
+        if cfg is None or not cfg.monitor_calls: return
+        caller,callee = frame_name(getframe(1)),func_name(fn)
+        if not callee: return
+        if cfg.on_call:
+            res = cfg.on_call(caller, callee, fn, code, off, cfg.data)
+            if res is mon.DISABLE: return mon.DISABLE
+            if res is False: return
+        try: audit('fastaudit.call', caller, callee)
+        except PermissionError as e:
+            e.__traceback__ = None
+            raise
+
+    def install_call_monitor(tool_id):
+        if not mon: raise RuntimeError('monitor_calls=True requires Python 3.12+ sys.monitoring')
+        if (old:=state['tool_id']) is not None:
+            if old!=tool_id: raise RuntimeError(f'fastaudit already uses sys.monitoring tool id {old}')
+            return
+        if (tool:=mon.get_tool(tool_id)) == 'fastaudit':
+            mon.set_events(tool_id, 0)
+            mon.register_callback(tool_id, mon.events.CALL, None)
+            mon.free_tool_id(tool_id)
+        elif tool: raise RuntimeError(f'sys.monitoring tool id {tool_id} is already used by {tool!r}')
+        mon.use_tool_id(tool_id, 'fastaudit')
+        mon.register_callback(tool_id, mon.events.CALL, call_cb)
+        mon.set_events(tool_id, mon.events.CALL)
+        state['tool_id'] = tool_id
+
+    def mk_audit_(oks, before_deny=None, on_call=None, data=None, tool_id=3, monitor_calls=True):
+        audit('audit_perms.set_config', oks)
+        if on_call and not monitor_calls: raise RuntimeError('on_call requires monitor_calls=True')
+        if monitor_calls: install_call_monitor(tool_id)
+        oks = tuple('.' if o=='.' else realpath(fsdecode(o)) for o in oks)
+        cfg = _AuditCfg(oks, before_deny, on_call, data, monitor_calls)
+
+        @contextmanager
+        def cm():
+            nonlocal cfg
+            old = ctx.get()
+            if old is not cfg: audit('audit_perms.set_config', cfg)
+            tok = ctx.set(cfg)
+            if cfg.monitor_calls: mon.restart_events()
+            try: yield
+            finally: ctx.reset(tok)
+
+        def set_data(d):
+            nonlocal cfg
+            audit('audit_perms.set_data', d)
+            cfg = cfg._replace(data=d)
+            return cfg.data
+
+        cm.set_data = set_data
+        return cm
+
+    sys.addaudithook(hook)
+    return mk_audit_
+
+
+def _get_mk_audit():
+    mk_audit_ = getattr(sys, _state_attr, None)
+    if mk_audit_ is None:
+        mk_audit_ = _new_state()
+        setattr(sys, _state_attr, mk_audit_)
+    return mk_audit_
+
+def mk_audit(oks, before_deny=None, on_call=None, data=None, tool_id=3, monitor_calls=True):
+    return _get_mk_audit()(oks, before_deny, on_call, data, tool_id, monitor_calls)

fastaudit-0.1.0/fastaudit.egg-info/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: fastaudit
+Version: 0.1.0
+Summary: A lightweight execution guard for running LLM-generated Python in a normal Python process.
+Author: Answer.AI
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/AnswerDotAI/fastaudit
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastcore
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: orjson; extra == "dev"
+Requires-Dist: numpy; extra == "dev"
+Requires-Dist: fastship; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# fastaudit
+
+`fastaudit` is a lightweight execution guard for running LLM-generated Python in a normal Python process.
+
+It is not intended to be a hardened adversarial sandbox. Its purpose is to stop accidental damage from overly broad file operations, unexpected subprocess calls, and tool use that reaches outside approved working directories.
+
+The core mechanism is Python's audit hook system. The first `mk_audit()` call installs one process-wide audit hook. On Python 3.12 and newer, `sys.monitoring` is also used to raise audit events for non-stdlib native calls. `mk_audit()` creates an audit context, then enables permission checks only while that execution context is active.
+
+`fastaudit` requires Python 3.10 or newer. Native call monitoring requires Python 3.12 or newer and is enabled by default. Pass `monitor_calls=False` to use audit-hook-only mode on Python 3.10/3.11 or to avoid monitoring overhead.
+
+## Why this exists
+
+LLM-generated code is usually helpful, but sometimes too determined. If a command fails, an assistant may try another route; if a path is wrong, it may broaden the search; if a tool exists, it may use it without fully understanding its side effects.
+
+`fastaudit` is designed for that case.
+
+It helps with:
+
+- blocking subprocess and process-escape operations unless explicitly allowed
+- allowing writes only under approved roots
+- allowing broad read access where appropriate
+- making permission failures clear and immediate
+- letting host policy callbacks allow trusted tools while ordinary generated code stays checked
+- avoiding global audit state leaks across async tasks
+
+It deliberately does not try to defeat malicious code running in the same interpreter.
+
+## Audit hook categorization
+
+The audit hook is designed as a lightweight guardrail for LLM/tool-generated code, not as a hardened security sandbox against malicious code. The goal is to prevent accidental or over-broad filesystem mutation outside approved working directories: e.g. deleting files in the wrong project, writing into a user’s home directory, or spawning subprocesses unexpectedly. It assumes the surrounding process, user account, and pre-existing filesystem layout are trusted, and that the code being checked is not actively trying to exploit races, pre-planted symlinks, or CPython internals.
+
+The design keeps the common path simple and cheap. Dangerous process-escape events such as subprocess execution are denied outright. Filesystem write/delete events are allowed only when the relevant parent directory is inside a precomputed allowlist, since most mutations are really changes to directory entries. For destination-only operations such as copy, only the destination parent matters; for move/rename/link-style operations, both paths are checked because both filesystem locations may be affected. Read-only operations are generally ignored, and file-descriptor-based truncation is allowed on the assumption that the path policy was enforced when the descriptor was opened. This gives practical protection against accidental damage while avoiding the complexity and cost of pretending to be a fully adversarial sandbox.
+
+Symlinks are treated as part of the trusted filesystem setup. The hook’s path checks focus on the parent directories of mutations, which is the right model for operations that create, remove, or rename directory entries. This means an existing symlink inside an allowed directory may still point outside the allowed roots; that is acceptable under this threat model because the user controls the workspace layout and is assumed not to pre-place hostile links. To avoid making that assumption worse, symlink and hard-link creation should be restricted: the new link’s parent must be allowed, and the link target should either be denied or required to resolve inside an allowed root.
+
+## Threat model
+
+`fastaudit` assumes:
+
+- the user, workspace, and pre-existing filesystem layout are trusted
+- code is LLM-generated or LLM-directed, not actively hostile
+- accidental overreach is the main risk
+- rich user tools may need access that ordinary generated code should not have
+- Solveit or the host application controls the execution wrapper
+
+It does not assume:
+
+- Python introspection is unavailable
+- frames, closures, or modules are impossible to inspect
+- same-process execution can provide a hard security boundary
+- OS-level sandboxing is unnecessary for adversarial workloads
+
+For adversarial code, use a subprocess, container, VM, or OS-level policy.
+
+## Audit scope
+
+Auditing is opt-in per logical task. The audit hook is registered globally when the first audit context is created, and the optional call monitor is registered globally when needed, but permission checks only run while `audit_perms()` is active. This matters for async code. A global boolean or counter would leak audit state between unrelated coroutines whenever one audited task awaits. A `ContextVar` gives logical scoping: child tasks inherit at creation time, nested contexts restore cleanly via tokens, and the guard follows execution flow rather than scheduler order. Threads are denied in the audit sandbox since context variables otherwise are not maintained.
+
+The hook is built once inside a closure rather than read from module globals on every event. Allowed roots and callbacks live in the active context config, the event-classification sets are converted to `frozenset`, and the helpers used in the hot path — `realpath`, `dirname`, `fsdecode`, `os.sep` — are captured as local names. Nothing the hook depends on lives in a mutable global that a generated cell could clear, replace, or reassign. This is not a security barrier against introspection or frame walking; it is a deliberate effort to remove the easy, accidental disabling paths that an enthusiastic LLM is most likely to take when retrying after a `PermissionError`.
+
+## Permission model
+
+The policy classifies audit events into a few groups:
+
+- events denied outright
+- events where the first path argument is checked
+- events where the destination path is checked
+- events where both source and destination paths are checked
+- special cases such as `open`, `os.truncate`, and sensitive `object.__setattr__`
+
+Writes and filesystem mutations are allowed only when the relevant parent directory is inside an approved root.
+
+Reads are generally allowed.
+
+Subprocess creation and similar process escapes are denied by default.
+
+The allowed root `'.'` is dynamic: it means the current directory at the time of each checked operation. This lets a sandbox follow allowed `chdir` calls into child directories. `os.chdir` itself is checked against the destination directory, not the destination's parent.
+
+Non-stdlib native calls raise a `fastaudit.call` audit event while `audit_perms()` is active when `monitor_calls=True`. Python calls and stdlib calls are ignored by the call monitor. The context manager calls `sys.monitoring.restart_events()` on entry so monitored call sites disabled before the context are seen again inside it. With `monitor_calls=False`, only normal Python audit-hook events are checked.
+
+### get/set attr hooks
+
+The `object.__setattr__` audit event fires only for a small fixed set of "sensitive" attribute assignments, not for general attribute setting. On types/classes, it fires when setting `__name__`, `__qualname__`, `__module__`, `__bases__`, `__doc__`, or `__type_params__` — these go through `check_set_special_type_attr` in `Objects/typeobject.c`. The `__class__` reassignment on any object is also audited, via `object_set_class` in the same file. On function objects, assignments to `__code__`, `__defaults__`, and `__kwdefaults__` are audited, via the relevant setters in `Objects/funcobject.c`.
+
+All other attribute assignments — including ordinary `C.x = 1` on a class, instance attribute assignment, and even some dunders like `__abstractmethods__` and `__annotations__` (which write directly via `PyDict_SetItem`) — bypass the audit hook entirely. This is why `@dataclass` triggers an event (it sets `cls.__doc__`) and `namedtuple` triggers one (it sets `cls.__module__`), while `class C: pass; C.x = 1; C.foo = lambda self: None` is silent. The authoritative list lives in the CPython source at [`Objects/typeobject.c`](https://github.com/python/cpython/blob/v3.12.0/Objects/typeobject.c) and [`Objects/funcobject.c`](https://github.com/python/cpython/blob/v3.12.0/Objects/funcobject.c); the public docs only describe the event as firing for "certain sensitive attribute assignments" without enumerating them.
+
+## Host policy
+
+Some user-provided tools need permissions that ordinary generated code should not have. For instance, a search tool may need to call `rg`, or a helper may need to spawn a tightly controlled subprocess.
+
+`fastaudit` does not define that policy itself. Host code can pass `before_deny`, which is called after `fastaudit` decides an operation should be blocked and before `PermissionError` is raised:
+
+```python
+before_deny(event, args, frame, msg, data)
+```
+
+The callback receives the event name, audit arguments, the first non-`fastaudit` stack frame, the error message, and the current host data. Returning a truthy value allows the operation. Returning a falsey value denies it. Exceptions from the callback propagate.
+
+For non-stdlib native calls, host code can also pass `on_call`, which runs before `fastaudit.call` is raised. `on_call` requires `monitor_calls=True`:
+
+```python
+on_call(caller, callee, fn, code, off, data)
+```
+
+It receives the caller, callee, function object, code object, bytecode offset, and current host data. It can return `False` to suppress the audit event for that call, or `sys.monitoring.DISABLE` to disable that monitored call site. Exceptions from the callback propagate.
+
+The optional `data` argument is stored in the audit context config and passed to both callbacks. A host can build mutable policy state outside the sandbox, pass a frozen snapshot to `mk_audit`, and later update that snapshot with `audit_perms.set_data(...)`. Creating or entering a new audit context, or calling `set_data`, raises an internal audit event and is denied while `audit_perms()` is active.
+
+`mk_audit()` uses `sys.monitoring` tool id `3` by default when call monitoring is enabled. Pass `tool_id=...` if the host already uses that id.
+
+## API sketch
+
+```python
+audit_perms = mk_audit(['/tmp', os.getcwd()], before_deny=allow_trusted_tool, data=frozenset(allowed))
+
+with audit_perms():
+    exec(code, restricted_globals)
+
+audit_perms.set_data(frozenset(new_allowed))
+
+audit_perms = mk_audit(['/tmp'], monitor_calls=False)  # audit hooks only
+```
+
+## Implementation notes
+
+The hook should avoid relying on mutable globals during enforcement.
+
+At construction time, bind or freeze:
+
+- approved roots
+- audit event sets
+- write flags
+- path helpers such as `realpath`, `dirname`, and `fsdecode`
+- frame lookup helper
+- call-monitor helpers and callbacks
+
+This prevents the most likely accidental disabling paths, such as clearing a global deny set or replacing a helper function. The implementation still does not claim to be secure against deliberate frame walking or introspection.
+
+## Limitations
+
+`fastaudit` does not provide a hard security boundary.
+
+Known limitations:
+
+- same-process Python code can inspect a lot of runtime state
+- pre-existing writable file descriptors may bypass path-open checks
+- host callbacks can do anything their implementation permits
+- thread support is intentionally restricted unless explicitly designed for
+- The `CALL` event in `sys.monitoring` does not fire for operators invoked via dedicated bytecode opcodes — `BINARY_OP` (`a + b`), `BINARY_SUBSCR` (`a[i]`), comparisons, etc. These dispatch directly to the C-level numeric/subscript/compare slots, which aren't "calls" in PEP 669's model. Explicit dunder invocations (`a.__add__(b)`) do fire CALL normally.
+
+These limitations are acceptable for a guardrail system aimed at LLM-directed execution. They are not acceptable for hostile code.
+
+## Design principle
+
+The goal is not to make escape impossible. The goal is to make the safe path easy, the risky path explicit, and accidental overreach fail early with a useful error.
+
+## Release
+
+1) Ensure your GitHub issues are labeled (`bug`, `enhancement`, `breaking`).
+2) Run:
+
+```bash
+ship-gh
+ship-pypi
+ship-bump
+```

fastaudit-0.1.0/fastaudit.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+CHANGELOG.md
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+fastaudit/__init__.py
+fastaudit/core.py
+fastaudit.egg-info/PKG-INFO
+fastaudit.egg-info/SOURCES.txt
+fastaudit.egg-info/dependency_links.txt
+fastaudit.egg-info/requires.txt
+fastaudit.egg-info/top_level.txt
+tests/test_core.py

fastaudit-0.1.0/fastaudit.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

fastaudit-0.1.0/fastaudit.egg-info/requires.txt

@@ -0,0 +1,9 @@
+fastcore
+
+[dev]
+pytest
+orjson
+numpy
+fastship
+build
+twine

fastaudit-0.1.0/fastaudit.egg-info/top_level.txt

@@ -0,0 +1 @@
+fastaudit

fastaudit-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "fastaudit"
+description = "A lightweight execution guard for running LLM-generated Python in a normal Python process."
+
+dynamic = ["version"]
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Answer.AI" }]
+classifiers = [ "Programming Language :: Python :: 3", "Programming Language :: Python :: 3 :: Only", ]
+
+dependencies = [ "fastcore", ]
+
+[project.optional-dependencies]
+dev = [ "pytest", "orjson", "numpy", "fastship", "build", "twine", ]
+
+[project.urls]
+Homepage = "https://github.com/AnswerDotAI/fastaudit"
+
+[tool.setuptools.dynamic]
+version = { attr = "fastaudit.__version__" }
+
+[tool.setuptools.packages.find]
+include = ["fastaudit"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

fastaudit-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

fastaudit-0.1.0/tests/test_core.py

@@ -0,0 +1,124 @@
+import numpy as np, orjson, os, shutil, subprocess, sys, traceback
+from fastcore.foundation import working_directory
+from fastcore.test import expect_fail
+from fastaudit.core import mk_audit
+from os.path import join,realpath,expanduser
+
+
+def touch(p, s='x'):
+    with open(p, 'w') as f: f.write(s)
+
+def test_audit_blocks(tmp_path):
+    start = os.getcwd()
+    dotdest = tmp_path/'dotdest'
+    okdest = tmp_path/'okdest'
+    (dotdest/'child').mkdir(parents=True)
+    okdest.mkdir()
+    okdest = realpath(okdest)
+    inside = join(okdest, 'audit-test.txt')
+    inside2 = join(okdest, 'audit-test-2.txt')
+    inside3 = join(okdest, 'audit-test-3.txt')
+    outside = expanduser('~/audit-test-outside.txt')
+    permissive = mk_audit([expanduser('~')], monitor_calls=False)
+
+    with working_directory(dotdest), mk_audit((okdest,'.'))():
+        # Sensitive function mutation is blocked.
+        def f(): pass
+        with expect_fail(PermissionError): f.__code__ = f.__code__
+
+        # Reads outside approved roots are allowed.
+        open('/etc/passwd', 'r').close()
+        fd = os.open('/etc/passwd', os.O_RDONLY)
+        os.close(fd)
+
+        # Writes and deletes outside approved roots are blocked.
+        with expect_fail(PermissionError): os.open(outside, os.O_WRONLY)
+        with expect_fail(PermissionError): os.remove(outside)
+
+        # Copy destinations must stay inside approved roots.
+        shutil.copyfile('/etc/passwd', inside)
+        with expect_fail(PermissionError): shutil.copyfile(inside, outside)
+        os.remove(inside)
+
+        # Renames touching unapproved roots, and subprocesses, are blocked.
+        touch(inside2)
+        with expect_fail(PermissionError): os.rename(outside, inside3)
+        with expect_fail(PermissionError): os.rename(inside2, outside)
+        os.remove(inside2)
+        with expect_fail(PermissionError): subprocess.run(['echo', 'hi'])
+
+        # "." allows writes under the current directory and chdir checks the destination.
+        touch('dot-inside.txt')
+        touch('child/nested.txt')
+        with expect_fail(PermissionError): touch('../sibling.txt')
+        with expect_fail(PermissionError): os.chdir(start)
+
+        # fastaudit frames are removed from tracebacks.
+        try: subprocess.run(['echo', 'hi'])
+        except PermissionError as e: frames = traceback.extract_tb(e.__traceback__)
+        assert not [f for f in frames if f.filename.endswith('fastaudit/core.py')]
+
+        # Python classes and callable instances are not treated as native calls.
+        class PyCallable:
+            def __init__(self): super().__init__()
+            def __call__(self): return 'ok'
+        assert PyCallable()() == 'ok'
+
+        # Non-stdlib native calls are blocked.
+        with expect_fail(PermissionError): orjson.dumps({'a': 1})
+
+        # Audit policy cannot be replaced from inside the sandbox.
+        with expect_fail(PermissionError): mk_audit([expanduser('~')], monitor_calls=False)
+        with expect_fail(PermissionError), permissive(): pass
+
+
+def test_callbacks(tmp_path):
+    def before_deny(event, args, frame, msg, data): return event=='subprocess.Popen' and args[1][:1]==['echo']
+    def on_call(caller, callee, fn, code, off, data):
+        if callee=='orjson.dumps': return False
+        if callee.startswith('numpy.'): return sys.monitoring.DISABLE
+
+    with mk_audit([tmp_path], before_deny=before_deny, on_call=on_call)():
+        # Host callbacks can allow specific native calls…
+        assert orjson.dumps({'a': 1}) == b'{"a":1}'
+        assert np.array([1, 2, 3]).sum() == 6
+        # …and audit events
+        res = subprocess.run(['echo', 'hi'], capture_output=True, text=True)
+        assert res.stdout == 'hi\n'
+        # Neighboring subprocess commands remain blocked.
+        with expect_fail(PermissionError): subprocess.run(['ls'])
+
+
+def test_monitor_calls_can_be_disabled(tmp_path):
+    with expect_fail(RuntimeError): mk_audit([tmp_path], on_call=lambda *args: None, monitor_calls=False)
+    with mk_audit([tmp_path], monitor_calls=False)():
+        # Audit-hook checks still run without native call monitoring.
+        with expect_fail(PermissionError): subprocess.run(['echo', 'hi'])
+        assert orjson.dumps({'a': 1}) == b'{"a":1}'
+
+
+def test_implement_allow_list(tmp_path):
+    "A brief demo of creating an `allow()` system"
+    def trusted_echo(): return subprocess.run(['echo', 'hi'], capture_output=True, text=True)
+
+    allowed = set()
+    def allow(fn): allowed.add(f'{fn.__module__}.{fn.__qualname__}')
+    allow(trusted_echo)
+
+    def before_deny(event, args, frame, msg, data):
+        while frame:
+            if f"{frame.f_globals.get('__name__')}.{frame.f_code.co_qualname}" in data: return True
+            frame = frame.f_back
+
+    audit_perms = mk_audit([tmp_path], before_deny=before_deny, data=frozenset(allowed))
+    with audit_perms():
+        # A callback can implement frame-based tool allowance.
+        assert trusted_echo().stdout == 'hi\n'
+        with expect_fail(PermissionError): subprocess.run(['echo', 'hi'])
+        # Callback data cannot be replaced from inside the sandbox.
+        with expect_fail(PermissionError): audit_perms.set_data(frozenset())
+
+    # Trusted host code can update callback data between sandboxed runs.
+    audit_perms.set_data(frozenset())
+    with audit_perms():
+        with expect_fail(PermissionError): trusted_echo()