Python: [Generated by SRE Agent] docs: clarify checkpoint storage security model and deserialization trust boundaries

[chetantoshniwal]

Summary

Adds documentation sections to the checkpoint encoding and Azure Functions serialization modules, clarifying the trust model for checkpoint storage backends.

Changes

• _checkpoint_encoding.py: Added a "Security Model" section to the module docstring documenting:

  • Checkpoint storage is a trusted data source requiring proper access controls
  • The RestrictedUnpickler allowlist is defense-in-depth, not a security boundary
  • Developer responsibilities for securing storage backends
  • Guidance on using allowed_types and strip_pickle_markers

• _serialization.py (azurefunctions): Added a "Security Model" section explaining:

  • Azure Durable Functions storage account trust requirements
  • RBAC / shared-access policy guidance
  • Cross-reference to the core encoding security documentation

Motivation

Improve developer guidance around the security model for checkpoint serialization so that integrators understand the trust boundaries and their responsibilities when configuring storage backends.

[Copilot]

Pull request overview

This PR adds explicit Security Model documentation to Python checkpoint encoding and Azure Functions serialization utilities, clarifying the trust boundary around checkpoint storage and the limits of the restricted unpickler approach.

Changes:

• Documented that checkpoint storage must be treated as a trusted data source and that restricted unpickling is defense-in-depth rather than a hard security boundary.
• Added guidance on storage access controls and on using type restrictions (allowed_types / storage configuration) to reduce deserialization attack surface.
• Added Azure Functions–specific notes about Durable Functions storage trust assumptions and marker stripping for untrusted inputs.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
python/packages/core/agent_framework/_workflows/_checkpoint_encoding.py	Adds a Security Model section describing trust assumptions and responsibilities for checkpoint decode.
python/packages/azurefunctions/agent_framework_azurefunctions/_serialization.py	Adds a Security Model section for Durable Functions storage and references core checkpoint encoding guidance.

[github-actions]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/azurefunctions/agent_framework_azurefunctions
_serialization.py	55	10	81%	65–71, 190–192
packages/core/agent_framework/_workflows
_checkpoint_encoding.py	64	0	100%
TOTAL	37787	4420	88%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
7510	34 💤	0 ❌	0 🔥	1m 55s ⏱️

[github-actions]

Automated Code Review

Reviewers: 4 | Confidence: 94%

✓ Correctness

This is a documentation-only PR adding Security Model sections to two module docstrings. All claims in the documentation are accurate: _RestrictedUnpickler exists with an allowlist mechanism, getattr is indeed in the allowlist for enum reconstruction, strip_pickle_markers exists and works as described, allowed_types is a parameter on decode_checkpoint_value, and all cross-references point to correct module/function paths. No correctness issues found.

✓ Security Reliability

This is a documentation-only PR adding security model sections to two module docstrings. The documented claims are accurate: RestrictedUnpickler exists with the described allowlist behavior, strip_pickle_markers correctly neutralizes pickle marker injection, and allowed_types is a real parameter. The guidance is sound and consistent with the implementation. No security or reliability issues introduced.

✓ Test Coverage

This is a documentation-only PR that adds Security Model sections to two module docstrings. No code behavior is changed, so no new tests are needed. All referenced functions (RestrictedUnpickler, strip_pickle_markers, allowed_types, decode_checkpoint_value, deserialize_value) exist and already have comprehensive test coverage, including dedicated security tests in test_checkpoint_unrestricted_pickle.py that verify the restricted unpickler blocks arbitrary callables, reduce payloads, and code execution while allowing listed types.

✓ Design Approach

The new security-model documentation is mostly aligned with the existing deserialization trust boundary, but the Azure Functions module introduces one actionable documentation bug: it tells readers to configure allowed_types on checkpoint storage even though this package’s wrapper does not expose that parameter and the storage-facing API elsewhere in the repo uses allowed_checkpoint_types instead.

---

Automated review by chetantoshniwal's agents