-
Notifications
You must be signed in to change notification settings - Fork 1.4k
Open
Labels
docs-onlypythonv1.0Features being tracked for the version 1.0 GAFeatures being tracked for the version 1.0 GAworkflowsRelated to Workflows in agent-frameworkRelated to Workflows in agent-framework
Description
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:
- 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. - Never load checkpoints from untrusted or potentially tampered sources. Loading a malicious checkpoint can execute arbitrary code.
- Pickle usage disclosure. The Python
FileCheckpointStorageusespicklefor 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. - Developer responsibility for storage location.
FileCheckpointStoragerequires an explicitstorage_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
FileCheckpointStoragedocstring and_checkpoint_encodingmodule
Reactions are currently unavailable
Metadata
Metadata
Assignees
Labels
docs-onlypythonv1.0Features being tracked for the version 1.0 GAFeatures being tracked for the version 1.0 GAworkflowsRelated to Workflows in agent-frameworkRelated to Workflows in agent-framework