| 1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192 |
- """AST-level deep audit for skill Python files — opt-in diagnostic (``hermes skills audit --deep``), not a
- security gate (SECURITY.md §2.4). Flags dynamic import / attribute access for human review; every pattern has
- legitimate uses, so findings are hints, not verdicts."""
- from __future__ import annotations
- import ast
- from contextlib import suppress
- from pathlib import Path
- from typing import List, Tuple
- # (file, line, pattern_id, description)
- Finding = tuple[str, int, str, str]
- _IGNORED_DIRS = {"__pycache__", ".venv", "venv", "node_modules"}
- # builtin name -> (index of the argument that must be a literal, pattern_id, description)
- _DYNAMIC_CALLS = {"__import__": (0, "dynamic_import_computed", "__import__ with non-literal module name"),
- "getattr": (1, "dynamic_getattr", "getattr with non-literal attribute name")}
- def _is_importlib(name: str) -> bool:
- return name == "importlib" or name.startswith("importlib.")
- def _scan_source(content: str, rel_path: str) -> list[Finding]:
- try:
- tree = ast.parse(content)
- except (SyntaxError, ValueError, RecursionError):
- return []
- findings: list[Finding] = []
- hit = lambda node, pid, desc: findings.append((rel_path, node.lineno, pid, desc))
- class V(ast.NodeVisitor):
- def visit_Call(self, node):
- f = node.func
- if isinstance(f, ast.Attribute) and f.attr == "import_module":
- hit(node, "dynamic_import", "importlib.import_module() — loads arbitrary modules at runtime")
- elif isinstance(f, ast.Name) and f.id in _DYNAMIC_CALLS:
- arg_index, pid, desc = _DYNAMIC_CALLS[f.id]
- if len(node.args) > arg_index and not isinstance(node.args[arg_index], ast.Constant):
- hit(node, pid, desc)
- self.generic_visit(node)
- def visit_Subscript(self, node):
- if (isinstance(node.value, ast.Attribute) and node.value.attr == "__dict__"
- and not isinstance(node.slice, ast.Constant)):
- hit(node, "dict_access", "__dict__[<computed>] — dynamic attribute access")
- self.generic_visit(node)
- def visit_Import(self, node):
- for a in node.names:
- if _is_importlib(a.name):
- hit(node, "importlib_import", f"import {a.name} — enables dynamic module loading")
- self.generic_visit(node)
- def visit_ImportFrom(self, node):
- if _is_importlib(node.module or ""):
- hit(node, "importlib_import", f"from {node.module} import ... — enables dynamic module loading")
- self.generic_visit(node)
- with suppress(RecursionError, ValueError, RuntimeError): # hostile input: keep what was collected so far
- V().visit(tree)
- return findings
- def _scan_file(py: Path, rel: str) -> list[Finding]:
- try:
- return _scan_source(py.read_text(encoding="utf-8-sig", errors="replace"), rel)
- except OSError:
- return []
- def ast_scan_path(path: Path) -> list[Finding]:
- """Scan one .py file or every .py under a directory; [] for non-Python/missing paths."""
- if path.is_file():
- return _scan_file(path, path.name) if path.suffix.lower() == ".py" else []
- return [f for py in sorted(path.rglob("*.py")) if not set(py.parent.parts) & _IGNORED_DIRS
- for f in _scan_file(py, py.relative_to(path).as_posix())] if path.is_dir() else []
- def format_ast_report(findings: list[Finding], skill_name: str = "") -> str:
- """Plain-text (Rich-markup-free) report grouped by file."""
- header = f"AST deep scan: {skill_name}" if skill_name else "AST deep scan"
- if not findings:
- return f"{header}\n No dynamic import/access patterns detected."
- lines, current = [header, f" {len(findings)} finding(s):"], None
- for f, line, pid, desc in sorted(findings):
- if f != current:
- current = f
- lines.append(f" {f}")
- lines.append(f" L{line} {pid} — {desc}")
- return "\n".join(lines + ["", " Note: diagnostic hints for human review, not security verdicts."])
|