1. Il bilancio potenza/sicurezza, esplicitato

Una sandbox può essere restrittiva — al limite impedire tutto. In quel caso protegge, ma myclaw non agisce. Una sandbox può essere permissiva — al limite subprocess.run() diretto. In quel caso l'agente è potente, ma un bug LLM può causare disastri. Il punto giusto è intermedio, e questo doc lo fissa esplicitamente.

Tre principi che guidano ogni decisione qui:

1. Nominare le capability, non lo stile Unix. Invece di "posso scrivere file?", "posso scrivere dove?". La granularità è il path + tipo di operazione.
2. Due perimetri: gateway vs sandbox. Il gateway (vedi gateway §8) è pesantemente ristretto. La sandbox è selettivamente permissiva entro aree espliciti.
3. Default narrow, allargabile con giustificazione. La prima invocazione di un tool restrittivo apre solo ciò che serve; se la Policy accetta di ampliare, l'ampliamento è loggato e revocabile.

2. La filosofia: "abbastanza potente"

"Abbastanza potente" significa: myclaw può fare i compiti domestici concreti, non finti. Concretamente, tutte queste operazioni devono riuscire nel profilo di default (Supervised):

Questa tabella è il contratto operativo. Tutto il resto del documento è come ottenerla.

3. I tre profili bubblewrap

bubblewrap (bwrap) è lo strumento scelto: leggero, user-space, no privilegi necessari, compone namespace in stile container. Tre profili, uno per livello di autonomy. Ogni tool eredita il profilo del livello corrente, con override opzionali dichiarati nel tool stesso.

Profilo readonly (autonomy=ReadOnly)

bwrap \
  --unshare-all --share-net \
  --die-with-parent --new-session \
  --ro-bind / / \
  --tmpfs /tmp --tmpfs /home/roberto/.cache \
  --bind /opt/myclaw/workspace/.audit /opt/myclaw/workspace/.audit \
  # niente scrittura da nessun'altra parte
  --proc /proc --dev /dev \
  --unsetenv TMPDIR \
  --setenv HOME /home/roberto \
  --seccomp /opt/myclaw/sandbox-profiles/seccomp-readonly.bpf \
  -- "$@"

Filesystem read-only ovunque; scrittura solo su /tmp (tmpfs) e su .audit/ per registrare la trace.

Profilo supervised (autonomy=Supervised, default)

bwrap \
  --unshare-all --share-net \
  --die-with-parent --new-session \
  --ro-bind / / \
  --tmpfs /tmp --tmpfs /home/roberto/.cache \
  --bind /opt/myclaw/workspace /opt/myclaw/workspace \
  --bind /tmp/myclaw /tmp/myclaw \
  # forbidden paths blinded
  --tmpfs /etc/ssh \
  --tmpfs /home/roberto/.ssh --tmpfs /home/roberto/.aws \
  --tmpfs /home/roberto/.gnupg --tmpfs /home/roberto/.config/claude \
  --proc /proc --dev /dev \
  --setenv HOME /home/roberto \
  --seccomp /opt/myclaw/sandbox-profiles/seccomp-supervised.bpf \
  -- "$@"

Scrittura abilitata in workspace/ e /tmp/myclaw/. Le forbidden paths sono sovrapposte con tmpfs vuoti — l'agente vede una directory vuota al posto dei file reali (non una permission error: non sa nemmeno cosa c'è sotto).

Profilo full (autonomy=Full, session breve)

bwrap \
  --unshare-all --share-net --unshare-ipc --unshare-uts --unshare-pid \
  --die-with-parent --new-session \
  --bind / /                   # default writable per TUTTO ciò che l'utente può scrivere
  # forbidden paths ancora blinded
  --tmpfs /etc/ssh \
  --tmpfs /home/roberto/.ssh --tmpfs /home/roberto/.aws \
  --tmpfs /home/roberto/.gnupg --tmpfs /home/roberto/.config/claude \
  --tmpfs /var/backups --tmpfs /opt/myclaw/src \
  --proc /proc --dev /dev \
  --setenv HOME /home/roberto \
  --seccomp /opt/myclaw/sandbox-profiles/seccomp-full.bpf \
  -- "$@"

full è per sessioni esplicite e brevi (myclaw session --level full --for 10m). I forbidden paths restano non negoziabili. La rete resta aperta (stesso profilo seccomp), ma il logging audit è esteso: ogni syscall rilevante viene tracciata.

4. Matrice permessi per autonomy level

5. La mount strategy

La regola: tutto è read-only tranne quello che serve. "Serve" è dichiarato per-profilo in §3, non lasciato al caso.

Mount per il profilo Supervised (annotato)

6. Rete: outbound whitelist, non firewall totale

L'agente deve poter chiamare LLM, fare web fetch, usare SearXNG. Un firewall totale lo castra (direttiva di Roberto). Strategia: outbound concesso, con dichiarazione dei destinatari e rate-limit.

Decisione: user-space, non iptables

Outbound whitelist default

outbound_allowlist:
  # LLM providers (via supra, già controllati lì)
  - api.anthropic.com
  - api.openai.com
  - generativelanguage.googleapis.com

  # Servizi locali di casa
  - 127.0.0.1:*
  - 192.168.1.0/24:*            # LAN
  - localhost

  # Telegram
  - api.telegram.org

  # Web fetch general purpose (si allarga con permesso)
  - "*"                          # catch-all: tool web_fetch può verso chiunque, ma con audit

outbound_denylist:
  # Niente cloud personale di Roberto
  - "*.dropbox.com"
  - "*.gdrive.google.com"       # tranne lettura via API autenticata, futuro
  - "*.icloud.com"

  # Niente SMTP / mail server diretti
  - "*:25"
  - "*:465"
  - "*:587"

  # Niente botnet ports suspicious
  - "*:6667"
  - "*:6697"

Per i tool "verso esterno" (es. telegram_send, futuro email_send) l'outbound è sempre via un API specifico: il tool stesso incapsula il destinatario, non l'LLM.

7. Capability Linux e seccomp

Capability Bounding Set

Via systemd del gateway (già in gateway §8): zero capability. Il bwrap non aggiunge nulla. Eredità pulita.

Seccomp filter

Tre profili seccomp in /opt/myclaw/sandbox-profiles/seccomp-{readonly,supervised,full}.bpf. Partono dalla allowlist di systemd's @system-service, aggiungono esplicitamente:

allowed_syscalls:
  # I/O base
  - read, write, pread64, pwrite64, readv, writev
  - open, openat, close, fstat, stat, lstat, newfstatat
  - lseek, fsync, fdatasync

  # Process/thread
  - clone, fork, execve, execveat
  - wait4, waitid, exit, exit_group
  - kill, tgkill (solo su proprio gruppo)
  - getpid, getppid, gettid

  # Memory
  - mmap, munmap, mprotect, brk, madvise

  # Signals
  - rt_sigaction, rt_sigprocmask, rt_sigreturn

  # Net (solo AF_INET/INET6/UNIX)
  - socket (filtered), connect, bind, accept, listen
  - send, sendto, recv, recvfrom, sendmsg, recvmsg
  - setsockopt, getsockopt, getsockname, getpeername

  # Misc utili
  - nanosleep, clock_gettime, clock_nanosleep
  - pipe, pipe2, dup, dup2, dup3

denied_syscalls:
  - ptrace                       # no debugging processi esterni
  - kexec_load, kexec_file_load  # no kernel swap
  - init_module, delete_module   # no kernel module
  - reboot, sethostname
  - mount, umount2               # no filesystem mount arbitrario
  - iopl, ioperm                 # no I/O diretto hardware
  - bpf                          # no eBPF program loading
  - userfaultfd                  # no user-space page fault tricks
  - perf_event_open              # no perf instrumentation
  - keyctl, add_key, request_key # no kernel keyring
  - io_uring_setup, io_uring_register  # surface asincrona che preferiamo evitare
  - pivot_root                   # no chroot escape tricks
  - unshare, setns (filtered)   # bwrap li usa, nested no

Il profilo readonly ha inoltre tutte le syscall di scrittura filtrate a EPERM, oltre al filesystem ro.

8. Forbidden paths: la lista hard-coded

Questi path non sono configurabili via YAML. Vivono come costante Python in src/myclaw/sandbox/forbidden.py. Una modifica richiede cambio di codice + riavvio del gateway + entry esplicita in audit log ("constitution modified").

FORBIDDEN_PATHS = [
    # Sistema
    "/etc",
    "/root",
    "/boot",
    "/sys",
    "/var/log",          # leggibili via journalctl allowlist, non tramite fs_read
    "/var/backups",
    "/var/spool/cron",

    # Credenziali utente
    "~/.ssh",
    "~/.gnupg",
    "~/.aws",
    "~/.azure",
    "~/.gcloud",
    "~/.kube",
    "~/.docker",
    "~/.config/claude",  # configurazione di Claude Code — off-limits
    "~/.config/gh",
    "~/.netrc",
    "~/.pypirc",
    "~/.npmrc",

    # Browser / password managers
    "~/.mozilla",
    "~/.config/google-chrome",
    "~/.config/chromium",
    "~/.config/Bitwarden",
    "~/.password-store",

    # Progetti sibling (non sono "miei") -- esempi, da adattare all'ambiente
    "/opt/suprastructure",    # read OK via fs_read se autorizzato esplicitamente in doc
    "/opt/",  # es. assistente domotico
    "/opt/",  # es. bot specializzato
    "/opt/",
    "/opt/",

    # Il codice di myclaw stesso
    "/opt/myclaw/src",
    "/opt/myclaw/.claude",
    "/opt/myclaw/config/secrets.env",
]

Modifica dei forbidden paths (il "rito")

Se Roberto vuole aggiungere o rimuovere un forbidden path:

1. Edit manuale di src/myclaw/sandbox/forbidden.py (fuori da myclaw CLI).
2. Restart del gateway: systemctl --user restart myclaw-gateway.
3. Al boot, il runtime scrive in audit log un record "forbidden_paths_modified" con diff e timestamp.

Non c'è un endpoint API per modificare questa lista. Non c'è un comando myclaw. È un atto deliberato, low-frequency, tracciato.

9. Quote di esecuzione (CPU, RAM, I/O, tempo)

Applicate via systemd-run --scope --user wrappando la bwrap. Cosi stringono anche l'albero dei processi figli.

# Wrapper per profilo supervised
systemd-run --scope --user \
  --property=CPUQuota=100% \
  --property=MemoryMax=512M \
  --property=MemoryHigh=384M \
  --property=IOWeight=50 \
  --property=TasksMax=20 \
  --property=RuntimeMaxSec=30 \
  bwrap [profile args] \
  -- "$@"

10. Integrazione con il Tool dispatch

11. Docker opzionale: quando e perché

Per la maggior parte dei tool, bwrap + seccomp è sufficiente e leggero. Docker è supportato come runtime alternativo per tool che richiedono un isolamento più forte (es. quando si esegue codice arbitrario in un neurone nuovo, fase 6+).

Quando Docker

• Sintesi di un neurone nuovo, test di nascita (gate 5 del ciclo synthesizer).
• Tool che esegue codice generato al volo (futuro, fase 5+).
• Tool di processing pesante (compilazioni, elaborazioni GPU) che beneficia di isolamento robusto.

Docker runtime config

docker run --rm \
  --network=host \               # allineato a bwrap; niente bridge custom
  --user $(id -u):$(id -g) \
  --read-only \
  --tmpfs /tmp \
  --volume /opt/myclaw/workspace:/workspace:ro \
  --security-opt=no-new-privileges \
  --security-opt seccomp=/opt/myclaw/sandbox-profiles/seccomp-docker.json \
  --cap-drop ALL \
  --memory 512m --cpus 1 \
  --rm \
  myclaw-tool-sandbox:latest <cmd>

12. Contratto Python

from typing import Protocol, Literal
from dataclasses import dataclass
from pathlib import Path

@dataclass
class SandboxRequest:
    tool_name: str
    tool_module_path: Path           # il .py del tool
    args: dict                       # gia validati contro schema
    autonomy: Literal["readonly", "supervised", "full"]
    timeout_s: int                   # override del default di profilo
    extra_ro_binds: list[Path] = None
    extra_rw_binds: list[Path] = None

@dataclass
class SandboxResult:
    exit_code: int
    stdout: bytes
    stderr: bytes
    wall_time_ms: int
    oom_killed: bool
    timed_out: bool

class Sandbox(Protocol):
    async def run(self, req: SandboxRequest) -> SandboxResult:
        """Esegue un Tool in un profilo bwrap+systemd-run. Non solleva su errori tool."""
        ...

    async def dry_run_simulate(self, req: SandboxRequest) -> SandboxResult:
        """Esegue in profilo tmpfs totale: qualunque side-effect è temporaneo."""
        ...

13. Alternative considerate

14. Test di conformità

15. Riferimenti

Continua a leggere

myclaw — sandbox microprogettazione v1.0 — 2026-04-21
Ultimo dei 4 classici. Fase 1 di microprogettazione completa.