devguard-scanner 0.1.0__py3-none-any.whl

devguard/analyzers/carriers.py

@@ -0,0 +1,345 @@
+"""Payload carriers: binaries, disguised files, archives, pickle-based model files (TC-09).
+
+Archives are listed in memory only (never extracted). Pickles are disassembled with `pickletools`
+(a static opcode reader); they are never loaded.
+"""
+
+from __future__ import annotations
+
+import bz2
+import io
+import lzma
+import pickletools
+import tarfile
+import zipfile
+import zlib
+
+from devguard.analyzers.base import AnalysisContext, FileView
+from devguard.core.filetype import (
+    ARCHIVE_MAGIC,
+    EXECUTABLE_MAGIC,
+    EXPECTED_MAGIC,
+    TEXT_EXTENSIONS,
+    looks_like_code,
+)
+from devguard.core.models import Finding, Severity
+from devguard.core.redact import make_excerpt
+from devguard.rules.catalog import build_finding, rule
+
+R_EXEC = rule(
+    "DG-CAR-EXEC-001",
+    "Executable binary committed to the repository",
+    "medium",
+    "high",
+    "carrier",
+    "TC-09.1, TC-09.8",
+    "The repository contains a compiled executable or library. Binaries cannot be reviewed like source and "
+    "are a common way to ship second-stage payloads.",
+    "Projects sometimes vendor tools or ship prebuilt native modules.",
+    "Do not run it. Check where it came from and whether a trigger or script references it.",
+)
+R_MISMATCH = rule(
+    "DG-CAR-DISGUISED-001",
+    "File content does not match its extension",
+    "high",
+    "high",
+    "carrier",
+    "TC-09.2",
+    "The file's bytes do not match its extension (for example JavaScript inside a .woff font or a program "
+    "inside a .png). Malware hides loaders as fonts and images so reviewers skip them.",
+)
+R_ARCHIVE = rule(
+    "DG-CAR-ARCHIVE-001",
+    "Archive committed to the repository",
+    "low",
+    "high",
+    "carrier",
+    "TC-09.5",
+    "The repository contains an archive. Its contents were listed (not extracted).",
+)
+R_PICKLE_DANGER = rule(
+    "DG-CAR-PICKLE-001",
+    "Pickle file references dangerous functions",
+    "critical",
+    "high",
+    "carrier",
+    "TC-09.4",
+    "A pickle-based file (ML model, cache) imports functions such as os.system, subprocess, eval, or exec. "
+    "Loading it with pickle/torch.load/joblib executes them.",
+    "Legitimate model files only reference library classes (torch, numpy, collections).",
+    "Never load this file. Use safetensors or inspect it with a static tool such as fickling.",
+)
+R_PICKLE_INFO = rule(
+    "DG-CAR-PICKLE-INFO-001",
+    "Pickle-based file present",
+    "info",
+    "high",
+    "carrier",
+    "TC-09.4",
+    "The file uses Python pickle serialization; loading a pickle can execute code by design. No dangerous "
+    "imports were found by static inspection.",
+)
+
+_PICKLE_EXT = (".pkl", ".pickle", ".joblib", ".pt", ".ckpt", ".bin", ".pth", ".dill", ".sav")
+_ARCHIVE_EXEC_EXT = (
+    ".exe",
+    ".dll",
+    ".scr",
+    ".bat",
+    ".cmd",
+    ".ps1",
+    ".vbs",
+    ".js",
+    ".jse",
+    ".wsf",
+    ".hta",
+    ".jar",
+    ".lnk",
+    ".msi",
+    ".sh",
+    ".app",
+    ".command",
+    ".so",
+    ".dylib",
+    ".elf",
+    ".py",
+    ".apk",
+)
+_DANGEROUS_MODULES = {
+    "os",
+    "posix",
+    "nt",
+    "subprocess",
+    "sys",
+    "socket",
+    "shutil",
+    "runpy",
+    "importlib",
+    "webbrowser",
+    "pty",
+    "ctypes",
+    "requests",
+    "urllib",
+    "urllib.request",
+    "http.client",
+    "commands",
+    "code",
+    "pickle",
+    "marshal",
+    "types",
+    "multiprocessing",
+    "asyncio",
+    "pip",
+    "platform",
+    "builtins",
+    "__builtin__",
+    "operator",
+}
+_DANGEROUS_BUILTINS = {
+    "eval",
+    "exec",
+    "compile",
+    "__import__",
+    "open",
+    "getattr",
+    "setattr",
+    "globals",
+    "execfile",
+    "input",
+    "breakpoint",
+    "apply",
+}
+MAX_ARCHIVE_MEMBERS = 10_000
+MAX_DECOMPRESSED = 64 * 1024 * 1024
+_DECOMPRESSORS = ("gzip", "bzip2", "xz")
+
+
+class CarrierAnalyzer:
+    name = "carriers"
+
+    def applies(self, fv: FileView) -> bool:
+        return fv.record.size > 0
+
+    def analyze(self, fv: FileView, ctx: AnalysisContext) -> list[Finding]:
+        out: list[Finding] = []
+        suffix = fv.suffix
+        magic = fv.magic
+        expected = EXPECTED_MAGIC.get(suffix)
+        if expected is not None and magic not in expected:
+            if fv.text is not None and looks_like_code(fv.text):
+                out.append(
+                    build_finding(
+                        R_MISMATCH.id,
+                        [fv.evidence_at_line(1)],
+                        detail=f"'{suffix}' file contains source code ({fv.lang or 'text'}).",
+                    )
+                )
+            elif magic in EXECUTABLE_MAGIC:
+                out.append(
+                    build_finding(
+                        R_MISMATCH.id, [fv.evidence_at_line(None)], detail=f"'{suffix}' file is a {magic} executable."
+                    )
+                )
+        elif suffix in TEXT_EXTENSIONS and magic in EXECUTABLE_MAGIC:
+            out.append(
+                build_finding(
+                    R_MISMATCH.id, [fv.evidence_at_line(None)], detail=f"'{suffix}' file is a {magic} executable."
+                )
+            )
+        if magic in EXECUTABLE_MAGIC and not out:
+            sev = Severity.LOW if suffix in (".class", ".node", ".wasm") else None
+            out.append(
+                build_finding(
+                    R_EXEC.id,
+                    [fv.evidence_at_line(None)],
+                    severity=sev,
+                    detail=f"Format: {magic}, {fv.record.size} bytes.",
+                )
+            )
+        if magic in ARCHIVE_MAGIC:
+            out += self._archive(fv, ctx)
+        if suffix in _PICKLE_EXT and fv.text is None:
+            out += self._pickle(fv, ctx)
+        return out
+
+    # ------------------------------------------------------------------ archives
+    def _archive(self, fv: FileView, ctx: AnalysisContext) -> list[Finding]:
+        names: list[str] = []
+        encrypted = False
+        note = ""
+        try:
+            if fv.magic == "zip":
+                with zipfile.ZipFile(io.BytesIO(fv.data)) as zf:
+                    infos = zf.infolist()[:MAX_ARCHIVE_MEMBERS]
+                    names = [i.filename for i in infos]
+                    encrypted = any(i.flag_bits & 0x1 for i in infos)
+                    if fv.suffix in _PICKLE_EXT:  # torch .pt / .pth are zip archives of pickles
+                        return self._torch_zip(fv, zf)
+            elif fv.magic == "tar" or (
+                fv.magic in _DECOMPRESSORS and (".tar" in fv.name or fv.suffix in (".tgz", ".tbz2", ".txz"))
+            ):
+                raw = fv.data if fv.magic == "tar" else _bounded_decompress(fv.magic, fv.data)
+                names = _tar_names(raw)
+            else:
+                note = f"{fv.magic} archive (contents not listed)."
+        except (zipfile.BadZipFile, tarfile.TarError, EOFError, OSError, ValueError, zlib.error, lzma.LZMAError) as exc:
+            note = f"Could not list contents: {type(exc).__name__}" + (
+                " (file truncated by size limit)" if fv.truncated else ""
+            )
+        exec_members = [n for n in names if n.lower().split(" -> ")[0].endswith(_ARCHIVE_EXEC_EXT)]
+        traversal = [n for n in names if n.startswith("/") or "../" in n or n.startswith("..")]
+        sev = Severity.LOW
+        parts = [note] if note else [f"{len(names)} member(s)."]
+        if encrypted:
+            sev = Severity.MEDIUM
+            parts.append("Password-protected (scanners cannot see inside; a password in the README is a red flag).")
+        if exec_members:
+            sev = Severity.HIGH if encrypted else Severity.MEDIUM
+            parts.append("Executable/script members: " + ", ".join(make_excerpt(n, limit=80) for n in exec_members[:8]))
+        if traversal:
+            sev = max(sev, Severity.MEDIUM, key=lambda s: s.rank)
+            parts.append(
+                "Members with absolute or parent-directory paths: "
+                + ", ".join(make_excerpt(n, limit=80) for n in traversal[:5])
+            )
+        return [build_finding(R_ARCHIVE.id, [fv.evidence_at_line(None)], severity=sev, detail=" ".join(parts))]
+
+    # ------------------------------------------------------------------ pickles
+    def _torch_zip(self, fv: FileView, zf: zipfile.ZipFile) -> list[Finding]:
+        refs: set[str] = set()
+        for info in zf.infolist()[:MAX_ARCHIVE_MEMBERS]:
+            if info.filename.endswith(".pkl") and info.file_size <= 64 * 1024 * 1024:
+                refs |= pickle_globals(zf.read(info))
+        return self._pickle_findings(fv, refs)
+
+    def _pickle(self, fv: FileView, ctx: AnalysisContext) -> list[Finding]:
+        if not fv.data[:1] == b"\x80" and fv.data[:1] not in (b"(", b"c", b"]", b"}"):
+            return []
+        return self._pickle_findings(fv, pickle_globals(fv.data))
+
+    def _pickle_findings(self, fv: FileView, refs: set[str]) -> list[Finding]:
+        dangerous = sorted(r for r in refs if _is_dangerous_global(r))
+        if dangerous:
+            return [
+                build_finding(
+                    R_PICKLE_DANGER.id,
+                    [fv.evidence_at_line(None)],
+                    detail="Imports: " + ", ".join(dangerous[:10]) + ".",
+                )
+            ]
+        return [
+            build_finding(
+                R_PICKLE_INFO.id, [fv.evidence_at_line(None)], detail=f"{len(refs)} distinct global reference(s)."
+            )
+        ]
+
+
+def pickle_globals(data: bytes) -> set[str]:
+    """Static extraction of module.name references from a pickle stream (no unpickling)."""
+    refs: set[str] = set()
+    strings: list[str] = []
+    try:
+        for opcode, arg, _pos in pickletools.genops(io.BytesIO(data)):
+            name = opcode.name
+            if name in (
+                "SHORT_BINUNICODE",
+                "BINUNICODE",
+                "UNICODE",
+                "BINUNICODE8",
+                "SHORT_BINSTRING",
+                "BINSTRING",
+                "STRING",
+            ):
+                strings.append(str(arg))
+                strings = strings[-2:]
+            elif name in ("GLOBAL", "INST"):
+                mod, _, attr = str(arg).partition(" ")
+                refs.add(f"{mod}.{attr}")
+            elif name == "STACK_GLOBAL" and len(strings) == 2:
+                refs.add(f"{strings[0]}.{strings[1]}")
+            if len(refs) > 1000:
+                break
+    except Exception:  # noqa: S110 - malformed/truncated streams: keep what was read
+        pass
+    return refs
+
+
+def _is_dangerous_global(ref: str) -> bool:
+    module, _, attr = ref.rpartition(".")
+    if module in ("builtins", "__builtin__"):
+        return attr in _DANGEROUS_BUILTINS
+    root = module.split(".")[0]
+    return module in _DANGEROUS_MODULES or root in {
+        "os",
+        "subprocess",
+        "socket",
+        "pty",
+        "ctypes",
+        "runpy",
+        "webbrowser",
+        "requests",
+        "urllib",
+        "shutil",
+    }
+
+
+def _bounded_decompress(magic: str | None, data: bytes) -> bytes:
+    """Decompress at most MAX_DECOMPRESSED bytes (decompression-bomb guard). Truncation is fine for listing."""
+    if magic == "gzip":
+        return zlib.decompressobj(16 + zlib.MAX_WBITS).decompress(data, MAX_DECOMPRESSED)
+    if magic == "bzip2":
+        return bz2.BZ2Decompressor().decompress(data, max_length=MAX_DECOMPRESSED)
+    return lzma.LZMADecompressor().decompress(data, max_length=MAX_DECOMPRESSED)
+
+
+def _tar_names(raw: bytes) -> list[str]:
+    names: list[str] = []
+    try:
+        with tarfile.open(fileobj=io.BytesIO(raw), mode="r:") as tf:
+            for i, member in enumerate(tf):
+                if i >= MAX_ARCHIVE_MEMBERS:
+                    break
+                names.append(member.name + (f" -> {member.linkname}" if member.issym() else ""))
+    except tarfile.ReadError:
+        pass  # truncated by the decompression cap: keep what was listed
+    return names

devguard/analyzers/command.py

@@ -0,0 +1,343 @@
+"""Static analysis of command strings found in configuration (SURF-019).
+
+Commands are tokenized with shlex (never handed to a shell) and checked for download-and-execute,
+encoded payloads, inline interpreter code, reverse shells, LOLBins, hidden execution, and
+on-the-fly package runners. Repository files the command references become evidence-graph edges.
+"""
+
+from __future__ import annotations
+
+import re
+import shlex
+from dataclasses import dataclass, field
+
+from devguard.analyzers.base import FileView
+from devguard.core.models import Evidence, Finding, Severity
+from devguard.core.redact import make_excerpt
+from devguard.core.safefs import Inventory, normalize_rel
+from devguard.rules.catalog import build_finding, rule
+
+_SPLIT_OPS = re.compile(r"\s*(?:&&|\|\||;|\||&(?!>)|\n)\s*")
+_VAR_ROOT = re.compile(
+    r"\$\{(workspaceFolder|workspaceRoot|fileWorkspaceFolder|containerWorkspaceFolder|localWorkspaceFolder"
+    r"|CLAUDE_PROJECT_DIR|PWD|workspaceFolderBasename)\}|\$(CLAUDE_PROJECT_DIR|PWD)\b|%cd%|\$\(pwd\)"
+)
+_PIPE_SHELL = re.compile(
+    r"\b(curl|wget|iwr|irm|Invoke-WebRequest|Invoke-RestMethod)\b[^|\n]*\|\s*(sudo\s+)?"
+    r"((ba|z|da|k)?sh|python3?|node|perl|ruby|iex|Invoke-Expression|pwsh|powershell)\b",
+    re.IGNORECASE,
+)
+_SUBSHELL_FETCH = re.compile(r"\$\(\s*(curl|wget)\b|<\(\s*(curl|wget)\b|`\s*(curl|wget)\b", re.IGNORECASE)
+_DOWNLOAD_CRADLE = re.compile(
+    r"\b(iex|Invoke-Expression)\b.*\b(DownloadString|Net\.WebClient|iwr|irm|Invoke-WebRequest)\b", re.IGNORECASE
+)
+_ENCODED = re.compile(
+    r"\s-(e|ec|en|enc|encodedcommand)\s+[A-Za-z0-9+/=]{16,}|base64\s+(-d|--decode|-D)\b|FromBase64String"
+    r"|\batob\s*\(|b64decode|Buffer\.from\([^)]*base64",
+    re.IGNORECASE,
+)
+_REVSHELL = re.compile(
+    r"/dev/tcp/|\bnc(at)?\s+(-[a-zA-Z]+\s+)*-[a-zA-Z]*e\b|\bsocat\b.*\bexec:|\b(ba)?sh\s+-i\s*>&|\bpty\.spawn\b"
+)
+_LOLBIN = re.compile(
+    r"\b(mshta|rundll32|regsvr32|bitsadmin|wmic)(\.exe)?\b|\bcertutil(\.exe)?\b.*-urlcache", re.IGNORECASE
+)
+_HIDDEN = re.compile(
+    r"\bnohup\b|\bdisown\b|&\s*$|>\s*/dev/null\s+2>&1\s*&|\bstart\s+/(b|min)\b|-w(indowstyle)?\s+h(idden)?\b"
+    r"|\bwindowsHide\b|\bsetsid\b",
+    re.IGNORECASE,
+)
+_INLINE = re.compile(
+    r"\b(node|deno|bun)\s+(-e|--eval|-p|--print)\b|\bpython[\d.]*\s+-c\b|\b(perl|ruby)\s+-e\b|\bphp\s+-r\b"
+    r"|\b(pwsh|powershell)(\.exe)?\b.*\s-(c|command)\s",
+    re.IGNORECASE,
+)
+_INLINE_CAPABILITY = re.compile(
+    r"require\s*\(|\bimport\b|https?://|\beval\b|\bexec\b|child_process|socket|base64|fetch\(|urlopen|"
+    r"Invoke-WebRequest|DownloadString|subprocess|os\.system",
+    re.IGNORECASE,
+)
+_FETCHERS = {
+    "curl",
+    "wget",
+    "iwr",
+    "irm",
+    "invoke-webrequest",
+    "invoke-restmethod",
+    "start-bitstransfer",
+    "aria2c",
+}
+_URL = re.compile(r"\b(?:https?|ftp)://[^\s'\"`)<>|]+", re.IGNORECASE)
+_RAW_IP_URL = re.compile(
+    r"\b(?:https?|ftp)://(?!127\.|0\.0\.0\.0|10\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.|169\.254\.)"
+    r"(\d{1,3}\.){3}\d{1,3}\b"
+)
+_NPM_INSTALL = {"install", "i", "ci", "add"}
+
+R_PIPE = rule(
+    "DG-CMD-PIPE-SHELL-001",
+    "Command executes downloaded content",
+    "high",
+    "high",
+    "command",
+    "TC-07.1",
+    "The command downloads content and executes it immediately (pipe to a shell/interpreter or a download cradle).",
+    "Official installers are sometimes run this way, but never automatically from project configuration.",
+)
+R_ENCODED = rule(
+    "DG-CMD-ENCODED-001",
+    "Command contains an encoded payload",
+    "high",
+    "high",
+    "command",
+    "TC-07.2, TC-08.5",
+    "The command decodes base64 or uses an encoded PowerShell command, hiding what it really runs.",
+)
+R_INLINE = rule(
+    "DG-CMD-INLINE-CODE-001",
+    "Command runs inline interpreter code",
+    "medium",
+    "medium",
+    "command",
+    "TC-07.2",
+    "The command passes source code directly to an interpreter (node -e, python -c, powershell -c), "
+    "and that code uses networking, process, or decoding capabilities.",
+)
+R_REVSHELL = rule(
+    "DG-CMD-REVSHELL-001",
+    "Command opens a reverse shell",
+    "critical",
+    "high",
+    "command",
+    "TC-07.7",
+    "The command connects a shell to a remote host.",
+)
+R_LOLBIN = rule(
+    "DG-CMD-LOLBIN-001",
+    "Command uses a Windows LOLBin",
+    "high",
+    "medium",
+    "command",
+    "TC-07.1",
+    "The command invokes a Windows system binary commonly abused to fetch or execute payloads "
+    "(mshta, rundll32, regsvr32, bitsadmin, wmic, certutil -urlcache).",
+)
+R_FETCH = rule(
+    "DG-CMD-FETCH-001",
+    "Command downloads content",
+    "low",
+    "medium",
+    "command",
+    "TC-07.1",
+    "The command downloads content from the network when it runs.",
+    "Setup scripts often download pinned tools. Check the URL and what happens to the download.",
+)
+R_RAWIP = rule(
+    "DG-CMD-RAW-IP-001",
+    "Command contacts a public IP address",
+    "medium",
+    "medium",
+    "command",
+    "TC-07.5",
+    "The command talks to a hard-coded public IP address rather than a domain name.",
+)
+R_HIDDEN = rule(
+    "DG-CMD-HIDDEN-001",
+    "Command runs hidden or in the background",
+    "medium",
+    "medium",
+    "command",
+    "TC-07.3, TC-07.9",
+    "The command detaches into the background or hides its window, so it keeps running unnoticed.",
+    "Dev servers and watchers are commonly backgrounded.",
+)
+R_PKG_RUNNER = rule(
+    "DG-CMD-PKG-RUNNER-001",
+    "Command runs a package fetched on the fly",
+    "low",
+    "medium",
+    "command",
+    "TC-11.2, TC-03.2",
+    "The command downloads and runs a package from a registry at execution time (npx/uvx/pipx/bunx/dlx). "
+    "Whatever the registry serves at that moment is executed.",
+    "Common for MCP servers and one-off tools. Verify the exact package name (typosquats) and pin a version.",
+)
+
+
+@dataclass
+class CommandAssessment:
+    command: str
+    pipe_to_shell: bool = False
+    encoded: bool = False
+    inline_code: bool = False
+    revshell: bool = False
+    lolbin: bool = False
+    hidden: bool = False
+    fetches: list[str] = field(default_factory=list)
+    raw_ip: bool = False
+    urls: list[str] = field(default_factory=list)
+    package_runs: list[str] = field(default_factory=list)
+    references: list[str] = field(default_factory=list)
+    npm_scripts: list[str] = field(default_factory=list)
+
+    @property
+    def dangerous(self) -> bool:
+        return self.pipe_to_shell or self.encoded or self.revshell or self.lolbin
+
+
+def _tokens(segment: str) -> list[str]:
+    try:
+        return shlex.split(segment, posix=True)
+    except ValueError:
+        return segment.split()
+
+
+def resolve_ref(token: str, inventory: Inventory, base_dirs: list[str]) -> str | None:
+    token = token.strip().strip("'\"`")
+    if "=" in token and token.startswith("-"):
+        token = token.split("=", 1)[1]
+    if not token or token.startswith("-") or "://" in token:
+        return None
+    if _VAR_ROOT.search(token):
+        token = _VAR_ROOT.sub("", token).lstrip("/\\")
+        candidates = [f"{b}/{token}" if b else token for b in base_dirs] + [token]
+    else:
+        if token.startswith(("/", "~", "$")) or re.match(r"^[A-Za-z]:\\", token):
+            return None
+        candidates = [f"{b}/{token}" if b else token for b in base_dirs]
+    for cand in candidates:
+        norm = normalize_rel(cand)
+        if norm and inventory.exists(norm):
+            return norm
+    return None
+
+
+def analyze_command(command: str, inventory: Inventory, base_dirs: list[str] | None = None) -> CommandAssessment:
+    bases = base_dirs or [""]
+    a = CommandAssessment(command=command)
+    a.pipe_to_shell = bool(
+        _PIPE_SHELL.search(command) or _SUBSHELL_FETCH.search(command) or _DOWNLOAD_CRADLE.search(command)
+    )
+    a.encoded = bool(_ENCODED.search(command))
+    a.revshell = bool(_REVSHELL.search(command))
+    a.lolbin = bool(_LOLBIN.search(command))
+    a.hidden = bool(_HIDDEN.search(command))
+    a.urls = _URL.findall(command)[:10]
+    a.raw_ip = bool(_RAW_IP_URL.search(command))
+    if _INLINE.search(command) and _INLINE_CAPABILITY.search(command):
+        a.inline_code = True
+    for segment in _SPLIT_OPS.split(command):
+        toks = _tokens(segment)
+        if not toks:
+            continue
+        # strip env assignments and common wrappers
+        while toks and (
+            re.match(r"^[A-Za-z_][A-Za-z0-9_]*=", toks[0]) or toks[0] in ("sudo", "env", "exec", "cross-env")
+        ):
+            toks = toks[1:]
+        if not toks:
+            continue
+        prog = toks[0].rsplit("/", 1)[-1].rsplit("\\", 1)[-1].lower().removesuffix(".exe")
+        if prog in _FETCHERS:
+            a.fetches.append(prog)
+        _package_runner(prog, toks, a)
+        _npm_script_refs(prog, toks, a)
+        for tok in toks:
+            ref = resolve_ref(tok, inventory, bases)
+            if ref:
+                a.references.append(ref)
+    a.references = sorted(set(a.references))
+    a.npm_scripts = sorted(set(a.npm_scripts))
+    return a
+
+
+def _first_positional(args: list[str]) -> str | None:
+    skip_next = {"-p", "--package", "--from", "--with", "-c", "--call"}
+    i = 0
+    while i < len(args):
+        arg = args[i]
+        if arg in skip_next:
+            i += 2
+            continue
+        if arg.startswith("-"):
+            i += 1
+            continue
+        return arg
+    return None
+
+
+def _package_runner(prog: str, toks: list[str], a: CommandAssessment) -> None:
+    pkg: str | None = None
+    if prog in ("npx", "bunx", "uvx", "pnpx"):
+        pkg = _first_positional(toks[1:])
+    elif prog == "pipx" and len(toks) > 1 and toks[1] == "run":
+        pkg = _first_positional(toks[2:])
+    elif prog in ("pnpm", "yarn") and len(toks) > 1 and toks[1] == "dlx":
+        pkg = _first_positional(toks[2:])
+    elif prog == "npm" and len(toks) > 1 and toks[1] in ("exec", "x"):
+        pkg = _first_positional(toks[2:])
+    elif prog == "uv" and len(toks) > 2 and toks[1] == "tool" and toks[2] == "run":
+        pkg = _first_positional(toks[3:])
+    if pkg and not pkg.startswith((".", "/")):
+        a.package_runs.append(pkg)
+
+
+def _npm_script_refs(prog: str, toks: list[str], a: CommandAssessment) -> None:
+    if prog not in ("npm", "yarn", "pnpm", "bun") or len(toks) < 2:
+        if prog in ("yarn", "pnpm") and len(toks) == 1:
+            a.npm_scripts.append("@install")
+        return
+    sub = toks[1]
+    if sub in ("run", "run-script") and len(toks) > 2:
+        a.npm_scripts.append(toks[2])
+    elif sub in _NPM_INSTALL and (len(toks) == 2 or toks[2].startswith("-")):
+        a.npm_scripts.append("@install")  # lifecycle scripts of the local package run
+    elif sub in ("start", "test", "stop", "restart"):
+        a.npm_scripts.append(sub)
+    elif (
+        prog in ("yarn", "pnpm", "bun")
+        and not sub.startswith("-")
+        and sub not in ("add", "remove", "dlx", "exec", "x", "create", "init", "why", "info", "upgrade")
+    ):
+        a.npm_scripts.append(sub)
+
+
+def command_findings(
+    a: CommandAssessment,
+    fv: FileView,
+    line: int | None,
+    *,
+    autorun: bool,
+    context: str,
+) -> list[Finding]:
+    """Turn an assessment into findings. Autorun contexts are one severity tier higher."""
+    bump = 1 if autorun else 0
+    excerpt = make_excerpt(a.command)
+    ev = fv.evidence_at_line(line)
+    ev = Evidence(path=ev.path, line_start=ev.line_start, line_end=ev.line_end, excerpt=excerpt)
+    detail = f"Context: {context}{' (runs automatically)' if autorun else ''}."
+    out: list[Finding] = []
+
+    def add(meta_id: str, base: Severity, extra: str = "") -> None:
+        sev = base.bump(bump) if bump else base
+        out.append(build_finding(meta_id, [ev], severity=sev, detail=(detail + extra).strip()))
+
+    if a.revshell:
+        add(R_REVSHELL.id, R_REVSHELL.severity)
+    if a.pipe_to_shell:
+        add(R_PIPE.id, R_PIPE.severity)
+    if a.encoded:
+        add(R_ENCODED.id, R_ENCODED.severity)
+    if a.lolbin:
+        add(R_LOLBIN.id, R_LOLBIN.severity)
+    if a.inline_code:
+        add(R_INLINE.id, R_INLINE.severity)
+    if a.raw_ip:
+        add(R_RAWIP.id, R_RAWIP.severity)
+    if a.fetches and not a.pipe_to_shell:
+        add(R_FETCH.id, R_FETCH.severity, f" Tools: {', '.join(sorted(set(a.fetches)))}.")
+    if a.hidden and (autorun or a.dangerous or a.fetches):
+        add(R_HIDDEN.id, R_HIDDEN.severity)
+    if a.package_runs:
+        add(R_PKG_RUNNER.id, R_PKG_RUNNER.severity, f" Packages: {', '.join(sorted(set(a.package_runs)))}.")
+    return out