Fickling

0.1.10 · active · verified Sat Apr 11

Fickling is a static analyzer and interpreter for Python pickle data. It identifies dangerous modules, functions, and attributes used within pickle files to prevent arbitrary code execution vulnerabilities. The current version is 0.1.10, and it maintains an active release cadence, frequently publishing security updates and expanded blocklists.

Warnings

breaking Python 3.9 is no longer supported; the minimum required version is now Python 3.10.
Fix: Upgrade your Python environment to 3.10 or newer to use `fickling` versions 0.1.8 and above.
breaking CLI exit codes have changed to follow ClamAV conventions: `0` for clean, `1` for unsafe, and `2` for errors.
Fix: Update any scripts or automation that rely on `fickling`'s command-line interface to check the new exit code scheme.
breaking Malformed pickle data now raises `fickling.errors.InterpretationError` instead of `ValueError`.
Fix: Update exception handling blocks to catch `fickling.errors.InterpretationError` when processing potentially malformed pickle data.
gotcha The internal blocklist of unsafe modules, functions, and attributes has been significantly expanded across various versions to address new bypasses. Older versions may be vulnerable to unpickling attacks that newer versions effectively detect.
Fix: Always use the latest version of `fickling` to benefit from the most up-to-date security protections and expanded detection capabilities.
gotcha `torch` is an optional dependency. If you intend to analyze PyTorch models, you must install `fickling[pytorch]` or `torch` separately, as it is not included in the base installation.
Fix: Install with `pip install fickling[pytorch]` if you need PyTorch analysis capabilities.

Install

pip install fickling Base installation
pip install fickling[pytorch] With PyTorch support

Imports

analyze_pickle
```
from fickling.analysis import analyze_pickle
```
Main function for static analysis of pickle bytes.
interpret_pickle
```
from fickling.interpretation import interpret_pickle
```
Main function for interpreting pickle bytes.
UnsafeError
```
from fickling.errors import UnsafeError
```
Common exception raised when unsafe patterns are detected during analysis or interpretation.

Quickstart

This quickstart demonstrates how to use `fickling.analysis.analyze_pickle` to check both benign and potentially malicious pickle data. It shows how to catch `UnsafeError` and iterate through detected violations.

import pickle
from fickling.analysis import analyze_pickle
from fickling.errors import UnsafeError

# Create a benign pickle (for demonstration)
class MyObject:
    def __init__(self, name):
        self.name = name

obj = MyObject("safe_data")
benign_pickled_data = pickle.dumps(obj)

# Analyze the pickled data
try:
    print("\n--- Analyzing benign pickle ---")
    results = analyze_pickle(benign_pickled_data)
    if results.is_safe():
        print("Pickle is safe. No violations found.")
    else:
        print("Pickle is potentially unsafe. Violations:")
        for violation in results.violations:
            print(f"- {violation.severity.name}: {violation.message}")
except UnsafeError as e:
    print(f"Analysis detected an unsafe pickle: {e}")
except Exception as e:
    print(f"An unexpected error occurred during analysis: {e}")

# Example of a potentially unsafe pickle (e.g., using os.system)
# NOTE: Do NOT run this with untrusted data in production!
# This is purely illustrative of what Fickling detects.
class MaliciousObject:
    def __reduce__(self):
        return (getattr(os, 'system'), ('echo malicious command executed!',))
import os
malicious_obj = MaliciousObject()
unsafe_pickled_data = pickle.dumps(malicious_obj)

# Analyze the potentially unsafe pickled data
try:
    print("\n--- Analyzing potentially unsafe pickle ---")
    results = analyze_pickle(unsafe_pickled_data)
    if results.is_safe():
        print("Pickle is safe. No violations found.")
    else:
        print("Pickle is potentially unsafe. Violations:")
        for violation in results.violations:
            print(f"- {violation.severity.name}: {violation.message}")
except UnsafeError as e:
    print(f"Analysis detected an unsafe pickle: {e}")
except Exception as e:
    print(f"An unexpected error occurred during analysis: {e}")

view raw JSON →