---

Visão Geral

Um serviço de execução reforçado para segurança, destinado a código em que você não confia. Os chamadores enviam o código-fonte por meio de uma pequena API REST; o daemon inicia cada payload em uma jail efêmera do kernel, onde o próprio kernel do Linux — e não a lógica da aplicação — garante a contenção:

• o processo não consegue escapar do sistema de arquivos (pivot_root para um rootfs somente leitura),
• ele não consegue se comunicar com a rede ou com o host (namespaces privados + lo desativada + seccomp encerra socket),
• ele não consegue esgotar a máquina (limites de memória/CPU/PID via cgroups v2),
• ele não consegue sobreviver ao seu orçamento (watchdog de 5 s de tempo real), e
• cada resultado — incluindo violações — é registrado em uma trilha de auditoria imutável.

Principais Recursos

• 🧱 Defesa em profundidade — seis namespaces do Linux (PID · MOUNT · NET · IPC · UTS · USER), uma allowlist seccomp-BPF estrita, jails de recursos via cgroups v2 e um sistema de arquivos pivot_root somente leitura com espaço de rascunho tmpfs de 16 MB.
• ⚡ Inicializações em menos de um segundo — um pool aquecido de 16 slots de execução com timeout de aquisição de 3 segundos evita o custo de cold-start por requisição enquanto limita a concorrência.
• ⏱️ Limites determinísticos — timeout rígido de 5 s de tempo real, teto de memória de 128 MB (swap desabilitado, OOM kill instantâneo), 0,5 núcleo de CPU, pids.max = 32 para imunidade a fork bombs e limites de saída de 512 KB em stdout/stderr.
• 📜 Auditoria completa de execução — código de saída, tempo real, memória de pico, tempo de CPU, flags de truncamento e eventos de segurança são gravados de forma assíncrona no PostgreSQL (execution_runs).
• 🧪 Suíte de testes de nível de ataque — testes de integração dedicados para fork bombs, fuga de rede, OOM de memória, watchdog de timeout e estresse de concorrência, executáveis dentro de um contêiner privilegiado contra o kernel real.

---

Arquitetura do Sistema

flowchart LR
    CLI["👤 API Client<br/><i>tenant / CI job</i>"]

    subgraph CP["🔐 Trusted Control Plane — Go daemon"]
        API["Ingestion Daemon<br/><i>net/http :8080</i>"]
        POOL["Warm Runner Pool<br/><i>16 slots · 3 s cap</i>"]
        RUN["Process Runner<br/><i>watchdog + pipes</i>"]
        ISO["Kernel Isolation<br/><i>cgroups v2 · namespaces · seccomp-BPF</i>"]
    end

    subgraph JAIL["⛓️ Ephemeral Kernel Jail — untrusted"]
        INIT["sandbox_init<br/><i>exec trampoline</i>"]
        GUEST["💀 Untrusted Code<br/><i>python · node · bash</i>"]
    end

    PG[("🗄️ PostgreSQL 16<br/><i>execution_runs</i>")]
    RD[("📮 Redis 7 Queue<br/><i>sandbox:jobs</i>")]

    CLI -->|"POST /api/v1/execute"| API
    API -->|"validate + acquire"| POOL
    POOL -->|"spawn + limits"| RUN
    RUN -.->|"apply jail"| ISO
    ISO ==>|"seccomp · pivot_root"| GUEST
    RUN -->|"fork / exec"| INIT
    INIT -->|"syscall.Exec"| GUEST
    RUN -.->|"stdout / stderr ≤ 512 KB"| POOL
    API -.->|"async audit INSERT"| PG
    RD -.->|"BRPop drain · worker module"| POOL

    style JAIL fill:#2a1215,stroke:#f87171,stroke-width:2px
    style CP fill:#0d1b2a,stroke:#38bdf8,stroke-width:1px

Detalhamento dos Componentes

Componente	Responsabilidade	Origem
Daemon de Ingestão	Superfície REST: POST /api/v1/execute + /health; validação de requisições; emissão assíncrona de auditoria	cmd/server/main.go
Pool de Runners Pré-aquecidos	Slots de execução limitados por semáforo (16) com timeout de aquisição de 3 s → backpressure de esgotamento no estilo 503	internal/runner/pool.go
Runner de Processo	Monta o comando da linguagem, anexa o cgroup, transmite pipes através de writers truncadores, aplica o watchdog de 5 s, coleta métricas do cgroup, classifica resultados	internal/runner/process.go
Isolamento de Kernel	Limitador de cgroups v2 (memory.max, cpu.max, pids.max), flags de namespace (CLONE_NEWPID/NET/NS/IPC/UTS/USER), compilador de filtro seccomp-BPF	internal/isolation/
sandbox_init	Trampolim filho: pivot_root somente leitura + tmpfs /dev//tmp, desanexação de rede (lo down), aplicação de seccomp, depois syscall.Exec do alvo	cmd/sandbox_init/main.go
Código Não Confiável	O payload convidado. Dispositivos do host removidos, /proc oculto (hidepid=2), todas as syscalls fora da allowlist eliminadas	imagens rootfs em runtimes/
PostgreSQL 16	Log de auditoria durável de cada execução, incluindo violações de segurança	migrations/001_init_sandbox_schema.sql
Redis 7	Fila sandbox:jobs + worker BRPop drenando para o pool (módulo implementado, ainda não conectado ao daemon — ver Limitações Conhecidas)	internal/queue/redis_consumer.go

Fronteiras de Confiança

Fronteira	O que separa	Aplicação
Cliente ↔ Daemon	Submissão de payload não autenticada do plano de controle	validação de schema (tenant_id, language, code)
Plano de controle ↔ Jail	Código Go confiável vs. payload hostil	fork para namespaces privados; pivot_root; seccomp com herança no exec
Jail ↔ Limites do Kernel	Consumo de recursos do convidado vs. capacidade do host	cgroups v2 memory.max=128MB, swap.max=0, cpu.max="50000 100000", pids.max=32
Jail ↔ Rede	Qualquer saída ou alcançabilidade pelo lado do host	namespace NET privado, lo down, syscall socket eliminada

🔍 Uma versão interativa e adaptável ao tema deste diagrama (com exportação PNG/SVG) é criada a partir dos candidatos respaldados por evidências em docs/archify/.

---

Ciclo de Vida da Execução — Da Requisição à Auditoria

sequenceDiagram
    autonumber
    participant C as Client
    participant A as REST API
    participant P as Warm Pool
    participant R as Process Runner
    participant I as sandbox_init
    participant G as Untrusted Code
    participant DB as PostgreSQL

    C->>A: POST /api/v1/execute
    A->>P: acquire slot · 16 max, 3 s timeout
    P->>R: Run(req, limits)
    R->>I: fork under CLONE_NEWPID·NET·NS·IPC·UTS·USER
    R->>R: create cgroup scope → attach PID<br/>128 MB · 0.5 CPU · 32 PIDs
    I->>I: pivot_root RO rootfs · lo down · seccomp-BPF
    I->>G: syscall.Exec target interpreter
    G-->>R: stdout / stderr via pipes (512 KB cap)
    R->>R: watchdog: SIGKILL at 5 s → exit 137
    R-->>P: result + cgroup metrics (peak mem, CPU)
    P-->>A: ExecutionResult
    A-->>C: 200 JSON
    A-)DB: async audit INSERT (non-blocking)