pickle-sentry 0.2.0__py3-none-any.whl

pickle_sentry/__init__.py

@@ -0,0 +1,3 @@
+"""pickle-sentry: scan for unsafe pickle deserialization. Never executes inspected files."""
+
+__version__ = "0.2.0"

pickle_sentry/cli.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+from . import __version__
+from .inspector import inspect_file
+from .model import ScanResult
+from .report import to_json, to_sarif, to_text
+from .scanner import scan_python_file
+
+SKIP_DIRS = {".git", "__pycache__", ".venv", "venv", "node_modules", ".tox", ".mypy_cache"}
+PICKLE_EXTS = {".pkl", ".pickle", ".joblib", ".pt", ".pth"}
+
+
+def collect(root: str, exclude: list[str] | None = None) -> ScanResult:
+    exclude = exclude or []
+    result = ScanResult(root=root)
+    paths: list[str] = []
+    if os.path.isfile(root):
+        paths = [root]
+    else:
+        for dirpath, dirnames, filenames in os.walk(root):
+            dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS]
+            for name in filenames:
+                paths.append(os.path.join(dirpath, name))
+    if exclude:
+        paths = [p for p in paths if not any(x in p for x in exclude)]
+    for p in sorted(paths):
+        ext = os.path.splitext(p)[1].lower()
+        if ext == ".py":
+            result.files_scanned += 1
+            result.findings.extend(scan_python_file(p))
+        elif ext in PICKLE_EXTS:
+            result.pickle_files_inspected += 1
+            result.findings.extend(inspect_file(p))
+    return result
+
+
+def _hub_main(argv: list[str]) -> int:
+    from .hub import scan_hub_repo
+    ap = argparse.ArgumentParser(
+        prog="pickle-sentry hub",
+        description="Scan a Hugging Face Hub repository for pickle files and unsafe "
+                    "deserialization. Files are inspected by disassembly, never executed.")
+    ap.add_argument("repo_id", help="e.g. user/dataset-name")
+    ap.add_argument("--repo-type", choices=["dataset", "model", "space"], default="dataset")
+    ap.add_argument("--revision", default="main")
+    ap.add_argument("--max-size-mb", type=float, default=64.0,
+                    help="Per-file inspection cap in MB (default: 64)")
+    ap.add_argument("--format", choices=["text", "json", "sarif"], default="text")
+    ap.add_argument("--output", help="Write the report to this file instead of stdout")
+    ap.add_argument("--fail-on", choices=["critical", "high", "medium", "low", "none"],
+                    default="high")
+    args = ap.parse_args(argv)
+    result = scan_hub_repo(args.repo_id, repo_type=args.repo_type, revision=args.revision,
+                           max_bytes=int(args.max_size_mb * 1024 * 1024))
+    rendered = {"text": to_text, "json": to_json, "sarif": to_sarif}[args.format](result)
+    if args.output:
+        with open(args.output, "w", encoding="utf-8") as fh:
+            fh.write(rendered)
+    else:
+        sys.stdout.write(rendered)
+    return 1 if result.meets(args.fail_on) else 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if argv and argv[0] == "hub":
+        return _hub_main(argv[1:])
+    ap = argparse.ArgumentParser(
+        prog="pickle-sentry",
+        description="Scan code and dataset files for unsafe pickle deserialization "
+                    "(incl. CVE-2026-57845). Inspected pickle files are never executed.")
+    ap.add_argument("path", help="File or directory to scan")
+    ap.add_argument("--format", choices=["text", "json", "sarif"], default="text")
+    ap.add_argument("--output", help="Write the report to this file instead of stdout")
+    ap.add_argument("--fail-on", choices=["critical", "high", "medium", "low", "none"],
+                    default="high",
+                    help="Exit 1 if any finding is at or above this severity (default: high)")
+    ap.add_argument("--exclude", action="append", default=[],
+                    help="Skip paths containing this substring (repeatable, e.g. --exclude /tests/)")
+    ap.add_argument("--version", action="version", version=f"pickle-sentry {__version__}")
+    args = ap.parse_args(argv)
+
+    if not os.path.exists(args.path):
+        print(f"error: no such path: {args.path}", file=sys.stderr)
+        return 2
+
+    result = collect(args.path, exclude=args.exclude)
+    rendered = {"text": to_text, "json": to_json, "sarif": to_sarif}[args.format](result)
+    if args.output:
+        with open(args.output, "w", encoding="utf-8") as fh:
+            fh.write(rendered)
+    else:
+        sys.stdout.write(rendered)
+    return 1 if result.meets(args.fail_on) else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pickle_sentry/hub.py

@@ -0,0 +1,88 @@
+"""Scan a Hugging Face Hub repository without executing anything in it.
+
+Lists the repo's files via the Hub API, downloads pickle-family files and
+inspects them by disassembly only, and AST-scans any Python files.
+"""
+from __future__ import annotations
+
+import json
+import os
+import urllib.request
+import urllib.error
+
+from .inspector import inspect_pickle_bytes
+from .model import Finding, ScanResult
+from .scanner import scan_python_source
+
+PICKLE_EXTS = {".pkl", ".pickle", ".joblib", ".pt", ".pth"}
+# Model weights in classic PyTorch format are pickle zip archives.
+MODEL_PICKLE_NAMES = {"pytorch_model.bin"}
+DEFAULT_MAX_BYTES = 64 * 1024 * 1024  # per file
+
+
+def _default_fetch(url: str) -> bytes:
+    req = urllib.request.Request(url, headers={"User-Agent": "pickle-sentry/0.2"})
+    token = os.environ.get("HF_TOKEN")
+    if token:
+        req.add_header("Authorization", f"Bearer {token}")
+    with urllib.request.urlopen(req, timeout=60) as resp:
+        return resp.read()
+
+
+def _api_base(repo_type: str) -> str:
+    return {"dataset": "https://huggingface.co/api/datasets/",
+            "model": "https://huggingface.co/api/models/",
+            "space": "https://huggingface.co/api/spaces/"}[repo_type]
+
+
+def _resolve_base(repo_id: str, repo_type: str, revision: str) -> str:
+    prefix = {"dataset": "datasets/", "model": "", "space": "spaces/"}[repo_type]
+    return f"https://huggingface.co/{prefix}{repo_id}/resolve/{revision}/"
+
+
+def scan_hub_repo(repo_id: str, repo_type: str = "dataset", revision: str = "main",
+                  max_bytes: int = DEFAULT_MAX_BYTES, fetch=None) -> ScanResult:
+    fetch = fetch or _default_fetch
+    result = ScanResult(root=f"hub://{repo_type}/{repo_id}@{revision}")
+    try:
+        info = json.loads(fetch(_api_base(repo_type) + repo_id))
+    except (urllib.error.URLError, ValueError) as exc:
+        result.findings.append(Finding("HUB-UNREACHABLE", "low", result.root, None,
+                                       f"Could not read Hub repo info: {exc}"))
+        return result
+
+    siblings = info.get("siblings") or []
+    base = _resolve_base(repo_id, repo_type, revision)
+    for sib in siblings:
+        name = sib.get("rfilename", "")
+        ext = os.path.splitext(name)[1].lower()
+        display = f"{result.root}/{name}"
+        is_pickle = ext in PICKLE_EXTS or os.path.basename(name) in MODEL_PICKLE_NAMES
+        if is_pickle:
+            result.pickle_files_inspected += 1
+            size = sib.get("size")
+            if size is not None and size > max_bytes:
+                result.findings.append(Finding(
+                    "HUB-PICKLE-TOO-LARGE", "high", display, None,
+                    f"Pickle-family file of {size/1e6:.1f} MB exceeds the {max_bytes/1e6:.0f} MB "
+                    "inspection cap and was NOT downloaded. Inspect it locally before trusting it.",
+                    cve="CVE-2026-57845"))
+                continue
+            try:
+                data = fetch(base + urllib.request.quote(name))
+            except urllib.error.URLError as exc:
+                result.findings.append(Finding("HUB-DOWNLOAD-FAILED", "low", display, None,
+                                               f"Could not download for inspection: {exc}"))
+                continue
+            result.findings.extend(inspect_pickle_bytes(data, display))
+        elif ext == ".py":
+            result.files_scanned += 1
+            try:
+                source = fetch(base + urllib.request.quote(name)).decode("utf-8", "replace")
+            except urllib.error.URLError:
+                continue
+            result.findings.extend(scan_python_source(source, display))
+    if not siblings:
+        result.findings.append(Finding("HUB-EMPTY", "info", result.root, None,
+                                       "Hub API returned no files for this repository."))
+    return result

pickle_sentry/inspector.py

@@ -0,0 +1,184 @@
+"""Inspect pickle byte streams WITHOUT executing them.
+
+Uses pickletools.genops only — a pure disassembler. A malicious pickle's
+__reduce__ payload is never run by this module.
+"""
+from __future__ import annotations
+
+import io
+import pickletools
+import zipfile
+
+from .model import Finding
+
+# Globals that give a pickle direct code / command execution, file or network access.
+DANGEROUS_GLOBALS = {
+    "os.system", "os.popen", "os.execv", "os.execve", "os.execvp", "os.spawnl",
+    "os.spawnle", "os.spawnlp", "os.spawnve", "os.spawnvp", "posix.system",
+    "nt.system", "subprocess.Popen", "subprocess.run", "subprocess.call",
+    "subprocess.check_output", "subprocess.check_call", "subprocess.getoutput",
+    "builtins.eval", "builtins.exec", "builtins.__import__", "builtins.compile",
+    "builtins.open", "builtins.input", "builtins.getattr", "builtins.setattr",
+    "__builtin__.eval", "__builtin__.exec", "__builtin__.__import__",
+    "pty.spawn", "commands.getoutput", "socket.socket", "urllib.request.urlopen",
+    "http.client.HTTPConnection", "shutil.rmtree", "pathlib.Path.write_text",
+    "pathlib.Path.write_bytes", "code.InteractiveConsole", "code.eval",
+    "runpy.run_module", "runpy.run_path", "importlib.import_module",
+    "ctypes.CDLL", "ctypes.cdll", "multiprocessing.Process",
+}
+
+# Modules whose mere import inside a pickle is a strong smell.
+DANGEROUS_MODULES = {"os", "posix", "nt", "subprocess", "pty", "commands",
+                      "socket", "shutil", "runpy", "ctypes"}
+
+# Globals routinely used to reconstruct ordinary data (DataFrames, tensors,
+# datetimes). A REDUCE invoking only these is normal pickle mechanics.
+BENIGN_GLOBAL_PREFIXES = (
+    "collections.", "copyreg.", "builtins.object", "__builtin__.object",
+    "numpy.", "pandas.", "pyarrow.", "torch.", "datetime.", "dateutil.",
+    "decimal.", "uuid.", "re.", "codecs.", "typing.", "enum.",
+)
+
+
+def _globals_from_ops(data: bytes) -> tuple[list[str], bool]:
+    """Return (global names referenced, whether a REDUCE opcode is present)."""
+    globals_found: list[str] = []
+    has_reduce = False
+    buf: list[str] = []  # for STACK_GLOBAL: two strings pushed before the opcode
+    last_strings: list[str] = []
+    try:
+        for opcode, arg, _pos in pickletools.genops(data):
+            if opcode.name == "REDUCE":
+                has_reduce = True
+            elif opcode.name == "GLOBAL":
+                # arg is "module name"
+                if isinstance(arg, str):
+                    parts = arg.split(" ", 1)
+                    if len(parts) == 2:
+                        globals_found.append(f"{parts[0]}.{parts[1]}")
+            elif opcode.name in ("SHORT_BINUNICODE", "BINUNICODE", "UNICODE", "BINUNICODE8"):
+                if isinstance(arg, str):
+                    last_strings.append(arg)
+                    last_strings = last_strings[-2:]
+            elif opcode.name == "STACK_GLOBAL":
+                if len(last_strings) >= 2:
+                    globals_found.append(f"{last_strings[-2]}.{last_strings[-1]}")
+                last_strings = []
+    except Exception:
+        # Truncated / corrupt stream: return what we have; caller reports parse failure.
+        return globals_found, has_reduce
+    return globals_found, has_reduce
+
+
+def inspect_pickle_bytes(data: bytes, path: str) -> list[Finding]:
+    # Torch checkpoints / model .bin files are zip archives holding a pickle stream.
+    if data[:2] == b"PK":
+        try:
+            with zipfile.ZipFile(io.BytesIO(data)) as zf:
+                inner: list[Finding] = []
+                for name in zf.namelist():
+                    if name.endswith("data.pkl") or name.endswith(".pkl"):
+                        inner.extend(inspect_pickle_bytes(zf.read(name), f"{path}!{name}"))
+                if inner:
+                    return inner
+        except zipfile.BadZipFile:
+            pass
+        return [Finding("PICKLE-FILE-PRESENT", "medium", path, None,
+                        "Zip-based checkpoint present; no pickle stream could be parsed. "
+                        "Treat as untrusted code-bearing data until verified.")]
+    findings: list[Finding] = []
+    globals_found, has_reduce = _globals_from_ops(data)
+    dangerous = sorted({g for g in globals_found if g in DANGEROUS_GLOBALS})
+    dangerous_mods = sorted({g for g in globals_found
+                             if g.split(".")[0] in DANGEROUS_MODULES and g not in dangerous})
+
+    if dangerous and has_reduce:
+        findings.append(Finding(
+            rule_id="PICKLE-DANGEROUS-REDUCE",
+            severity="critical",
+            path=path, line=None,
+            message=("Pickle calls a dangerous callable via REDUCE "
+                     f"({', '.join(dangerous)}). Loading this file executes code. "
+                     "Treat as malicious unless you created it yourself."),
+            evidence=", ".join(dangerous),
+            cve="CVE-2026-57845",
+        ))
+    elif dangerous:
+        findings.append(Finding(
+            rule_id="PICKLE-DANGEROUS-GLOBAL",
+            severity="high",
+            path=path, line=None,
+            message=f"Pickle references dangerous callable(s): {', '.join(dangerous)}.",
+            evidence=", ".join(dangerous),
+            cve="CVE-2026-57845",
+        ))
+
+    if dangerous_mods:
+        findings.append(Finding(
+            rule_id="PICKLE-SUSPICIOUS-MODULE",
+            severity="high" if has_reduce else "medium",
+            path=path, line=None,
+            message=f"Pickle references OS/subprocess-level module globals: {', '.join(dangerous_mods)}.",
+            evidence=", ".join(dangerous_mods),
+        ))
+
+    # Any other callable invoked via REDUCE: the pickle runs *someone's* function
+    # on load — e.g. the CVE PoC's __main__._write_marker_and_return_dataframe.
+    unknown_callables = sorted({g for g in globals_found
+                                if g not in dangerous
+                                and not g.startswith(BENIGN_GLOBAL_PREFIXES)})
+    if has_reduce and unknown_callables and not dangerous:
+        findings.append(Finding(
+            rule_id="PICKLE-REDUCE-CALLABLE",
+            severity="high",
+            path=path, line=None,
+            message=("Pickle invokes non-standard callable(s) via REDUCE "
+                     f"({', '.join(unknown_callables)}). Loading it runs that code — "
+                     "this is the shape of the CVE-2026-57845 PoC payload."),
+            evidence=", ".join(unknown_callables),
+            cve="CVE-2026-57845",
+        ))
+
+    if not findings:
+        findings.append(Finding(
+            rule_id="PICKLE-FILE-PRESENT",
+            severity="medium",
+            path=path, line=None,
+            message=("Pickle file present. Pickle is code, not data: never load it from an "
+                     "untrusted source. Globals seen: "
+                     + (", ".join(sorted(set(globals_found))[:8]) or "none parsed")),
+            evidence=", ".join(sorted(set(globals_found))[:8]),
+        ))
+    return findings
+
+
+def inspect_file(path: str) -> list[Finding]:
+    """Inspect a .pkl/.pickle/.joblib file, or a torch .pt/.pth zip archive."""
+    try:
+        with open(path, "rb") as fh:
+            head = fh.read(4)
+    except OSError as exc:
+        return [Finding("PICKLE-UNREADABLE", "low", path, None, f"Could not read file: {exc}")]
+
+    # Torch checkpoints are zip archives containing a pickled data.pkl stream.
+    if head[:2] == b"PK":
+        findings: list[Finding] = []
+        try:
+            with zipfile.ZipFile(path) as zf:
+                for name in zf.namelist():
+                    if name.endswith("data.pkl") or name.endswith(".pkl"):
+                        findings.extend(inspect_pickle_bytes(zf.read(name), f"{path}!{name}"))
+            if findings:
+                return findings
+        except zipfile.BadZipFile:
+            pass
+        return [Finding("PICKLE-FILE-PRESENT", "medium", path, None,
+                        "Zip-based checkpoint present; no pickle stream could be parsed. "
+                        "Treat as untrusted code-bearing data until verified.")]
+
+    try:
+        with open(path, "rb") as fh:
+            data = fh.read()
+    except OSError as exc:
+        return [Finding("PICKLE-UNREADABLE", "low", path, None, f"Could not read file: {exc}")]
+    return inspect_pickle_bytes(data, path)

pickle_sentry/model.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field, asdict
+
+SEVERITY_ORDER = {"info": 0, "low": 1, "medium": 2, "high": 3, "critical": 4}
+
+
+@dataclass
+class Finding:
+    rule_id: str
+    severity: str  # info | low | medium | high | critical
+    path: str
+    line: int | None
+    message: str
+    evidence: str = ""
+    cve: str | None = None
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+@dataclass
+class ScanResult:
+    root: str
+    files_scanned: int = 0
+    pickle_files_inspected: int = 0
+    findings: list[Finding] = field(default_factory=list)
+
+    @property
+    def max_severity(self) -> str | None:
+        if not self.findings:
+            return None
+        return max((f.severity for f in self.findings), key=lambda s: SEVERITY_ORDER[s])
+
+    def meets(self, threshold: str) -> bool:
+        if threshold == "none" or not self.findings:
+            return False
+        t = SEVERITY_ORDER[threshold]
+        return any(SEVERITY_ORDER[f.severity] >= t for f in self.findings)
+
+    def to_dict(self) -> dict:
+        return {
+            "root": self.root,
+            "files_scanned": self.files_scanned,
+            "pickle_files_inspected": self.pickle_files_inspected,
+            "max_severity": self.max_severity,
+            "findings": [f.to_dict() for f in self.findings],
+        }

pickle_sentry/report.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import json
+
+from .model import ScanResult, SEVERITY_ORDER
+
+_ICON = {"critical": "CRITICAL", "high": "HIGH", "medium": "MEDIUM", "low": "LOW", "info": "INFO"}
+
+
+def to_text(result: ScanResult) -> str:
+    lines = [
+        f"pickle-sentry scan: {result.root}",
+        f"  python files scanned: {result.files_scanned}",
+        f"  pickle files inspected (never executed): {result.pickle_files_inspected}",
+        f"  findings: {len(result.findings)}"
+        + (f" (max severity: {result.max_severity})" if result.max_severity else ""),
+        "",
+    ]
+    ordered = sorted(result.findings, key=lambda f: (-SEVERITY_ORDER[f.severity], f.path, f.line or 0))
+    for f in ordered:
+        loc = f.path + (f":{f.line}" if f.line else "")
+        lines.append(f"[{_ICON[f.severity]}] {f.rule_id}  {loc}")
+        lines.append(f"    {f.message}")
+        if f.cve:
+            lines.append(f"    CVE: {f.cve}")
+    if not result.findings:
+        lines.append("No unsafe deserialization patterns found.")
+    return "\n".join(lines) + "\n"
+
+
+def to_json(result: ScanResult) -> str:
+    return json.dumps(result.to_dict(), indent=2) + "\n"
+
+
+def to_sarif(result: ScanResult) -> str:
+    runs = [{
+        "tool": {"driver": {"name": "pickle-sentry", "version": "0.2.0",
+                            "informationUri": "https://github.com/Sun-Wukhan/pickle-sentry"}},
+        "results": [
+            {
+                "ruleId": f.rule_id,
+                "level": {"critical": "error", "high": "error", "medium": "warning",
+                          "low": "note", "info": "note"}[f.severity],
+                "message": {"text": f.message},
+                "locations": [{"physicalLocation": {
+                    "artifactLocation": {"uri": f.path},
+                    "region": {"startLine": f.line or 1},
+                }}],
+                "properties": {"cve": f.cve} if f.cve else {},
+            } for f in result.findings
+        ],
+    }]
+    return json.dumps({"version": "2.1.0",
+                       "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
+                       "runs": runs}, indent=2) + "\n"

pickle_sentry/scanner.py

@@ -0,0 +1,144 @@
+"""AST-based code scanner. Parses Python source; never imports or runs it."""
+from __future__ import annotations
+
+import ast
+
+from .model import Finding
+
+PICKLE_MODULES = {"pickle", "cPickle", "_pickle", "dill", "cloudpickle", "marshal", "shelve"}
+UNPICKLE_FUNCS = {"load", "loads", "Unpickler"}
+
+
+class _Visitor(ast.NodeVisitor):
+    def __init__(self, path: str):
+        self.path = path
+        self.findings: list[Finding] = []
+        self.aliases: dict[str, str] = {}   # local name -> dotted module/object
+        self.from_imports: dict[str, str] = {}  # local name -> full dotted name
+
+    # -- import bookkeeping -------------------------------------------------
+    def visit_Import(self, node: ast.Import):
+        for a in node.names:
+            self.aliases[a.asname or a.name.split(".")[0]] = a.name
+        self.generic_visit(node)
+
+    def visit_ImportFrom(self, node: ast.ImportFrom):
+        mod = node.module or ""
+        for a in node.names:
+            self.from_imports[a.asname or a.name] = f"{mod}.{a.name}" if mod else a.name
+        self.generic_visit(node)
+
+    # -- helpers ------------------------------------------------------------
+    def _dotted(self, node: ast.expr) -> str | None:
+        parts: list[str] = []
+        cur: ast.expr | None = node
+        while isinstance(cur, ast.Attribute):
+            parts.append(cur.attr)
+            cur = cur.value
+        if isinstance(cur, ast.Name):
+            parts.append(cur.id)
+            parts.reverse()
+            root = self.aliases.get(parts[0], parts[0])
+            if parts[0] in self.from_imports:
+                return ".".join([self.from_imports[parts[0]]] + parts[1:])
+            return ".".join([root] + parts[1:])
+        return None
+
+    def _add(self, rule, severity, node, message, cve=None):
+        self.findings.append(Finding(
+            rule_id=rule, severity=severity, path=self.path,
+            line=getattr(node, "lineno", None), message=message, cve=cve))
+
+    # -- calls ---------------------------------------------------------------
+    def visit_Call(self, node: ast.Call):
+        dotted = self._dotted(node.func) or ""
+
+        # Hugging Face datasets: load_dataset("pandas", ...) — CVE-2026-57845
+        if dotted == "load_dataset" or dotted.endswith(".load_dataset"):
+            if node.args and isinstance(node.args[0], ast.Constant) and node.args[0].value == "pandas":
+                self._add("HF-DATASETS-PANDAS-BUILDER", "critical", node,
+                          'load_dataset("pandas", ...) routes files to pandas.read_pickle(). '
+                          "A crafted pickle executes code on load (CVE-2026-57845, CVSS 8.8; "
+                          "affects datasets <= 5.1.0, no patched release yet). "
+                          "Use parquet/csv/json/arrow, or Dataset.from_pandas() for your own DataFrame.",
+                          cve="CVE-2026-57845")
+            elif not (node.args and isinstance(node.args[0], ast.Constant)
+                      and isinstance(node.args[0].value, str)):
+                # Dynamic / inferred builder: the extension decides, and .pkl means pandas.
+                for kw in node.keywords:
+                    if kw.arg == "data_files":
+                        self._add("HF-DATASETS-DATA-FILES", "info", node,
+                                  "load_dataset(...) with data_files and no explicit safe builder: "
+                                  "confirm the builder inferred from the file extensions is not "
+                                  "'pandas' and the source is trusted.")
+
+        # pickle-family unpickling: pickle.load/loads, dill.load, marshal.load, shelve.open...
+        root = dotted.split(".")[0] if dotted else ""
+        leaf = dotted.rsplit(".", 1)[-1] if dotted else ""
+        if root in PICKLE_MODULES and leaf in UNPICKLE_FUNCS:
+            self._add("UNSAFE-DESERIALIZATION", "high", node,
+                      f"{dotted}(...) deserializes pickle-family data. Never call it on "
+                      "untrusted input — it is arbitrary code execution by design.")
+        elif dotted.endswith(".read_pickle"):
+            self._add("PANDAS-READ-PICKLE", "high", node,
+                      "pandas.read_pickle(...) executes pickle payloads. Only use on files you "
+                      "created; prefer read_parquet / read_csv for shared data.",
+                      cve="CVE-2026-57845")
+
+        # joblib.load is pickle under the hood
+        if dotted == "joblib.load" or dotted.endswith(".joblib.load"):
+            self._add("UNSAFE-DESERIALIZATION", "high", node,
+                      "joblib.load(...) is pickle deserialization. Never call it on untrusted files.")
+
+        # torch.load without weights_only=True
+        if dotted == "torch.load" or dotted.endswith(".torch.load"):
+            wo = None
+            for kw in node.keywords:
+                if kw.arg == "weights_only":
+                    wo = kw.value.value if isinstance(kw.value, ast.Constant) else "dynamic"
+            if wo is True:
+                pass  # safe form
+            elif wo is False:
+                self._add("TORCH-LOAD-WEIGHTS-ONLY-FALSE", "high", node,
+                          "torch.load(..., weights_only=False) unpickles the checkpoint — "
+                          "arbitrary code execution from a crafted file. Use weights_only=True.")
+            else:
+                self._add("TORCH-LOAD-NO-WEIGHTS-ONLY", "medium", node,
+                          "torch.load(...) without an explicit weights_only=True. Older torch "
+                          "defaults to full unpickling; set weights_only=True for shared checkpoints.")
+
+        # numpy.load(..., allow_pickle=True) — np.load defaults to allow_pickle=False, so only True is a sink
+        if dotted == "numpy.load" or dotted.endswith(".numpy.load"):
+            for kw in node.keywords:
+                if kw.arg == "allow_pickle" and isinstance(kw.value, ast.Constant) and kw.value.value is True:
+                    self._add("NUMPY-ALLOW-PICKLE", "high", node,
+                              "numpy.load(..., allow_pickle=True) unpickles object arrays. "
+                              "Never use it on shared .npy/.npz files; save data arrays instead.")
+
+        # yaml.load without SafeLoader
+        if dotted in ("yaml.load",) or dotted.endswith(".yaml.load"):
+            has_loader = any(kw.arg == "Loader" for kw in node.keywords) or len(node.args) >= 2
+            if not has_loader:
+                self._add("YAML-UNSAFE-LOAD", "medium", node,
+                          "yaml.load(...) without a SafeLoader can construct arbitrary objects. "
+                          "Use yaml.safe_load(...).")
+        self.generic_visit(node)
+
+
+def scan_python_source(source: str, path: str) -> list[Finding]:
+    try:
+        tree = ast.parse(source)
+    except SyntaxError as exc:
+        return [Finding("PARSE-ERROR", "low", path, exc.lineno,
+                        f"Could not parse Python source: {exc.msg}")]
+    v = _Visitor(path)
+    v.visit(tree)
+    return v.findings
+
+
+def scan_python_file(path: str) -> list[Finding]:
+    try:
+        with open(path, encoding="utf-8", errors="replace") as fh:
+            return scan_python_source(fh.read(), path)
+    except OSError as exc:
+        return [Finding("UNREADABLE", "low", path, None, f"Could not read file: {exc}")]

pickle_sentry-0.2.0.dist-info/METADATA

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: pickle-sentry
+Version: 0.2.0
+Summary: Scan code and dataset files for unsafe pickle deserialization — including the Hugging Face datasets pandas builder RCE (CVE-2026-57845). Never executes the files it inspects.
+Author: Navid Khan
+License: MIT
+Keywords: security,pickle,deserialization,huggingface,cve-2026-57845,scanner
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# pickle-sentry
+
+Scan code and dataset files for unsafe pickle deserialization — including the
+Hugging Face `datasets` pandas builder RCE, **CVE-2026-57845** (CVSS 8.8).
+
+Pickle is code, not data. Any file, checkpoint, or dataset that passes through
+a pickle loader executes whatever its author put in it. `pickle-sentry` finds
+those paths in your code, and inspects pickle files by *disassembly only* —
+**it never executes the files it inspects** (its test suite proves this with a
+canary payload).
+
+## Why now
+
+CVE-2026-57845 (published 23 Oct 2026): Hugging Face `datasets` through 5.1.0 —
+the latest release — routes `load_dataset("pandas", data_files=...)` to
+`pandas.read_pickle()`. A crafted pickle runs arbitrary Python with the
+victim's privileges the moment the dataset loads. The upstream fix
+(huggingface/datasets#8879) disables the pandas builder, but no patched
+release exists yet. Until one ships, the mitigation is: find every place you
+load pickle-backed data, and migrate to Parquet / CSV / JSON / Arrow.
+
+## Install
+
+```bash
+pip install -e .
+```
+
+Zero dependencies. Python 3.9+.
+
+## Use
+
+```bash
+pickle-sentry scan-path/                     # text report, exit 1 on high+
+pickle-sentry . --format json --output report.json
+pickle-sentry . --format sarif --output report.sarif   # for GitHub code scanning
+pickle-sentry . --fail-on critical           # CI: only fail on critical
+pickle-sentry . --exclude /tests/            # production surface only
+```
+
+### Scan a Hugging Face Hub repo (new in 0.2.0)
+
+```bash
+pickle-sentry hub stanfordnlp/imdb                          # a dataset
+pickle-sentry hub hf-internal-testing/tiny-random-bert --repo-type model
+pickle-sentry hub user/repo --max-size-mb 16 --format json
+```
+
+Lists the repo's files via the Hub API, downloads pickle-family files
+(`.pkl`, `.pickle`, `.joblib`, `.pt`, `.pth`, and classic `pytorch_model.bin`)
+and inspects them by disassembly — including the pickle stream inside torch
+zip archives — and AST-scans any Python files in the repo. Files over the
+size cap are flagged, not downloaded. Set `HF_TOKEN` for private repos.
+Nothing downloaded is ever executed.
+
+## What it catches
+
+**In Python code (AST scan — parses, never imports your code):**
+
+| Rule | Severity | What |
+|---|---|---|
+| `HF-DATASETS-PANDAS-BUILDER` | critical | `load_dataset("pandas", ...)` — CVE-2026-57845 |
+| `UNSAFE-DESERIALIZATION` | high | `pickle.load/loads`, `dill`, `cloudpickle`, `marshal`, `shelve`, `joblib.load` |
+| `PANDAS-READ-PICKLE` | high | `pandas.read_pickle(...)` |
+| `TORCH-LOAD-WEIGHTS-ONLY-FALSE` | high | `torch.load(..., weights_only=False)` |
+| `TORCH-LOAD-NO-WEIGHTS-ONLY` | medium | `torch.load(...)` with no explicit `weights_only=True` |
+| `YAML-UNSAFE-LOAD` | medium | `yaml.load(...)` without a SafeLoader |
+| `NUMPY-ALLOW-PICKLE` | high | `numpy.load(..., allow_pickle=True)` |
+
+**In data files (disassembly via `pickletools`, never unpickled):**
+
+| Rule | Severity | What |
+|---|---|---|
+| `PICKLE-DANGEROUS-REDUCE` | critical | Pickle calls `os.system`, `subprocess.*`, `eval`, `exec`, etc. via `REDUCE` |
+| `PICKLE-REDUCE-CALLABLE` | high | Pickle invokes a non-standard callable via `REDUCE` (the CVE PoC payload's shape) |
+| `PICKLE-DANGEROUS-GLOBAL` / `PICKLE-SUSPICIOUS-MODULE` | high/medium | Dangerous globals referenced without a reduce |
+| `PICKLE-FILE-PRESENT` | medium | Any other `.pkl` / `.pickle` / `.joblib` file, and pickle streams inside torch `.pt`/`.pth` zip archives |
+
+## Real-life use case
+
+[docs/USE-CASE.md](docs/USE-CASE.md) walks through a real one end to end:
+scanning the **actual published CVE-2026-57845 PoC repository** before
+touching it. pickle-sentry flags the vulnerable loader (`run_poc.py:139`,
+critical) and disassembles the live payload (`attacker-controlled.pkl`,
+high) — and the PoC's own `marker.txt` proves the payload never executed
+during the scan.
+
+## Live examples
+
+Scanned two real codebases on 9 Nov 2026 — full results, methodology, and
+honest limits in [docs/LIVE-EXAMPLES.md](docs/LIVE-EXAMPLES.md):
+
+- **huggingface/datasets**: 258 files, 24 findings — and exactly **one** in
+  production source: the CVE sink itself, `pd.read_pickle(f)` at
+  `packaged_modules/pandas/pandas.py:56`.
+- **scikit-learn**: 1,037 files, 73 findings — 16 outside tests, concentrated
+  in `sklearn/datasets/` loaders unpickling cached copies of remotely fetched
+  datasets.
+
+Also included: a composite **GitHub Action** (`action.yml`, use it as
+`uses: Sun-Wukhan/pickle-sentry@main`) and a **pre-commit hook**
+(`.pre-commit-hooks.yaml`). Use `--exclude /tests/` to cut test-fixture noise.
+
+## Demo
+
+```bash
+pickle-sentry examples/vulnerable   # flags the CVE pattern + every sink, exit 1
+pickle-sentry examples/safe         # clean, exit 0
+pickle-sentry examples/hf-datasets-pandas.py
+# ^ the actual upstream datasets pandas builder (verbatim from
+#   huggingface/datasets main): flags pd.read_pickle(f) at line 56 —
+#   the exact sink behind CVE-2026-57845.
+```
+
+## Migrate off pickle
+
+- Datasets: `load_dataset("parquet" | "csv" | "json" | "arrow", ...)`
+- Your own DataFrame: `Dataset.from_pandas(df)` instead of a pickle file
+- DataFrames on disk: `df.to_parquet(...)` / `pd.read_parquet(...)`
+- Torch: `torch.load(path, weights_only=True)`
+
+## Tests
+
+```bash
+pip install pytest
+pytest
+```
+
+The inspector tests build a real malicious pickle (`__reduce__` → `os.system`)
+and assert two things: it is flagged critical, and the payload's canary file
+**never appears** — i.e. inspection did not execute it.
+
+## Licence
+
+MIT

pickle_sentry-0.2.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+pickle_sentry/__init__.py,sha256=DpF_J_lwwRLWCWd4owZIC3dykM3okZ9xJn3RFozdpFE,116
+pickle_sentry/cli.py,sha256=h52vygg2xD1CbrgZBp-b6d1GMrAAQgbV-_9ddXvYn-U,4416
+pickle_sentry/hub.py,sha256=Or5lBonj9ODZJKzj9dbXLbKvNAC4otnHVDi-4I9djKg,3850
+pickle_sentry/inspector.py,sha256=R7oRG6mvaAZBS8EIJqsZ7Vy4s8RZ7rpbvAfEkxzdGJE,8348
+pickle_sentry/model.py,sha256=lXC5QeIwrQIJIJcEAxLI0QhzcdUTd_n_7vCDZzOt42w,1348
+pickle_sentry/report.py,sha256=7u478n1Rm1gkXbqYXmiaJt-nCVB3mRJCX4n56Epz7Z8,2164
+pickle_sentry/scanner.py,sha256=JTUpFxDG1enPyxfuPlc2ZyOa2qSK4ChWTiiPGT3gJF0,7355
+pickle_sentry-0.2.0.dist-info/licenses/LICENSE,sha256=Ie-HoTe4ZNaEAGslImATP-l7iMRef20baLqXUDlDDV0,1067
+pickle_sentry-0.2.0.dist-info/METADATA,sha256=oGVyauvrFINMI62trAzO_o8_jhxKX2JTvy1lJN1K0H0,6038
+pickle_sentry-0.2.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+pickle_sentry-0.2.0.dist-info/entry_points.txt,sha256=wfeBPlTLGq-WApa0n3K38tUn96KXz5-DaTrDQgIn7Gg,57
+pickle_sentry-0.2.0.dist-info/top_level.txt,sha256=Nkx1JGlrcF5UARKdDylJlUDT9squOniJI2k_aJGfK9A,14
+pickle_sentry-0.2.0.dist-info/RECORD,,

pickle_sentry-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pickle_sentry-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pickle-sentry = pickle_sentry.cli:main

pickle_sentry-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Navid Khan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pickle_sentry-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pickle_sentry