@jaguilar87/gaia 5.0.9 → 5.0.10

package/hooks/modules/security/inline_ast_analyzer.py

@@ -38,6 +38,7 @@ from __future__ import annotations
 
 import ast
 import logging
+import re
 from dataclasses import dataclass
 from typing import FrozenSet, Optional, Set, Tuple
 
@@ -239,6 +240,242 @@ def analyze_python_inline(code: str) -> InlineAstResult:
     return InlineAstResult()
 
 
+# ============================================================================
+# Provable read-only classification (positive allowlist)
+# ============================================================================
+# Rationale: ``analyze_python_inline`` uses a *blocklist* — a clean result
+# means "no KNOWN dangerous call was found", which is NOT the same as
+# "read-only".  Bound-method mutations the catalog cannot see statically —
+# ``cur.execute("INSERT ...")``, ``con.commit()``, ``f.write(...)`` on a
+# handle whose write-mode was set elsewhere — parse cleanly yet mutate.
+#
+# This second classifier exists ONLY to safely exempt long-but-harmless
+# inline code from the length heuristic (``heuristic-long-code``).  It is the
+# inverse discipline: it returns True ONLY when EVERY statement and EVERY call
+# in the payload is on a positive read-only allowlist.  Anything unrecognized
+# — any node type, call target, assignment target, or SQL verb it cannot
+# prove safe — makes it return False, leaving the length heuristic in force.
+# No-false-negative is the contract: a mutation must never be classified
+# read-only, even at the cost of leaving some genuinely-read-only payloads
+# subject to the length flag (those remain T3-approvable, never silently run).
+
+# Builtins that never mutate external state.  Deliberately conservative:
+# ``open`` is excluded (write modes), ``exec``/``eval``/``compile``/
+# ``__import__``/``input``/``getattr``/``setattr``/``delattr`` are excluded
+# (dynamic dispatch defeats static analysis), ``print`` is allowed (stdout
+# only).
+_READ_ONLY_BUILTINS: FrozenSet[str] = frozenset({
+    "print", "len", "str", "repr", "int", "float", "bool", "list", "tuple",
+    "dict", "set", "frozenset", "sorted", "reversed", "enumerate", "zip",
+    "map", "filter", "range", "sum", "min", "max", "abs", "round", "any",
+    "all", "format", "ascii", "bin", "hex", "oct", "ord", "chr", "type",
+    "isinstance", "issubclass", "hasattr", "iter", "next", "bytes",
+    "bytearray", "id", "hash", "divmod", "pow", "vars", "dir",
+})
+
+# Read-only methods, matched by leaf attribute name regardless of receiver.
+# These are common DB-cursor / mapping / sequence / string read accessors.
+# ``execute``/``executemany``/``executescript`` are handled SEPARATELY: they
+# are allowed ONLY when the SQL argument is a literal read-only statement.
+_READ_ONLY_METHODS: FrozenSet[str] = frozenset({
+    # DB cursor/connection read surface
+    "fetchone", "fetchall", "fetchmany", "cursor", "close",
+    # mapping / sequence reads
+    "keys", "values", "items", "get", "copy", "index", "count",
+    # string reads
+    "strip", "lstrip", "rstrip", "split", "rsplit", "splitlines", "join",
+    "lower", "upper", "title", "capitalize", "startswith", "endswith",
+    "find", "rfind", "format", "encode", "decode", "replace", "zfill",
+    "ljust", "rjust", "center",
+    # iteration / misc pure reads
+    "isoformat", "total_seconds", "group", "groups", "groupdict", "read",
+    "readline", "readlines",
+})
+
+# SQL statement prefixes that are read-only.  Matched case-insensitively
+# against the leading token of a literal SQL string.  ``WITH`` (CTE) is
+# allowed only when it ultimately SELECTs — but a CTE can wrap an
+# INSERT/UPDATE/DELETE (``WITH x AS (...) DELETE ...``), so to stay airtight
+# we require the literal to ALSO contain no mutating keyword.  Simpler and
+# safer: allow the prefix, then reject if any mutating keyword appears
+# anywhere in the literal.
+_READ_ONLY_SQL_PREFIXES: Tuple[str, ...] = (
+    "select", "pragma", "explain", "with", "values", "show",
+)
+_MUTATING_SQL_KEYWORDS: Tuple[str, ...] = (
+    "insert", "update", "delete", "drop", "create", "alter", "replace",
+    "truncate", "attach", "detach", "vacuum", "reindex", "commit",
+    "rollback", "savepoint", "grant", "revoke", "merge", "upsert", "begin",
+)
+_SQL_EXEC_METHODS: FrozenSet[str] = frozenset({
+    "execute", "executemany", "executescript",
+})
+
+
+def is_provably_read_only_python(code: str) -> bool:
+    """Return True ONLY if every construct in ``code`` is provably read-only.
+
+    Positive allowlist over the AST.  Any node type, call, assignment target,
+    or SQL verb that cannot be proven safe returns False.  Used to exempt
+    long-but-harmless inline code from the length heuristic; never used to
+    grant execution by itself.
+
+    Args:
+        code: Python source extracted from ``python3 -c "..."`` (unquoted).
+
+    Returns:
+        True when the payload contains exclusively read-only constructs;
+        False on any uncertainty (including parse failure).
+    """
+    if not code or not code.strip():
+        # Empty payload: nothing to exempt; let caller's default path handle.
+        return False
+
+    try:
+        tree = ast.parse(code, mode="exec")
+    except SyntaxError:
+        return False
+
+    checker = _ReadOnlyChecker()
+    return checker.is_read_only(tree)
+
+
+class _ReadOnlyChecker:
+    """Walks an AST and proves it contains only read-only constructs."""
+
+    # Statement node types that are structurally inert (control flow,
+    # definitions, expression evaluation).  Mutation can only happen via a
+    # Call, an attribute/subscript assignment, del, or import side effects —
+    # all handled explicitly below.
+    _ALLOWED_STMT_TYPES = (
+        ast.Import, ast.ImportFrom, ast.Expr, ast.Assign, ast.AnnAssign,
+        ast.AugAssign, ast.For, ast.While, ast.If, ast.With, ast.FunctionDef,
+        ast.Return, ast.Pass, ast.Break, ast.Continue, ast.Assert,
+        ast.AsyncFunctionDef, ast.AsyncFor, ast.AsyncWith,
+    )
+
+    def is_read_only(self, tree: ast.AST) -> bool:
+        for node in ast.walk(tree):
+            # Reject statements we do not explicitly allow.
+            if isinstance(node, ast.stmt):
+                if not isinstance(node, self._ALLOWED_STMT_TYPES):
+                    return False
+                # ``del`` removes bindings / can call __delitem__/__delattr__.
+                if isinstance(node, ast.Delete):
+                    return False
+            # Assignment targets must be plain names or name-tuples.  A
+            # Subscript or Attribute target (``os.environ[k]=v``,
+            # ``obj.attr=v``) can mutate external state via __setitem__ /
+            # __setattr__.
+            if isinstance(node, (ast.Assign, ast.AnnAssign, ast.AugAssign)):
+                if not self._targets_are_local(node):
+                    return False
+            # Every call must be on the allowlist.
+            if isinstance(node, ast.Call):
+                if not self._call_is_read_only(node):
+                    return False
+            # ``with`` items: the context manager is itself a Call/expr and is
+            # validated by the Call check above; nothing extra needed.
+        return True
+
+    def _targets_are_local(self, node: ast.AST) -> bool:
+        targets = []
+        if isinstance(node, ast.Assign):
+            targets = node.targets
+        elif isinstance(node, (ast.AnnAssign, ast.AugAssign)):
+            targets = [node.target]
+        for tgt in targets:
+            if not self._is_local_target(tgt):
+                return False
+        return True
+
+    def _is_local_target(self, tgt: ast.AST) -> bool:
+        if isinstance(tgt, ast.Name):
+            return True
+        if isinstance(tgt, (ast.Tuple, ast.List)):
+            return all(self._is_local_target(e) for e in tgt.elts)
+        if isinstance(tgt, ast.Starred):
+            return self._is_local_target(tgt.value)
+        # Subscript / Attribute targets can mutate external state.
+        return False
+
+    def _call_is_read_only(self, node: ast.Call) -> bool:
+        func = node.func
+        # Bare name call: must be a read-only builtin.  (Unresolved local
+        # function calls are rejected — we cannot prove their body is safe.)
+        if isinstance(func, ast.Name):
+            return func.id in _READ_ONLY_BUILTINS
+        # Attribute call: ``x.method(...)``.
+        if isinstance(func, ast.Attribute):
+            method = func.attr
+            if method in _SQL_EXEC_METHODS:
+                return self._sql_arg_is_read_only(node)
+            if method in _READ_ONLY_METHODS:
+                return True
+            # Allow ``sqlite3.connect(...)`` and module-qualified pure reads
+            # we can name explicitly; everything else is rejected.
+            return self._dotted_call_is_read_only(func)
+        # Any other callable form (subscript result, lambda, call chain head)
+        # cannot be proven safe.
+        return False
+
+    def _dotted_call_is_read_only(self, func: ast.Attribute) -> bool:
+        # Build dotted source name (best-effort).  Only a tiny set of
+        # module-level read-only constructors are permitted.
+        parts = []
+        cur: ast.AST = func
+        while isinstance(cur, ast.Attribute):
+            parts.append(cur.attr)
+            cur = cur.value
+        if isinstance(cur, ast.Name):
+            parts.append(cur.id)
+            parts.reverse()
+            dotted = ".".join(parts)
+            return dotted in _READ_ONLY_DOTTED_CALLS
+        return False
+
+    def _sql_arg_is_read_only(self, node: ast.Call) -> bool:
+        # ``execute``/``executemany`` are read-only ONLY when the first
+        # positional argument is a string LITERAL whose leading token is a
+        # read-only SQL verb AND which contains no mutating keyword.  A
+        # non-literal SQL argument (variable, f-string, concatenation) cannot
+        # be proven safe and is rejected.
+        if not node.args:
+            return False
+        first = node.args[0]
+        if not (isinstance(first, ast.Constant) and isinstance(first.value, str)):
+            return False
+        sql = first.value.strip().lower()
+        if not sql:
+            return False
+        # Strip a leading comment / whitespace already done; take first word.
+        leading = sql.split(None, 1)[0] if sql.split() else ""
+        if leading not in _READ_ONLY_SQL_PREFIXES:
+            return False
+        # Reject if ANY mutating keyword appears anywhere (defeats CTE-wrapped
+        # writes like ``WITH x AS (...) DELETE ...`` and stacked statements).
+        for kw in _MUTATING_SQL_KEYWORDS:
+            if re.search(r"\b" + re.escape(kw) + r"\b", sql):
+                return False
+        return True
+
+
+# Module-level read-only constructors permitted in a provable-read-only
+# payload (dotted source names).  ``sqlite3.connect`` opens a handle;
+# mutation would require a subsequent write call, which is independently
+# checked.  Kept deliberately small.
+_READ_ONLY_DOTTED_CALLS: FrozenSet[str] = frozenset({
+    "sqlite3.connect",
+    "json.dumps", "json.loads", "json.load",
+    "os.getcwd", "os.getenv", "os.listdir", "os.path.join", "os.path.exists",
+    "os.path.basename", "os.path.dirname", "os.path.abspath",
+    "os.path.isfile", "os.path.isdir", "os.path.getsize",
+    "sys.exit",
+    "datetime.now", "datetime.utcnow", "time.time",
+    "pathlib.Path", "Path",
+})
+
+
 # ============================================================================
 # Internal helpers
 # ============================================================================