01-architecture.md

Architecture Overview

Layered Security Model

This sandbox uses multiple security layers that work together to create defense in depth. Each layer addresses a specific attack vector, ensuring that if one layer is bypassed, others still protect the system. The layers are ordered from the most fundamental (container runtime) to the highest level (monitoring and logging).

flowchart TB
    subgraph "Security Layers"
        direction TB
        L7["Layer 7: Monitoring & Logging"]
        L6["Layer 6: JWT Authentication"]
        L5["Layer 5: Process Isolation"]
        L4["Layer 4: Resource Limits"]
        L3["Layer 3: Network Control"]
        L2["Layer 2: Filesystem Isolation"]
        L1["Layer 1: Container Runtime (gVisor)"]
    end

    L7 --> L6 --> L5 --> L4 --> L3 --> L2 --> L1

Loading

Component-Technology Mapping

The following diagram shows how each security layer maps to a specific technology and purpose. This helps understand which component addresses which threat.

flowchart TB
    subgraph "Layer"
        direction TB
        L1[Layer 1]
        L2[Layer 2]
        L3[Layer 3]
        L4[Layer 4]
    end

    subgraph "Component"
        direction TB
        C1[Container Runtime]
        C2[Filesystem]
        C3[Network]
        C4[Resources]
    end

    subgraph "Technology"
        direction TB
        T1[gVisor]
        T2[9P Protocol]
        T3[Envoy JWT]
        T4[cgroups]
    end

    subgraph "Purpose"
        direction TB
        P1[Isolate kernel]
        P2[Control file access]
        P3[Filter egress]
        P4[Limit usage]
    end

    L1 --> C1 --> T1 --> P1
    L2 --> C2 --> T2 --> P2
    L3 --> C3 --> T3 --> P3
    L4 --> C4 --> T4 --> P4

Loading

Core Principles

These principles guide all security decisions in this architecture. They are designed to minimize attack surface and reduce the impact of potential breaches.

1. Verify Every Request: Authenticate and authorize all access - never trust any operation by default
2. Short-Lived Containers: Destroy containers after each session - limits the window of opportunity for attackers
3. Minimal Permissions: Grant only necessary capabilities - reduces damage if a container is compromised
4. Multiple Barriers: Security through layered defenses - no single point of failure
5. Default Deny: Block everything not explicitly allowed - fail-secure by default