ModelScan

Overview

Serialized model formats — pickle in particular, which underpins PyTorch checkpoints — allow arbitrary code execution on load by design. That makes a model downloaded from a hub like Hugging Face just as risky as an untrusted binary. ModelScan statically inspects model files across common formats (Pickle, PyTorch .pt/.pth, TensorFlow SavedModel, Keras H5, and more) for known-dangerous opcodes and operators (os.system, subprocess, eval, __reduce__ abuse, etc.) without executing the file, flagging supply-chain-poisoned models before they ever get loaded into a training or inference pipeline.

Installation

pip install modelscan
# Optional: extras for specific frameworks
pip install "modelscan[tensorflow,h5py]"

CLI Usage

Scan a single model file

modelscan -p <model_file.pkl>

Scan an entire directory (e.g. a downloaded HF repo snapshot)

modelscan -p ./downloaded_model/

Output as JSON for CI pipelines

modelscan -p <model_file.pt> --output-format json --output-file scan-report.json

Show only the summary, skip verbose per-operator detail

modelscan -p <model_file.h5> -s

Library Usage

from modelscan.modelscan import ModelScan

scanner = ModelScan()
results = scanner.scan("<model_file.pkl>")

if results["summary"]["total_issues"] > 0:
    for issue in results["issues"]:
        print(issue["severity"], issue["description"])
    raise RuntimeError("Untrusted model failed ModelScan checks")

Tips

• Wire ModelScan into CI/CD as a pre-deploy gate for any pipeline that pulls model weights from an external hub — treat a failed scan the same as a failed dependency audit.
• A clean scan means “no known-dangerous serialization opcodes found,” not “the model’s numeric weights are safe” — it doesn’t detect adversarial weight tampering, only code-execution vectors in the file format itself.
• For pickle-heavy PyTorch checkpoints specifically, cross-check suspicious findings with Fickling for deeper bytecode-level analysis.

usage: modelscan [-h] -p PATH [-o OUTPUT_FILE]
                  [--output-format {console,json}] [-s]
                  [-l LOG_LEVEL] [--reporting-modules MODULES]

required arguments:
  -p, --path PATH           file or directory to scan

optional arguments:
  -o, --output-file FILE     write report to file
  --output-format FORMAT     console (default) or json
  -s, --show-skipped         list files skipped as unsupported format
  -l, --log-level LEVEL      DEBUG, INFO, WARNING, ERROR
  --reporting-modules LIST   restrict to specific scanners
                              (pickle, h5, keras, tensorflow, ...)

exit codes:
  0   no issues found
  1   issues found (see report)
  2   scan error (unreadable/corrupt file)

Vue d’ensemble

Les formats de modèles sérialisés, en particulier pickle, qui sous-tend les checkpoints PyTorch, permettent par conception l’exécution de code arbitraire au chargement. Cela rend un modèle téléchargé depuis un hub comme Hugging Face aussi risqué qu’un binaire non fiable. ModelScan inspecte statiquement les fichiers de modèles dans les formats courants (Pickle, PyTorch .pt/.pth, TensorFlow SavedModel, Keras H5, et plus) à la recherche d’opcodes et d’opérateurs connus comme dangereux (os.system, subprocess, eval, abus de __reduce__, etc.) sans exécuter le fichier, signalant les modèles empoisonnés dans la chaîne d’approvisionnement avant qu’ils ne soient chargés dans un pipeline d’entraînement ou d’inférence.

Installation

pip install modelscan
# Optionnel : extras pour des frameworks spécifiques
pip install "modelscan[tensorflow,h5py]"

Utilisation en ligne de commande

# Scanner un seul fichier de modèle
modelscan -p <model_file.pkl>

# Scanner un répertoire entier (ex. un snapshot de repo HF téléchargé)
modelscan -p ./downloaded_model/

# Sortie au format JSON pour les pipelines CI
modelscan -p <model_file.pt> --output-format json --output-file scan-report.json

# Afficher uniquement le résumé, sans le détail verbeux par opérateur
modelscan -p <model_file.h5> -s

Utilisation en bibliothèque

from modelscan.modelscan import ModelScan

scanner = ModelScan()
results = scanner.scan("<model_file.pkl>")

if results["summary"]["total_issues"] > 0:
    for issue in results["issues"]:
        print(issue["severity"], issue["description"])
    raise RuntimeError("Untrusted model failed ModelScan checks")

Conseils

• Intégrer ModelScan dans la CI/CD comme garde-fou avant déploiement pour tout pipeline qui récupère des poids de modèle depuis un hub externe, traiter un scan en échec comme un audit de dépendances en échec.
• Un scan propre signifie « aucun opcode de sérialisation connu comme dangereux trouvé », pas « les poids numériques du modèle sont sûrs » : il ne détecte pas la falsification adverse des poids, seulement les vecteurs d’exécution de code dans le format du fichier lui-même.
• Pour les checkpoints PyTorch fortement basés sur pickle en particulier, croiser les résultats suspects avec Fickling pour une analyse plus poussée au niveau du bytecode.

usage: modelscan [-h] -p PATH [-o OUTPUT_FILE]
                  [--output-format {console,json}] [-s]
                  [-l LOG_LEVEL] [--reporting-modules MODULES]

required arguments:
  -p, --path PATH           file or directory to scan

optional arguments:
  -o, --output-file FILE     write report to file
  --output-format FORMAT     console (default) or json
  -s, --show-skipped         list files skipped as unsupported format
  -l, --log-level LEVEL      DEBUG, INFO, WARNING, ERROR
  --reporting-modules LIST   restrict to specific scanners
                              (pickle, h5, keras, tensorflow, ...)

exit codes:
  0   no issues found
  1   issues found (see report)
  2   scan error (unreadable/corrupt file)