skill_lock.py 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441
  1. """User skill locks, enforced on every agent write path.
  2. ``hermes curator lock <skill>`` (or the Desktop lock switch) records ``locked: true`` beside
  3. ``pinned`` in the profile's ``skills/.usage.json``. While a skill is locked the agent cannot change
  4. it: ``skill_manage`` refuses every mutating action, ``write_file``/``patch`` refuse any path inside
  5. the skill's directory, and ``terminal`` refuses commands that write there. The lock record itself
  6. is protected the same way, and the agent cannot run ``hermes curator unlock``. The user's own edits
  7. (Desktop editor, their own editor, the CLI) are not gated.
  8. The terminal check reads the command's write targets (redirections, tee, cp/mv/rm/sed -i and
  9. friends, git in the skill's tree, ``cd`` into it, inline interpreter code naming it). It is a
  10. policy check, not a sandbox: a script that writes there through its own logic is not seen.
  11. """
  12. from __future__ import annotations
  13. import glob
  14. import itertools
  15. import os
  16. import re
  17. import shlex
  18. from typing import Iterable
  19. # Verbs whose every path operand is written (or removed/renamed).
  20. _WRITES_EVERY_OPERAND = frozenset({
  21. "rm", "rmdir", "unlink", "truncate", "shred", "touch", "chmod", "chown", "chgrp", "chattr",
  22. "setfacl", "mkdir", "mv", "patch", "dos2unix", "unix2dos", "xattr", "ed", "ex", "vi", "vim",
  23. "nvim", "nano", "emacs"})
  24. # Verbs that write only to their LAST operand (the destination).
  25. _WRITES_LAST_OPERAND = frozenset({"cp", "install", "ln", "rsync", "scp"})
  26. # Verbs that reach INTO a directory operand recursively, so an ancestor of a locked skill counts.
  27. _RECURSIVE = frozenset({"rm", "mv", "chmod", "chown", "chgrp", "chattr", "setfacl", "rsync", "find"})
  28. _INPLACE_EDITORS = frozenset({"sed", "perl", "ruby"})
  29. _GIT_MUTATIONS = frozenset({
  30. "add", "am", "apply", "checkout", "clean", "commit", "merge", "mv", "pull", "rebase", "reset",
  31. "restore", "revert", "rm", "stash", "switch", "cherry-pick"})
  32. _INTERPRETERS = re.compile(
  33. r"^(?:python[0-9.]*|node|nodejs|deno|bun|ruby|perl|php|bash|sh|zsh|dash|ksh|pwsh|powershell)$")
  34. _WRAPPERS = frozenset({"sudo", "env", "command", "builtin", "exec", "nohup", "setsid", "time", "nice", "xargs"})
  35. # Inline code that writes: open() with a write/append/create mode, pathlib/fs write calls, deletes,
  36. # renames, copies, and shell write forms. A plain open(path) / read stays allowed.
  37. _WRITEISH_CODE = re.compile(
  38. r"open\s*\([^)]*['\"][rbt]*[wax+][^'\"]*['\"]|\.write(?:_text|_bytes|lines)?\s*\(|"
  39. r"\b(?:unlink|rmtree|removedirs|remove|rmdir|rename|truncate|chmod|chown|mkdir|makedirs|symlink|"
  40. r"copyfile|copytree|copy2?|move|touch)\s*\(|\bos\.replace\s*\(|\.replace\s*\(\s*(?:Path|['\"]/)|"
  41. r"(?:write|append)File(?:Sync)?|(?:rm|unlink|rename|mkdir|copyFile|cp)Sync|"
  42. r"(?:^|[\s;|&])>{1,2}|\bsed\s+-i|\b(?:mv|rm|cp|tee|touch)\s", re.IGNORECASE)
  43. _SEPARATORS = frozenset({";", "&", "&&", "|", "||", "(", ")", "|&", ";;"})
  44. def _skill_usage():
  45. from tools import skill_usage
  46. return skill_usage
  47. def locked_skill_dirs() -> list[tuple[str, str]]:
  48. """``(name, realpath)`` of every locked skill in the active profile, from ONE walk of the
  49. skills dirs (locks are keyed by directory name, so no frontmatter is read)."""
  50. names = set(_skill_usage().locked_skill_names())
  51. if not names:
  52. return []
  53. from agent.skill_utils import get_all_skills_dirs, is_excluded_skill_path
  54. found: dict[str, str] = {}
  55. for base in get_all_skills_dirs():
  56. if not base.is_dir():
  57. continue
  58. for skill_md in base.rglob("SKILL.md"):
  59. name = skill_md.parent.name
  60. if name in names and name not in found and not is_excluded_skill_path(skill_md, root=base):
  61. found[name] = os.path.realpath(skill_md.parent)
  62. return sorted(found.items())
  63. def is_locked_skill(name: str, locked_names: Iterable[str] | None = None) -> bool:
  64. """Whether *name* (directory, ``cat/name`` or frontmatter name) is locked. Locks are keyed by
  65. directory name, while curator rows and some callers carry the frontmatter name."""
  66. names = set(_skill_usage().locked_skill_names() if locked_names is None else locked_names)
  67. if not names:
  68. return False
  69. if name in names or os.path.basename(name) in names:
  70. return True
  71. from tools.skill_manager_tool import _find_skill
  72. found = _find_skill(name)
  73. return bool(found) and found["path"].name in names
  74. def _record_path() -> str:
  75. return os.path.realpath(_skill_usage()._usage_file())
  76. def _inside(path: str, root: str) -> bool:
  77. return path == root or path.startswith(root.rstrip(os.sep) + os.sep)
  78. def skill_refusal(name: str) -> str:
  79. return (f"Skill '{name}' is locked by the user, so the agent cannot change it: skill_manage, "
  80. f"write_file, patch and terminal all refuse. Don't retry or work around it (no copying it "
  81. f"under another name); tell the user what you would change. They can unlock it with "
  82. f"`hermes curator unlock {name}` or the lock switch in Desktop.")
  83. RECORD_REFUSAL = ("skills/.usage.json holds the user's skill locks, so the agent cannot change it "
  84. "while any skill is locked.")
  85. UNLOCK_REFUSAL = ("Only the user can unlock a skill. Ask them to run `hermes curator unlock <skill>` "
  86. "themselves or use the lock switch in Desktop.")
  87. def _skills_roots() -> list[str]:
  88. from agent.skill_utils import get_all_skills_dirs
  89. return [os.path.realpath(d) for d in get_all_skills_dirs()]
  90. def _hit(path: str, locked: list[tuple[str, str]], record: str, *, ancestor: str = "") -> str | None:
  91. """Refusal text when *path* is the lock record or inside a locked skill. ``ancestor="any"`` also
  92. counts a directory ABOVE a locked skill (recursive deletes/moves); ``ancestor="skills"`` counts it
  93. only inside a skills root (a recursive copy or extraction there can merge into the skill)."""
  94. real = os.path.realpath(path)
  95. if real == record or (ancestor == "any" and real != os.sep and _inside(record, real)):
  96. return RECORD_REFUSAL
  97. for name, root in locked:
  98. if _inside(real, root):
  99. return skill_refusal(name)
  100. if ancestor and real != os.sep and _inside(root, real) and (
  101. ancestor == "any" or any(_inside(real, r) for r in _skills_roots())):
  102. return skill_refusal(name)
  103. return None
  104. def path_refusal(paths: Iterable[str]) -> str | None:
  105. """write_file/patch guard: refusal text when any path lands in a locked skill or the lock record."""
  106. locked = locked_skill_dirs()
  107. if not locked:
  108. return None
  109. record = _record_path()
  110. for path in paths:
  111. if path and (reason := _hit(path, locked, record)):
  112. return reason
  113. return None
  114. # ── terminal ──────────────────────────────────────────────────────────────────────────────────
  115. _VAR = re.compile(r"\$\{(\w+)\}|\$(\w+)")
  116. def _shell_env(assigned: dict[str, str] | None = None) -> dict[str, str]:
  117. from hermes_constants import get_hermes_home
  118. return {**os.environ, "HOME": os.path.expanduser("~"), "HERMES_HOME": str(get_hermes_home()),
  119. **(assigned or {})}
  120. def _expand(word: str, cwd: str, env: dict[str, str] | None = None) -> list[str]:
  121. """Shell word -> absolute path(s): $VARS (environment + assignments earlier in the command), ~,
  122. relative to *cwd*; a glob expands against the filesystem the way the shell would (unmatched:
  123. its literal directory prefix)."""
  124. env = env if env is not None else _shell_env()
  125. word = _VAR.sub(lambda m: env.get(m.group(1) or m.group(2), m.group(0)), word)
  126. home = env["HOME"]
  127. if word == "~" or word.startswith("~/"):
  128. word = home + word[1:]
  129. path = os.path.normpath(os.path.join(cwd, word))
  130. if not any(ch in word for ch in "*?["):
  131. return [path]
  132. if matches := glob.glob(path):
  133. return matches
  134. return [path[: min(path.index(ch) for ch in "*?[" if ch in path)].rsplit(os.sep, 1)[0] or os.sep]
  135. def _unquoted_newlines_to_semicolons(command: str) -> str:
  136. """Newlines separate commands like ``;`` does; shlex would read them as plain whitespace."""
  137. out, quote = [], None
  138. for ch in command:
  139. if quote:
  140. quote = None if ch == quote else quote
  141. elif ch in "'\"":
  142. quote = ch
  143. elif ch == "\n":
  144. ch = ";"
  145. out.append(ch)
  146. return "".join(out)
  147. def _tokens(command: str) -> list[str]:
  148. lexer = shlex.shlex(_unquoted_newlines_to_semicolons(command), posix=True, punctuation_chars=";&|<>()")
  149. lexer.whitespace_split = True
  150. lexer.commenters = ""
  151. try:
  152. return list(lexer)
  153. except ValueError: # unbalanced quotes: fall back to whitespace words
  154. return command.split()
  155. def _segments(tokens: list[str]) -> Iterable[tuple[list[str], list[str], str]]:
  156. """Yield ``(argv, redirect_targets, separator_that_ended_it)`` per simple command."""
  157. argv: list[str] = []
  158. targets: list[str] = []
  159. it = iter(tokens)
  160. for tok in it:
  161. if ">" in tok and set(tok) <= set("&>|0123456789"):
  162. if not tok.endswith("&"):
  163. target = next(it, "")
  164. if target and not target.startswith("&") and target != "/dev/null":
  165. targets.append(target)
  166. continue
  167. if tok in ("<", "<<", "<<<", "<<-"):
  168. next(it, "") # input file / heredoc delimiter / here-string: read, never written
  169. continue
  170. if tok and set(tok) <= set(";&|()"):
  171. yield argv, targets, tok
  172. argv, targets = [], []
  173. continue
  174. argv.append(tok)
  175. yield argv, targets, ""
  176. _XARGS_OPTIONS_WITH_ARG = frozenset({"-n", "-I", "-L", "-P", "-d", "-E", "-s", "-a"})
  177. def _strip_wrappers(argv: list[str]) -> list[str]:
  178. from tools.self_repo_guard import _WRAPPER_OPTIONS_WITH_ARG
  179. while argv:
  180. if re.match(r"^[A-Za-z_][A-Za-z0-9_]*=", argv[0]):
  181. argv = argv[1:]
  182. continue
  183. head = os.path.basename(argv[0])
  184. if head not in _WRAPPERS:
  185. break
  186. takes_value = _XARGS_OPTIONS_WITH_ARG if head == "xargs" else _WRAPPER_OPTIONS_WITH_ARG.get(head, frozenset())
  187. argv = argv[1:]
  188. while argv and argv[0].startswith("-"):
  189. argv = argv[2:] if argv[0] in takes_value else argv[1:]
  190. return argv
  191. def _operands(args: list[str]) -> list[str]:
  192. return [a for a in args if a and not a.startswith("-")]
  193. def _target_directory(args: list[str]) -> tuple[str | None, list[str]]:
  194. """``cp/mv/install/ln -t DIR`` / ``--target-directory[=]DIR``: (DIR, remaining args)."""
  195. rest = list(args)
  196. for i, arg in enumerate(rest):
  197. if arg.startswith("--target-directory="):
  198. return arg.split("=", 1)[1], rest[:i] + rest[i + 1:]
  199. if arg in ("-t", "--target-directory") and i + 1 < len(rest):
  200. return rest[i + 1], rest[:i] + rest[i + 2:]
  201. if arg.startswith("-t") and len(arg) > 2 and not arg.startswith("--"):
  202. return arg[2:], rest[:i] + rest[i + 1:]
  203. return None, rest
  204. class _Scope:
  205. """What a command is checked against: its working dir, the locked skills and the lock record."""
  206. def __init__(self, cwd: str, locked: list[tuple[str, str]], record: str, depth: int,
  207. env: dict[str, str] | None = None) -> None:
  208. self.cwd, self.locked, self.record, self.depth = cwd, locked, record, depth
  209. self.env = env if env is not None else _shell_env()
  210. def hit(self, word: str, ancestor: str = "") -> str | None:
  211. return next((r for path in _expand(word, self.cwd, self.env)
  212. if (r := _hit(path, self.locked, self.record, ancestor=ancestor))), None)
  213. def first_hit(self, words: Iterable[str], ancestor: str = "") -> str | None:
  214. return next((r for w in words if (r := self.hit(w, ancestor))), None)
  215. def _check_unlock(verb: str, args: list[str], scope: _Scope) -> str | None:
  216. if verb == "hermes" or (verb.startswith("python") and "hermes_cli.main" in args):
  217. if "curator" in args and "unlock" in args[args.index("curator"):]:
  218. return UNLOCK_REFUSAL
  219. return None
  220. _RECURSIVE_COPY_FLAGS = re.compile(r"^(?:-[A-Za-z]*[rRa][A-Za-z]*|--recursive|--archive)$")
  221. def _check_file_verbs(verb: str, args: list[str], scope: _Scope) -> str | None:
  222. if verb in _WRITES_EVERY_OPERAND or verb == "tee":
  223. return scope.first_hit(_operands(args), ancestor="any" if verb in _RECURSIVE else "")
  224. if verb not in _WRITES_LAST_OPERAND:
  225. return None
  226. target, rest = _target_directory(args)
  227. ops = _operands(rest)
  228. dest = target if target is not None else (ops[-1] if ops else None)
  229. if dest is None:
  230. return None
  231. # A recursive copy into a directory above the skill merges into it; rsync is recursive with -a/-r.
  232. merges = verb == "rsync" or any(_RECURSIVE_COPY_FLAGS.match(a) for a in rest)
  233. return scope.hit(dest, ancestor="skills" if merges else "")
  234. def _check_inplace(verb: str, args: list[str], scope: _Scope) -> str | None:
  235. if verb in _INPLACE_EDITORS and any(
  236. a.startswith("--in-place") or (a.startswith("-") and not a.startswith("--") and "i" in a) for a in args):
  237. return scope.first_hit(_operands(args))
  238. return None
  239. def _find_exec_commands(args: list[str]) -> Iterable[list[str]]:
  240. group: list[str] | None = None
  241. for arg in args:
  242. if arg in ("-exec", "-execdir", "-ok", "-okdir"):
  243. group = []
  244. elif group is not None and arg in (";", "+"):
  245. yield group
  246. group = None
  247. elif group is not None:
  248. group.append(arg)
  249. if group:
  250. yield group
  251. def _check_find(verb: str, args: list[str], scope: _Scope) -> str | None:
  252. """``find -delete``, or ``-exec`` of a command that writes, over a tree holding a locked skill."""
  253. if verb != "find":
  254. return None
  255. starts = list(itertools.takewhile(lambda a: not a.startswith("-"), args)) or ["."]
  256. writes = "-delete" in args
  257. for cmd in _find_exec_commands(args):
  258. # Judge the executed command as if `{}` were a file in the locked skill.
  259. probe = [w if w != "{}" else os.path.join(scope.locked[0][1], "SKILL.md") for w in cmd] if scope.locked else cmd
  260. writes = writes or (bool(probe) and _argv_refusal(
  261. probe, scope.cwd, scope.locked, scope.record, scope.depth, scope.env) is not None)
  262. return scope.first_hit(starts, ancestor="any") if writes else None
  263. def _check_git(verb: str, args: list[str], scope: _Scope) -> str | None:
  264. if verb != "git":
  265. return None
  266. where, rest = scope.cwd, list(args)
  267. while rest and rest[0].startswith("-"):
  268. flag = rest.pop(0)
  269. if flag == "-C" and rest:
  270. where = _expand(rest.pop(0), scope.cwd, scope.env)[0]
  271. elif flag in ("-c", "--git-dir", "--work-tree") and rest:
  272. rest.pop(0)
  273. if rest and rest[0] in _GIT_MUTATIONS:
  274. return _hit(where, scope.locked, scope.record, ancestor="any")
  275. return None
  276. def _check_extract(verb: str, args: list[str], scope: _Scope) -> str | None:
  277. if verb not in ("tar", "unzip", "bsdtar"):
  278. return None
  279. dest = scope.cwd
  280. for flag, value in itertools.pairwise(args):
  281. if flag in ("-C", "--directory", "-d"):
  282. dest = _expand(value, scope.cwd, scope.env)[0]
  283. bundled = bool(args) and not args[0].startswith("-") and "x" in args[0] # `tar xzf a.tgz`
  284. extracting = verb == "unzip" or bundled or any(
  285. a == "--extract" or (a.startswith("-") and not a.startswith("--") and "x" in a) for a in args)
  286. # The archive's paths are unknown: extracting into a directory above the skill can overwrite it.
  287. return _hit(dest, scope.locked, scope.record, ancestor="skills") if extracting else None
  288. def _check_interpreter(verb: str, args: list[str], scope: _Scope) -> str | None:
  289. if not _INTERPRETERS.match(verb):
  290. return None
  291. for flag, code in itertools.pairwise(args):
  292. if flag not in ("-c", "-e", "-E", "--eval", "-Command", "-r"):
  293. continue
  294. if verb in ("bash", "sh", "zsh", "dash", "ksh") and scope.depth < 3:
  295. reason = _command_refusal(code, scope.cwd, scope.locked, scope.record, scope.depth + 1)
  296. else:
  297. reason = _code_refusal(code, scope.locked, scope.record, scope.cwd)
  298. if reason:
  299. return reason
  300. return None
  301. _ARGV_CHECKS = (_check_unlock, _check_file_verbs, _check_inplace, _check_find, _check_git,
  302. _check_extract, _check_interpreter)
  303. def _argv_refusal(argv: list[str], cwd: str, locked, record, depth: int,
  304. env: dict[str, str] | None = None) -> str | None:
  305. scope = _Scope(cwd, locked, record, depth, env)
  306. verb = os.path.basename(argv[0])
  307. return next((r for check in _ARGV_CHECKS if (r := check(verb, argv[1:], scope))), None)
  308. def _code_refusal(code: str, locked, record, cwd: str = "") -> str | None:
  309. """Inline interpreter code that looks like it writes AND names a locked skill (or the record),
  310. or runs with its working directory inside one (relative paths)."""
  311. from hermes_constants import get_hermes_home
  312. if not _WRITEISH_CODE.search(code):
  313. return None
  314. if cwd and (reason := _hit(cwd, locked, record)):
  315. return reason
  316. home, hermes_home = os.path.expanduser("~"), str(get_hermes_home())
  317. text = code.replace("$HERMES_HOME", hermes_home).replace("~", home)
  318. skills_root = os.path.realpath(_skill_usage()._skills_dir())
  319. if ".usage.json" in text:
  320. return RECORD_REFUSAL
  321. for name, root in locked:
  322. rel = os.path.relpath(root, skills_root) if skills_root and _inside(root, skills_root) else ""
  323. if root in text or (rel and f"skills/{rel}" in text) or f"skills/{os.path.basename(root)}" in text:
  324. return skill_refusal(name)
  325. return None
  326. _ASSIGNMENT = re.compile(r"^([A-Za-z_][A-Za-z0-9_]*)=(.*)$", re.DOTALL)
  327. def _command_refusal(command: str, cwd: str, locked, record, depth: int = 0) -> str | None:
  328. if "<<" in command and (reason := _code_refusal(command, locked, record, cwd)):
  329. return reason # heredoc-fed interpreter body
  330. env = _shell_env()
  331. subshells: list[str] = [] # cwd to restore when each ( ... ) closes
  332. for argv, targets, separator in _segments(_tokens(command)):
  333. words = argv[1:] if argv[:1] == ["export"] else argv
  334. if words and all(_ASSIGNMENT.match(w) for w in words): # `p=...` / `export p=...` persist
  335. for w in words:
  336. name, value = _ASSIGNMENT.match(w).groups()
  337. env[name] = _VAR.sub(lambda m: env.get(m.group(1) or m.group(2), m.group(0)), value)
  338. argv = []
  339. for target in targets:
  340. if reason := next((r for path in _expand(target, cwd, env)
  341. if (r := _hit(path, locked, record))), None):
  342. return reason
  343. argv = _strip_wrappers(argv)
  344. if argv and argv[0] in ("cd", "pushd") and len(argv) > 1:
  345. cwd = _expand(argv[1], cwd, env)[0]
  346. elif argv and (reason := _argv_refusal(argv, cwd, locked, record, depth, env)):
  347. return reason
  348. for ch in separator:
  349. if ch == "(":
  350. subshells.append(cwd)
  351. elif ch == ")" and subshells:
  352. cwd = subshells.pop()
  353. return None
  354. def command_refusal(command: str, cwd: str) -> str | None:
  355. """terminal guard: refusal text when *command* writes into a locked skill, the lock record, or
  356. runs ``hermes curator unlock``. None when nothing is locked."""
  357. locked = locked_skill_dirs()
  358. if not locked:
  359. return None
  360. return _command_refusal(command, cwd or os.getcwd(), locked, _record_path())