agent-framework-lib 0.8.7.post4__tar.gz → 0.8.7.post5__tar.gz

{agent_framework_lib-0.8.7.post4/agent_framework_lib.egg-info → agent_framework_lib-0.8.7.post5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-framework-lib
-Version: 0.8.7.post4
+Version: 0.8.7.post5
 Summary: A comprehensive Python framework for building and serving conversational AI agents with FastAPI
 Author-email: Sebastian Pavel <sebastian@cinco.ai>, Elliott Girard <elliott.girard@icloud.com>
 Maintainer-email: Sebastian Pavel <sebastian@cinco.ai>

{agent_framework_lib-0.8.7.post4 → agent_framework_lib-0.8.7.post5}/agent_framework/core/agent_interface.py

@@ -892,6 +892,22 @@ class AgentInterface(abc.ABC):
             "memory_adapter": None,
         }
 
+    def get_secret_redactor(self) -> Any:
+        """Return a redactor used to mask secret values in outgoing data.
+
+        The redactor exposes ``redact_text``, ``redact_parts``, ``feed`` and
+        ``flush`` and is used by the server as a last-line defense to strip
+        secret values (container env keys, workspace secrets) from responses,
+        persisted data, and logs.
+
+        The default implementation returns an inert redactor (nothing to mask).
+        ``BaseAgent`` overrides this to build a redactor from the sensitive
+        environment values and the current workspace secrets.
+        """
+        from ..security.secret_redactor import SecretRedactor
+
+        return SecretRedactor([])
+
     def get_custom_tool_display_info(self) -> dict[str, Any]:
         """
         Returns custom display info for agent-specific tools (e.g., MCP tools).

{agent_framework_lib-0.8.7.post4 → agent_framework_lib-0.8.7.post5}/agent_framework/core/base_agent.py

@@ -29,6 +29,7 @@ if TYPE_CHECKING:
     from collections.abc import AsyncGenerator
 
     from ..capabilities.resolver import CapabilitySet
+    from ..security.secret_redactor import SecretRedactor
     from ..subagents.executor import SubagentExecutor
     from ..subagents.message_queue import SessionMessageQueue
     from ..subagents.spawn_tool import SubagentSpawnTool
@@ -377,6 +378,41 @@ class BaseAgent(SkillsMixin, MemoryMixin, AgentInterface):
             except Exception as e:
                 logger.warning(f"Could not propagate workspace secrets to live ShellTool: {e}")
 
+    def _loaded_skill_env_keys(self) -> set[str]:
+        """Return env-var names declared by currently loaded skills.
+
+        Reads ``requires_env`` from the metadata of every loaded skill so that
+        ``ShellTool`` can expose those variables to the shell while everything
+        else is scrubbed. Returns an empty set if skills are unavailable.
+        """
+        if not SKILLS_AVAILABLE or not getattr(self, "_enable_skills", False):
+            return set()
+        keys: set[str] = set()
+        try:
+            registry = self._skill_registry
+            for name in registry.list_loaded():
+                skill = registry.get(name)
+                if skill is not None:
+                    keys.update(skill.metadata.requires_env)
+        except Exception as e:  # noqa: BLE001 — never break shell wiring
+            logger.warning(f"Could not collect loaded skill env keys: {e}")
+        return keys
+
+    def get_secret_redactor(self) -> SecretRedactor:
+        """Build a redactor masking sensitive env values + workspace secrets.
+
+        The returned redactor masks any occurrence of a sensitive container
+        environment value (LLM keys, infra creds, ``API_KEYS``) or workspace
+        secret in outgoing text, parts, persisted data, and logs. Rebuilt on
+        demand so it always reflects the current environment and workspace.
+        """
+        from ..security.secret_redactor import SecretRedactor
+        from ..security.shell_env import sensitive_env_values
+
+        env_values = sensitive_env_values(os.environ)
+        workspace_values = list(self._workspace_secrets.values())
+        return SecretRedactor(env_values + workspace_values)
+
     def set_subagent_executor(self, executor: SubagentExecutor | None) -> None:
         """Inject or remove the shared SubagentExecutor.
 
@@ -641,7 +677,10 @@ class BaseAgent(SkillsMixin, MemoryMixin, AgentInterface):
         try:
             from ..tools.shell_tool import ShellTool
 
-            shell_tool = ShellTool(default_timeout=120)
+            shell_tool = ShellTool(
+                default_timeout=120,
+                skill_env_provider=self._loaded_skill_env_keys,
+            )
             # Inject session context so that AGENT_USER_ID / AGENT_SESSION_ID are
             # propagated to subprocesses (register_to_storage / create_and_register).
             # Without this, generated files are uploaded without session_id and

agent_framework_lib-0.8.7.post5/agent_framework/security/__init__.py

@@ -0,0 +1,17 @@
+"""Security utilities for the agent framework.
+
+Provides secret redaction (masking secret values in any output reaching the
+client, persistence, or logs) and the shell environment allowlist used to
+prevent the shell sandbox from reading container secrets it does not need.
+"""
+
+from .secret_redactor import SecretRedactor, build_redaction_value_set
+from .shell_env import build_shell_env, sensitive_env_values
+
+
+__all__ = [
+    "SecretRedactor",
+    "build_redaction_value_set",
+    "build_shell_env",
+    "sensitive_env_values",
+]

agent_framework_lib-0.8.7.post5/agent_framework/security/secret_redactor.py

@@ -0,0 +1,291 @@
+"""Masquage des valeurs de secrets dans les chaînes et les output parts.
+
+Le ``SecretRedactor`` remplace toute occurrence d'une valeur secrète connue par
+un masque fixe (``********``), avant que la donnée n'atteigne le client, le
+stockage de session/Elasticsearch ou les logs.
+
+Deux sources de valeurs à masquer :
+- les variables d'environnement sensibles du conteneur (clés LLM, creds infra) ;
+- les secrets workspace injectés dans le shell.
+
+Le masquage est littéral (pas de regex sur la valeur), insensible à rien
+d'autre que la casse exacte, et trie les valeurs par longueur décroissante pour
+éviter qu'un secret court inclus dans un secret long ne soit masqué de façon
+incohérente.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING, Any
+
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Sequence
+
+
+MASK = "********"
+
+DEFAULT_MIN_LEN = 4
+"""Longueur minimale d'une valeur pour être masquée (sous ce seuil = bruit)."""
+
+
+def _redaction_min_len() -> int:
+    """Lit le seuil de longueur minimale depuis l'environnement."""
+    raw = os.environ.get("SECRET_REDACTION_MIN_LEN", "")
+    try:
+        value = int(raw)
+    except (TypeError, ValueError):
+        return DEFAULT_MIN_LEN
+    return value if value > 0 else DEFAULT_MIN_LEN
+
+
+def build_redaction_value_set(
+    *value_groups: Iterable[str] | None,
+    min_len: int | None = None,
+) -> list[str]:
+    """Construit la liste triée des valeurs à masquer.
+
+    Fusionne plusieurs groupes de valeurs, retire les doublons, ignore les
+    valeurs vides ou trop courtes, puis trie par longueur décroissante.
+
+    Args:
+        *value_groups: Itérables de valeurs candidates (env sensibles,
+            secrets workspace, etc.). Les ``None`` sont tolérés.
+        min_len: Longueur minimale d'une valeur pour être retenue. Si ``None``,
+            lit ``SECRET_REDACTION_MIN_LEN`` (défaut 4).
+
+    Returns:
+        Liste de valeurs uniques triées par longueur décroissante.
+    """
+    threshold = min_len if min_len is not None else _redaction_min_len()
+    seen: set[str] = set()
+    for group in value_groups:
+        if not group:
+            continue
+        for raw in group:
+            if raw is None:
+                continue
+            value = str(raw)
+            if len(value) < threshold:
+                continue
+            seen.add(value)
+    return sorted(seen, key=len, reverse=True)
+
+
+class SecretRedactor:
+    """Masque des valeurs secrètes dans des chaînes et des output parts.
+
+    Stateless vis-à-vis de la session, sauf pour le buffer de ``feed()`` utilisé
+    en streaming. Construire un nouveau redacteur par session (ou réutiliser tant
+    que l'ensemble des secrets ne change pas).
+    """
+
+    def __init__(self, secret_values: Iterable[str] | None = None) -> None:
+        """Initialise le redacteur.
+
+        Args:
+            secret_values: Valeurs à masquer. Filtrées/triées via
+                ``build_redaction_value_set``.
+        """
+        self._values: list[str] = build_redaction_value_set(secret_values)
+        self._max_len: int = self._values[0].__len__() if self._values else 0
+        self._buffer: str = ""
+
+    @property
+    def active(self) -> bool:
+        """``True`` si au moins une valeur est à masquer."""
+        return bool(self._values)
+
+    @property
+    def secret_values(self) -> list[str]:
+        """Copie de la liste des valeurs masquées (triée par longueur décr.)."""
+        return list(self._values)
+
+    def redact_text(self, text: str | None) -> str | None:
+        """Masque toutes les occurrences des valeurs secrètes dans ``text``.
+
+        Args:
+            text: Texte à nettoyer. ``None`` est renvoyé tel quel.
+
+        Returns:
+            Le texte avec chaque valeur secrète remplacée par ``********``.
+        """
+        if text is None or not self._values:
+            return text
+        if not text:
+            return text
+        result = text
+        for value in self._values:
+            if value in result:
+                result = result.replace(value, MASK)
+        return result
+
+    def redact_obj(self, obj: Any) -> Any:
+        """Masque récursivement les valeurs secrètes dans une structure JSON.
+
+        Gère str, dict, list, tuple. Les autres types sont renvoyés tels quels.
+        """
+        if not self._values:
+            return obj
+        if isinstance(obj, str):
+            return self.redact_text(obj)
+        if isinstance(obj, dict):
+            return {k: self.redact_obj(v) for k, v in obj.items()}
+        if isinstance(obj, list):
+            return [self.redact_obj(v) for v in obj]
+        if isinstance(obj, tuple):
+            return tuple(self.redact_obj(v) for v in obj)
+        return obj
+
+    def redact_parts(self, parts: Sequence[Any] | None) -> list[Any]:
+        """Masque les champs textuels de chaque output part.
+
+        Couvre ``TextOutputPart.text``, ``TextOutputStreamPart.text``,
+        ``ActivityOutputPart.content``/``results``/``tools``, et
+        ``TechnicalDetails.raw_result``/``error_message``. Retourne de nouvelles
+        instances (immutabilité) — les parts non concernées sont conservées.
+
+        Args:
+            parts: Liste d'output parts (modèles Pydantic) ou de dicts.
+
+        Returns:
+            Nouvelle liste avec les valeurs secrètes masquées.
+        """
+        if not parts:
+            return list(parts) if parts is not None else []
+        if not self._values:
+            return list(parts)
+        return [self._redact_part(part) for part in parts]
+
+    def _redact_part(self, part: Any) -> Any:
+        """Masque une seule part (dict ou modèle Pydantic)."""
+        if isinstance(part, dict):
+            return self.redact_obj(part)
+
+        part_type = getattr(part, "type", None)
+
+        if part_type in ("text_output", "text_output_stream"):
+            text = getattr(part, "text", None)
+            redacted = self.redact_text(text)
+            if redacted != text:
+                return part.model_copy(update={"text": redacted})
+            return part
+
+        if part_type == "activity":
+            return self._redact_activity_part(part)
+
+        return part
+
+    def _redact_activity_part(self, part: Any) -> Any:
+        """Masque le contenu textuel et les détails techniques d'une activité."""
+        updates: dict[str, Any] = {}
+
+        content = getattr(part, "content", None)
+        redacted_content = self.redact_text(content)
+        if redacted_content != content:
+            updates["content"] = redacted_content
+
+        for field in ("results", "tools"):
+            value = getattr(part, field, None)
+            if value:
+                redacted = self.redact_obj(value)
+                if redacted != value:
+                    updates[field] = redacted
+
+        td = getattr(part, "technical_details", None)
+        if td is not None:
+            td_updates: dict[str, Any] = {}
+            raw_result = getattr(td, "raw_result", None)
+            redacted_raw = self.redact_text(raw_result)
+            if redacted_raw != raw_result:
+                td_updates["raw_result"] = redacted_raw
+            err = getattr(td, "error_message", None)
+            redacted_err = self.redact_text(err)
+            if redacted_err != err:
+                td_updates["error_message"] = redacted_err
+            args = getattr(td, "arguments", None)
+            if args:
+                redacted_args = self.redact_obj(args)
+                if redacted_args != args:
+                    td_updates["arguments"] = redacted_args
+            if td_updates:
+                updates["technical_details"] = td.model_copy(update=td_updates)
+
+        if updates:
+            return part.model_copy(update=updates)
+        return part
+
+    def feed(self, delta: str) -> str:
+        """Masquage incrémental pour le streaming.
+
+        Conserve un buffer brut et n'émet que le préfixe qui ne peut plus être
+        affecté par les caractères futurs. On retient au minimum
+        ``max_len - 1`` caractères (longueur du plus long secret moins un), puis
+        on abaisse la coupure pour ne jamais scinder une occurrence présente
+        dans le buffer. Le préfixe émis est masqué ; le reste est conservé.
+
+        Args:
+            delta: Nouveau fragment de texte.
+
+        Returns:
+            Portion masquée et sûre à émettre immédiatement (peut être vide).
+        """
+        if not self._values:
+            return delta
+        self._buffer += delta
+        buf = self._buffer
+        margin = self._max_len - 1
+        cut = len(buf) - margin
+        if cut <= 0:
+            return ""
+
+        cut = self._safe_cut(buf, cut)
+        if cut <= 0:
+            return ""
+
+        emitted = self.redact_text(buf[:cut]) or ""
+        self._buffer = buf[cut:]
+        return emitted
+
+    def _safe_cut(self, buf: str, cut: int) -> int:
+        """Abaisse ``cut`` jusqu'à ce qu'aucune occurrence ne le chevauche.
+
+        Une occurrence ``buf[start:start+len(v)]`` chevauche ``cut`` si
+        ``start < cut < start + len(v)``. On ramène ``cut`` au début de la
+        première occurrence chevauchante, en itérant jusqu'au point fixe car
+        abaisser ``cut`` peut révéler des occurrences plus précoces.
+        """
+        changed = True
+        while changed and cut > 0:
+            changed = False
+            for value in self._values:
+                lv = len(value)
+                start = 0
+                while True:
+                    idx = buf.find(value, start)
+                    if idx == -1 or idx >= cut:
+                        break
+                    if idx + lv > cut:
+                        cut = idx
+                        changed = True
+                        break
+                    start = idx + 1
+                if cut <= 0:
+                    return 0
+        return cut
+
+    def flush(self) -> str:
+        """Vide le buffer de streaming en masquant le résidu.
+
+        Returns:
+            Le reste du buffer, masqué.
+        """
+        if not self._buffer:
+            return ""
+        remaining = self.redact_text(self._buffer) or ""
+        self._buffer = ""
+        return remaining
+
+
+__all__ = ["SecretRedactor", "build_redaction_value_set", "MASK"]

agent_framework_lib-0.8.7.post5/agent_framework/security/shell_env.py

@@ -0,0 +1,195 @@
+"""Construction de l'environnement exposé à la sandbox ``shell_exec``.
+
+Le shell ne doit voir que les variables dont il a réellement besoin :
+- un socle système (PATH, HOME, locale, runtime ``uv``…) ;
+- le wiring framework (``AGENT_*``) injecté explicitement ailleurs ;
+- l'auth requise par les scripts d'upload (``REQUIRE_AUTH``/``API_KEYS``) ;
+- les variables déclarées par les skills chargées (``requires_env``) ;
+- les secrets workspace (injectés volontairement pour usage) ;
+- un override d'exploitation (``SHELL_ENV_ALLOWLIST``).
+
+Toute autre variable de ``os.environ`` (clés LLM, creds DB/cloud, mots de passe)
+est retirée : ``echo $OPENAI_API_KEY`` renvoie une chaîne vide en conversation
+normale. Les valeurs qui restent exposées mais sensibles (``API_KEYS``,
+``OPENAI_API_KEY`` quand ``image_gen`` est chargée) sont masquées en sortie par
+le ``SecretRedactor``.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING
+
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+
+# Socle système toujours exposé. Préfixes via _ALLOW_PREFIXES.
+_BASE_ALLOW: frozenset[str] = frozenset(
+    {
+        "PATH",
+        "HOME",
+        "USER",
+        "LOGNAME",
+        "SHELL",
+        "PWD",
+        "OLDPWD",
+        "TERM",
+        "TZ",
+        "TMPDIR",
+        "TEMP",
+        "TMP",
+        "HOSTNAME",
+        "LANG",
+        "LANGUAGE",
+        "PYTHONPATH",
+        "PYTHONHOME",
+        "PYTHONUNBUFFERED",
+        "PYTHONDONTWRITEBYTECODE",
+        "PYTHONIOENCODING",
+        "VIRTUAL_ENV",
+        "CONDA_PREFIX",
+        "NODE_PATH",
+        "SSL_CERT_FILE",
+        "SSL_CERT_DIR",
+        "REQUESTS_CA_BUNDLE",
+        "CURL_CA_BUNDLE",
+    }
+)
+
+# Préfixes système exposés en bloc (locale + chaînes d'outils courantes).
+_ALLOW_PREFIXES: tuple[str, ...] = (
+    "LC_",
+    "UV_",
+    "XDG_",
+    "DENO_",
+    "NODE_",
+    "NPM_",
+    "PLAYWRIGHT_",
+    "NODEENV_",
+)
+
+# Wiring framework + auth requise par les scripts d'upload (process séparés qui
+# lisent ces variables depuis l'environnement). API_KEYS reste exposé mais sa
+# valeur est masquée en sortie par le SecretRedactor.
+_FRAMEWORK_ALLOW: frozenset[str] = frozenset(
+    {
+        "AGENT_USER_ID",
+        "AGENT_SESSION_ID",
+        "AGENT_HOST",
+        "AGENT_PORT",
+        "AGENT_OUTPUT_DIR",
+        "AGENT_CLEANUP_LOCAL",
+        "REQUIRE_AUTH",
+        "API_KEYS",
+    }
+)
+
+
+def _allow_prefixes() -> tuple[str, ...]:
+    return tuple(p for p in _ALLOW_PREFIXES if p)
+
+
+def shell_env_mode() -> str:
+    """Mode de filtrage de l'environnement shell.
+
+    Returns:
+        ``"allowlist"`` (défaut), ``"passthrough"`` (legacy, debug uniquement).
+    """
+    mode = os.environ.get("SHELL_ENV_MODE", "allowlist").strip().lower()
+    return mode if mode in ("allowlist", "passthrough") else "allowlist"
+
+
+def _extra_allowlist() -> set[str]:
+    """Clés additionnelles exposées via ``SHELL_ENV_ALLOWLIST`` (CSV)."""
+    raw = os.environ.get("SHELL_ENV_ALLOWLIST", "")
+    return {k.strip() for k in raw.split(",") if k.strip()}
+
+
+def _is_allowed(key: str, allow_exact: frozenset[str] | set[str]) -> bool:
+    if key in allow_exact:
+        return True
+    return any(key.startswith(prefix) for prefix in _allow_prefixes())
+
+
+def build_shell_env(
+    source_env: dict[str, str] | None = None,
+    *,
+    skill_env_keys: Iterable[str] | None = None,
+    extra_keys: Iterable[str] | None = None,
+) -> dict[str, str]:
+    """Construit l'environnement filtré pour le sous-processus shell.
+
+    Args:
+        source_env: Environnement source (défaut ``os.environ``).
+        skill_env_keys: Variables déclarées par les skills chargées
+            (``requires_env``). Exposées car nécessaires à l'exécution des skills.
+        extra_keys: Clés additionnelles à exposer (override programmatique).
+
+    Returns:
+        Dictionnaire d'environnement ne contenant que les clés autorisées.
+        En mode ``passthrough``, renvoie une copie complète de ``source_env``.
+    """
+    src = dict(source_env if source_env is not None else os.environ)
+
+    if shell_env_mode() == "passthrough":
+        return src
+
+    allow_exact: set[str] = set(_BASE_ALLOW) | set(_FRAMEWORK_ALLOW)
+    allow_exact |= _extra_allowlist()
+    if skill_env_keys:
+        allow_exact |= {str(k).strip() for k in skill_env_keys if str(k).strip()}
+    if extra_keys:
+        allow_exact |= {str(k).strip() for k in extra_keys if str(k).strip()}
+
+    return {key: value for key, value in src.items() if _is_allowed(key, allow_exact)}
+
+
+def sensitive_env_values(
+    source_env: dict[str, str] | None = None,
+    *,
+    extra_allowed: Iterable[str] | None = None,
+) -> list[str]:
+    """Renvoie les valeurs des variables d'env considérées sensibles.
+
+    Utilisé pour alimenter le ``SecretRedactor`` : toute variable qui n'est pas
+    dans le socle système / wiring framework est considérée comme potentiellement
+    secrète, plus les variables sensibles qui restent exposées au shell
+    (``API_KEYS`` notamment).
+
+    Args:
+        source_env: Environnement source (défaut ``os.environ``).
+        extra_allowed: Clés exposées au shell (skills chargées) dont la valeur
+            doit malgré tout être masquée si elle ressemble à un secret.
+
+    Returns:
+        Liste de valeurs (chaînes) à masquer. Doublons et vides inclus — le
+        ``SecretRedactor`` les filtre et déduplique.
+    """
+    src = dict(source_env if source_env is not None else os.environ)
+    allow_exact: set[str] = set(_BASE_ALLOW)
+    values: list[str] = []
+    for key, value in src.items():
+        if not value:
+            continue
+        # Variables système non sensibles: ignorées.
+        if _is_allowed(key, allow_exact):
+            continue
+        # Wiring framework non secret: ne pas masquer (sinon on masque host/port,
+        # session_id, etc.). Seul API_KEYS du framework est secret.
+        if key in _FRAMEWORK_ALLOW and key != "API_KEYS":
+            continue
+        values.append(value)
+    # API_KEYS peut contenir plusieurs clés séparées par des virgules.
+    api_keys = src.get("API_KEYS", "").strip()
+    if api_keys:
+        values.extend(k.strip() for k in api_keys.split(",") if k.strip())
+    return values
+
+
+__all__ = [
+    "build_shell_env",
+    "sensitive_env_values",
+    "shell_env_mode",
+]