> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandbox

> Isolamento a livello di sistema operativo per le sessioni di Devin CLI: funzionamento della sandbox, filtraggio del traffico di rete e imposizione in ambito Enterprise.

Il flag `--sandbox` esegue la CLI con isolamento a livello di sistema operativo, applicando a livello di sistema operativo gli ambiti di autorizzazione Read e Write attivi e, facoltativamente, limitando il traffico di rete.

<div id="how-the-sandbox-works">
  ## Come funziona la sandbox
</div>

Quando la sandbox è attiva:

* I **percorsi scrivibili** derivano dagli ambiti delle autorizzazioni `Write(...)` concessi, oltre che dalla directory del workspace
* I **percorsi leggibili** derivano dagli ambiti `Read(...)` concessi (i percorsi predefiniti della piattaforma, come `/usr/bin`, sono sempre leggibili)
* Gli ambiti concessi nel corso della sessione espandono dinamicamente la sandbox per i comandi successivi

<Warning>
  Se la risoluzione della sandbox non riesce (ad es. gli strumenti di sandboxing non sono disponibili sulla piattaforma dell'utente), la CLI **si rifiuta di avviarsi** invece di avviarsi senza sandbox. Questo comportamento fail-closed si applica sia quando la sandbox è stata abilitata tramite un'[impostazione del team](/it/cli/enterprise/team-settings#sandbox-enforcement), sia quando l'utente passa direttamente `--sandbox`, garantendo che l'obiettivo di sicurezza non venga mai aggirato silenziosamente.

  Cause comuni degli errori di risoluzione della sandbox:

  * **Windows**: il sandboxing a livello di sistema operativo non è attualmente supportato su Windows. Le sessioni su Windows non si avviano quando viene passato `--sandbox` o quando l'applicazione della sandbox è **Required**, incluso il caso in cui la CLI venga eseguita come server ACP all'interno di un IDE (ad es. Devin Desktop).
  * **Linux**: il sandboxing richiede che `bubblewrap` (`bwrap`) e `socat` siano installati. Se mancano, l'avvio delle sessioni non riesce e vengono mostrate le istruzioni di installazione.
  * **Errori negli ambiti di autorizzazione**: percorsi non validi negli ambiti di autorizzazione che non possono essere risolti.
</Warning>

<div id="network-filtering">
  ## Filtro di rete
</div>

<Warning>
  Il filtro di rete del sandbox è attualmente instabile. Se hai bisogno di questa funzionalità, contatta il referente del tuo account per conoscere le tempistiche di stabilizzazione.
</Warning>

Configura il filtro di rete a livello di dominio per il sandbox nella [sezione `sandbox` del file di configurazione](/it/cli/reference/configuration/config-file#sandbox) (solo configurazione utente). Quando `--sandbox` è attivo e il filtraggio dei domini è configurato, viene avviato un proxy di rete gestito sull'interfaccia di loopback e il sandbox limita tutto il traffico dei processi figli a passare attraverso di esso.

| Opzione           | Tipo      | Predefinito | Descrizione                                                                                                                       |
| ----------------- | --------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `allowed_domains` | string\[] | `[]`        | Pattern di dominio consentiti tramite il proxy. Se non è vuoto, sono consentiti solo i domini corrispondenti (modalità allowlist) |
| `denied_domains`  | string\[] | `[]`        | Pattern di dominio sempre bloccati. Le regole `deny` hanno la precedenza sulle regole di autorizzazione                           |
| `network_mode`    | string    | `"full"`    | `"full"` consente tutti i metodi HTTP; `"limited"` consente solo GET/HEAD/OPTIONS                                                 |

**Sintassi dei pattern di dominio:**

| Pattern          | Corrisponde a                                      |
| ---------------- | -------------------------------------------------- |
| `example.com`    | Solo corrispondenza esatta                         |
| `*.example.com`  | Qualsiasi sottodominio (non il dominio principale) |
| `**.example.com` | Dominio principale e qualsiasi sottodominio        |

**Esempio:**

```json theme={null}
{
  "sandbox": {
    "allowed_domains": [
      "github.com",
      "**.npmjs.org",
      "**.crates.io",
      "**.pypi.org"
    ],
    "denied_domains": ["evil.example.com"],
    "network_mode": "full"
  }
}
```

<Note>
  Il filtraggio dei domini si applica quando la sandbox è attiva (`--sandbox`). Senza `--sandbox`, la sezione relativa alla sandbox viene ignorata.
</Note>

<div id="excluded-commands">
  ## Comandi esclusi
</div>

A volte un comando specifico deve essere eseguito *al di fuori* della sandbox, ad esempio i comandi `git` che devono accedere alle credenziali o gli hook bloccati dalla sandbox. La sezione di configurazione `sandbox.excluded` consente di escludere i comandi corrispondenti dall'isolamento della sandbox usando la stessa sintassi di regola `Exec(...)` di [autorizzazioni](/it/cli/reference/permissions):

| Opzione          | Tipo      | Descrizione                                                                                         |
| ---------------- | --------- | --------------------------------------------------------------------------------------------------- |
| `excluded.allow` | string\[] | I comandi corrispondenti vengono eseguiti automaticamente al di fuori della sandbox                 |
| `excluded.ask`   | string\[] | I comandi corrispondenti vengono eseguiti al di fuori della sandbox dopo l'approvazione dell'utente |
| `excluded.deny`  | string\[] | I comandi corrispondenti non vengono mai esclusi: restano sempre all'interno della sandbox          |

**Esempio:**

```json theme={null}
{
  "sandbox": {
    "excluded": {
      "allow": ["Exec(git status *)"],
      "ask": ["Exec(git push *)"],
      "deny": ["Exec(git tag *)"]
    }
  }
}
```

**Risoluzione delle regole:** per ogni comando, all'interno di una sorgente prevale la regola corrispondente più specifica (ad es. `Exec(git push *)` prevale su `Exec(git *)`), e quando corrispondono sia la configurazione utente sia le [impostazioni del team](#enterprise-excluded-commands), prevale il verdetto più restrittivo (`deny` > `ask` > `allow`). I comandi senza alcuna regola corrispondente — anche quando `sandbox.excluded` non è configurato — vengono sempre eseguiti all'interno della sandbox.

<Note>
  * In `sandbox.excluded` sono supportate solo le regole `Exec(...)`; qualsiasi altro tipo di regola (ad es. `Read(...)`, `Write(...)`) viene ignorato con un avviso.
  * L'esclusione opera in modalità fail-closed: se un comando non può essere determinato in modo sicuro (ad es. perché non può essere analizzato), rimane all'interno della sandbox.
  * Le esclusioni si applicano al percorso exec predefinito per comando. I comandi eseguiti tramite una shell PTY persistente (sessioni interattive, oppure quando `pty_for_noninteractive_exec` è abilitato) rimangono sempre all'interno della sandbox.
</Note>

<div id="enterprise-enforcement">
  ## Applicazione a livello Enterprise
</div>

Gli amministratori Enterprise possono controllare il comportamento della sandbox per l'intera organizzazione tramite [Team Settings](/it/cli/enterprise/team-settings#sandbox-enforcement).

<div id="sandbox-enforcement-mode">
  ### Modalità di applicazione della sandbox
</div>

Imposta il livello di applicazione del flag `--sandbox` per tutta la tua organizzazione:

* **Facoltativo** (predefinito) — Gli utenti scelgono se specificare `--sandbox`. Nessuna imposizione.
* **Obbligatorio** — Il flag `--sandbox` viene imposto per tutti gli utenti, anche se non lo specificano sulla riga di comando. Tutte le sessioni CLI vengono eseguite con sandboxing del file system a livello di sistema operativo, che applica gli ambiti di autorizzazione in lettura/scrittura.

Una futura modalità **Strict** potrebbe bloccare completamente la configurazione della sandbox, impedendo agli utenti di modificarne le impostazioni.

<Warning>
  Assicurati che tutte le macchine di destinazione siano state predisposte prima di impostare la modalità di applicazione della sandbox su **Obbligatorio** per tutta la tua organizzazione. Se alcuni utenti utilizzano Windows, non potranno eseguire la CLI finché il sandboxing a livello di sistema operativo non sarà supportato su Windows o finché il criterio non verrà allentato su **Facoltativo**.
</Warning>

<div id="enterprise-domain-filtering">
  ### Filtraggio dei domini Enterprise
</div>

Gli amministratori possono anche configurare allowlist e denylist di domini valide per l'intera organizzazione:

* **Allowlist di domini** — Se impostata, **solo** i domini presenti in questo elenco sono raggiungibili tramite il proxy di rete della sandbox. Questo elenco è **vincolante**: sostituisce completamente qualsiasi `allowed_domains` configurato dall'utente. Gli utenti non possono aggiungere altri domini per aggirare le restrizioni impostate dagli amministratori.
* **Denylist di domini** — Domini sempre bloccati. I domini negati a livello Enterprise sono **additivi**: vengono uniti ai `denied_domains` locali dell'utente, rendendo l'elenco risultante più restrittivo.

**Come interagiscono gli elenchi di domini Enterprise e quelli dell'utente:**

| Scenario                                        | Configurazione Enterprise         | Configurazione utente             | Risultato effettivo                                                          |
| ----------------------------------------------- | --------------------------------- | --------------------------------- | ---------------------------------------------------------------------------- |
| L'amministratore imposta un'allowlist           | `allowed_domains: ["github.com"]` | `allowed_domains: ["npmjs.org"]`  | È consentito solo `github.com` (Enterprise sostituisce l'elenco dell'utente) |
| L'amministratore imposta una denylist           | `denied_domains: ["evil.com"]`    | `denied_domains: ["risky.io"]`    | Sia `evil.com` sia `risky.io` sono bloccati (uniti)                          |
| Nessuna allowlist impostata dall'amministratore | `allowed_domains: []`             | `allowed_domains: ["github.com"]` | Viene usata l'allowlist dell'utente                                          |

<Note>
  Poiché i `denied_domains` locali dell'utente vengono mantenuti e uniti in modo additivo, un utente potrebbe negare un dominio presente nell'allowlist Enterprise. È intenzionale: l'effetto combinato è sempre più restrittivo, mai meno. Se questo causa problemi di accesso, l'utente deve rimuovere la voce in conflitto dalla propria configurazione locale.
</Note>

<div id="enterprise-excluded-commands">
  ### Comandi esclusi a livello Enterprise
</div>

Gli admin possono anche impostare nelle impostazioni del team regole di [comandi esclusi](#excluded-commands) valide per tutta l'organizzazione:

* **Allow / ask esclusi** — regole `Exec(...)` per i comandi che possono essere eseguiti fuori dal sandbox in tutta l'organizzazione, automaticamente o dopo una richiesta di conferma.
* **Deny esclusi** — regole `Exec(...)` per i comandi che non devono mai essere eseguiti fuori dal sandbox. Un `deny` del team ha la precedenza su qualsiasi `allow` o `ask` a livello utente per i comandi corrispondenti, quindi gli utenti non possono escludere comandi che i loro admin hanno bloccato.

Le regole del team e dell'utente vengono risolte insieme: all'interno di ogni origine prevale la regola corrispondente più specifica, e tra origini prevale il verdetto più restrittivo (`deny` > `ask` > `allow`).

**Esempio: bloccare tutte le esclusioni tranne `gh`.** Un `deny` wildcard con un'eccezione `allow` mantiene tutti i comandi all'interno del sandbox tranne `gh`, indipendentemente da ciò che gli utenti configurano localmente. Questi valori vanno nella configurazione `excluded-commands` delle impostazioni del team (non nel file di configurazione dell'utente, quindi non c'è alcuna chiave `sandbox` esterna):

```json theme={null}
{
  "excluded": {
    "deny": ["Exec(**)"],
    "allow": ["Exec(gh *)"]
  }
}
```

Poiché la regola più specifica `Exec(gh *)` prevale sul wildcard `Exec(**)`, i comandi `gh` vengono eseguiti fuori dal sandbox, mentre tutto il resto rimane all'interno — e il `deny` wildcard a livello di team prevale su qualsiasi regola `allow` o `ask` a livello di singolo utente per gli altri comandi.

<div id="further-reading">
  ## Approfondimenti
</div>

* [Team Settings](/it/cli/enterprise/team-settings#sandbox-enforcement) — applicazione della sandbox a livello Enterprise e filtraggio dei domini
* [Riferimento del file di configurazione](/it/cli/reference/configuration/config-file#sandbox) — la sezione di configurazione `sandbox` a livello utente
* [Autorizzazioni](/it/cli/reference/permissions) — gli ambiti di autorizzazione che determinano la risoluzione dei percorsi della sandbox