Workflow:Trailofbits Fickling PyTorch Format Identification
| Knowledge Sources | |
|---|---|
| Domains | Supply_Chain_Security, ML_Security, File_Format_Analysis |
| Last Updated | 2026-02-14 13:00 GMT |
Overview
End-to-end process for identifying PyTorch file formats and detecting polyglot files that can be validly interpreted as multiple formats, exposing supply chain attack surfaces.
Description
This workflow provides format-level analysis of PyTorch model files by examining their structural properties (ZIP headers, tar headers, pickle magic bytes, NumPy headers) and matching them against known PyTorch file format signatures. It supports eight distinct PyTorch file formats spanning the evolution from v0.1.1 through v1.3 and TorchScript variants.
A critical security capability is polyglot detection: identifying files that satisfy the structural requirements of multiple formats simultaneously. Polyglot files represent a supply chain attack vector because different parsers (torch.load() vs torch.jit.load()) may interpret the same file differently, enabling attackers to hide malicious content in the format that one parser ignores but another executes. Fickling can also create polyglot files for testing purposes.
Usage
Execute this workflow when auditing model files from external sources for format ambiguities, building supply chain security tooling that needs to understand PyTorch file internals, investigating suspicious model files that behave differently across loading methods, or testing parser behavior with polyglot files.
Execution Steps
Step 1: Discover File Properties
Examine the target file's structural properties: check for PyTorch ZIP magic bytes (via torch.serialization._is_zipfile), standard ZIP format, tar archive format, valid pickle opcodes, and NumPy array headers. For ZIP files, additionally check for the presence of data.pkl, constants.pkl, version, model.json, and attributes.pkl entries.
Key considerations:
- PyTorch uses a specific magic number at offset 0 for its ZIP files, distinct from standard ZIP
- The tar file check has false positives because tar files often start with . which is a valid single-opcode pickle
- A file can satisfy multiple format checks simultaneously (this is the polyglot condition)
Step 2: Identify File Formats
Match the discovered properties against known PyTorch format signatures to produce a ranked list of possible formats:
Supported formats:
- PyTorch v0.1.1 - Tar file with sys_info, pickle, storages, and tensors
- PyTorch v0.1.10 - Stacked pickle files
- TorchScript v1.0 - ZIP with model.json
- TorchScript v1.1 - ZIP with model.json and attributes.pkl
- TorchScript v1.3 - ZIP with data.pkl and constants.pkl
- TorchScript v1.4 - ZIP with data.pkl, constants.pkl, and version >= 2
- PyTorch v1.3 - ZIP containing data.pkl only
- PyTorch model archive format - ZIP with Python code, JSON, and .pt/.pth files
Key considerations:
- The first format in the returned list is the most likely interpretation
- Multiple formats indicate a potential polyglot file
- Format identification order intentionally matches PyTorch's own parser precedence
Step 3: Detect Polyglot Conditions
Analyze the format identification results for polyglot conditions. A file is a polyglot if it matches two or more formats. This is a security concern because different PyTorch loading functions may interpret the file differently.
Key considerations:
- Common polyglot combinations: PyTorch v1.3 + TorchScript v1.4, PyTorch model archive + PyTorch v0.1.10
- Polyglots can be used to hide malicious payloads in a format that the primary parser ignores
- Corruption detection checks for structurally invalid combinations (e.g., model.json without constants.pkl)
Step 4: Check for Corruption
Run corruption checks that identify structurally invalid format combinations. For example, a file containing model.json without attributes.pkl or constants.pkl may indicate file corruption or tampering.
Key considerations:
- Corruption at the format level is distinct from malicious content at the pickle level
- Corrupted files should be treated with suspicion and analyzed further
Step 5: Create Polyglot Files (Optional)
For security testing, create polyglot files by combining two PyTorch files of different formats. Fickling supports creating three types of polyglots: MAR/legacy pickle, standard PyTorch/TorchScript, and MAR/legacy tar combinations.
Key considerations:
- Polyglot creation is for authorized security testing only
- The resulting file is valid when parsed by either format's loader
- Use these files to test that security tools and model registries correctly handle format ambiguity