# protectai/modelscan architecture

> Architecture diagram of the GitHub repository protectai/modelscan, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/protectai/modelscan
- Repository: https://github.com/protectai/modelscan

## Overview

ModelScan is a static scanner for unsafe code in serialized ML models. A user supplies a model through the CLI; the scan orchestrator prepares the model and dispatches format-specific checks, which report findings, errors, or skipped scans for presentation. The README documents Pickle, H5, Keras, and TensorFlow SavedModel support, with severity-ranked findings. The source index supports the main module relationships shown; because several implementations are only partially excerpted, some wiring is omitted rather than inferred.

Main entry points: [`modelscan/modelscan.py`](https://github.com/protectai/modelscan/blob/main/modelscan/modelscan.py) (Scan orchestrator), [`modelscan/cli.py`](https://github.com/protectai/modelscan/blob/main/modelscan/cli.py) (Command-line interface), [`modelscan/tools/picklescanner.py`](https://github.com/protectai/modelscan/blob/main/modelscan/tools/picklescanner.py) (Pickle opcode analysis), [`modelscan/model.py`](https://github.com/protectai/modelscan/blob/main/modelscan/model.py) (Model stream and context)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry"]
  node_cli["Command-line interface<br/>[cli.py]"]
  node_cliutils["CLI utilities<br/>[cli_utils.py]"]
end

subgraph group_runtime["Scan runtime"]
  node_orchestrator["Scan orchestrator<br/>[modelscan.py]"]
  node_settings["Scan settings<br/>[settings.py]"]
  node_middleware["Middleware pipeline<br/>[middleware.py]"]
  node_formatdetect["Extension format detection"]
  node_model["Model stream and context<br/>[model.py]"]
  node_dispatcher["Scanner interface<br/>[scan.py]"]
end

subgraph group_formats["Format scanners"]
  node_pickle["Pickle and PyTorch scans<br/>[scan.py]"]
  node_pickleops["Pickle opcode analysis<br/>[picklescanner.py]"]
  node_h5["H5 Lambda scan<br/>[scan.py]"]
  node_keras["Keras archive scan<br/>[scan.py]"]
  node_savedmodel["SavedModel scans<br/>[scan.py]"]
end

subgraph group_results["Findings and output"]
  node_issues["Issue model and severity<br/>[issues.py]"]
  node_errors["Scan errors<br/>[error.py]"]
  node_skips["Skip records<br/>[skip.py]"]
  node_reports["Report output<br/>[reports.py]"]
end

node_user(("Model provider"))

node_user -->|"supplies model"| node_cli
node_cli -->|"starts scan"| node_orchestrator
node_cli -->|"loads settings"| node_settings
node_cli -->|"uses utilities"| node_cliutils
node_orchestrator -->|"uses settings"| node_settings
node_orchestrator -->|"runs middleware"| node_middleware
node_middleware -->|"configures middleware"| node_formatdetect
node_formatdetect -->|"sets format context"| node_model
node_orchestrator -->|"prepares model"| node_model
node_orchestrator -->|"uses scanner interface"| node_dispatcher
node_orchestrator -->|"handles errors"| node_errors
node_orchestrator -->|"handles skips"| node_skips
node_orchestrator -->|"collects findings"| node_issues
node_pickle -->|"analyzes opcodes"| node_pickleops
node_pickle -->|"reads model"| node_model
node_h5 -->|"reuses operator checks"| node_savedmodel
node_keras -->|"reuses operator checks"| node_savedmodel
node_savedmodel -.->|"reads model"| node_model
node_pickleops -->|"creates findings"| node_issues
node_pickleops -->|"raises scan errors"| node_errors
node_pickleops -->|"records skips"| node_skips
node_reports -->|"formats scan results"| node_orchestrator
node_reports -->|"renders findings"| node_issues

click node_cli "https://github.com/protectai/modelscan/blob/main/modelscan/cli.py"
click node_cliutils "https://github.com/protectai/modelscan/blob/main/modelscan/tools/cli_utils.py"
click node_orchestrator "https://github.com/protectai/modelscan/blob/main/modelscan/modelscan.py"
click node_settings "https://github.com/protectai/modelscan/blob/main/modelscan/settings.py"
click node_middleware "https://github.com/protectai/modelscan/blob/main/modelscan/middlewares/middleware.py"
click node_formatdetect "https://github.com/protectai/modelscan/blob/main/modelscan/middlewares/format_via_extension.py"
click node_model "https://github.com/protectai/modelscan/blob/main/modelscan/model.py"
click node_dispatcher "https://github.com/protectai/modelscan/blob/main/modelscan/scanners/scan.py"
click node_pickle "https://github.com/protectai/modelscan/blob/main/modelscan/scanners/pickle/scan.py"
click node_pickleops "https://github.com/protectai/modelscan/blob/main/modelscan/tools/picklescanner.py"
click node_h5 "https://github.com/protectai/modelscan/blob/main/modelscan/scanners/h5/scan.py"
click node_keras "https://github.com/protectai/modelscan/blob/main/modelscan/scanners/keras/scan.py"
click node_savedmodel "https://github.com/protectai/modelscan/blob/main/modelscan/scanners/saved_model/scan.py"
click node_issues "https://github.com/protectai/modelscan/blob/main/modelscan/issues.py"
click node_errors "https://github.com/protectai/modelscan/blob/main/modelscan/error.py"
click node_skips "https://github.com/protectai/modelscan/blob/main/modelscan/skip.py"
click node_reports "https://github.com/protectai/modelscan/blob/main/modelscan/reports.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_cliutils toneBlue
class node_orchestrator,node_settings,node_middleware,node_formatdetect,node_model,node_dispatcher toneAmber
class node_pickle,node_pickleops,node_h5,node_keras,node_savedmodel toneMint
class node_issues,node_errors,node_skips,node_reports toneRose
class node_user toneIndigo
```

## Components

### User entry

- [Command-line interface](https://github.com/protectai/modelscan/blob/main/modelscan/cli.py): `modelscan/cli.py`
- [CLI utilities](https://github.com/protectai/modelscan/blob/main/modelscan/tools/cli_utils.py): `modelscan/tools/cli_utils.py`

### Scan runtime

- [Scan orchestrator](https://github.com/protectai/modelscan/blob/main/modelscan/modelscan.py): `modelscan/modelscan.py`
- [Scan settings](https://github.com/protectai/modelscan/blob/main/modelscan/settings.py): `modelscan/settings.py`
- [Middleware pipeline](https://github.com/protectai/modelscan/blob/main/modelscan/middlewares/middleware.py): `modelscan/middlewares/middleware.py`
- [Extension format detection](https://github.com/protectai/modelscan/blob/main/modelscan/middlewares/format_via_extension.py): `modelscan/middlewares/format_via_extension.py`
- [Model stream and context](https://github.com/protectai/modelscan/blob/main/modelscan/model.py): `modelscan/model.py`
- [Scanner interface](https://github.com/protectai/modelscan/blob/main/modelscan/scanners/scan.py): `modelscan/scanners/scan.py`

### Format scanners

- [Pickle and PyTorch scans](https://github.com/protectai/modelscan/blob/main/modelscan/scanners/pickle/scan.py): `modelscan/scanners/pickle/scan.py`
- [Pickle opcode analysis](https://github.com/protectai/modelscan/blob/main/modelscan/tools/picklescanner.py): `modelscan/tools/picklescanner.py`
- [H5 Lambda scan](https://github.com/protectai/modelscan/blob/main/modelscan/scanners/h5/scan.py): `modelscan/scanners/h5/scan.py`
- [Keras archive scan](https://github.com/protectai/modelscan/blob/main/modelscan/scanners/keras/scan.py): `modelscan/scanners/keras/scan.py`
- [SavedModel scans](https://github.com/protectai/modelscan/blob/main/modelscan/scanners/saved_model/scan.py): `modelscan/scanners/saved_model/scan.py`

### Findings and output

- [Issue model and severity](https://github.com/protectai/modelscan/blob/main/modelscan/issues.py): `modelscan/issues.py`
- [Scan errors](https://github.com/protectai/modelscan/blob/main/modelscan/error.py): `modelscan/error.py`
- [Skip records](https://github.com/protectai/modelscan/blob/main/modelscan/skip.py): `modelscan/skip.py`
- [Report output](https://github.com/protectai/modelscan/blob/main/modelscan/reports.py): `modelscan/reports.py`

### Other components

- **Model provider**

## Connections

- Model provider → Command-line interface: supplies model (evidence: `README.md`)
- Command-line interface → Scan orchestrator: starts scan (evidence: `modelscan/cli.py`)
- Command-line interface → Scan settings: loads settings (evidence: `modelscan/cli.py`)
- Command-line interface → CLI utilities: uses utilities (evidence: `modelscan/cli.py`)
- Scan orchestrator → Scan settings: uses settings (evidence: `modelscan/modelscan.py`)
- Scan orchestrator → Middleware pipeline: runs middleware (evidence: `modelscan/modelscan.py`)
- Middleware pipeline → Extension format detection: configures middleware (evidence: `modelscan/middlewares/format_via_extension.py`)
- Extension format detection → Model stream and context: sets format context (evidence: `modelscan/middlewares/format_via_extension.py`)
- Scan orchestrator → Model stream and context: prepares model (evidence: `modelscan/modelscan.py`)
- Scan orchestrator → Scanner interface: uses scanner interface (evidence: `modelscan/modelscan.py`)
- Scan orchestrator → Scan errors: handles errors (evidence: `modelscan/modelscan.py`)
- Scan orchestrator → Skip records: handles skips (evidence: `modelscan/modelscan.py`)
- Scan orchestrator → Issue model and severity: collects findings (evidence: `modelscan/modelscan.py`)
- Pickle and PyTorch scans → Pickle opcode analysis: analyzes opcodes (evidence: `modelscan/scanners/pickle/scan.py`)
- Pickle and PyTorch scans → Model stream and context: reads model (evidence: `modelscan/scanners/pickle/scan.py`)
- H5 Lambda scan → SavedModel scans: reuses operator checks (evidence: `modelscan/scanners/h5/scan.py`)
- Keras archive scan → SavedModel scans: reuses operator checks (evidence: `modelscan/scanners/keras/scan.py`)
- SavedModel scans → Model stream and context: reads model (evidence: `modelscan/scanners/saved_model/scan.py`)
- Pickle opcode analysis → Issue model and severity: creates findings (evidence: `modelscan/tools/picklescanner.py`)
- Pickle opcode analysis → Scan errors: raises scan errors (evidence: `modelscan/tools/picklescanner.py`)
- Pickle opcode analysis → Skip records: records skips (evidence: `modelscan/tools/picklescanner.py`)
- Report output → Scan orchestrator: formats scan results (evidence: `modelscan/reports.py`)
- Report output → Issue model and severity: renders findings (evidence: `modelscan/reports.py`)
