Model Scanner

@guardbee/mcp-model-scanner

🇬🇧 English | 🇹🇷 Türkçe | 🇨🇳 中文 | 🇯🇵 日本語 | 🇰🇷 한국어 | 🇧🇷 Português | 🇪🇸 Español | 🇩🇪 Deutsch

An MCP (Model Context Protocol) server that scans ML model files for supply-chain risks — the file itself, not the code that loads it.

Most "AI security" tooling looks at your integration code or the prompts flowing through it. This package looks at the artifact you (or a teammate, or a pip install) downloaded from Hugging Face, a registry, or an S3 bucket — or at a Hugging Face repo directly, pinned to a commit. A .pt/.pth/.pkl/.joblib checkpoint is a pickle file, and unpickling isn't just data deserialization — it can call arbitrary Python code the moment the file is loaded (torch.load(), pickle.load(), etc). A malicious checkpoint is a real, well-documented attack vector, not a hypothetical one.

Telemetry is off by default. With GUARDBEE_TELEMETRY=1 it sends the server, tool, success, duration and short parameter values such as a file path; longer strings and fields like content, token or password are replaced with a placeholder. See @guardbee/mcp-telemetry.

Claude ──► model-scanner ──► Your model files

│ ├─ .pt / .pth / .ckpt → PyTorch zip container: extract data.pkl, walk the pickle ├─ .pkl / .pickle / .bin / .dill → raw pickle stream (dill gadgets included) ├─ .joblib / .jbl → pickle + the array bytes and nested pickles joblib embeds ├─ .npy / .npz → object arrays (pickled data), pickles disguised as NumPy ├─ .safetensors → header structure + disguised-binary check ├─ .h5 / .hdf5 / .keras → Keras Lambda-layer RCE (HDF5 and Keras 3 zip) ├─ .onnx → external_data path-traversal heuristic ├─ .gguf → header/tensor bounds, chat-template SSTI and injected text ├─ saved_model.pb / .pb / .pbtxt / .tflite → graph ops that touch files or Python └─ hf://owner/repo@rev → every model file of a Hugging Face repo at one commit

---

Why pickle is the core of this

Pickle streams are bytecode for a tiny stack VM. A GLOBAL/STACK_GLOBAL opcode names any importable Python object; the very next opcodes typically call it. There is nothing stopping a crafted pickle from naming os.system or subprocess.Popen instead of a tensor-rebuilding function — and pickle.load()/torch.load() will happily resolve and invoke it. This is the same technique tools like picklescan/fickling/Hugging Face's Picklescan integration are built around.

This package implements a from-scratch pickle machine (protocols 0–5) rather than shelling out to Python or using a regex. It walks the opcode stream byte by byte and tracks the stack and memo without calling anything, so a protocol 4+ STACK_GLOBAL resolves to the module and name actually on the stack, including strings fetched back from the memo, as NumPy 2 pickles do. A regex over raw bytes would both miss and misfire constantly.

joblib needs the same machine: joblib.dump writes each NumPy array's raw bytes (or, for object arrays, a whole nested pickle) right after the array's NumpyArrayWrapper. The scanner reads the wrapper's shape and dtype from the stack, skips exactly that many bytes, and checks the nested pickles too.

Every GLOBAL/STACK_GLOBAL/INST reference found is checked against:

• a denylist of modules with no legitimate reason to appear in a tensor deserialization path (os, subprocess, socket, builtins.eval, ctypes, …) → reported as critical/high
• an allowlist of the modules real ML frameworks actually reference (numpy, torch, sklearn, collections, …) → silently safe, no noise
• anything else → reported as medium ("unknown", not "malicious" — for manual review, keeping the false-positive rate low)

For PyTorch's default zip-based checkpoint format, the scanner reads the ZIP central directory directly off disk (with Zip64 support) to locate and extract just the small data.pkl metadata entry — it never loads a multi-gigabyte checkpoint fully into memory.

---

Features

• Real pickle parsing — a stack-tracking pickle machine, not a regex, not a Python subprocess call
• 44 dangerous-global rules across 6 risk categories (code-execution, process-execution, network, filesystem, reflection, deserialization), including dill's code-object and import gadgets
• PyTorch zip container support (including Zip64) — extracts and scans data.pkl without loading the full checkpoint
• joblib — walks past embedded arrays to every pickle opcode in the file, nested object-array pickles included; zlib/gzip dumps are decompressed
• NumPy `.npy`/`.npz` — object arrays (stored as a pickle, loaded with allow_pickle=True) and plain pickles renamed to a NumPy extension
• `.safetensors` structural validation — malformed/out-of-bounds headers, and detection of a pickle/zip disguised with a .safetensors extension
• Keras Lambda-layer RCE — in .h5, Keras 3 .keras zips and SavedModel keras_metadata.pb
• ONNX `external_data` path-traversal heuristic
• GGUF — header counts, string and array lengths, tensor dimensions, types and data bounds checked against the file; chat templates checked for Jinja sandbox escapes, hidden characters and instructions aimed at the model
• TensorFlow — SavedModel, frozen GraphDef (.pb/.pbtxt) and TFLite Flex ops that read or write files, call Python or send tensors to a debug URL
• Hugging Face repos — scan_hf_repo / scan hf://owner/repo@revision resolves the revision to a commit and scans every model file from it
• Bounded reads everywhere (10MB pickle prefix, 100MB safetensors header cap, 50MB zip-entry cap, GGUF and joblib read through a 4MB window) — safe against decompression bombs and won't OOM on huge model files
• SARIF 2.1.0 output — CI/CD integration (GitHub Code Scanning, etc.)
• Config file support via guardbee.yml
• 82 unit tests with malicious and benign fixtures for every format, plus a false-positive check against popular public models

---

Quick Start

Claude Desktop / MCP Client

{

"mcpServers": { "guardbee-model-scanner": { "command": "npx", "args": ["-y", "@guardbee/mcp-model-scanner"] } } }

CLI (CI/CD)

npx @guardbee/mcp-model-scanner scan ./models --fail-on=high --format=sarif > results.sarif

A Hugging Face model repo at a pinned commit (branch, tag or sha; HF_TOKEN for gated/private repos)

npx @guardbee/mcp-model-scanner scan hf://openai-community/gpt2@607a30d783dfa663caf39e06633721c8d4cfcd7e

In repo mode the revision is resolved to a commit sha and every file is read from that commit, so the result describes a fixed snapshot; findings point at hf://owner/repo@sha/path. Files up to 256 MB are downloaded whole. Larger ones are checked from their first 64 MB, plus the last 64 MB for zip containers (the central directory), which holds every header, pickle stream and tensor table the checks read.

---

MCP Tools

---

What it catches

Full dangerous-global catalog: run the list_patterns tool, or see src/dangerousGlobals.ts.

Rule IDs added in 0.4

| gguf_chat_template_url, gguf_unknown_tensor_type, `gguf_not_pa