{"id":4001,"library":"fickling","title":"Fickling","description":"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.","status":"active","version":"0.1.10","language":"en","source_language":"en","source_url":"https://github.com/trailofbits/fickling","tags":["security","static analysis","pickle","serialization","vulnerability detection"],"install":[{"cmd":"pip install fickling","lang":"bash","label":"Base installation"},{"cmd":"pip install fickling[pytorch]","lang":"bash","label":"With PyTorch support"}],"dependencies":[{"reason":"Required for analyzing PyTorch model pickles.","package":"torch","optional":true}],"imports":[{"note":"Main function for static analysis of pickle bytes.","symbol":"analyze_pickle","correct":"from fickling.analysis import analyze_pickle"},{"note":"Main function for interpreting pickle bytes.","symbol":"interpret_pickle","correct":"from fickling.interpretation import interpret_pickle"},{"note":"Common exception raised when unsafe patterns are detected during analysis or interpretation.","symbol":"UnsafeError","correct":"from fickling.errors import UnsafeError"}],"quickstart":{"code":"import pickle\nfrom fickling.analysis import analyze_pickle\nfrom fickling.errors import UnsafeError\n\n# Create a benign pickle (for demonstration)\nclass MyObject:\n    def __init__(self, name):\n        self.name = name\n\nobj = MyObject(\"safe_data\")\nbenign_pickled_data = pickle.dumps(obj)\n\n# Analyze the pickled data\ntry:\n    print(\"\\n--- Analyzing benign pickle ---\")\n    results = analyze_pickle(benign_pickled_data)\n    if results.is_safe():\n        print(\"Pickle is safe. No violations found.\")\n    else:\n        print(\"Pickle is potentially unsafe. Violations:\")\n        for violation in results.violations:\n            print(f\"- {violation.severity.name}: {violation.message}\")\nexcept UnsafeError as e:\n    print(f\"Analysis detected an unsafe pickle: {e}\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred during analysis: {e}\")\n\n# Example of a potentially unsafe pickle (e.g., using os.system)\n# NOTE: Do NOT run this with untrusted data in production!\n# This is purely illustrative of what Fickling detects.\nclass MaliciousObject:\n    def __reduce__(self):\n        return (getattr(os, 'system'), ('echo malicious command executed!',))\nimport os\nmalicious_obj = MaliciousObject()\nunsafe_pickled_data = pickle.dumps(malicious_obj)\n\n# Analyze the potentially unsafe pickled data\ntry:\n    print(\"\\n--- Analyzing potentially unsafe pickle ---\")\n    results = analyze_pickle(unsafe_pickled_data)\n    if results.is_safe():\n        print(\"Pickle is safe. No violations found.\")\n    else:\n        print(\"Pickle is potentially unsafe. Violations:\")\n        for violation in results.violations:\n            print(f\"- {violation.severity.name}: {violation.message}\")\nexcept UnsafeError as e:\n    print(f\"Analysis detected an unsafe pickle: {e}\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred during analysis: {e}\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to 3.10 or newer to use `fickling` versions 0.1.8 and above.","message":"Python 3.9 is no longer supported; the minimum required version is now Python 3.10.","severity":"breaking","affected_versions":">=0.1.8"},{"fix":"Update any scripts or automation that rely on `fickling`'s command-line interface to check the new exit code scheme.","message":"CLI exit codes have changed to follow ClamAV conventions: `0` for clean, `1` for unsafe, and `2` for errors.","severity":"breaking","affected_versions":">=0.1.8"},{"fix":"Update exception handling blocks to catch `fickling.errors.InterpretationError` when processing potentially malformed pickle data.","message":"Malformed pickle data now raises `fickling.errors.InterpretationError` instead of `ValueError`.","severity":"breaking","affected_versions":">=0.1.8"},{"fix":"Always use the latest version of `fickling` to benefit from the most up-to-date security protections and expanded detection capabilities.","message":"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.","severity":"gotcha","affected_versions":"<0.1.10"},{"fix":"Install with `pip install fickling[pytorch]` if you need PyTorch analysis capabilities.","message":"`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.","severity":"gotcha","affected_versions":">=0.1.3"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}