ModelAudit

Proteggi i tuoi modelli AI prima della distribuzione. Scanner statico che rileva codice malevolo, potenziali indicatori di backdoor e vulnerabilità di sicurezza nei file di modelli ML — senza mai caricarli o eseguirli.

Documentazione completa | Esempi di utilizzo | Formati supportati

Perché ModelAudit

I modelli vengono scaricati da registry non affidabili, passano attraverso la CI e finiscono in produzione. Gli strumenti SAST tradizionali non esaminano gli opcode pickle, i layout dei gruppi HDF5, i grafi proto ONNX o le firme TensorFlow SavedModel — ModelAudit lo fa:

Scansionare staticamente. Nessun modello viene mai caricato, unpicklato o eseguito.
Coprire i formati che distribuisci realmente. Oltre 40 scanner che coprono pickle, PyTorch, SafeTensors, ONNX, TensorFlow, Keras, GGUF, archivi e configurazioni.
Integrarsi nella CI. Output leggibili dalle macchine (JSON, SARIF), modalità strict, codici di uscita e scanner selezionabili.
Evidenziare i limiti di copertura. Gli scanner riconosciuti segnalano lacune dell'analisi limitata, come letture troncate o budget esauriti, invece di presentarli come risultati completamente coperti.

Strumenti comparabili: picklescan (solo pickle, basato su Python), fickling (solo pickle, basato su AST), modelscan (sottoinsieme pickle + TensorFlow + Keras). ModelAudit offre una copertura più ampia e include un motore pickle Rust nativo tramite il pacchetto complementare modelaudit-picklescan.

Avvio rapido

Richiede Python 3.10-3.13```bash pip install "modelaudit[all]"

Scan a file or directory

modelaudit model.pkl modelaudit ./models/

Export results for CI/CD

modelaudit model.pkl --format json --output results.json

I received no content to translate. The input after "INPUT:" is empty. Please provide chunk 3 of 23.```
$ modelaudit suspicious_model.pkl

Files scanned: 1 | Issues found: 2 critical, 1 warning

1. suspicious_model.pkl (pos 28): [CRITICAL] Malicious code execution attempt
   Why: Contains os.system() call that could run arbitrary commands

2. suspicious_model.pkl (pos 52): [WARNING] Dangerous pickle deserialization
   Why: Could execute code when the model loads

Cosa rileva

Attacchi di esecuzione di codice in file Pickle, PyTorch, NumPy e Joblib
Indicatori di potenziali backdoor — pattern di pesi sospetti, tensori anomali o segnali di codice nascosto
Segreti incorporati — chiavi API, token e credenziali nei pesi o nei metadati del modello
Indicatori di rete — URL, IP e uso di socket che potrebbero consentire l'esfiltrazione di dati
Exploit di archivi — path traversal, attacchi tramite symlink in file ZIP/TAR/7z
Operazioni ML non sicure — layer Lambda, operazioni personalizzate, TorchScript/JIT, injection di template
Rischi della supply chain — manomissioni, violazioni di licenza, configurazioni sospette

Formati supportati

ModelAudit include 45 scanner registrati che coprono formati di modelli, archivi e configurazioni:

Inoltre include scanner per ZIP, TAR, 7-Zip, layer OCI, template Jinja2, metadati JSON/YAML, manifest, model card, file di testo e riconoscimento RAR. Gli archivi RAR vengono segnalati come non supportati/fail-closed invece di essere saltati.

Anche i protobuf TensorFlow SavedModel e MetaGraph strutturalmente validi vengono riconosciuti quando rinominati con suffissi non di modello. Anche i modelli CoreML possono essere riconosciuti se rinominati, con copertura incompleta segnalata esplicitamente. I file SafeTensors con struttura sovradimensionata ma plausibile vengono conservati per un'analisi limitata e inconcludente sotto suffissi altrimenti non rivendicati, come .jpg. Anche i checkpoint Flax/JAX MessagePack strutturalmente plausibili vengono riconosciuti quando rinominati con suffissi non di modello; le strutture rinominate che non possono essere classificate completamente vengono segnalate come copertura incompleta. Anche i metadati strutturati dei checkpoint JAX/Orbax JSON vengono riconosciuti quando rinominati; i candidati ambigui sovradimensionati vengono segnalati come copertura incompleta; i pattern di sicurezza osservabili nel prefisso ispezionato limitato possono comunque essere segnalati in modo conservativo.

Visualizza la documentazione completa dei formati

Sorgenti Remote

Scansiona modelli direttamente da registry remoti e archiviazione cloud:```bash

Hugging Face

modelaudit https://huggingface.co/gpt2 modelaudit hf://microsoft/DialoGPT-medium

Cloud storage

modelaudit s3://bucket/model.pt modelaudit gs://bucket/models/

MLflow registry

Non-local artifact stores: export MODELAUDIT_MLFLOW_ALLOWED_ARTIFACT_URIS=s3://trusted-bucket/models

modelaudit models:/MyModel/Production

JFrog Artifactory (files and folders)

Auth: export JFROG_API_TOKEN=...

modelaudit https://company.jfrog.io/artifactory/repo/model.pt modelaudit https://company.jfrog.io/artifactory/repo/models/

DVC-tracked models

modelaudit model.dvc

### Variabili d'ambiente per l'autenticazione

- `HF_TOKEN` per repository Hugging Face privati
- `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` (e opzionale `AWS_SESSION_TOKEN`) per S3
- `GOOGLE_APPLICATION_CREDENTIALS` per GCS
- `MLFLOW_TRACKING_URI` per l'accesso al registry MLflow
- `MODELAUDIT_MLFLOW_ALLOWED_ARTIFACT_URIS` per radici di artefatti MLflow non locali (prefissi URI separati da virgole)
- Usa radici backend concrete come `s3://bucket/prefix`; gli URI logici `models:/` o `runs:/` e i percorsi remoti con codifica percentuale vengono rifiutati.
- `JFROG_API_TOKEN` o `JFROG_ACCESS_TOKEN` per JFrog Artifactory
- `MODELAUDIT_JFROG_ALLOWED_HOSTS` per nomi host JFrog personalizzati separati da virgole che possono ricevere credenziali
- `MODELAUDIT_JFROG_ALLOWED_REDIRECT_HOSTS` per nomi host di reindirizzamento esterni separati da virgole che possono essere scaricati senza credenziali
- Conserva le credenziali in variabili d'ambiente o in un gestore di segreti e non committare mai token/chiavi.

## Installazione```bash
# Broad scanner coverage (recommended; excludes the TensorFlow runtime and platform-specific TensorRT)
pip install "modelaudit[all]"

# Core only (static scanners, pickle, NumPy, archives, manifests, metadata)
pip install modelaudit

# Specific frameworks (TensorFlow installs on Python 3.11-3.12; ONNX installs on Python 3.10-3.12)
pip install "modelaudit[tensorflow,pytorch,h5,onnx,safetensors]"

# CI/CD environments
pip install "modelaudit[all-ci]"

# On Python 3.11-3.12, add TensorFlow only when you need runtime-dependent checkpoint or weight analysis
pip install "modelaudit[all,tensorflow]"

# Docker
docker run --rm -v "$(pwd)":/app ghcr.io/promptfoo/modelaudit:latest model.pkl

The ONNX extra, inclusa la parte ONNX di modelaudit[all], è impacchettato per Python 3.10-3.12. Gli extra che includono PyTorch richiedono Python 3.10-3.12 o CPython 3.13 standard (con GIL); le wheel di PyTorch 2.13 patchate non supportano CPython 3.13t free-threaded. Usa CPython standard, poiché lo scanner pickle nativo di ModelAudit non supporta CPython 3.13t. Su Apple Silicon, gli extra che includono PyTorch richiedono macOS 14 o successivo perché le wheel hanno come target macosx_14_0_arm64; l'installazione solo core rimane disponibile per la scansione statica su macOS 11-13.

Opzioni CLI

Comandi principali:```bash modelaudit [PATHS...] # Default scan command modelaudit scan [OPTIONS] PATHS... # Explicit scan command modelaudit scan --list-scanners # List scanner IDs for targeted scans modelaudit metadata [OPTIONS] PATH # Extract model metadata safely (no deserialization by default) modelaudit doctor [--show-failed] # Diagnose scanner/dependency availability modelaudit debug [--json] [--verbose] # Environment and configuration diagnostics modelaudit cache [stats|clear|cleanup] [OPTIONS]

Opzioni di scansione comuni:```text
--format {text,json,sarif}   Output format (default: auto-detected)
--output FILE                Write results to file
--strict                     Fail on warnings, scan all file types, strict license validation
--sbom FILE                  Generate CycloneDX SBOM
--stream                     Process files one-by-one; remote downloads are deleted after scanning
--assume-shard-family        Treat explicitly listed cross-directory shards as one model family
--max-size SIZE              Size limit (e.g., 10GB)
--timeout SECONDS            Override scan timeout
--dry-run                    Preview what would be scanned
--verbose / --quiet          Control output detail
--blacklist PATTERN          Additional patterns to flag
--no-cache                   Disable result caching
--cache-dir DIR              Set cache directory for downloads and scan results
--progress                   Force progress display
--scanners LIST              Only run selected scanners (IDs/classes; comma-separated or repeated)
--exclude-scanner NAME       Exclude a scanner from the active set (comma-separated or repeated)
--list-scanners              List scanner IDs, class names, extensions, and dependencies

Selezione mirata dello scanner:```bash

Discover scanner IDs and class names

modelaudit scan --list-scanners modelaudit scan --list-scanners --format json

Run only selected scanners

modelaudit scan ./models --scanners pickle,tf_savedmodel modelaudit scan ./model.pkl --scanners PickleScanner

Run the default scanner set except a noisy or slow scanner

modelaudit scan ./models --exclude-scanner weight_distribution

For container formats, include both the container scanner and nested scanner

modelaudit scan ./archive.zip --scanners zip,pickle

`--scanners` parte da una allowlist esplicita. `--exclude-scanner` sottrae scanner da tale allowlist o dal set di scanner predefinito. La selezione degli scanner viene riflessa nell'output JSON sotto `scanner_selection`.

Per le cartelle remote, ModelAudit restringe i download in base alle estensioni degli scanner selezionati quando è sicuro. Il routing basato sul contenuto per wrapper rinominati viene applicato dopo l'acquisizione; esegui la scansione di un URL di file diretto quando i nomi dei file del repository potrebbero essere intenzionalmente fuorvianti.

## Estrazione dei Metadati```bash
# Human-readable summary (safe default: no model deserialization)
modelaudit metadata model.safetensors

# Machine-readable output
modelaudit metadata ./models --format json --output metadata.json

# Focus only on security-relevant metadata fields
modelaudit metadata model.onnx --security-only

--trust-loaders abilita i loader di metadati dello scanner che possono deserializzare il contenuto del modello. Usalo solo su artefatti attendibili in ambienti isolati.

Codici di uscita

0: Nessun problema di sicurezza rilevato
1: Problemi di sicurezza rilevati
2: Errori di scansione

Telemetria e privacy

ModelAudit include la telemetria per l'affidabilità del prodotto e l'analisi dell'utilizzo.

I metadati raccolti possono includere l'uso di comandi e funzionalità, metadati di tempi o dimensioni di scansione e download, uso di scanner/tipi di file, identificatori stabili di regole o CVE, aggregati di gravità, estensioni di file registrate, categorie approssimative di origini o provider e metadati di versione runtime, piattaforma e CI.
La telemetria non include percorsi locali grezzi, nomi di file, ID o nomi di modelli, identificatori di repository o artefatti, chiavi di bucket o oggetti, percorsi URL remoti, testo libero di problemi o errori, userinfo di URL, stringhe di query, frammenti o contenuti binari dei modelli.
Le installazioni pacchettizzate abilitano la telemetria per impostazione predefinita. La telemetria viene disabilitata automaticamente quando CI=true è impostato o IS_TESTING=true è impostato, e nelle installazioni di sviluppo in modalità editable a meno che MODELAUDIT_TELEMETRY_DEV=1. Gli eventi inviati da altri provider CI (TeamCity, CodeBuild, Bitbucket Pipelines, Jenkins) vengono contrassegnati con isRunningInCi=true in modo da poter essere filtrati a valle.
Un identificatore utente pseudonimo persistente è memorizzato in ~/.promptfoo/promptfoo.yaml per la correlazione tra strumenti con Promptfoo, e ogni sessione di telemetria utilizza un nuovo identificatore di sessione. Gli ID esistenti da ~/.modelaudit/user_config.json vengono migrati al primo avvio dopo l'aggiornamento. Un valore email legacy in quel file, se presente, può essere associato al profilo utente di analisi.

Disattiva esplicitamente con una delle due variabili d'ambiente:```bash export PROMPTFOO_DISABLE_TELEMETRY=1

or

export NO_ANALYTICS=1

Per aderire durante le installazioni editabili/di sviluppo:```bash
export MODELAUDIT_TELEMETRY_DEV=1

Esempi di output```bash

JSON for CI/CD pipelines