Se preferisci non usare --shell-install, aggiungi tu stesso la riga:```bash

zsh / bash

eval "$(cplt --shell-setup --agent opencode)"

fish

alias opencode 'cplt --agent opencode'

Lo stesso schema usato da mise, direnv e starship.
</details>

**Perché ogni alias nomina il suo agente.** `alias opencode=cplt` non farebbe ciò che sembra. Il semplice `cplt` sceglie il suo agente da `--agent`, poi dal file di configurazione, poi da qualunque cosa trovi nel PATH — e il rilevamento del PATH preferisce `copilot`. Digitare `opencode` metterebbe invece in sandbox Copilot, senza nulla sullo schermo che lo segnali. L'alias passa `--agent` in modo che il comando che digiti sia l'agente che ottieni.

**Perché un alias invece di un symlink?** cplt e Copilot CLI si installano nella stessa directory bin di Homebrew (`/opt/homebrew/bin/`), e solo un file chiamato `copilot` può risiedervi, quindi un symlink entrerebbe in conflitto. Un alias aggira il problema. Il vero binario `copilot` resta nel PATH dove cplt può trovarlo e incapsularlo, e l'alias reindirizza il tuo comando.

> **Nota:** cplt rifiuta di annidarsi. Se rileva di essere già in esecuzione all'interno di una sandbox (tramite la variabile d'ambiente `__CPLT_WRAPPED`), non si avvierà di nuovo. I sottocomandi di sola lettura come `--print-profile` e `cplt doctor` funzionano comunque all'interno di una sandbox esistente.

## Utilizzo```
cplt [OPTIONS] [-- <AGENT_ARGS>...]

Tutto ciò che segue -- viene passato direttamente al processo dell'agente (copilot, opencode, gemini, antigravity, pi, claude, goose, dsh o shell).

Preset delle policy

Un preset imposta una base per i cinque toggle principali della sandbox con un solo flag invece di un elenco. I flag individuali hanno comunque la precedenza sul preset, quindi --preset permissive --no-allow-tmp-exec fa esattamente ciò che dice. Impostabile anche come [sandbox] preset = "..." nella configurazione.

Matrice completa dei preset e ordine di risoluzione: docs/configuration.md.

Accesso ai file

La directory del progetto è lo spazio di lavoro scrivibile, più una ristretta allowlist necessaria per auth, runtime e tooling (vedi la tabella sopra). Il kernel blocca tutto il resto, chiavi SSH e credenziali cloud incluse.

Variabili d'ambiente

cplt sanifica l'ambiente figlio per default. Solo le variabili sicure passano, e credenziali cloud, URL di database e token dei package vengono rimossi. Inietta anche variabili di hardening che bloccano gli script lifecycle di npm/yarn/pnpm (hook postinstall, il vettore di attacco della supply chain numero uno), disabilitano la firma di commit e tag git (poiché ~/.ssh e ~/.gnupg sono irraggiungibili dentro la sandbox), e disattivano la telemetria del tooling di sviluppo (DO_NOT_TRACK=1, NEXT_TELEMETRY_DISABLED=1, TURBO_TELEMETRY_DISABLED=1, CHECKPOINT_DISABLE=1 e altri).

Cosa passa:

Allowlist per prefisso con protezione dal suffisso segreto. Una variabile che corrisponde a un prefisso consentito come COPILOT_* o YARN_* viene comunque scartata se termina con un suffisso che porta segreti: _TOKEN, _AUTH, _SECRET, _SECRET_KEY, _KEY, _PASSWORD o _CREDENTIALS. Quindi COPILOT_DEBUG passa e COPILOT_API_KEY no.

Sempre bloccate: AWS_*, AZURE_*, NPM_TOKEN, DATABASE_URL, VAULT_TOKEN, SSH_AUTH_SOCK, variabili Docker, token CI e qualsiasi cosa non sia nell'allowlist.

Toggle della sandbox

Runtime supportati

cplt rileva automaticamente gli strumenti installati e scrive regole di sandbox corrispondenti. In genere solo le directory che esistono su disco ricevono regole, quindi non ci sono percorsi fantasma. Su macOS, le directory delle app scrivibili vengono incluse quando rilevate anche se non esistono ancora, così possono essere create al primo utilizzo. Linux non può consentire una scrittura su un percorso inesistente, quindi lì la creazione deve avvenire fuori dalla sandbox.

Esegui cplt doctor per vedere se cplt funzionerà qui per il tuo agente, e cplt doctor --verbose per tutto ciò che ha rilevato sulla tua macchina.

Debug

Flag di sessione

Questi si traducono nei flag di sessione dell'agente stesso, quindi non serve un separatore --.

--continue e --resume sono mappati anche per OpenCode, Antigravity e Claude Code:

¹ Né OpenCode né Antigravity hanno un selettore interattivo di sessione, quindi un --resume da solo significa "continua l'ultima sessione". Claude Code ne ha uno, quindi viene mappato direttamente.

--remote e --name sono solo per Copilot. Pi e la modalità shell non ricevono alcuna traduzione, quindi tutti e quattro i flag vengono scartati per loro. L'auto-resume è un meccanismo separato: quando invochi cplt senza argomenti pass-through e senza flag di sessione, aggiunge --resume per te, e questo vale solo per Copilot.

Combinabili con i flag della sandbox e gli argomenti pass-through dopo --:```bash cplt --resume=my-task # resume by name cplt --remote --name my-task -- -p "fix tests" # remote + named + prompt

### Agenti

Scegline uno con `--agent <name>`, oppure rendilo predefinito con `cplt config set sandbox.agent <name>`. Copilot, OpenCode e Antigravity vengono rilevati automaticamente da `PATH` in quest'ordine quando non ne specifichi uno.

| Agente | Valore `--agent` | Rilevato automaticamente | Autenticazione |
| --- | --- | --- | --- |
| GitHub Copilot CLI | `copilot` | sì, priorità 1 | Token GitHub, dal Keychain o da `gh` |
| [OpenCode](https://opencode.ai/) | `opencode` | sì, priorità 2 | Abbonamento Copilot tramite `/connect`, oppure `--pass-env ANTHROPIC_API_KEY` |
| [Antigravity CLI](https://github.com/google-antigravity/antigravity-cli) | `antigravity`, alias `agy` e `agi` | sì, priorità 3 | Google OAuth nel browser |
| [Pi](https://github.com/earendil-works/pi) | `pi` | no | `--pass-env ANTHROPIC_API_KEY` e simili |
| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | `claude`, alias `cc` e `claude-code` | no | OAuth dell'abbonamento in `~/.claude` o nel Keychain, `CLAUDE_CODE_OAUTH_TOKEN` (rimuove la concessione del Keychain), oppure `--pass-env ANTHROPIC_API_KEY` |
| [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) | `dsh`, alias `deepseek` e `deepseek-harness` | no | `--pass-env DEEPSEEK_API_KEY`, oppure `$DSH_HOME/.env` (`~/.dsh/.env`) |
| La tua shell | `shell` | no | nessuna |

- **Pi, Claude Code, goose e DeepSeek Harness non vengono mai rilevati automaticamente.** `pi` e `dsh` sono nomi di binari generici che potrebbero entrare in conflitto con qualcos'altro sulla tua macchina, e Claude Code deve essere scelto intenzionalmente.
- **Le chiavi API di terze parti sono opt-in.** `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `OPENROUTER_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, `CLAUDE_CODE_OAUTH_TOKEN` e le variabili di routing Bedrock/Vertex (`CLAUDE_CODE_USE_BEDROCK`, `AWS_BEARER_TOKEN_BEDROCK`, `CLAUDE_CODE_USE_VERTEX`, `ANTHROPIC_VERTEX_PROJECT_ID`, `GOOGLE_CLOUD_PROJECT`) non passano mai a meno che tu non le specifichi con `--pass-env`.
- **L'autenticazione tramite abbonamento non richiede variabili d'ambiente.** Il flusso device di `/connect` di OpenCode memorizza il suo token in `~/.local/share/opencode/auth.json`, e il token OAuth di Claude Code risiede in `~/.claude` (`.credentials.json` su Linux) o nel Keychain di macOS. Entrambi sono raggiungibili all'interno della sandbox, quindi cplt non ti avvisa di una chiave API mancante per nessuno dei due.
- **I flussi OAuth nel browser richiedono `--allow-browser`** quando appare una richiesta di accesso. Questo vale per Antigravity; ogni altro agente qui utilizza un flusso device che stampa un codice e un URL e non richiede un browser. Il flag consente all'agente di avviare qualsiasi applicazione al di fuori della sandbox e non può essere limitato a URL specifici, quindi attivalo per l'accesso e disattivalo subito dopo — vedi la [tabella dei flag](#sandbox-toggles) e [docs/security.md](https://github.com/navikt/cplt/blob/main/docs/security.md#--allow-browser-is-a-sandbox-escape-and-cannot-be-scoped).
- **L'aggiornamento automatico di Claude Code è disabilitato** con `DISABLE_AUTOUPDATER=1`. Claude Code non ha un flag `--no-auto-update`, l'auto-aggiornamento all'interno della sandbox è un vettore di persistenza, e fallirebbe comunque contro percorsi di installazione in sola lettura.
- **`CLAUDE_CONFIG_DIR` è rispettato.** Quando è impostato, cplt concede quella directory invece di `~/.claude` e passa la variabile, così una radice di configurazione spostata continua a funzionare.
- OpenCode è [un client Copilot ufficialmente supportato](https://github.blog/changelog/2026-01-16-github-copilot-now-supports-opencode/), quindi il tuo abbonamento Copilot esistente funziona con `/connect` all'interno di OpenCode.

Le directory di configurazione per agente, l'uso del Keychain, i permessi di esecuzione e l'isolamento delle variabili d'ambiente sono in [SECURITY.md](https://github.com/navikt/cplt/blob/main/SECURITY.md#supported-agents).

### Supporto goose

cplt può eseguire in sandbox [goose](https://github.com/aaif-goose/goose), l'agente AI open-source (binario `goose`). Verificato con goose 1.48.0.```bash
# Run goose (must be explicit — not auto-detected)
cplt --agent goose

# goose is provider-agnostic — pass your provider's API key
cplt --agent goose --pass-env ANTHROPIC_API_KEY
cplt --agent goose --pass-env OPENAI_API_KEY

# Skip the keyring entirely: keep the key in the environment
GOOSE_DISABLE_KEYRING=1 cplt --agent goose --pass-env OPENAI_API_KEY --pass-env GOOSE_DISABLE_KEYRING

# Set goose as your default agent
cplt config set sandbox.agent goose

Note di sicurezza per goose:

• Non rilevato automaticamente: selezionalo esplicitamente con --agent goose o imposta sandbox.agent = "goose" nella configurazione
• Indipendente dal provider: goose instrada il traffico del modello verso un provider configurato dall'utente (Anthropic, OpenAI, Google, Databricks, OpenRouter, …). Le chiavi dei provider comuni (ANTHROPIC_API_KEY, OPENAI_API_KEY, AZURE_OPENAI_API_KEY, GOOGLE_API_KEY, DATABRICKS_HOST/DATABRICKS_TOKEN, GROQ_API_KEY, OPENROUTER_API_KEY, XAI_API_KEY, AWS_BEARER_TOKEN_BEDROCK) sono riconosciute come suggerimenti di autenticazione e devono essere passate tramite --pass-env. goose legge , non . Qualsiasi provider al di fuori di questo sottoinsieme funziona comunque: assegna un nome alla sua variabile con

Supporto DeepSeek Harness

cplt può eseguire in sandbox DeepSeek Harness (binario dsh), l'agent harness orientato ai plugin di DeepSeek. A monte viene distribuito come anteprima per sviluppatori e il suo stesso SAFETY.md afferma di non fare affidamento sui suoi controlli come unico confine, che è il caso per cui esiste cplt.```bash

Run DSH (must be explicit — not auto-detected)

cplt --agent dsh

Pass the API key, or keep it in $DSH_HOME/.env

cplt --agent dsh --pass-env DEEPSEEK_API_KEY

Set DSH as your default agent

cplt config set sandbox.agent dsh

**Note di sicurezza per DSH:**
- **Non rilevato automaticamente**: selezionalo con `--agent dsh` (alias `deepseek`, `deepseek-harness`) oppure imposta `sandbox.agent = "dsh"`. `dsh` è un nome di comando breve e generico che potrebbe appartenere a qualcos'altro sulla tua macchina
- **Disattiva la sandbox interna di DSH dentro cplt**: DSH avvolge ogni chiamata agli strumenti shell e file nel proprio sandbox di processo — Seatbelt su macOS, bwrap o Landlock su Linux. Nessuno dei due si annida dentro cplt. macOS non supporta chiamate `sandbox-exec` annidate (la stessa limitazione che fa disattivare a cplt la sandbox interna di Gradle, vedi [Limitazioni](#limitations)), e bwrap costruisce il suo namespace con `unshare`, che il filtro seccomp di cplt nega. In ogni caso cplt è il confine che applica le restrizioni, quindi scegli il preset di permessi `danger-full-access` fornito da DSH per le sessioni in sandbox. Lascia attivo il runner interno e le chiamate agli strumenti falliranno con un errore del sandbox runner anziché un errore del task
- **Una sola radice home, e cplt segue l'override**: DSH mantiene sessioni, impostazioni, cache e profili sotto `$DSH_HOME` (`~/.dsh` per impostazione predefinita). `DSH_HOME` è nella allowlist delle variabili d'ambiente, quindi il processo figlio risolve la stessa radice che cplt concede. Un valore che punta a una radice di sistema o alla tua directory home viene rifiutato prima dell'avvio, lo stesso veto a cui va incontro `CLAUDE_CONFIG_DIR`
- **Protezione della persistenza sull'host**: `$DSH_HOME/cordis.patch.yml`, l'overlay a livello di home che il Loader legge all'avvio, è protetto da scrittura. `$DSH_HOME/profiles/` rimane scrivibile perché DSH riscrive la radice di inclusione `cordis.yml` di ogni profilo a ogni avvio, quindi un `cordis.patch.yml` per profilo e i plugin installati sono un residuo documentato — fai le modifiche ai profili e a `dsh plugin` fuori da cplt, e avvia sempre `dsh` tramite cplt così qualunque cosa impiantata viene comunque eseguita in sandbox
- **Domini predefiniti**: solo `deepseek.com`. L'adattatore `dsh-llm-deepseek` fornito punta per impostazione predefinita a `https://api.deepseek.com`. Punta `DEEPSEEK_BASE_URL` a un gateway e dovrai aggiungere il dominio di quel gateway tramite `allowed_domains`
- **Autenticazione**: passa la chiave con `--pass-env DEEPSEEK_API_KEY`, oppure conservala in `$DSH_HOME/.env`. Una chiave salvata tramite l'interfaccia dei modelli di DSH finisce in `$DSH_HOME/.credentials.yaml`, dentro la stessa radice scrivibile. Il Keychain di macOS è negato, quindi `git push` su HTTPS richiede il token di `gh` in `hosts.yml` oppure `--pass-env GH_TOKEN`

### Modalità shell

Esegui una semplice shell in sandbox senza alcun agente AI e con le stesse restrizioni. Utile per testare strumenti di build, fare debug di problemi della sandbox, o semplicemente lavorare con attenzione manualmente.```bash
# Interactive sandboxed shell (uses $SHELL: fish, zsh, bash)
cplt --agent shell

# Inspect what's allowed without entering the shell
cplt --agent shell --print-profile

Le stesse regole di negazione predefinita si applicano: isolamento del filesystem, restrizioni di rete, sanificazione delle variabili d'ambiente. Le directory di configurazione della shell (variabili e cronologia di fish, cronologia di zsh) rimangono scrivibili.

Per un singolo comando, cplt exec è più pulito di cplt --agent shell -- -c 'cmd'.

Modalità Exec

Esegui qualsiasi comando all'interno della sandbox senza avviare un agente. Nessun banner di avvio, nessun prompt di conferma, quindi è adatto a script, pipe e alias della shell.```bash

Sandbox a single command

cplt exec -- npm install cplt exec -- make build cplt exec -- go test ./...

Compound commands via $SHELL -c

cplt exec -c "npm install && npm test"

Pass sandbox flags as usual

cplt exec --allow-lifecycle-scripts -- npm install cplt exec --project-dir /path/to/repo -- make build cplt exec --with-proxy -- curl https://example.com

Shell aliases for sandboxed tools

alias npm="cplt exec -- npm" alias node="cplt exec -- node" alias python="cplt exec -- python"

Ogni flag di primo livello di `cplt` si applica: `--project-dir`, `--allow-read`, `--deny-path`, `--with-proxy`, `--pass-env` e gli altri. Aggiungi `--no-quiet` per vedere il riepilogo completo della configurazione della sandbox prima che il comando venga eseguito.

### Esempi```bash
# The common case: Copilot in the sandbox
cplt -- -p "fix the tests"

# Sessions
cplt --resume                                   # pick one interactively
cplt --resume=my-refactor                       # by name
cplt --continue                                 # most recent in this directory
cplt --remote --name my-task -- -p "fix tests"  # named remote session

# Check the environment before the first run
cplt doctor

# Let Copilot read a shared library directory
cplt --allow-read ~/shared-libs -- -p "use shared-libs"

# Block a path you don't want Copilot to see
cplt --deny-path ~/.config/gh -- -p "refactor auth"

# Extra outbound port, e.g. an external API
cplt --allow-port 8443 -- -p "test the API"

# Localhost for MCP servers or dev servers
cplt --allow-localhost 3000 --allow-localhost 8080 -- -p "use the MCP server"

# All of localhost, needed by Next.js/Turbopack and Vite builds
cplt --allow-localhost-any -- -p "fix the build"

# Pass specific env vars through
cplt --pass-env MY_CUSTOM_VAR --pass-env ANOTHER_VAR -- -p "run with custom config"

# Inherit the full environment (dangerous, debugging only)
cplt --inherit-env -- -p "debug the build"

# Network
cplt --no-proxy -- -p "fix the tests"                    # proxy is on by default
cplt --blocked-domains ./blocked-domains.txt -- -p "refactor"
cplt --allow-private-domain intern.nav.no -- -p "use mcp-onboarding"

# Non-interactive / CI (skip the confirmation prompt)
cplt --yes -- -p "fix the tests"

# Inspect and debug the sandbox itself
cplt --print-profile
cplt --show-denials -- -p "fix the tests"

Configurazione

La configurazione avviene a due livelli: globale, per le preferenze dello sviluppatore, e per-repo, per le policy del team.```bash

Browse and change settings interactively

cplt settings

Set global preferences

cplt config set sandbox.quiet true cplt config set proxy.blocked_domains "~/.config/cplt/blocked-domains.txt" cplt config set git_guard.mode warn # observe pushes instead of blocking them cplt config set gh_guard.enabled false # opt out of the gh guard entirely

Set per-repo policy (committed to .cplt.toml)

cplt config set --repo sandbox.allow_jvm_attach true cplt config set --repo deny.paths "~/secrets"

Inspect

cplt config show # effective config (file + defaults) cplt config explain # every key with its description

`cplt settings` è l'editor interattivo, con viste Effective, Global e Repository, ricerca, modifiche in staging e una conferma esplicita prima di salvare qualsiasi cosa relativa alla sicurezza. `cplt config` rimane l'interfaccia stabile non interattiva per script e CI. Le proposte del repository vengono comunque committate e approvate separatamente con `cplt trust`. L'editor non le committa né le approva automaticamente.

La precedenza segue i flag CLI, poi il file di configurazione globale in `~/.config/cplt/config.toml`, poi i valori predefiniti integrati. La configurazione per-repo in `.cplt.toml` è un livello separato anziché un gradino di quella scala: `[deny]` restringe incondizionatamente, e i permessi approvati sono solo additivi, quindi un repo può abilitare una funzionalità ma non può mai disattivare qualcosa impostato da un flag CLI o dalla configurazione globale.

Un `.cplt.toml` nella radice del repository contiene la policy del team:```toml
[deny]                    # Applied automatically, no opt-in needed
paths = ["~/secrets", "~/.vault-token"]
env = ["VAULT_TOKEN", "DATABASE_URL"]

[propose]                 # Requires developer approval (cplt trust accept)
gh_guard = true
git_push_prevention = true
allow_jvm_attach = true
allow_docker = true

[propose.allow]
ports = [5432]
localhost = [3000]
socket = ["/var/run/docker.sock"]

cplt lo legge da git HEAD, quindi l'agente non può manomettere la propria policy a metà sessione, e le approvazioni di fiducia sono vincolate al contenuto del file. Un .cplt.toml non committato non concede nulla finché non viene committato, sebbene le sue chiavi [deny] si applichino comunque. In CI e negli script, dove nessuno può rispondere a un prompt, --accept-repo-config approva le proposte del file committato per quella singola esecuzione senza persistere alcuna fiducia. cplt init ne scrive uno per te rilevando il tooling del progetto:```bash cplt init # preview detected permissions cplt init --write # write .cplt.toml to disk cplt init --quiet # output only TOML (pipe-friendly) cplt init --global # generate a personal ~/.config/cplt/config.toml

Conosce JVM (Gradle/Maven), Node.js, Docker, Python, Rust, Go, Playwright, Spring Boot, Ktor, TestContainers, Next.js, Vite, Flyway, Cypress e i segreti d'ambiente da `.env.example`. Le autorizzazioni pericolose escono dal generatore con un avviso di rischio allegato. `--global` esamina invece le cose a livello di macchina: browser Playwright, firma GPG, credenziali del registry, agenti alternativi.

Alcune chiavi sono solo globali e vengono rifiutate da `.cplt.toml` perché sono specifiche della macchina o una preferenza locale: `sandbox.agent`, `sandbox.quiet`, `sandbox.yes`, `sandbox.validate`, `sandbox.scratch_dir`, `sandbox.pass_env`, `sandbox.inherit_env`, `sandbox.allow_cache_exec`, `sandbox.allow_cache_exec_any`, `proxy.enabled`, `proxy.port`, `proxy.log_file`, `proxy.log_level`, `proxy.blocked_domains`, `proxy.allowed_domains`, e ogni chiave `[gh_guard]` e `[git_guard]`.

Dettagli completi, incluso il modello di fiducia, le regole di espansione dei percorsi e il riferimento completo del file di configurazione: [docs/configuration.md](https://github.com/navikt/cplt/blob/main/docs/configuration.md).

## Architettura```
┌──────────────────────────────────┐
│  cplt (Rust binary)              │
│  ┌───────────┐  ┌─────────────┐  │
│  │ Policy    │  │ CONNECT     │  │
│  │ Generator │  │ Proxy       │  │
│  └─────┬─────┘  │ (optional)  │  │
│        │        └─────────────┘  │
│        ▼                         │
│  ┌─────────────┬────────────┐    │
│  │   macOS     │   Linux    │    │
│  │  Seatbelt   │  Landlock  │    │
│  │  sandbox-   │  + seccomp │    │
│  │  exec       │  pre_exec  │    │
│  └─────────────┴────────────┘    │
│        │                         │
│        ▼                         │
│  copilot (sandboxed)             │
│  ├── All child processes         │
│  ├── Cannot read ~/.ssh          │
│  ├── Network port-restricted     │
│  ├── SSH agent blocked           │
│  └── Filesystem = primary ctrl   │
└──────────────────────────────────┘

Il modello di sicurezza è un filesystem deny-by-default con enforcement a livello di kernel. Su macOS, e su Linux con kernel 6.7+ (Landlock ABI v4), la rete è limitata alla porta 443 per impostazione predefinita, con --allow-port per le eccezioni. Su kernel Linux più vecchi il proxy CONNECT fornisce invece quella restrizione, ed è per questo che è abilitato per impostazione predefinita. L'accesso all'agente SSH e l'outbound verso localhost sono bloccati nel kernel su macOS. Su Linux nessuno dei due lo è: le regole Landlock basate sulle porte non riescono a distinguere localhost da un host remoto, e la connect() su unix socket non è gestita da Landlock sotto il kernel 7.1, quindi a parte i socket che bubblewrap maschera, il SSH_AUTH_SOCK trattenuto è l'unica cosa che si frappone tra l'agente e le tue chiavi caricate. Il generatore di profili rileva il tuo ambiente (cplt doctor --verbose mostra gli stessi risultati della sonda) ed emette regole solo per le directory degli strumenti che esistono effettivamente su disco. Meno regole, sandbox più stretta.

• macOS: viene generato un profilo Seatbelt/SBPL e passato a sandbox-exec
• Linux: regole Landlock LSM più un filtro seccomp-BPF, applicati tramite pre_exec (kernel 5.13+, filtraggio delle porte TCP su 6.7+)

Internals e struttura dei moduli: docs/architecture.md. Modello di minaccia, livelli di difesa e lacune dichiarate: SECURITY.md.

Sicurezza

Un solo binario, dipendenze minime, nessun servizio runtime, nessuna telemetria. Tre livelli di difesa, con confini chiari tra loro:

Da cosa protegge cplt:

• Esfiltrazione di segreti (chiavi SSH, credenziali cloud, file .env): bloccata dal kernel
• Esecuzione di codice non autorizzata da directory temporanee: bloccata dal kernel
• Persistenza tramite binari nelle cache-dir: bloccata dal kernel, poiché l'exec in quelle directory è negato
• Persistenza tramite git hook nel progetto: .git/hooks è in scrittura negata a livello di kernel su macOS. Su Linux, con Landlock e senza Bubblewrap, rimane scrivibile, e il git lato genitore di cplt viene poi eseguito con core.hooksPath=/dev/null così non esegue mai un hook impiantato, anche se un git che esegui tu stesso lo farà comunque
• Persistenza tramite directory degli strumenti dei package manager che sono sia scrivibili che eseguibili (shim di mise, PNPM_HOME, ~/.deno/bin, ~/.bun/bin): la scrittura è concessa lì così pnpm add -g e simili funzionano nella sandbox, quindi un agente può lasciare dietro un binario che una successiva shell raccoglierà dal tuo PATH
• Un binario impiantato che dirotta l'agente che cplt avvia: all'avvio e in fase di audit, cplt risolve gli helper che esegue esso stesso (, , , , e il da cui legge un token) da directory di sistema fisse anziché dal , ma il binario dell'agente stesso viene eseguito da dove è stato scoperto, che per un'installazione npm-global è comunemente sotto un albero mise o node scrivibile. cplt non può risolverlo da una directory fissa — vive legittimamente dove il tuo version manager l'ha messo — quindi verifica il percorso risolto rispetto alle regole di scrittura che la sandbox sta per applicare e , indicando il binario e l'albero scrivibile, poi procede

Da cosa cplt non protegge:

• Codice malevolo già presente nella directory del progetto. L'agente ha pieno accesso in lettura/scrittura lì
• Bug logici introdotti dall'agente. Il codice lo revisioni comunque tu
• Un avversario sofisticato che aggira la guardia dei comandi. Usa la protezione dei branch lato server
• Attacchi di rete verso domini consentiti. Se github.com è consentito, l'agente può leggere e scrivere lì
• Accesso al Keychain di macOS, per gli agenti che vi memorizzano l'autenticazione. I contenuti sono protetti da password, e sandbox.keychain_substitute può scambiare la concessione dove un agente ha un'altra credenziale

Le nostre priorità, in ordine: corretto (ogni affermazione è testata, ogni caso limite ha un CVE o un riferimento di ricerca), trasparente (SECURITY.md non nasconde nulla), semplice (un binario, zero configurazione richiesta, default sensati) e utile (togliersi di mezzo e lasciare che l'agente lavori, in sicurezza).

Altro: docs/security.md · SECURITY.md

Rete e proxy

Il proxy è attivo per impostazione predefinita. Tutto il traffico in uscita da Copilot CLI, gh e curl passa attraverso un proxy CONNECT su localhost tramite HTTP_PROXY/HTTPS_PROXY e NODE_USE_ENV_PROXY=1. Ascolta su una porta effimera assegnata dal sistema operativo, quindi nulla va in conflitto. Ottieni logging delle connessioni in tempo reale, blocco dei domini, allowlisting dei domini, un log di audit persistente e la stessa politica sulle porte applicata dalla sandbox (443 più qualsiasi cosa in allow.ports).```bash cplt --proxy-forced -- -p "fix tests" # force all egress through the proxy cplt --no-proxy -- -p "fix tests" # disable for one run cplt --blocked-domains blocked-domains.txt -- -p "x" # block known-bad domains cplt --allowed-domains allowed-domains.txt -- -p "x" # allowlist mode cplt --default-allowlist -- -p "x" # fail-closed: only the agent's own domains cplt --observe-domains -- -p "x" # record what the agent contacts, block nothing cplt --proxy-upstream http://proxy.corp:8080 -- -p "x" # chain through a corporate proxy

`--observe-domains-out <FILE>` scrive l'insieme osservato con un dominio per riga, e
`--proxy-upstream-no-proxy <HOST>` elenca gli host da raggiungere direttamente invece che attraverso
l'upstream.```bash
cplt config set proxy.enabled false
cplt config set proxy.blocked_domains "~/.config/cplt/blocked-domains.txt"
cplt config set proxy.allowed_domains "~/.config/cplt/allowed-domains.txt"
cplt config set proxy.log_file "~/.config/cplt/proxy.log"

La modalità forzata tramite proxy è opt-in. Limita l'egress del kernel alla porta del proxy, così un socket aperto direttamente, o un env -u HTTPS_PROXY, non può scivolare oltre. L'applicazione è completa su macOS, che si fissa a localhost:<proxy_port>. Su Linux blocca il TCP diretto su :443, e una regola seccomp consente solo SOCK_STREAM con protocollo 0 o IPPROTO_TCP per AF_INET/AF_INET6, quindi anche UDP, raw, SCTP e DCCP sono chiusi — al costo di qualsiasi cosa apra un socket di quel tipo, non solo il codice che invia UDP. Ciò che rimane è un residuo basato sulla porta, evil.com:<proxy_port>, fino a #114.

Al di fuori della modalità forzata tramite proxy, Linux non limita UDP. I diritti di rete di Landlock sono solo TCP fino all'ABI v10, cplt gestisce solo AccessNet::ConnectTcp, e la regola seccomp sopra non viene deliberatamente applicata — negare SOCK_DGRAM lì romperebbe getaddrinfo(3), e quindi tutto il DNS, per ogni strumento non proxato. L'UDP in uscita verso qualsiasi host, il bind UDP in entrata, il DNS tunnelling e QUIC/HTTP-3 sono quindi non mediati in modalità predefinita, e il proxy CONNECT trasporta solo TCP, quindi nulla di tutto ciò appare nel log del proxy. macOS limita UDP in modalità predefinita ma non lo instrada nemmeno: remote ip "*:443" copre UDP, quindi QUIC/HTTP-3 sulla 443 esce senza toccare il proxy anche lì. Sotto proxy.forced il log del proxy è un record completo dell'egress su macOS. Su Linux è completo tranne il residuo evil.com:<proxy_port> sopra, che non attraversa il proxy e quindi non appare nel suo log.

Entrambe le liste corrispondono allo stesso modo: example.com copre il dominio esatto e ogni sottodominio, la corrispondenza è case-insensitive e i punti finali vengono rimossi. I file blocklist e allowlist vengono riletti ogni cinque secondi, quindi puoi modificarli a caldo. Il traffico localhost bypassa il proxy tramite NO_PROXY e non appare mai nel log di audit. --proxy-timeout <SECONDS> limita le letture di richieste e header (predefinito 60) e non chiude i tunnel CONNECT stabiliti, che possono restare inattivi fino a un'ora.

Ogni flag del proxy, dettaglio del filtraggio dei domini, concatenamento con proxy aziendali upstream e il formato del log delle connessioni: docs/proxy.md.

Guardie dei comandi

Abilitale e cplt intercetta gh e git tramite script wrapper in $PATH:

Questo è il Livello 3, una barriera soft. Impedisce a un agente compiacente di fare qualcosa di distruttivo per errore. Per un confine rigido, affidati al sandbox del kernel e alla protezione dei branch lato server.

Con la guardia gh attiva, cplt mette anche in cache il token GitHub all'avvio e lo serve una volta tramite il callback gh auth token, poi elimina la cache. Questo riduce le fughe accidentali e basate sull'ambiente. Non è un confine contro un agente ostile, perché la cache vive nel TMPDIR dell'agente stesso e un agente che la legge prima del consumatore legittimo ottiene comunque il token. SECURITY.md contiene la dichiarazione completa su block_auth_token.

Comportamento completo: docs/gh-guard.md · docs/git-guard.md

Impatti noti

Il sandbox blocca alcuni flussi di lavoro di proposito. Quelli comuni e le relative soluzioni:

Playwright Chromium richiede cplt config set sandbox.allow_cache_exec ms-playwright, e Chromium deve essere eseguito senza il proprio sandbox annidato. Su macOS i suoi helper non possono inizializzare un secondo sandbox Seatbelt dentro cplt (forbidden-sandbox-reinit); su Linux il filtro seccomp di cplt blocca le syscall dei namespace di cui quel sandbox ha bisogno. Playwright come libreria si avvia già con --no-sandbox, e quello stesso opt-in imposta PLAYWRIGHT_MCP_SANDBOX=false per Playwright MCP, che altrimenti lo riattiverebbe. Qualsiasi altro launcher Chromium necessita di --no-sandbox esso stesso. cplt rimane il confine di applicazione a livello kernel, ma un renderer compromesso riceve quindi il profilo Playwright completo di cplt invece del profilo figlio più ristretto di Chromium. Vedi Cache exec e SECURITY.md.

Il commit Git funziona per ogni agente; se git push funziona su HTTPS dipende dall'agente. Tre prerequisiti: usa remote HTTPS invece di SSH (git remote set-url origin https://github.com/org/repo.git, oppure riscrivi globalmente con git config --global url."https://github.com/".insteadOf "[email protected]:"), esegui gh auth login una volta fuori dal sandbox, ed esegui gh auth setup-git se l'helper delle credenziali non è ancora configurato. Il push esegue quindi gh auth git-credential, che necessita di un token che gh possa raggiungere dall'interno del sandbox — questo varia per agente, vedi Git workflow. I push verso il branch predefinito e tutti i force push vengono rifiutati dalla guardia git per impostazione predefinita; fai push di un feature branch. Il socket dell'agente SSH è bloccato perché sblocca ogni chiave caricata e può autenticarsi verso qualsiasi host, mentre l'helper delle credenziali gh è limitato a GitHub.

La JVM è proxy-aware, quindi un repository Maven interno su un IP privato ora necessita di essere consentito. cplt inietta http(s).proxyHost/proxyPort in JAVA_TOOL_OPTIONS, quindi la risoluzione delle dipendenze di Gradle e Maven passa attraverso il proxy CONNECT e appare nel log del proxy invece di bypassarlo. La guardia SSRF del proxy rifiuta quindi un Nexus o Artifactory interno che si risolve in spazio di indirizzi privato, esattamente come già fa per curl, npm e pip. Aggiungi il suo nome DNS a proxy.allow_private_domains. Un URL di repository scritto come IP letterale nudo (https://10.20.30.40/repository/maven-public/) non può essere consentito da nessuna chiave — quel controllo viene eseguito prima che la allow list venga consultata — quindi un tale repository necessita di un nome DNS. I fork dei plugin WorkerExecutor, e un daemon Gradle avviato fuori da cplt e riutilizzato all'interno, non sono proxati. Vedi Repository Maven/Gradle interni su IP privati.

Gradle 9+ esegue il proprio sandbox annidato, e cplt lo disattiva. Da Gradle 8.8 il daemon si avvolge in sandbox-exec (controllato da GRADLE_MACOS_SANDBOX, in precedenza la proprietà org.gradle.daemon.sandbox). macOS non supporta chiamate sandbox-exec annidate, quindi il sandbox interno fallisce con "Operation not permitted" sulle operazioni sui socket. cplt inietta GRADLE_MACOS_SANDBOX=off, poiché fornisce già sandboxing a livello kernel. Questo è un problema upstream noto che colpisce qualsiasi strumento che avvolge Gradle in un sandbox esterno. Sovrascrivi con --pass-env GRADLE_MACOS_SANDBOX se vuoi davvero il sandbox di Gradle stesso.

Copilot CLI 1.0.83 esegue il proprio sandbox annidato, e cplt lo disattiva. Su Linux quel sandbox costruisce un network namespace — slirp4netns, iptables, /dev/net/tun — e il filtro seccomp di cplt nega la unshare che richiede. cplt imposta anche HTTP_PROXY/HTTPS_PROXY, il che nella 1.0.83 mette un sandbox Linux sul percorso di egress del proxy che tu l'abbia richiesto o meno, quindi i due collidono a ogni avvio. Sintomo: [cplt] Starting Copilot in sandbox... e poi nulla. cplt inietta l'opt-out di Copilot stesso, COPILOT_CLI_SANDBOX_SUPPORT_OVERRIDE=unsupported; Copilot si fa da parte per la sessione, lo dichiara, e lascia intatto il tuo sandbox.enabled salvato. cplt è il confine, come lo è per Gradle e Chromium. Sovrascrivi con --pass-env COPILOT_CLI_SANDBOX_SUPPORT_OVERRIDE. Una policy gestita aziendale che richiede il sandbox sovrascrive tutto questo — vedi Il sandbox dei comandi di Copilot CLI.

Ogni impatto, con le tabelle per strumento, le note sui daemon JVM e Kotlin, la risoluzione dei problemi GPG e le differenze di piattaforma per i registry privati: docs/known-impacts.md.

Limitazioni

macOS

• sandbox-exec è deprecato. Apple non l'ha rimosso, ma potrebbe farlo in una versione futura di macOS.
• SBPL non ha filtraggio basato sul dominio. Il proxy CONNECT opzionale fornisce invece il blocco dei domini.
• Anche lsopen di SBPL non ha filtri, quindi --allow-browser è tutto Launch Services o niente. Con esso attivo l'agente può avviare qualsiasi applicazione fuori dal sandbox, e nessun wrapper può restringere ciò — vedi docs/security.md.

Linux

• Richiesto kernel 5.13+, con Landlock LSM abilitato.
• Il filtraggio delle porte TCP richiede kernel 6.7+. I kernel più vecchi ottengono solo l'applicazione sul filesystem.
• Landlock non può negare sottopercorsi all'interno di percorsi consentiti, quindi la lettura/scrittura/cancellazione di .env dentro la directory del progetto non è applicata dal kernel. Le scritture in .git/hooks sono bloccate quando Bubblewrap è attivo.
• --deny-path richiede Bubblewrap. Viene applicato tramite maschere di mount quando bwrap è attivo. Senza di esso, Landlock è solo allowlist e cplt avvisa del deny invece di applicarlo.

Altro: docs/security.md

Contribuire

I contributi sono benvenuti.```bash git clone https://github.com/navikt/cplt.git && cd cplt git config core.hooksPath hack # enables pre-commit fmt + clippy checks mise run check # runs fmt, clippy, and tests

Apri una issue prima di iniziare una modifica importante. Ogni PR deve superare la CI (fmt, clippy, test).

## Riferimenti

- [SECURITY.md](https://github.com/navikt/cplt/blob/main/SECURITY.md), il modello di sicurezza completo, l'analisi delle minacce, la strategia di test e lo stato dell'arte
- [Apple sandbox-exec(1)](https://keith.github.io/xcode-man-pages/sandbox-exec.1.html)
- [Chromium Seatbelt V2 Design](https://chromium.googlesource.com/chromium/src/sandbox/+show/refs/heads/main/mac/seatbelt_sandbox_design.md)
- [Documentazione Landlock LSM](https://docs.kernel.org/userspace-api/landlock.html)
- [Documentazione seccomp-BPF](https://www.kernel.org/doc/html/latest/userspace-api/seccomp_filter.html)
- [OWASP SSRF Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Server_Side_Request_Forgery_Prevention_Cheat_Sheet.html)
- [michaelneale/agent-seatbelt-sandbox](https://github.com/michaelneale/agent-seatbelt-sandbox)

## Licenza

[MIT](https://github.com/navikt/cplt/blob/main/LICENSE)