ModelAudit

Proteja seus modelos de IA antes da implantação. Scanner estático que detecta código malicioso, possíveis indicadores de backdoor e vulnerabilidades de segurança em arquivos de modelos de ML — sem nunca carregá-los ou executá-los.

Documentação Completa | Exemplos de Uso | Formatos Suportados

Por que ModelAudit

Modelos são baixados de registries não confiáveis, passam pela CI e acabam rodando em produção. Ferramentas SAST tradicionais não analisam opcodes de pickle, layouts de grupos HDF5, grafos proto ONNX ou assinaturas de TensorFlow SavedModel — o ModelAudit analisa:

Faça varredura estática. Nenhum modelo é carregado, desserializado ou executado.
Cubra os formatos que você realmente utiliza. 40+ scanners abrangendo pickle, PyTorch, SafeTensors, ONNX, TensorFlow, Keras, GGUF, arquivos compactados e configurações.
Integre-se à CI. Saída legível por máquina (JSON, SARIF), modo estrito, códigos de saída e scanners selecionáveis.
Evidencie limites de cobertura. Scanners reconhecidos relatam lacunas de análise limitada, como leituras truncadas ou orçamentos esgotados, em vez de apresentá-las como resultados totalmente cobertos.

Ferramentas comparáveis: picklescan (somente pickle, baseado em Python), fickling (somente pickle, baseado em AST), modelscan (pickle + TensorFlow + subconjunto de Keras). O ModelAudit tem cobertura mais ampla e vem com um mecanismo pickle nativo em Rust por meio de seu pacote complementar modelaudit-picklescan.

Início Rápido

Requer 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

(empty)```
$ 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

O que ele detecta

Ataques de execução de código em arquivos Pickle, PyTorch, NumPy e Joblib
Possíveis indicadores de backdoor — padrões de pesos suspeitos, tensores anômalos ou sinais de código oculto
Segredos incorporados — chaves de API, tokens e credenciais em pesos ou metadados do modelo
Indicadores de rede — URLs, IPs e uso de sockets que possam permitir exfiltração de dados
Explorações de arquivos compactados — path traversal, ataques de symlink em arquivos ZIP/TAR/7z
Operações de ML inseguras — camadas Lambda, operações personalizadas, TorchScript/JIT, injeção de templates
Riscos na cadeia de suprimentos — adulteração, violações de licença, configurações suspeitas

Formatos Suportados

O ModelAudit inclui 45 scanners registrados cobrindo formatos de modelo, arquivo e configuração:

Além disso, há scanners para ZIP, TAR, 7-Zip, camadas OCI, templates Jinja2, metadados JSON/YAML, manifestos, model cards, arquivos de texto e reconhecimento de RAR. Arquivos RAR são relatados como não suportados/fail-closed em vez de serem ignorados.

Protobufs TensorFlow SavedModel e MetaGraph estruturalmente válidos também são reconhecidos quando renomeados para sufixos não relacionados a modelos. Modelos CoreML também podem ser reconhecidos quando renomeados, com cobertura incompleta relatada explicitamente. Arquivos SafeTensors com enquadramento superdimensionado, porém plausível, são retidos para análise limitada e inconclusiva sob sufixos que de outra forma não seriam reivindicados, como .jpg. Checkpoints Flax/JAX MessagePack estruturalmente plausíveis também são reconhecidos quando renomeados para sufixos não relacionados a modelos; estruturas renomeadas que não podem ser totalmente classificadas são relatadas como cobertura incompleta. Metadados estruturados de checkpoints JSON JAX/Orbax também são reconhecidos quando renomeados; candidatos ambíguos superdimensionados são relatados como cobertura incompleta; padrões de segurança observáveis no prefixo inspecionado limitado ainda podem ser relatados de forma conservadora.

Ver documentação completa de formatos

Fontes Remotas

Examine modelos diretamente de registros remotos e armazenamento em nuvem:```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

### Variáveis de Ambiente de Autenticação

- `HF_TOKEN` para repositórios privados do Hugging Face
- `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` (e opcionalmente `AWS_SESSION_TOKEN`) para S3
- `GOOGLE_APPLICATION_CREDENTIALS` para GCS
- `MLFLOW_TRACKING_URI` para acesso ao registro do MLflow
- `MODELAUDIT_MLFLOW_ALLOWED_ARTIFACT_URIS` para raízes de artefatos do MLflow não locais (prefixos de URI separados por vírgula)
- Use raízes de backend concretas, como `s3://bucket/prefix`; URIs lógicos `models:/` ou `runs:/` e caminhos remotos com codificação percentual são recusados.
- `JFROG_API_TOKEN` ou `JFROG_ACCESS_TOKEN` para JFrog Artifactory
- `MODELAUDIT_JFROG_ALLOWED_HOSTS` para nomes de host personalizados do JFrog separados por vírgula que podem receber credenciais
- `MODELAUDIT_JFROG_ALLOWED_REDIRECT_HOSTS` para nomes de host de redirecionamento externo separados por vírgula que podem ser baixados sem credenciais
- Armazene credenciais em variáveis de ambiente ou em um gerenciador de segredos e nunca faça commit de tokens/chaves.

## Instalação```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

O extra ONNX, incluindo a parte ONNX de modelaudit[all], é empacotado para Python 3.10-3.12. Extras que contêm PyTorch exigem Python 3.10-3.12 ou CPython 3.13 padrão (com GIL); as wheels do PyTorch 2.13 com patch não suportam CPython 3.13t sem GIL. Use CPython padrão, pois o scanner pickle nativo do ModelAudit também não suporta CPython 3.13t. Em Apple Silicon, extras que contêm PyTorch exigem macOS 14 ou mais recente porque as wheels têm como alvo macosx_14_0_arm64; a instalação somente do núcleo permanece disponível para análise estática no macOS 11-13.

Opções de CLI

Comandos principais:```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]

Opções de varredura comuns:```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

Seleção de scanner direcionado:```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` começa a partir de uma allowlist explícita. `--exclude-scanner` subtrai scanners dessa allowlist ou do conjunto de scanners padrão. A seleção de scanners é refletida na saída JSON sob `scanner_selection`.

Para pastas remotas, o ModelAudit restringe downloads pelas extensões de scanner selecionadas quando seguro. O roteamento de wrappers renomeados com base no conteúdo é aplicado após a aquisição; escaneie um URL de arquivo direto quando os nomes de arquivos do repositório podem ser intencionalmente enganosos.

## Extração de Metadados```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 ativa carregadores de metadados do scanner que podem desserializar conteúdo de modelos. Use apenas em artefatos confiáveis em ambientes isolados.

Códigos de Saída

0: Nenhum problema de segurança detectado
1: Problemas de segurança detectados
2: Erros de varredura

Telemetria e Privacidade

O ModelAudit inclui telemetria para confiabilidade do produto e análises de uso.

Os metadados coletados podem incluir uso de comandos e recursos, metadados de tempo ou tamanho de varreduras e downloads, uso de scanners/tipos de arquivo, identificadores estáveis de regras ou CVEs, agregados de gravidade, extensões de arquivo registradas, categorias amplas de origem ou provedor e metadados de versão de runtime, plataforma e CI.
A telemetria não inclui caminhos locais brutos, nomes de arquivos, IDs ou nomes de modelos, identificadores de repositório ou artefato, chaves de bucket ou objeto, caminhos de URL remotos, texto livre de problemas ou erros, userinfo de URL, strings de consulta, fragmentos ou conteúdos binários de modelos.
Instalações empacotadas habilitam a telemetria por padrão. A telemetria é desativada automaticamente quando CI=true está definido ou IS_TESTING=true está definido, e em instalações de desenvolvimento editáveis, a menos que MODELAUDIT_TELEMETRY_DEV=1 esteja definido. Eventos enviados de outros provedores de CI (TeamCity, CodeBuild, Bitbucket Pipelines, Jenkins) são marcados com isRunningInCi=true para que possam ser filtrados posteriormente.
Um identificador de usuário pseudônimo persistente é armazenado em ~/.promptfoo/promptfoo.yaml para correlação entre ferramentas com Promptfoo, e cada sessão de telemetria usa um novo identificador de sessão. IDs existentes de ~/.modelaudit/user_config.json são migrados na primeira execução após a atualização. Um valor de e-mail legado nesse arquivo, se presente, pode ser anexado ao perfil de usuário de análises.

Opte por não participar explicitamente com qualquer uma das variáveis de ambiente:```bash export PROMPTFOO_DISABLE_TELEMETRY=1

or

export NO_ANALYTICS=1

Para optar durante instalações editáveis/de desenvolvimento:```bash
export MODELAUDIT_TELEMETRY_DEV=1

Exemplos de Saída```bash

JSON for CI/CD pipelines