Container Escape in Fastapi with Jwt Tokens

A container escape in a FastAPI application that uses JWT tokens typically occurs when runtime behavior diverges from the intended security boundaries of the container. FastAPI itself does not manage containers, but deployment choices—such as running the process as root inside a container or mounting sensitive host paths—can allow an attacker who compromises the application to break out of the container. JWT tokens, if not validated strictly, can be abused to escalate privileges or access internal endpoints that should remain isolated.

Consider an example where FastAPI decodes a JWT without verifying the issuer (iss) or audience (aud), and the token contains additional claims that the server uses to route internal requests. If the application trusts claims like container_id or pod_name to make authorization decisions, an attacker who crafts a token with modified claims could reach internal Kubernetes endpoints or metadata services that are normally blocked from the container network. This can lead to discovery of other containers, access to the Kubernetes API, or attempts to read mounted secrets.

Another scenario involves file paths or volumes mounted into the container. If the FastAPI application deserializes user input (e.g., data extracted from a JWT payload) and uses it to construct file system paths without canonicalization, an attacker may traverse outside the container’s intended directory tree. For instance, a token that includes a manipulated sub or custom claim could direct file operations toward host paths such as /host/proc/1/cmdline, exposing host process information. This becomes more impactful when the container runs with elevated capabilities or when sensitive host directories are bind-mounted.

JWT tokens may also carry permissions that the FastAPI application interprets as container-level access hints. If the application maps token scopes to internal routes that expose administrative or debugging endpoints (e.g., /debug/pprof or a custom status endpoint), an attacker who forges or steals a token could pivot from a standard API role to an internal management interface. Because these endpoints may not enforce the same network policies as public services, the container boundary is effectively bypassed from within.

Insecure configurations compound the issue. Running FastAPI as root inside the container means that any code execution flaw—potentially triggered via a maliciously crafted JWT or its associated data—can lead to container escape. Similarly, allowing the container to access the Docker socket or the Kubernetes API token mounted as a volume provides a direct path to cluster-level actions once the perimeter is violated.

middleBrick can detect scenarios where unauthenticated or weakly authenticated endpoints expose internal behavior that may facilitate container escape. By scanning the FastAPI service, it checks whether JWT validation is consistently enforced, whether claims are safely handled, and whether runtime observations align with declared security boundaries.

To mitigate container escape risks when using JWT tokens in FastAPI, enforce strict token validation and avoid using JWT claims to make security-sensitive runtime decisions. Below are concrete code examples that demonstrate secure handling of JWT tokens.

1. Strict JWT validation with PyJWT

Always verify the issuer, audience, expiration, and signature. Do not trust claims that influence authorization or routing.

import jwt
from fastapi import FastAPI, Depends, HTTPException, Security
from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials

app = FastAPI()
security = HTTPBearer()

def decode_token(credentials: HTTPAuthorizationCredentials = Security(security)):
    token = credentials.credentials
    try:
        payload = jwt.decode(
            token,
            key="your-secure-secret-or-public-key",
            algorithms=["HS256"],
            options={
                "require": ["exp", "iss", "aud"],
                "verify_signature": True,
                "verify_exp": True,
                "verify_nbf": True,
                "verify_iat": True,
                "verify_iss": True,
                "verify_aud": True,
            },
            issuer="api.example.com",
            audience="myapi.example.com",
        )
        # Do not use payload claims to determine container-level access
        return payload
    except jwt.ExpiredSignatureError:
        raise HTTPException(status_code=401, detail="Token expired")
    except jwt.InvalidTokenError:
        raise HTTPException(status_code=401, detail="Invalid token")

@app.get("/items/")
def read_items(token_data: dict = Depends(decode_token)):
    # Use token_data only for identity, not for routing or security decisions
    return {"items": ["item1", "item2"]}

2. Avoid path traversal when using token-derived data

If you must use data from the token, sanitize and restrict file paths. Never directly concatenate user-influenced claims with file system paths.

import os
from fastapi import FastAPI, Depends, HTTPException

def safe_join(base: str, path: str) -> str:
    # Resolve and ensure the final path stays within base
    final = os.path.realpath(os.path.join(base, path))
    if not final.startswith(os.path.realpath(base)):
        raise ValueError("Path traversal attempt")
    return final

app = FastAPI()

@app.get("/files/{name}")
def get_file(name: str, token_data: dict = Depends(decode_token)):
    base_dir = "/app/data"
    try:
        full_path = safe_join(base_dir, name)
    except ValueError:
        raise HTTPException(status_code=400, detail="Invalid file path")
    # Proceed to safely serve the file
    return {"path": full_path}

3. Do not map token scopes to internal endpoints

Avoid using JWT scopes or roles to decide whether to expose debugging or admin endpoints. Instead, manage access through network policies and service-level authentication.

from fastapi import APIRouter, Depends

internal_router = APIRouter()

@internal_router.get("/debug/health")
def debug_health():
    # This endpoint should not be exposed via JWT-based routing logic
    raise HTTPException(status_code=404, detail="Not found")

# Do not conditionally include internal_router based on token claims

4. Run as non-root and limit container capabilities

While not a code fix, runtime hardening reduces impact if a token-based flaw is exploited. Run the FastAPI process as a non-root user and avoid mounting sensitive host paths or the Docker socket.