Implementation:Trailofbits Fickling Run Import Hook
| Knowledge Sources | |
|---|---|
| Domains | Security, Pickle_Safety, Import_System |
| Last Updated | 2026-02-14 14:00 GMT |
Overview
Concrete tool for intercepting Python's `import pickle` statement to replace the pickle module's `load` function with fickling's safe version at the import level.
Description
The run_import_hook function installs a custom Python import hook that intercepts any `import pickle` statement. It uses the `importlib.abc.MetaPathFinder` protocol via PickleFinder, which is inserted at the front of `sys.meta_path`. When the pickle module is imported, FickleLoader replaces `pickle.load` with `fickling.loader.load`, which performs safety analysis before deserialization. The module emits a `UserWarning` on import indicating this feature is experimental.
Usage
Use this function when you want the deepest level of pickle protection by intercepting pickle at the import level. It must be called before any `import pickle` statement in the application. This is an alternative to the runtime hooks in `fickling.hook`, operating at a lower level but marked as experimental and not recommended for safety-critical use.
Code Reference
Source Location
- Repository: Trailofbits_Fickling
- File: fickling/import_hook.py
- Lines: 1-62
Signature
def run_import_hook(verbose: bool = False) -> None:
"""
Install a Python import hook that replaces pickle.load with fickling's safe version.
Must be called BEFORE any 'import pickle' statement.
Args:
verbose: If True, print a message when the pickle import is intercepted.
"""
class PickleFinder(importlib.abc.MetaPathFinder):
def __init__(self, verbose: bool = False): ...
def find_spec(
self,
fullname: str,
path: Sequence[bytes | str] | None,
target: ModuleType | None = None,
) -> importlib.machinery.ModuleSpec | None: ...
class FickleLoader(importlib.abc.Loader):
def create_module(self, spec: importlib.machinery.ModuleSpec) -> types.ModuleType | None: ...
def exec_module(self, module: types.ModuleType) -> None: ...
Import
from fickling.import_hook import run_import_hook
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| verbose | bool | No | Print message when pickle import is intercepted (default: False) |
Outputs
| Name | Type | Description |
|---|---|---|
| Side effect | None | Installs PickleFinder into sys.meta_path; removes cached pickle from sys.modules |
Usage Examples
Basic Usage
from fickling.import_hook import run_import_hook
# MUST be called before importing pickle
run_import_hook()
import pickle
# pickle.load is now fickling's safe version
with open("example_pickle_file.pkl", "rb") as file:
loaded_data = pickle.load(file)
print("Loaded data:", loaded_data)
Verbose Mode
from fickling.import_hook import run_import_hook
run_import_hook(verbose=True)
# Output: "Pickle module found: Running import hook"
import pickle