Heuristic:Trailofbits Fickling Force Flag Bypass
| Knowledge Sources | |
|---|---|
| Domains | Security_Research, Deep_Learning |
| Last Updated | 2026-02-14 13:00 GMT |
Overview
When and how to use the `force=True` flag in `PyTorchModelWrapper` to handle unsupported or unrecognized PyTorch file formats without raising exceptions.
Description
The `PyTorchModelWrapper` validates the PyTorch file format during initialization. If a file does not match any known format (PyTorch v1.3, TorchScript v1.4, etc.), it raises `ValueError` or `NotImplementedError` by default. The `force=True` parameter converts these exceptions into warnings, allowing users to proceed with potentially unsupported files. This is essential for security research on unusual or corrupted model files.
Usage
Use this heuristic when you encounter a PyTorch file that fickling does not recognize but you believe it contains valid pickle data. Common scenarios include: files from older PyTorch versions (v0.1.10), experimental formats, or files that may be polyglots or corrupted.
The Insight (Rule of Thumb)
- Action: Pass `force=True` to `PyTorchModelWrapper(path, force=True)` when the default validation rejects a file you need to analyze.
- Value: When `force=False` (default), unrecognized files raise exceptions. When `force=True`, they produce warnings instead.
- Trade-off: With `force=True`, fickling may produce incorrect results or fail silently on truly unsupported formats. The file structure may not match fickling's expectations (e.g., no `data.pkl` in the ZIP).
- Fallback: For `PyTorch v0.1.10` files (stacked pickles without ZIP), skip `PyTorchModelWrapper` entirely and use `Pickled.load()` or `StackedPickle.load()` directly.
- TorchScript warning: TorchScript v1.4 support is explicitly marked as experimental. Injections may not work depending on the model and the target parser.
Reasoning
The format validation in `validate_file_format()` handles three distinct error categories, each with different force behavior:
- No formats detected: The file does not match any known PyTorch format. With `force=True`, fickling warns but proceeds, which is useful for files with non-standard headers.
- v0.1.10 format: A legacy stacked pickle format. `PyTorchModelWrapper` expects ZIP-based formats; this format requires direct pickle loading.
- Unsupported format: A recognized but unsupported format. With `force=True`, fickling warns that no injection method exists.
Code evidence from `fickling/pytorch.py:42-101`:
def validate_file_format(self):
self._formats = fickling.polyglot.identify_pytorch_file_format(self.path)
if len(self._formats) == 0:
if self.force is True:
warnings.warn(
"This file has not been identified as a PyTorch file.",
UserWarning,
)
else:
raise ValueError(
"This file has not been identified as a PyTorch file."
)
if ("PyTorch v1.3" not in self._formats) and ("TorchScript v1.4" not in self._formats):
if "PyTorch v0.1.10" in self._formats:
if self.force is True:
warnings.warn(
"This file may be a PyTorch v0.1.10 file. "
"Try Pickled.load() or StackedPickle.load() if this fails",
UserWarning,
)
else:
raise ValueError(
"This file may be a PyTorch v0.1.10 file. "
"Try Pickled.load() or StackedPickle.load() instead"
)
if self._formats[0] == "TorchScript v1.4":
warnings.warn(
"Support for TorchScript v1.4 files is experimental.",
UserWarning,
)