jeevesagent.security.sandbox.filesystem
=======================================

.. py:module:: jeevesagent.security.sandbox.filesystem

.. autoapi-nested-parse::

   Path-aware sandbox.

   Wraps a :class:`ToolHost` and rejects tool calls whose path-typed
   arguments resolve outside a configured set of allowed roots. Detection
   is configurable:

   * Pass ``path_args=("path", "destination", ...)`` to validate exactly
     those argument names.
   * Otherwise the sandbox auto-detects: any string argument whose name
     is in :data:`DEFAULT_PATH_ARG_NAMES` *or* whose value contains a
     path separator (``/`` or ``\``) is treated as a path.

   Symlinks are resolved before the containment check so an attacker
   can't bypass the sandbox by symlinking ``/etc/passwd`` into the
   allowed root.



Attributes
----------

.. autoapisummary::

   jeevesagent.security.sandbox.filesystem.DEFAULT_PATH_ARG_NAMES


Classes
-------

.. autoapisummary::

   jeevesagent.security.sandbox.filesystem.FilesystemSandbox


Module Contents
---------------

.. py:class:: FilesystemSandbox(inner: jeevesagent.core.protocols.ToolHost, *, roots: collections.abc.Iterable[str | pathlib.Path], path_args: collections.abc.Iterable[str] | None = None, auto_detect: bool = True)

   Restrict a tool host's path-typed arguments to declared roots.


   .. py:method:: call(tool: str, args: collections.abc.Mapping[str, Any], *, call_id: str = '') -> jeevesagent.core.types.ToolResult
      :async:



   .. py:method:: list_tools(*, query: str | None = None) -> list[jeevesagent.core.types.ToolDef]
      :async:



   .. py:method:: watch() -> collections.abc.AsyncIterator[jeevesagent.core.types.ToolEvent]
      :async:



   .. py:property:: inner
      :type: jeevesagent.core.protocols.ToolHost



   .. py:property:: roots
      :type: tuple[pathlib.Path, Ellipsis]



.. py:data:: DEFAULT_PATH_ARG_NAMES
   :type:  frozenset[str]

