skills_ast_audit.py 4.0 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192
  1. """AST-level deep audit for skill Python files — opt-in diagnostic (``hermes skills audit --deep``), not a
  2. security gate (SECURITY.md §2.4). Flags dynamic import / attribute access for human review; every pattern has
  3. legitimate uses, so findings are hints, not verdicts."""
  4. from __future__ import annotations
  5. import ast
  6. from contextlib import suppress
  7. from pathlib import Path
  8. from typing import List, Tuple
  9. # (file, line, pattern_id, description)
  10. Finding = tuple[str, int, str, str]
  11. _IGNORED_DIRS = {"__pycache__", ".venv", "venv", "node_modules"}
  12. # builtin name -> (index of the argument that must be a literal, pattern_id, description)
  13. _DYNAMIC_CALLS = {"__import__": (0, "dynamic_import_computed", "__import__ with non-literal module name"),
  14. "getattr": (1, "dynamic_getattr", "getattr with non-literal attribute name")}
  15. def _is_importlib(name: str) -> bool:
  16. return name == "importlib" or name.startswith("importlib.")
  17. def _scan_source(content: str, rel_path: str) -> list[Finding]:
  18. try:
  19. tree = ast.parse(content)
  20. except (SyntaxError, ValueError, RecursionError):
  21. return []
  22. findings: list[Finding] = []
  23. hit = lambda node, pid, desc: findings.append((rel_path, node.lineno, pid, desc))
  24. class V(ast.NodeVisitor):
  25. def visit_Call(self, node):
  26. f = node.func
  27. if isinstance(f, ast.Attribute) and f.attr == "import_module":
  28. hit(node, "dynamic_import", "importlib.import_module() — loads arbitrary modules at runtime")
  29. elif isinstance(f, ast.Name) and f.id in _DYNAMIC_CALLS:
  30. arg_index, pid, desc = _DYNAMIC_CALLS[f.id]
  31. if len(node.args) > arg_index and not isinstance(node.args[arg_index], ast.Constant):
  32. hit(node, pid, desc)
  33. self.generic_visit(node)
  34. def visit_Subscript(self, node):
  35. if (isinstance(node.value, ast.Attribute) and node.value.attr == "__dict__"
  36. and not isinstance(node.slice, ast.Constant)):
  37. hit(node, "dict_access", "__dict__[<computed>] — dynamic attribute access")
  38. self.generic_visit(node)
  39. def visit_Import(self, node):
  40. for a in node.names:
  41. if _is_importlib(a.name):
  42. hit(node, "importlib_import", f"import {a.name} — enables dynamic module loading")
  43. self.generic_visit(node)
  44. def visit_ImportFrom(self, node):
  45. if _is_importlib(node.module or ""):
  46. hit(node, "importlib_import", f"from {node.module} import ... — enables dynamic module loading")
  47. self.generic_visit(node)
  48. with suppress(RecursionError, ValueError, RuntimeError): # hostile input: keep what was collected so far
  49. V().visit(tree)
  50. return findings
  51. def _scan_file(py: Path, rel: str) -> list[Finding]:
  52. try:
  53. return _scan_source(py.read_text(encoding="utf-8-sig", errors="replace"), rel)
  54. except OSError:
  55. return []
  56. def ast_scan_path(path: Path) -> list[Finding]:
  57. """Scan one .py file or every .py under a directory; [] for non-Python/missing paths."""
  58. if path.is_file():
  59. return _scan_file(path, path.name) if path.suffix.lower() == ".py" else []
  60. return [f for py in sorted(path.rglob("*.py")) if not set(py.parent.parts) & _IGNORED_DIRS
  61. for f in _scan_file(py, py.relative_to(path).as_posix())] if path.is_dir() else []
  62. def format_ast_report(findings: list[Finding], skill_name: str = "") -> str:
  63. """Plain-text (Rich-markup-free) report grouped by file."""
  64. header = f"AST deep scan: {skill_name}" if skill_name else "AST deep scan"
  65. if not findings:
  66. return f"{header}\n No dynamic import/access patterns detected."
  67. lines, current = [header, f" {len(findings)} finding(s):"], None
  68. for f, line, pid, desc in sorted(findings):
  69. if f != current:
  70. current = f
  71. lines.append(f" {f}")
  72. lines.append(f" L{line} {pid} — {desc}")
  73. return "\n".join(lines + ["", " Note: diagnostic hints for human review, not security verdicts."])