Implementation:Trailofbits Fickling Pickled Load

Knowledge Sources	Fickling Python pickletools module
Domains	Security, Reverse_Engineering, Deserialization
Last Updated	2026-02-14 14:00 GMT

Overview

Concrete tool for parsing pickle bytecode into a structured opcode list provided by the Fickling library.

Description

Pickled.load is a static method that reads raw pickle bytes or a file-like object and produces a Pickled object containing a list of typed Opcode instances. It uses pickletools.genops() internally and handles error recovery for malformed input. The resulting Pickled object supports iteration, indexing, AST generation, property extraction, and bytecode manipulation.

Usage

Use this to parse any pickle file for analysis, decompilation, or manipulation. This is the entry point for all Fickling operations on pickle data.

Code Reference

Source Location

• Repository: fickling
• File: fickling/fickle.py
• Lines: L920-964

Signature

class Pickled:
    @staticmethod
    def load(
        pickled: Buffer | BinaryIO,
        fail_on_decode_error: bool = True
    ) -> Pickled:
        """Parse pickle bytecode into a Pickled object.

        Args:
            pickled: Raw pickle bytes or file-like binary object.
            fail_on_decode_error: If False, returns partial opcodes on
                decode failure instead of raising. If True, raises
                a decode error exception.

        Returns:
            Pickled object containing parsed Opcode list.
        """

Import

from fickling.fickle import Pickled

I/O Contract

Inputs

Name	Type	Required	Description
pickled	Buffer or BinaryIO	Yes	Raw pickle bytes or file-like binary object
fail_on_decode_error	bool	No	If False, returns partial results on error (default: True)

Outputs

Name	Type	Description
(return)	Pickled	Object containing parsed Opcode list with .has_invalid_opcode flag
.ast	ast.Module	Python AST representation (lazy, via Interpreter)
.properties	ASTProperties	Extracted imports, calls, etc.
.opcodes	Iterator[Opcode]	Iterator over parsed opcodes

Usage Examples

Parse a Pickle File

from fickling.fickle import Pickled

# Parse from file
with open("model.pkl", "rb") as f:
    pickled = Pickled.load(f)

# Inspect opcodes
for opcode in pickled:
    print(f"{opcode.name}: {opcode.argument}")

# Check for invalid opcodes
if pickled.has_invalid_opcode:
    print("Warning: file contains invalid opcodes")

Parse from Bytes

import pickle
from fickling.fickle import Pickled

# Create pickle data
data = pickle.dumps({"key": "value"})

# Parse with error tolerance
pickled = Pickled.load(data, fail_on_decode_error=False)
print(f"Parsed {len(list(pickled))} opcodes")

Related Pages

Implements Principle

• Principle:Trailofbits_Fickling_Pickle_Bytecode_Parsing