Documentation
¶
Overview ¶
Package modelscan scans a machine-learning model file for malicious embedded Python pickles and reports which can execute code on load.
Operators rarely receive a bare pickle — they receive a model file. A modern PyTorch checkpoint (torch.save ≥ 1.6: .pt / .pth / .ckpt / .bin) is a ZIP archive whose `…/data.pkl` member is a pickle that runs on torch.load; a legacy checkpoint is a bare pickle. Either way, loading an untrusted model can execute arbitrary code (the supply-chain attack behind the HuggingFace / PyTorch-Hub pickle scares). This is the in-tree analogue of picklescan / modelscan: it detects the container, disassembles every embedded pickle with internal/pickle (the safe pickletools-style walk — never torch.load / pickle.load), and aggregates the verdict.
No confidently-wrong output: a ZIP member is scanned only when its name ends in `.pkl` or it begins with the pickle PROTO opcode (0x80), and an oversized member is skipped from the heuristic scan rather than read whole; the pickle disassembly itself never executes the stream and is anchored to pickletools; the danger flag is the labelled heuristic internal/pickle computes (absence of code-exec opcodes is not a safety guarantee).
Wrap-vs-native: native — stdlib archive/zip plus internal/pickle; no new go.mod dependency. safetensors / GGUF / Keras-HDF5 model formats are out of scope (safetensors is by design non-executable; the others are separate container formats).
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Entry ¶
type Entry struct {
Path string `json:"path"`
PickleProtocol int `json:"pickle_protocol"`
OpcodeCount int `json:"opcode_count"`
ExecutesCode bool `json:"executes_code"`
Imports []string `json:"imports,omitempty"`
DangerousImports []string `json:"dangerous_imports,omitempty"`
Error string `json:"error,omitempty"`
}
Entry is the scan result for one embedded pickle.
type Result ¶
type Result struct {
// Format is "pytorch-zip" (a ZIP container) or "raw-pickle".
Format string `json:"format"`
PickleCount int `json:"pickle_count"`
Entries []Entry `json:"entries"`
Dangerous bool `json:"dangerous"`
ExecutesCode bool `json:"executes_code"`
AllDangerousImports []string `json:"all_dangerous_imports,omitempty"`
Note string `json:"note"`
}
Result is the aggregate scan of a model file.
Source Files