Environment:Trailofbits Fickling Python Runtime

Knowledge Sources	Fickling pyproject.toml
Domains	Security, Static_Analysis
Last Updated	2026-02-14 13:00 GMT

Overview

Python 3.10+ environment with standard library modules pickle, ast, pickletools, and struct for pickle bytecode analysis and decompilation.

Description

This environment provides the base Python runtime required for all core fickling functionality. Fickling relies on Python standard library modules for pickle bytecode parsing (pickle, pickletools, struct), AST manipulation (ast), and symbolic execution. The minimum Python version is 3.10, with support through 3.14. For Python versions below 3.12, the typing_extensions package is required for the Buffer ABC.

Usage

Use this environment for all fickling operations: pickle decompilation, safety analysis, bytecode tracing, and code injection. This is the mandatory base environment; every fickling workflow requires it. The PyTorch-specific environment extends this one for model file operations.

System Requirements

Category	Requirement	Notes
OS	Any (Linux, macOS, Windows)	Tested on Linux in CI
Hardware	Standard CPU	No GPU required for core analysis
Disk	Minimal	Only pickle files and fickling source needed

Dependencies

System Packages

Python >= 3.10, <= 3.14

Python Packages

Core (no external dependencies beyond stdlib):

`pickle` (stdlib)
`ast` (stdlib)
`pickletools` (stdlib)
`struct` (stdlib)
`marshal` (stdlib)
`io` (stdlib)

Conditional:

`typing-extensions` (required for Python < 3.12, provides Buffer ABC)

Development:

`ruff` >= 0.8.0 (linting)
`pytest` >= 8.0.0 (testing)
`pytest-cov` >= 5.0.0 (coverage)
`coverage[toml]` >= 7.0.0

Credentials

No credentials are required for the base fickling environment.

Quick Install

# Install fickling (core only, no PyTorch)
pip install fickling

# Or with uv
uv pip install fickling

# For development
pip install fickling[dev]

Code Evidence

Python version constraint from `pyproject.toml:28`:

requires-python = ">=3.10"

Buffer ABC compatibility from `fickling/fickle.py:26-29`:

if sys.version_info < (3, 12):
    from typing_extensions import Buffer
else:
    from collections.abc import Buffer

Standard library imports used throughout `fickling/fickle.py:3-13`:

import ast
import keyword
import marshal
import re
import struct
import sys
from abc import ABC, abstractmethod
from collections.abc import Iterable, Iterator, MutableSequence, Sequence
from enum import Enum
from io import BytesIO
from pickletools import OpcodeInfo, genops, opcodes

Common Errors

Error Message	Cause	Solution
`SyntaxError` on install	Python < 3.10	Upgrade to Python 3.10+
`ImportError: cannot import name 'Buffer'`	Python < 3.12 without typing_extensions	`pip install typing-extensions`
`ModuleNotFoundError: No module named 'fickling'`	Package not installed	`pip install fickling`

Compatibility Notes

Python 3.10-3.14: Fully supported and tested in CI
Python 3.9: README mentions testing on 3.9, but `pyproject.toml` requires >= 3.10
Python < 3.12: Requires `typing-extensions` for the `Buffer` ABC
Windows/macOS/Linux: All supported; CI runs on Linux

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment