aws / aws/bedrock-agentcore-sdk-python

Document ASGI-only requirement for BedrockAgentCoreContext

Abierto
#219 0 comentarios 0 reacciones 0 asignados Ver en GitHub
documentation
Lenguaje dominante
Python
Estrellas
761
Forks
147
Merge medio
1 d 23 h
PR fusionados (30 d)
7

Descripción

## 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

Guía de contribución

Abrir la guía de contribución

Línea de trabajo

Comienza con src/bedrock_agentcore/runtime/context.py:16-21 y luego revisa la configuración del contexto de la solicitud en src/bedrock_agentcore/runtime/app.py:299-347. Documenta que BedrockAgentCoreContext está pensado para usarse con ASGI y explica el riesgo de aislamiento de ContextVar con WSGI; actualiza el README o la ubicación principal de la documentación identificada durante esa revisión. Se considera terminado cuando los usuarios puedan ver claramente el requisito de usar únicamente ASGI y la consecuencia de seguridad.

Escrito por el modelo de indexación a partir del texto del issue.

Evaluación

Stack tecnológico
python
Área
documentation, security
Tipo de issue
Documentación
Dificultad
2/5
Tiempo estimado
Medio día
Estado de actividad
Estancado
Claridad
Bastante claro
Aptitud para principiantes
45/100

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.