Document ASGI-only requirement for BedrockAgentCoreContext

Open
#219 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
Half a day
Newbie friendliness
45/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Stale
Tech stack
python

Research direction

Start with src/bedrock_agentcore/runtime/context.py:16-21 and then review request-context setup in src/bedrock_agentcore/runtime/app.py:299-347. Document that BedrockAgentCoreContext is intended for ASGI use and explain the ContextVar isolation risk with WSGI; update the README or main documentation location identified during that review. Done means users can clearly see the ASGI-only requirement and security consequence.

Written by the indexing model from the issue text.

Description

documentation

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:

# 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
Dominant language
Python
Stars
786
Forks
163
Avg merge
4h
Merged PRs (30d)
22

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from aws/bedrock-agentcore-sdk-python

All issues in aws/bedrock-agentcore-sdk-python

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.