How it Works
Picklescan is a specialized security scanner designed to detect malicious activity within Python Pickle files. Picklescan focuses on identifying dangerous imports and operations, such as calls to eval(), by analyzing the globals and actions performed within the Pickle file.
The tool operates by parsing Pickle files to extract their structure and behavior. It maintains a curated list of unsafe globals—functions, classes, or modules known to execute arbitrary code or perform other malicious actions. When a Pickle file references these unsafe elements, Picklescan flags them as potential security risks. This approach ensures that even seemingly harmless model files uploaded to platforms like Hugging Face can be scanned for hidden threats.
Picklescan supports multiple input sources, including local files, directories, URLs, and zip archives, which are commonly used in machine learning workflows (e.g., PyTorch model files). It can also scan Hugging Face model repositories directly by querying their hosted files. The scanner uses regular expressions to filter files and directories, allowing users to customize scans to focus on specific file types or exclude certain paths.
The tool’s design is modeled after ClamAV, a well-known antivirus engine, with similar exit status codes: 0 indicates no malware was found, 1 indicates malware was detected, and 2 indicates a scan failure.
Picklescan’s effectiveness relies on its maintained list of unsafe globals, which is regularly updated to address new attack vectors.
This combination allows it to dissect Pickle files step-by-step, identifying malicious patterns that might evade simpler static analysis tools.
Unit tests and manual tests (e.g., scanning local or remote PyTorch files) ensure its reliability in real-world scenarios.
Use Cases
Picklescan is primarily used in the context of securing the model supply chain, particularly for platforms hosting machine learning models. Hugging Face, for instance, employs Picklescan to scan uploaded model files for dangerous imports before they are made publicly available. This proactive measure helps prevent malicious actors from distributing backdoored or compromised models that could execute arbitrary code during inference.
One common use case is scanning PyTorch model files (.bin archives) stored on Hugging Face or other repositories. For example, a model file might appear benign but internally call eval() or use unsafe modules like pkgutil to execute malicious payloads. Picklescan detects such cases by analyzing the file’s globals and operations, providing clear warnings like global import 'builtin eval' FOUND.
Beyond Hugging Face, Picklescan is valuable for organizations developing or deploying AI models in production environments.
For example, studies like Backdooring Pickle Files (Johann Rehberger, 2022) or Never a dill moment: Exploiting machine learning pickle files (Evan Sultanik, 2021) highlight the dangers of Pickle deserialization.
The tool’s support for filtering files via regular expressions makes it adaptable to large-scale scans. For instance, a user might scan an entire directory of model files but exclude cache folders or focus only on .pkl files using --include='\.pkl$'.
Picklescan’s integration with Hugging Face’s ecosystem demonstrates its role in broader AI security initiatives. By automating the detection of dangerous Pickle operations, Picklescan reduces the likelihood of supply chain attacks that could compromise model integrity or user data.
Key Features & Capabilities
Picklescan’s core functionality revolves around its ability to detect dangerous globals and operations within Pickle files.
One of its standout features is the ability to scan multiple file formats and sources without requiring manual intervention. Users can scan local files, directories, URLs, or zip archives directly from the command line. For example, scanning a PyTorch model file hosted on Hugging Face is as simple as running picklescan --huggingface ykilcher/totally-harmless-model.
The scanner’s filtering capabilities allow for precise control over which files are analyzed. Regular expressions can be used to include or exclude specific file paths or directories. For instance, the command picklescan --path models/ --include='\.pkl$' --exclude-dir='cache' will scan only .pkl files within the models/ directory while skipping the cache/ subdirectory.
Picklescan’s exit codes follow the ClamAV convention, making it compatible with automated systems. A status code of 0 indicates a clean scan, 1 indicates malware was found, and 2 indicates a scan failure. For example, a failed scan (exit code 1) could trigger a rejection of a model upload or alert a security team for further investigation.
The project’s documentation and references underscore its technical depth. It cites resources like pickledoc for in-depth Pickle format documentation and pickletools.py for low-level analysis. These references guide developers and security researchers who seek to understand or extend Picklescan’s functionality. Additionally, the tool’s testing framework includes manual tests for local and remote PyTorch files, ensuring its reliability in diverse environments.
Picklescan’s design aligns with broader industry trends in AI security, particularly the focus on securing the model supply chain. By addressing vulnerabilities in Pickle files—a common serialization format in machine learning—it complements other tools and frameworks aimed at mitigating risks in AI workflows. Its permissive MIT license encourages adoption across organizations, from research labs to enterprise security teams.