modelformat

Documentation

Overview

Package modelformat identifies a model file's real format from its leading bytes and refuses the formats that execute code when loaded.

A model file's name lies: a ".bin" or ".pt" is usually a Python pickle (or a zip of pickles) that runs arbitrary code the moment a runtime loads it, regardless of the extension. So the decision of whether a file is safe to parse is made from its content, not its name, and it is an allowlist: only the formats that are pure data (GGUF and safetensors) are admitted; pickles, zip archives, and anything unrecognized are refused. This is the gate in front of any model load; the actual parsing of an admitted file (for example by package gguf) happens after it passes.

Index

• type Format
  • func Check(r io.Reader) (Format, error)
  • func Detect(head []byte) Format
  • func (f Format) SafeToParse() bool

Types

type Format

type Format string

Format is a model file format identified from its leading bytes.

const (
	// FormatGGUF is the single-file quantized format local runtimes load: pure data.
	FormatGGUF Format = "gguf"
	// FormatSafetensors is a header-prefixed tensor container with no code: pure data.
	FormatSafetensors Format = "safetensors"
	// FormatPickle is a Python pickle, which runs arbitrary code on load.
	FormatPickle Format = "pickle"
	// FormatZip is a zip archive (PyTorch .pt/.bin are zips of pickles): code on load.
	FormatZip Format = "zip"
	// FormatUnknown is anything not recognized; it is refused, since an unknown format
	// cannot be vouched for.
	FormatUnknown Format = "unknown"
)

func Check

func Check(r io.Reader) (Format, error)

Check reads a file's leading bytes from r, identifies the format, and returns a Forbidden error naming it when it is not safe to parse, so a caller refuses to load a code-executing or unrecognized model file rather than handing it to a runtime. On a safe format it returns the format and a nil error.

func Detect

func Detect(head []byte) Format

Detect identifies the format from a file's leading bytes. It never fails: bytes it does not recognize are FormatUnknown. Pass at least the first headerLen bytes (fewer is allowed; a short or empty input is simply unrecognized).

func (Format) SafeToParse

func (f Format) SafeToParse() bool

SafeToParse reports whether a format is pure data and so safe to hand to a parser. Only GGUF and safetensors qualify; everything else, including unknown, does not.