Implementation:Trailofbits Fickling Check Safety

Knowledge Sources	Fickling
Domains	Security, Static_Analysis, Deserialization
Last Updated	2026-02-14 14:00 GMT

Overview

Concrete tool for running multi-pass safety analysis on parsed pickle files provided by the Fickling library.

Description

check_safety orchestrates the full analysis pipeline: it takes a Pickled object, runs all registered Analysis passes via the Analyzer, and returns an AnalysisResults container. It optionally writes JSON output to a file. When no custom analyzer is provided, it uses the default instance which includes all auto-registered analysis subclasses.

Usage

Use this as the primary entry point for pickle safety scanning. Pass a Pickled object from Pickled.load() and inspect the returned AnalysisResults for severity and individual findings.

Code Reference

Source Location

Repository: fickling
File: fickling/analysis.py
Lines: L449-465

Signature

def check_safety(
    pickled: Pickled,
    analyzer: Analyzer | None = None,
    verbosity: Severity = Severity.POSSIBLY_UNSAFE,
    json_output_path: str | None = None,
) -> AnalysisResults:
    """Run safety analysis on a parsed pickle.

    Args:
        pickled: Parsed pickle to analyze (from Pickled.load()).
        analyzer: Custom Analyzer instance, or None to use default
                  (all Analysis.ALL subclasses).
        verbosity: Minimum severity threshold for JSON output.
        json_output_path: Optional path to write JSON results.

    Returns:
        AnalysisResults containing all findings.
    """

Import

from fickling.analysis import check_safety
# or
from fickling import check_safety

I/O Contract

Inputs

Name	Type	Required	Description
pickled	Pickled	Yes	Parsed pickle object from Pickled.load()
analyzer	Analyzer or None	No	Custom analyzer; defaults to Analyzer with all Analysis.ALL passes
verbosity	Severity	No	Minimum severity for JSON output (default: POSSIBLY_UNSAFE)
json_output_path	str or None	No	Optional file path for JSON results output

Outputs

Name	Type	Description
(return)	AnalysisResults	Container with .severity property and .results tuple
JSON file	File (optional)	Written to json_output_path if provided

Usage Examples

Basic Safety Check

from fickling.fickle import Pickled
from fickling.analysis import check_safety, Severity

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

results = check_safety(pickled)

if results.severity >= Severity.LIKELY_UNSAFE:
    print(f"UNSAFE: {results.severity.name}")
    print(results.to_string())
else:
    print("File appears safe")

With JSON Output

from fickling.fickle import Pickled
from fickling.analysis import check_safety

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

results = check_safety(
    pickled,
    json_output_path="safety_report.json"
)

Related Pages

Implements Principle

Principle:Trailofbits_Fickling_Static_Safety_Analysis

Uses Heuristic

Page Connections

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

Principle

Implementation

Heuristic

Environment