Skip to content

Commit a16503a

Browse files
moonbox3MAF Dashboard Bot
andauthored
Update agent framework docs for GA: checkpoints and storage security considerations (#933)
* Update agent framework docs for GA: middleware, providers, orchestrations, and agent executor Source issue: microsoft/agent-framework#4872 * Address review feedback for #933: review comment fixes * Address review feedback for #933: review comment fixes --------- Co-authored-by: MAF Dashboard Bot <maf-dashboard-bot@users.noreply.github.com>
1 parent c21b678 commit a16503a

1 file changed

Lines changed: 26 additions & 0 deletions

File tree

agent-framework/workflows/checkpoints.md

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ ms.service: agent-framework
2020
| Resuming from Checkpoints | ✅ | ✅ | |
2121
| Rehydrating from Checkpoints | ✅ | ✅ | |
2222
| Save Executor States | ✅ | ✅ | |
23+
| Security Considerations | ✅ | ✅ | |
2324
| Next Steps | ✅ | ✅ | |
2425
-->
2526

@@ -259,6 +260,31 @@ async def on_checkpoint_restore(self, state: dict[str, Any]) -> None:
259260

260261
::: zone-end
261262

263+
## Security Considerations
264+
265+
> [!IMPORTANT]
266+
> Checkpoint storage is a trust boundary. Whether you use the built-in storage implementations or a custom one, 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.
267+
268+
::: zone pivot="programming-language-csharp"
269+
270+
Ensure that the storage location used for checkpoints is secured appropriately. Only authorized services and users should have read or write access to checkpoint data.
271+
272+
::: zone-end
273+
274+
::: zone pivot="programming-language-python"
275+
276+
### Pickle serialization
277+
278+
`FileCheckpointStorage` uses Python's [`pickle`](https://docs.python.org/3/library/pickle.html) module to serialize non-JSON-native state such as dataclasses, datetimes, and custom objects. Because `pickle.loads()` can execute arbitrary code during deserialization, a compromised checkpoint file can run malicious code when loaded. The post-deserialization type check performed by the framework cannot prevent this.
279+
280+
If your threat model does not permit pickle-based serialization, use `InMemoryCheckpointStorage` or implement a custom `CheckpointStorage` with an alternative serialization strategy.
281+
282+
### Storage location responsibility
283+
284+
`FileCheckpointStorage` requires an explicit `storage_path` parameter — there is no default directory. While the framework validates against path traversal attacks, securing the storage directory itself (file permissions, encryption at rest, access controls) is the developer's responsibility. Only authorized processes should have read or write access to the checkpoint directory.
285+
286+
::: zone-end
287+
262288
## Next Steps
263289

264290
- [Learn how to monitor workflows](./observability.md).

0 commit comments

Comments
 (0)