Skip to content

Python: Add security guidance for checkpoint storage to public docs #4872

@moonbox3

Description

@moonbox3

Summary

The public checkpoints documentation currently contains no security guidance. The page covers how to enable, capture, resume, and rehydrate checkpoints but does not warn developers about the trust requirements of checkpoint storage.

This was identified during a review. The code-level docstrings on FileCheckpointStorage and _checkpoint_encoding already carry security warnings, but these need to be surfaced in the public-facing documentation.

What needs to be added

The checkpoints docs page should include a security callout covering:

  1. Checkpoint storage is a trust boundary. Whether using the built-in FileCheckpointStorage, InMemoryCheckpointStorage, or a custom implementation, the storage backend must be treated as trusted, private infrastructure.
  2. Never load checkpoints from untrusted or potentially tampered sources. Loading a malicious checkpoint can execute arbitrary code.
  3. Pickle usage disclosure. The Python FileCheckpointStorage uses pickle for serializing non-JSON-native state (dataclasses, datetimes, custom objects). pickle.loads() executes arbitrary code during deserialization — the post-deserialization type check cannot prevent this. This use of pickle is acknowledged as against policy and covered by an SDL exception.
  4. Developer responsibility for storage location. FileCheckpointStorage requires an explicit storage_path (no default directory). The framework validates against path traversal, but securing the storage location is the developer's responsibility.

Context

  • Threat model review feedback from security reviewer
  • Code-level warnings already exist in FileCheckpointStorage docstring and _checkpoint_encoding module

Metadata

Metadata

Assignees

Labels

docs-onlypythonv1.0Features being tracked for the version 1.0 GAworkflowsRelated to Workflows in agent-framework

Type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions