aws / aws/bedrock-agentcore-sdk-python

Document ASGI-only requirement for BedrockAgentCoreContext

Open
#219 0 comments 0 reactions 0 assignees View on GitHub
documentation
Dominant language
Python
Stars
761
Forks
147
Avg merge
1d 23h
Merged PRs (30d)
7

Description

## Summary

BedrockAgentCoreContext uses ContextVar for storing request-scoped sensitive data (workload access tokens, OAuth2 callback URLs, authorization headers). While this is safe for ASGI web frameworks, it creates a **critical security vulnerability** if used with WSGI frameworks.

## Problem

**ContextVar isolation behavior:**
- ✅ **ASGI frameworks** (Starlette, FastAPI, Quart): Automatically isolated per async task (each HTTP request)
- ❌ **WSGI frameworks** (Flask, Django WSGI): NOT automatically isolated - threads are reused across requests

**Security risk with WSGI:**
```python
# WSGI thread pool scenario
# Request A (Thread 1) → BedrockAgentCoreContext.set_workload_access_token("USER_A_TOKEN")
# Request B (Thread 1) → BedrockAgentCoreContext.get_workload_access_token()
# → Returns "USER_A_TOKEN" ❌ (LEAKED!)
```

This causes:
- Token leakage between requests
- Authorization bypass vulnerabilities
- Data access from one user by another

## Current Status

The AgentCore SDK correctly uses **Starlette (ASGI)**, making it safe. However, there's no documentation warning against using `BedrockAgentCoreContext` in non-ASGI environments.

## Recommendation

Add documentation to explicitly state:

1. **In `src/bedrock_agentcore/runtime/context.py` docstring:**
- BedrockAgentCoreContext is designed for ASGI web frameworks only
- Using with WSGI frameworks creates security vulnerabilities
- ContextVars rely on async task isolation, not thread isolation

2. **In README or main documentation:**
- Note that the SDK requires ASGI (already uses Starlette)
- If users want to integrate with Flask/WSGI, they need alternative approaches (Flask's `g` object, thread-local storage with manual cleanup)

3. **Consider adding a runtime check** (optional):
- Detect if running in WSGI context
- Emit warning about unsafe usage

## References

- BedrockAgentCoreContext implementation: `src/bedrock_agentcore/runtime/context.py:16-21`
- Context initialization in request handler: `src/bedrock_agentcore/runtime/app.py:299-347`
- Python ContextVar documentation: https://docs.python.org/3/library/contextvars.html

## Impact

- **Severity**: High (security vulnerability if misused)
- **Likelihood**: Low (SDK uses Starlette, but users might try to reuse context pattern)
- **Action**: Documentation update to prevent misuse

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.