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
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.
- 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
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
FileCheckpointStorageand_checkpoint_encodingalready 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:
FileCheckpointStorage,InMemoryCheckpointStorage, or a custom implementation, the storage backend must be treated as trusted, private infrastructure.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.FileCheckpointStoragerequires an explicitstorage_path(no default directory). The framework validates against path traversal, but securing the storage location is the developer's responsibility.Context
FileCheckpointStoragedocstring and_checkpoint_encodingmodule