approvals_suggest.py 16 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388
  1. """``hermes approvals suggest`` — mine approval history into allowlist proposals.
  2. Hermes has no dedicated approval-decision ledger: ``always`` answers land in ``command_allowlist``
  3. (config.yaml) via :func:`tools.approval.save_permanent_allowlist`, while ``once``/``session``
  4. approvals are in-memory only. So this module mines *implied approvals*: a command that matches a
  5. dangerous-command class (the same :func:`tools.approval.detect_dangerous_command` classifier that
  6. triggers the prompt) AND whose tool result is not a block/denial marker must have been approved by
  7. the user (once, session, always, smart-approve, or yolo) before it ran.
  8. """
  9. from __future__ import annotations
  10. import json
  11. import re
  12. import sqlite3
  13. import time
  14. from dataclasses import dataclass, field
  15. from pathlib import Path
  16. from typing import Iterable, Iterator, Optional
  17. # ---------------------------------------------------------------------------
  18. # Safety exclusions
  19. # ---------------------------------------------------------------------------
  20. # Dangerous-class descriptions matching ANY of these are never proposed, regardless of approval
  21. # frequency (matched case-insensitively against tools.approval's DANGEROUS_PATTERNS / execution-flag
  22. # descriptions). Deliberately conservative: a benign class accidentally excluded costs the user
  23. # one manual config edit; a destructive class accidentally proposed costs them data.
  24. _UNSAFE_CLASS_PATTERNS = [
  25. # deletion / destruction: recursive delete, find -delete, xargs rm, git reset --hard, mkfs, dd
  26. r"delete", r"\brm\b", r"destro", r"wipe", r"format", r"\bdisk\b", r"block device", r"\bdd\b",
  27. # process / host: fork bomb, force/regex/all kills, self-termination, shutdown
  28. r"fork bomb", r"kill (?:all )?process", r"kill all", r"self-termination", r"shutdown", r"reboot",
  29. # privilege / credentials / system files
  30. r"\bsudo\b", r"privilege", r"credential", r"\bssh\b", r"shell.rc", r"system config", r"system file",
  31. # data & permissions: SQL DROP/TRUNCATE/DELETE-without-WHERE, chown/chmod, world-writable, overwrite
  32. r"\bsql\b", r"\bchown\b", r"\bchmod\b", r"writable", r"overwrite", r"in-place edit",
  33. # remote/obfuscated execution: pipe-to-shell, encoded PowerShell, heredoc, substitutions
  34. r"pipe", r"obfuscation", r"remote content", r"remote script", r"heredoc", r"encoded",
  35. r"command substitution", r"process substitution",
  36. r"hardline",
  37. ]
  38. _UNSAFE_CLASS_RE = re.compile("|".join(_UNSAFE_CLASS_PATTERNS), re.IGNORECASE)
  39. # Root binaries that must never anchor a proposed command glob, even if the class survived the
  40. # description filter. Prefix match for the mkfs family.
  41. _UNSAFE_ROOT_BINARIES = {
  42. "rm", "rmdir", "unlink", "shred", "dd", "fdisk", "parted", "wipefs",
  43. "sudo", "doas", "su", "chmod", "chown", "chgrp",
  44. "kill", "killall", "pkill",
  45. "halt", "shutdown", "reboot", "poweroff", "init",
  46. "del", "format", "truncate", "mkswap",
  47. }
  48. _UNSAFE_ROOT_PREFIXES = ("mkfs",)
  49. # Substrings in a role='tool' result that mean the command did NOT execute with user consent
  50. # (blocked, denied, timed out, or still pending). Kept in sync with tools/approval.py templates.
  51. _BLOCK_MARKERS = (
  52. "BLOCKED (hardline)", "BLOCKED: User denied", "BLOCKED: Action ",
  53. "BLOCKED: Command flagged as dangerous", "BLOCKED: approval required",
  54. "BLOCKED: Failed to send approval request", "The user has NOT consented",
  55. "Asking the user for approval", "approval_required", "BLOCKED by user deny rule",
  56. )
  57. @dataclass
  58. class Proposal:
  59. """One ranked allowlist proposal."""
  60. pattern: str # command glob ("git push *") or class key
  61. kind: str # "glob" | "class"
  62. count: int = 0
  63. classes: set = field(default_factory=set)
  64. examples: list = field(default_factory=list)
  65. def add_example(self, command: str) -> None:
  66. short = command.strip()
  67. if len(short) > 100:
  68. short = short[:97] + "..."
  69. if short not in self.examples and len(self.examples) < 3:
  70. self.examples.append(short)
  71. # ---------------------------------------------------------------------------
  72. # Scan: session DB -> (command, class description) records
  73. # ---------------------------------------------------------------------------
  74. def default_db_path() -> Path:
  75. from hermes_constants import get_hermes_home
  76. return get_hermes_home() / "state.db"
  77. def _connect_readonly(db_path: Path) -> sqlite3.Connection:
  78. return sqlite3.connect(f"file:{db_path}?mode=ro", uri=True)
  79. def _fetch_rows(cur) -> Iterator[tuple]:
  80. """Stream cursor rows in 2000-row batches."""
  81. while rows := cur.fetchmany(2000):
  82. yield from rows
  83. def _json_or_none(raw):
  84. try:
  85. return json.loads(raw)
  86. except (TypeError, ValueError):
  87. return None
  88. def _iter_terminal_calls(con: sqlite3.Connection, since_ts: float) -> Iterator[tuple[str, str]]:
  89. """Yield ``(tool_call_id, command)`` for every terminal tool call."""
  90. cur = con.execute(
  91. "SELECT tool_calls FROM messages WHERE role='assistant' AND tool_calls IS NOT NULL "
  92. "AND tool_calls LIKE '%terminal%' AND timestamp >= ?",
  93. (since_ts,),
  94. )
  95. for (raw,) in _fetch_rows(cur):
  96. calls = _json_or_none(raw)
  97. for call in calls if isinstance(calls, list) else ():
  98. fn = call.get("function") or {} if isinstance(call, dict) else {}
  99. if fn.get("name") != "terminal":
  100. continue
  101. args = _json_or_none(fn.get("arguments") or "{}")
  102. if args is None:
  103. continue
  104. command = args.get("command")
  105. if isinstance(command, str) and command.strip():
  106. yield (call.get("id") or "", command)
  107. def _blocked_tool_call_ids(con: sqlite3.Connection, since_ts: float) -> set:
  108. """Collect tool_call_ids whose result shows the command never ran freely."""
  109. cur = con.execute(
  110. "SELECT tool_call_id, content FROM messages "
  111. "WHERE role='tool' AND tool_call_id IS NOT NULL AND timestamp >= ? "
  112. "AND (content LIKE '%BLOCKED%' OR content LIKE '%approval%')",
  113. (since_ts,),
  114. )
  115. return {
  116. tool_call_id
  117. for tool_call_id, content in _fetch_rows(cur)
  118. if content and any(marker in content for marker in _BLOCK_MARKERS)
  119. }
  120. def scan_approval_history(db_path: Optional[Path] = None, days: int = 90) -> list[tuple[str, str]]:
  121. """``(command, dangerous_class_description)`` records for dangerous-classified terminal commands
  122. that actually executed (i.e. carried an implied user approval).
  123. """
  124. from tools.approval_detection import detect_dangerous_command, detect_hardline_command
  125. path = Path(db_path) if db_path else default_db_path()
  126. if not path.exists():
  127. return []
  128. since_ts = 0.0 if days <= 0 else time.time() - days * 86400
  129. records: list[tuple[str, str]] = []
  130. con = _connect_readonly(path)
  131. try:
  132. blocked = _blocked_tool_call_ids(con, since_ts)
  133. for tool_call_id, command in _iter_terminal_calls(con, since_ts):
  134. if tool_call_id in blocked:
  135. continue
  136. # Hardline commands are unconditionally blocked at runtime; never mine them (defense in
  137. # depth against stale DB rows).
  138. if detect_hardline_command(command)[0]:
  139. continue
  140. is_dangerous, _key, description = detect_dangerous_command(command)
  141. if is_dangerous:
  142. records.append((command, description))
  143. finally:
  144. con.close()
  145. return records
  146. # ---------------------------------------------------------------------------
  147. # Normalize -> aggregate -> rank -> exclude
  148. # ---------------------------------------------------------------------------
  149. def normalize_command(command: str) -> str:
  150. """Fold user/hermes home prefixes and collapse whitespace."""
  151. from tools.approval_detection import _rewrite_resolved_hermes_home, _rewrite_resolved_user_home
  152. return " ".join(_rewrite_resolved_user_home(_rewrite_resolved_hermes_home(command)).split())
  153. def is_unsafe_class(description: str) -> bool:
  154. """True when a dangerous-class description must never be proposed."""
  155. return bool(_UNSAFE_CLASS_RE.search(description or ""))
  156. def _unsafe_root_binary(token: str) -> bool:
  157. tok = token.lower().rsplit("/", 1)[-1]
  158. return tok in _UNSAFE_ROOT_BINARIES or tok.startswith(_UNSAFE_ROOT_PREFIXES)
  159. def derive_glob(normalized: str) -> Optional[str]:
  160. """Derive a narrow command glob (``git push *``) from a simple command.
  161. Returns None for compound commands (shell operators — the runtime allowlist matcher refuses
  162. those anyway) and for commands anchored on an unsafe root binary.
  163. """
  164. from tools.approval_floors import _has_allowlist_shell_operator
  165. tokens = normalized.split()
  166. if _has_allowlist_shell_operator(normalized) or not tokens or _unsafe_root_binary(tokens[0]):
  167. return None
  168. if len(tokens) == 1:
  169. return tokens[0]
  170. second = tokens[1]
  171. if second.startswith("-") or any(ch in second for ch in "*?[$"):
  172. return f"{tokens[0]} *"
  173. return f"{tokens[0]} {second} *"
  174. def build_proposals(
  175. records: Iterable[tuple[str, str]], existing: Optional[set] = None, min_count: int = 2,
  176. limit: int = 20,
  177. ) -> list[Proposal]:
  178. """Aggregate scan records into a ranked, safety-filtered proposal list.
  179. Grain: a command glob (``git push *``) for simple commands; the dangerous-class description
  180. itself (the same key an interactive ``[a]lways`` answer persists) for compound commands where no
  181. safe glob can be derived.
  182. """
  183. from agent.redact import redact_sensitive_text
  184. existing = existing or set()
  185. by_pattern: dict[tuple[str, str], Proposal] = {}
  186. for command, description in records:
  187. if is_unsafe_class(description):
  188. continue
  189. # Commands mined from past tool calls can embed credentials (URL userinfo,
  190. # env assignments, bearer tokens). Examples are echoed to the operator, so
  191. # mask them like every other display boundary — classification above
  192. # still sees the raw command. The glob is derived from the raw command:
  193. # a redacted `***` inside a persisted pattern would be three fnmatch
  194. # wildcards, so when redaction touches the tokens the glob embeds, the
  195. # command is proposed under its class key instead.
  196. raw = normalize_command(command)
  197. normalized = redact_sensitive_text(raw, force=True)
  198. glob = derive_glob(raw)
  199. if glob is not None and derive_glob(normalized) != glob:
  200. glob = None
  201. pattern, kind = (glob, "glob") if glob is not None else (description, "class")
  202. if pattern in existing:
  203. continue
  204. proposal = by_pattern.setdefault((pattern, kind), Proposal(pattern=pattern, kind=kind))
  205. proposal.count += 1
  206. proposal.classes.add(description)
  207. proposal.add_example(normalized)
  208. ranked = sorted((p for p in by_pattern.values() if p.count >= max(min_count, 1)), key=lambda p: (-p.count, p.pattern))
  209. return ranked[: max(limit, 1)]
  210. # ---------------------------------------------------------------------------
  211. # Apply / render
  212. # ---------------------------------------------------------------------------
  213. def parse_apply_indices(spec: str, total: int) -> list[int]:
  214. """Parse ``"1,3"`` into validated zero-based indices."""
  215. indices: list[int] = []
  216. for part in (spec or "").split(","):
  217. part = part.strip()
  218. if not part:
  219. continue
  220. try:
  221. n = int(part)
  222. except ValueError:
  223. raise ValueError(f"invalid selection {part!r} — expected numbers like 1,3")
  224. if n < 1 or n > total:
  225. raise ValueError(f"selection {n} out of range (1..{total})")
  226. if (n - 1) not in indices:
  227. indices.append(n - 1)
  228. if not indices:
  229. raise ValueError("no valid selections in --apply")
  230. return indices
  231. def apply_proposals(proposals: list[Proposal], indices: list[int]) -> set:
  232. """Merge chosen proposal patterns into command_allowlist and persist."""
  233. import tools.approval as approval_module
  234. merged = set(approval_module.load_permanent_allowlist()) | {proposals[idx].pattern for idx in indices}
  235. approval_module.save_permanent_allowlist(merged)
  236. # Keep the in-process allowlist consistent so a long-lived process sees the new entries
  237. # immediately (mirrors the interactive 'always' path).
  238. approval_module.load_permanent(merged)
  239. return merged
  240. def _render_text(proposals: list[Proposal], days: int) -> None:
  241. window = "all history" if days <= 0 else f"last {days} days"
  242. if not proposals:
  243. print(
  244. f"No allowlist candidates found in approval history ({window}).\n"
  245. "Either nothing dangerous was approved often enough "
  246. "(see --min-count/--days), or the approved classes are excluded for safety."
  247. )
  248. return
  249. print(f"Proposed command_allowlist additions (from approval history, {window}):\n")
  250. for i, p in enumerate(proposals, 1):
  251. kind = " (class key)" if p.kind == "class" else ""
  252. print(f" {i}. {p.pattern} — approved {p.count}x{kind}")
  253. for cls in sorted(p.classes):
  254. print(f" class: {cls}")
  255. for ex in p.examples:
  256. print(f" e.g. {ex}")
  257. print(
  258. "\nNothing has been changed. Apply selected entries with:\n"
  259. " hermes approvals suggest --apply 1,3\n"
  260. "Entries are merged into command_allowlist in ~/.hermes/config.yaml."
  261. )
  262. def suggest_command(args) -> int:
  263. """Entry point for ``hermes approvals suggest``."""
  264. db_path = Path(args.db) if getattr(args, "db", None) else default_db_path()
  265. days = getattr(args, "days", 90)
  266. if not db_path.exists():
  267. print(f"Session database not found: {db_path}")
  268. return 1
  269. import tools.approval as approval_module
  270. existing = set(approval_module.load_permanent_allowlist())
  271. proposals = build_proposals(
  272. scan_approval_history(db_path, days=days), existing=existing,
  273. min_count=getattr(args, "min_count", 2), limit=getattr(args, "limit", 20),
  274. )
  275. as_json = getattr(args, "json", False)
  276. apply_spec = getattr(args, "apply_indices", None)
  277. if apply_spec:
  278. try:
  279. indices = parse_apply_indices(apply_spec, len(proposals))
  280. except ValueError as exc:
  281. print(f"--apply error: {exc}")
  282. return 1
  283. merged = apply_proposals(proposals, indices)
  284. applied = [proposals[i].pattern for i in indices]
  285. if as_json:
  286. print(json.dumps({"applied": applied, "allowlist_size": len(merged)}))
  287. else:
  288. print("Added to command_allowlist:")
  289. for pattern in applied:
  290. print(f" + {pattern}")
  291. print(f"\ncommand_allowlist now has {len(merged)} entries (~/.hermes/config.yaml).")
  292. return 0
  293. if as_json:
  294. payload = {
  295. "db": str(db_path),
  296. "days": days,
  297. "proposals": [
  298. {
  299. "n": i, "pattern": p.pattern, "kind": p.kind, "count": p.count,
  300. "classes": sorted(p.classes), "examples": p.examples,
  301. }
  302. for i, p in enumerate(proposals, 1)
  303. ],
  304. }
  305. print(json.dumps(payload, indent=2))
  306. return 0
  307. _render_text(proposals, days)
  308. return 0
  309. def approvals_command(args) -> int:
  310. """Dispatch ``hermes approvals <subcommand>``."""
  311. sub = getattr(args, "approvals_command", None)
  312. if sub == "suggest":
  313. return suggest_command(args)
  314. if sub == "test":
  315. from hermes_cli.approvals_test import approvals_test_command
  316. return approvals_test_command(args)
  317. print(
  318. "usage: hermes approvals <subcommand>\n"
  319. "\n"
  320. "subcommands:\n"
  321. " suggest Mine past approval decisions into a proposed\n"
  322. " command_allowlist (dry by default; --apply N,M to merge)\n"
  323. " test Dry-run the approval verdict for a command without\n"
  324. " executing it (exit 0 allow / 2 ask / 3 deny)\n"
  325. "\n"
  326. "Run `hermes approvals <subcommand> -h` for details."
  327. )
  328. return 1