← retour aux outils back to tools

# ModelScan

Scanner open source de Protect AI pour les fichiers de modèles ML sérialisés : inspecte statiquement les modèles Pickle, PyTorch, TensorFlow et Keras à la recherche de code malveillant embarqué, afin de se prémunir contre les attaques de la chaîne d'approvisionnement. Protect AI's open-source scanner for serialized ML model files — statically inspects Pickle, PyTorch, TensorFlow, and Keras models for embedded malicious code to guard against supply-chain attacks.

↗ https://github.com/protectai/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.

Help / Man page

    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.

Aide / Page de manuel

    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)