Installa e configura l'interfaccia a riga di comando

CodeMender è un agente autonomo di sicurezza del codice basato sull'AI che analizza, verifica e applica patch alle vulnerabilità di cybersicurezza più profonde nel tuo codebase. Prima di eseguire CodeMender, scarica l'interfaccia a riga di comando e inizializza le opzioni dell'area di lavoro.

Architettura e modello di sicurezza

CodeMender utilizza un modello di esecuzione local-first:

  • Motore di ragionamento ospitato: il ragionamento agentico, la modellazione delle minacce e la logica di orchestrazione vengono eseguiti in modo sicuro in Google Cloud su Gemini Enterprise Agent Platform.
  • Interfaccia a riga di comando per l'esecuzione locale: il codice sorgente non lascia mai la tua workstation o il tuo container CI/CD in blocco. Lo strumento CLI locale cm esegue letture di file, controlli di build locali e verifiche di exploit proof-of-concept (PoC) nella sandbox locale, inviando solo snippet di codice chirurgici e risultati di esecuzione dello strumento al backend cloud tramite l'API Interactions su Gemini Enterprise Agent Platform.

Configurazione dell'ambiente

Per iniziare a utilizzare CodeMender, configura il tuo progetto Google Cloud , scarica e installa l'interfaccia a riga di comando, configura le credenziali e il progetto di destinazione e inizializza l'area di lavoro.

Configurazione del progetto e autorizzazioni IAM

Prima di scaricare l'interfaccia a riga di comando e configurare le credenziali, assicurati che il progetto Google Cloud di destinazione sia configurato correttamente con le API e le autorizzazioni richieste.

API obbligatorie

Assicurati che le seguenti API Google Cloud siano abilitate nel tuo progetto:

  1. API Agent Platform (aiplatform.googleapis.com): gestisce lo streaming e la gestione delle sessioni attive.
  2. API Cloud Resource Manager (cloudresourcemanager.googleapis.com): convalida gli stati di autenticazione degli utenti e i metadati dei progetti.

Per eseguire i comandi dell'interfaccia a riga di comando, agli utenti deve essere assegnato il seguente ruolo IAM:

  • Agent Platform User (roles/aiplatform.user): consente agli utenti di creare, riprodurre in streaming e gestire sessioni di attività attive.

Scarica e installa l'interfaccia a riga di comando CodeMender

I file binari dell'interfaccia a riga di comando di CodeMender sono ospitati in Artifact Registry. Scegli la scheda relativa al tuo sistema operativo per scaricare e installare l'interfaccia a riga di comando.

Linux x86_64

Per scaricare e installare l'interfaccia a riga di comando CodeMender per Linux (x86_64):

  1. Scarica il pacchetto utilizzando uno dei seguenti metodi:
    • gcloud CLI: esegui il seguente comando:
      gcloud artifacts generic download \
        --project=cmoc-prod \
        --location=us \
        --repository=codemender-cli-production \
        --package=cm \
        --version=stable \
        --name=cm-linux-amd64.zip \
        --destination=./
    • curl: esegui questo comando:
      curl -L -o cm-linux-amd64.zip "https://artifactregistry.googleapis.com/download/v1/projects/cmoc-prod/locations/us/repositories/codemender-cli-production/files/cm%3Astable%3Acm-linux-amd64.zip:download?alt=media"
  2. Installa l'interfaccia a riga di comando:
    unzip cm-linux-amd64.zip
    chmod +x cm
    sudo mv cm /usr/local/bin/cm

Linux ARM64

Per scaricare e installare l'interfaccia a riga di comando CodeMender per Linux (ARM64):

  1. Scarica il pacchetto utilizzando uno dei seguenti metodi:
    • gcloud CLI: esegui il seguente comando:
      gcloud artifacts generic download \
        --project=cmoc-prod \
        --location=us \
        --repository=codemender-cli-production \
        --package=cm \
        --version=stable \
        --name=cm-linux-arm64.zip \
        --destination=./
    • curl: esegui questo comando:
      curl -L -o cm-linux-arm64.zip "https://artifactregistry.googleapis.com/download/v1/projects/cmoc-prod/locations/us/repositories/codemender-cli-production/files/cm%3Astable%3Acm-linux-arm64.zip:download?alt=media"
  2. Installa l'interfaccia a riga di comando:
    unzip cm-linux-arm64.zip
    chmod +x cm
    sudo mv cm /usr/local/bin/cm

macOS Intel

Per scaricare e installare l'interfaccia a riga di comando di CodeMender per macOS (Intel):

  1. Scarica il pacchetto utilizzando uno dei seguenti metodi:
    • gcloud CLI: esegui il seguente comando:
      gcloud artifacts generic download \
        --project=cmoc-prod \
        --location=us \
        --repository=codemender-cli-production \
        --package=cm \
        --version=stable \
        --name=cm-darwin-amd64.zip \
        --destination=./
    • curl: esegui questo comando:
      curl -L -o cm-darwin-amd64.zip "https://artifactregistry.googleapis.com/download/v1/projects/cmoc-prod/locations/us/repositories/codemender-cli-production/files/cm%3Astable%3Acm-darwin-amd64.zip:download?alt=media"
  2. Installa l'interfaccia a riga di comando:
    unzip cm-darwin-amd64.zip
    chmod +x cm
    mv cm /usr/local/bin/cm

Apple Silicon per macOS

Per scaricare e installare l'interfaccia a riga di comando di CodeMender per macOS (Apple Silicon):

  1. Scarica il pacchetto utilizzando uno dei seguenti metodi:
    • gcloud CLI: esegui il seguente comando:
      gcloud artifacts generic download \
        --project=cmoc-prod \
        --location=us \
        --repository=codemender-cli-production \
        --package=cm \
        --version=stable \
        --name=cm-darwin-arm64.zip \
        --destination=./
    • curl: esegui questo comando:
      curl -L -o cm-darwin-arm64.zip "https://artifactregistry.googleapis.com/download/v1/projects/cmoc-prod/locations/us/repositories/codemender-cli-production/files/cm%3Astable%3Acm-darwin-arm64.zip:download?alt=media"
  2. Installa l'interfaccia a riga di comando:
    unzip cm-darwin-arm64.zip
    chmod +x cm
    mv cm /usr/local/bin/cm

Windows x86_64

Per scaricare e installare l'interfaccia a riga di comando CodeMender per Windows (x86_64):

  1. Scarica il pacchetto utilizzando uno dei seguenti metodi:
    • gcloud CLI: esegui il seguente comando in PowerShell:
      gcloud artifacts generic download `
        --project=cmoc-prod `
        --location=us `
        --repository=codemender-cli-production `
        --package=cm `
        --version=stable `
        --name=cm-windows-amd64.zip `
        --destination=./
    • PowerShell: esegui questo comando:
      Invoke-WebRequest -Uri "https://artifactregistry.googleapis.com/download/v1/projects/cmoc-prod/locations/us/repositories/codemender-cli-production/files/cm%3Astable%3Acm-windows-amd64.zip:download?alt=media" -OutFile cm-windows-amd64.zip
  2. Installa l'interfaccia a riga di comando:
    Expand-Archive -Path cm-windows-amd64.zip -DestinationPath ./
    # Move cm.exe to a permanent folder and add it to your system PATH (e.g. Environmental Variables)

Windows ARM64

Per scaricare e installare l'interfaccia a riga di comando di CodeMender per Windows (ARM64):

  1. Scarica il pacchetto utilizzando uno dei seguenti metodi:
    • gcloud CLI: esegui il seguente comando in PowerShell:
      gcloud artifacts generic download `
        --project=cmoc-prod `
        --location=us `
        --repository=codemender-cli-production `
        --package=cm `
        --version=stable `
        --name=cm-windows-arm64.zip `
        --destination=./
    • PowerShell: esegui questo comando:
      Invoke-WebRequest -Uri "https://artifactregistry.googleapis.com/download/v1/projects/cmoc-prod/locations/us/repositories/codemender-cli-production/files/cm%3Astable%3Acm-windows-arm64.zip:download?alt=media" -OutFile cm-windows-arm64.zip
  2. Installa l'interfaccia a riga di comando:
    Expand-Archive -Path cm-windows-arm64.zip -DestinationPath ./
    # Move cm.exe to a permanent folder and add it to your system PATH (e.g. Environmental Variables)

Configura le credenziali e il progetto Google Cloud

Poiché l'interfaccia a riga di comando di CodeMender interagisce con il motore di ragionamento ospitato nel cloud tramite l'API Interactions, devi configurare le Google Cloud Credenziali predefinite dell'applicazione (ADC) e specificare il progetto di destinazione nel tuo ambiente.

  1. Per eseguire l'autenticazione, esegui questo comando e segui le istruzioni di accesso:

    gcloud auth application-default login
    
  2. Imposta la variabile di ambiente GOOGLE_CLOUD_PROJECT sul tuo ID progetto Google Cloud :

    export GOOGLE_CLOUD_PROJECT="PROJECT_ID"
    

    In alternativa, configura il progetto gcloud CLI attivo:

    gcloud config set project PROJECT_ID
    

    Sostituisci PROJECT_ID con l'ID progetto Google Cloud .

Inizializza il workspace

Dopo aver configurato le credenziali e il progetto di destinazione, il passaggio successivo consiste nell'inizializzare CodeMender nel tuo ambiente locale. L'inizializzazione di CodeMender prepara l'area di lavoro locale creando file di monitoraggio dello stato e stabilendo le impostazioni di connessione al motore di ragionamento ospitato nel cloud.

Esegui cm init dalla directory root del codebase per creare file di monitoraggio dello stato locale e stabilire configurazioni di base:

cm init

Utilizza il flag --verify per testare la connettività al motore di ragionamento ospitato nel cloud e verificare le impostazioni dello workspace:

cm init --verify

Controlla la connettività e le autorizzazioni del servizio

Per verificare le credenziali, la configurazione, la connettività di rete e le autorizzazioni IAM senza avviare una scansione o modificare l'area di lavoro, esegui cm health:

cm health

Il comando cm health esegue quattro controlli sequenziali e si interrompe al primo livello che non va a buon fine. Puoi eseguire cm health da qualsiasi directory, anche prima di eseguire cm init. Non scrive su disco né consuma la quota del modello.

Per i controlli preflight CI/CD automatici o il monitoraggio sintetico pianificato, utilizza --strict per generare un errore quando i controlli IAM a livello di progetto vengono ignorati e --json per generare un report JSON leggibile da macchina:

cm health --strict --json

La tabella seguente descrive i codici di uscita di cm health:

Codice di uscita incorporato Descrizione
0 — Tutti i controlli di integrità sono stati superati.
10 credentials La CLI non è riuscita ad acquisire un token OAuth o Credenziali predefinite dell'applicazione valido oppure il server ha rifiutato il token (401 Unauthorized).
20 config Il file config.yaml locale, il flag --team-id o la variabile di ambiente CM_TEAM_ID non sono validi.
30 reachability La CLI non è riuscita a raggiungere l'endpoint API Agent Platform (ad esempio, a causa di restrizioni DNS, TLS, proxy o Controlli di servizio VPC).
40 authorization Il server è stato raggiunto, ma il chiamante o il progetto non sono autorizzati a eseguire analisi CodeMender (ad esempio, mancano le autorizzazioni roles/aiplatform.user).
50 — Il controllo di integrità ha superato la durata di --timeout (valore predefinito 30s).

I seguenti flag sono supportati da cm health:

Flag Predefinito Descrizione
--json false Restituisce un singolo oggetto JSON nell'output standard, inclusi status, exit_code, backend, endpoint, location, project_id, agent_id, duration_ms, layers e (se presenti) warnings e error.
--strict false Tratta gli avvisi dei controllo di integrità (ad esempio i controlli delle autorizzazioni IAM a livello di progetto non verificati o ignorati) come errori con codice di uscita 40.
--timeout 30s Imposta il timeout complessivo per il probe del controllo di integrità.

Parametri di configurazione (config.yaml)

L'obiettivo principale di config.yaml è allineare i comportamenti dell'agente CodeMender alla sicurezza, ai vincoli dell'ambiente e alle esigenze di prestazioni del tuo sistema locale.

Poiché l'agente AI in hosting esegue comandi locali (come la creazione di codice, l'esecuzione di test o la modifica di file) utilizzando il tuo client daemon locale, questo file di configurazione funge da confine che definisce ciò che l'agente può e non può fare.

Utilizzo

  • Posizione: per impostazione predefinita, l'interfaccia a riga di comando legge questo file da ~/.codemender/config.yaml. Puoi eseguire l'override della directory del workspace e della configurazione impostando la variabile di ambiente CM_HOME (ad esempio, CM_HOME=/path/to/custom/dir, che legge /path/to/custom/dir/config.yaml).
  • Esecuzione: quando esegui comandi come cm find, cm verify o cm fix, il client locale legge questo file per configurare i parametri di sicurezza, applicare i bypass del sistema e specificare quali file o directory ignorare.

Impostazioni predefinite di base

Ecco il significato dei parametri predefiniti principali:

  • tools.confirm_commands: true

    • Cosa significa: per impostazione predefinita, CodeMender ti chiede una conferma [Y/n] nel terminale prima di eseguire i comandi della shell (run_command). Quando cm find viene eseguito con la sandbox a livello di sistema operativo abilitata (sandbox.enabled: true) e l'isolamento della rete predefinito (permissive-closed), lo spazio di lavoro viene montato in sola lettura e i prompt di conferma dei comandi vengono ignorati automaticamente.
    • Perché questa è l'impostazione predefinita: CodeMender potrebbe eseguire comandi di build, suite di test o script di exploit durante la verifica e l'applicazione di patch. Richiedere la conferma quando l'area di lavoro è scrivibile o non è in modalità sandbox aiuta a evitare l'esecuzione involontaria di comandi nell'ambiente locale.
    • Bypass: passa -y (o --yes) per una singola esecuzione o imposta tools.confirm_commands: false in config.yaml per le pipeline CI/CD non interattive.
  • tools.confirm_writes: true

    • Significato: ti chiede una conferma [Y/n] nel terminale prima che l'agente CodeMender scriva o modifichi i file sul disco (write_to_file e search_and_replace).
    • Perché questa è l'impostazione predefinita: richiedere la conferma manuale impedisce all'agente di apportare modifiche speculative o involontarie ai file di origine durante cm fix o cm verify. Imposta questo valore su false (o passa -y/--yes) solo se l'esecuzione avviene in ambienti isolati e usa e getta o in pipeline CI/CD automatizzate.
  • execution.interactive_mode: true

    • Cosa significa: attiva i prompt del terminale interattivo durante l'esecuzione dello strumento. Imposta questo valore su false (o passa -y/--yes) in ambienti CI/CD headless in cui non è collegato alcun terminale.
  • execution.duration: ""

    • Significato: imposta una durata massima predefinita del tempo di esecuzione per ogni chiamata di comando (ad esempio "15m" o "1h") in cm find, cm verify, cm fix e cm session resume. Lascia vuoto questo campo o impostalo su "0" per non avere limiti di tempo. Puoi eseguire l'override di questa impostazione con la variabile di ambiente CM_DURATION o il flag --duration (o --timeout). Quando un comando si interrompe al raggiungimento del limite di durata, salva i risultati completati ed esce con lo stato 1 se una scansione cm find --diff corrisponde a --fail-on, altrimenti con lo stato 50.
  • execution.stall_detection: false

    • Che cosa significa: se impostato su true (o se CM_STALL_DETECTION=on), interrompe una sessione dell'agente che non fa progressi nei turni consecutivi dello strumento. I comandi a sessione singola (cm find --quick, cm verify, cm fix e cm session resume a passaggio singolo) terminano con lo stato 50; nelle scansioni --deep, --diff e --parallel multisessione, una sessione bloccata viene registrata come non riuscita e la scansione continua.
  • scan.extensions.include: [".py", ".java", ".go", ".js", ".jsx", ".mjs", ".cjs", ".ts", ".tsx", ".c", ".cc", ".cpp", ".cxx", ".h", ".hh", ".hpp", ".hxx", ".inl", ".ipp", ".cs", ".rs", ".kt", ".kts", ".rb", ".php", ".sol", ".tf", ".hcl"]

    • Significato: definisce l'elenco esplicito di estensioni file che autorizzi CodeMender ad acquisire e analizzare durante la scansione del tuo workspace. CodeMender salta automaticamente tutti i file del repository con un'estensione non specificata in questo elenco.
    • Perché questa è l'impostazione predefinita: questo elenco utilizza per impostazione predefinita i principali linguaggi di programmazione per massimizzare l'efficienza della scansione ed evitare che l'agente perda tempo e token con file di testo, artefatti di build o file binari non pertinenti. Tuttavia, poiché le applicazioni moderne spesso incorporano vulnerabilità nelle configurazioni di deployment o negli strumenti di automazione, puoi espandere manualmente questo elenco predefinito in config.yaml per includere file di configurazione, formati di script e file IaC (ad esempio, script shell, XML, YAML, proprietà e file JSON) in modo che CodeMender non li ignori silenziosamente.
  • scan.exclude_dirs: ["node_modules", "vendor", "dist", "/target", "/obj", "/build", ".gradle"]

    • Cosa significa: CodeMender ignora queste directory durante la scansione del workspace e l'analisi del codice. Le voci con un / iniziale (come /target, /obj e /build) corrispondono solo alla radice dell'analisi, quindi i pacchetti di origine nidificati con questi nomi non vengono ignorati.
    • Perché questa è l'impostazione predefinita: le cartelle di dipendenza o di build di grandi dimensioni comportano una latenza elevata e una penalità dei token. Mantenere questi elementi esclusi per impostazione predefinita garantisce prestazioni elevate e tempi di risposta rapidi. Puoi personalizzare questo elenco in config.yaml per includere o escludere directory specifiche in base alla struttura del progetto.
  • project_paths: []

    • Significato: un elenco di percorsi di directory a cui CodeMender può accedere (in lettura/scrittura) durante l'esecuzione dello strumento.
    • Perché questa è l'impostazione predefinita: per impostazione predefinita, è vuoto, il che limita l'agente alla directory principale del progetto di inclusione (o alla directory di destinazione della scansione). Se il processo di build o test richiede l'accesso a file esterni alla directory principale del progetto, aggiungi i percorsi qui o passa --allow-all-paths per una singola esecuzione. Le scritture su .git, .hg e .codemender sono sempre bloccate.
    • Directory degli artefatti: l'agente può anche scrivere in una directory degli artefatti per sessione (~/.codemender/artifacts/<session_id>/ o l'equivalente in $CM_HOME).
    • File temporanei: quando la sandbox è attiva, la directory host /tmp è sempre bloccata, anche se aggiungi /tmp a project_paths. Gli strumenti che rispettano TMPDIR utilizzano invece una directory temporanea all'interno della directory degli artefatti.
  • sandbox:

    • Significato: blocco di configurazione per l'ambiente sandbox a livello di processo.
    • Sottoparametri:
      • enabled: true: (booleano) attiva o disattiva la sandbox. Se imposti questo valore su true (predefinito), l'agente esegue gli strumenti all'interno della sandbox locale. Se lo imposti su false (o passi --sandbox=false), l'agente esegue gli strumenti direttamente sul sistema host senza isolamento a livello di sistema operativo.
      • mounts: (oggetto)
        • target_dir: ".": (String) La directory da montare come area di lavoro attiva all'interno della sandbox. L'interfaccia a riga di comando risolve i percorsi relativi rispetto alla directory principale dell'area di lavoro.
      • network: (oggetto)
        • profile: "permissive-closed": (stringa) profilo di accesso alla rete in uscita all'interno della sandbox. La lista consentita granulare di domini o pattern URL specifici non è ancora supportata. Profili supportati:
          • permissive-closed (predefinito): isolamento completo della rete; la sandbox blocca tutte le connessioni in uscita.
          • permissive-open: consente l'accesso completo alla rete in uscita.
  • security:

    • Cosa significa: blocco di configurazione per le policy di sicurezza.
    • Sottoparametri:
      • protected_files: []: (elenco di stringhe) file o directory aggiuntivi sul sistema host che vuoi montare in sola lettura all'interno della sandbox per proteggerli da modifiche. Supporta l'espansione del percorso (~) e i caratteri jolly (*). Anche quando protected_files è vuoto, la sandbox protegge sempre .git/hooks, .git/config, .hg/hgrc e .codemender come di sola lettura ed esclude le directory delle credenziali comuni (~/.ssh, ~/.gnupg, ~/.aws, ~/.config/gcloud, ~/.config/gh, ~/.kube, ~/.docker).
  • Modello: config.yaml non imposta il modello. Per scegliere un modello, passa --model a cm find, cm verify o cm fix. Per i modelli supportati e il modello predefinito, consulta Specifica del modello.

  • vcs: { type: "git" }

    • Significato: definisce il tipo di sistema di controllo della versione utilizzato dal progetto tramite la chiave vcs. Se non configuri questa opzione, lo strumento tenta di identificare automaticamente i repository Git o Mercurial. Se imposti vcs su none, l'interfaccia a riga di comando genera un avviso, ma continua l'esecuzione senza la funzionalità VCS. CodeMender si basa su questa impostazione per gestire le correzioni di sicurezza speculative, monitorare le modifiche alla codebase e integrarsi con il tuo repository locale.
    • Perché questa è l'impostazione predefinita: CodeMender supporta le configurazioni Git, Mercurial o VCS personalizzate. Git è l'opzione predefinita in quanto è lo standard di settore per il monitoraggio del controllo della versione, garantendo un'integrazione perfetta delle differenze e la sicurezza del rollback.
  • build: { command: "make build && make test" }

    • Cosa significa: definisce il comando shell esatto che CodeMender esegue per compilare e creare il progetto, nonché per eseguire i test delle unità e di regressione.
    • Perché questa è l'impostazione predefinita: l'impostazione di un comando di build e test è fondamentale per il workflow di verifica. Consente a CodeMender di compilare il progetto ed eseguire la suite di test esistente nell'ambiente sandbox isolato per verificare che la patch di sicurezza generata riduca correttamente la vulnerabilità senza interrompere la logica dell'applicazione esistente.

Richieste di conferma

CodeMender chiede conferma prima di eseguire un comando della shell (tools.confirm_commands) e prima di scrivere un file (tools.confirm_writes). Le due impostazioni sono indipendenti e il valore predefinito per entrambe è true. Le seguenti impostazioni disattivano questi prompt, in ordine di precedenza:

  1. -y o --yes: approva tutti i prompt di comando e di scrittura dei file per un'esecuzione, indipendentemente da ciò che dice config.yaml.
  2. execution.interactive_mode: false in config.yaml: disattiva i prompt dei comandi e di scrittura dei file per ogni esecuzione.
  3. tools.confirm_commands: false o tools.confirm_writes: false in config.yaml: disattiva i prompt dei comandi o i prompt di scrittura dei file per ogni esecuzione, indipendentemente l'uno dall'altro.

Se nessuna di queste impostazioni è applicabile e nessuno può rispondere al prompt, ad esempio in un job CI/CD senza terminale, CodeMender non esegue il comando né scrive il file.

Oltre a questi prompt, l'interfaccia a riga di comando ti avvisa che l'agente può modificare i file ed eseguire comandi sul tuo sistema e ti chiede di confermare l'avviso. -y non ignora questo avviso. Per saltarlo, passa --bypass-warning. In un ambiente non interattivo senza --bypass-warning, cm non va a buon fine con warning not acknowledged. cm find ignora l'avviso quando la sandbox è attivata con il profilo di rete permissive-closed predefinito.

Policy dei comandi (command_policy.yaml)

Oltre alla sandbox a livello di sistema operativo, puoi definire una lista bloccata di comandi in ~/.codemender/command_policy.yaml (globale) e <project>/.codemender/command_policy.yaml (specifico per il progetto). Quando sono presenti entrambi i file, CodeMender unisce le relative regole.

Alla prima esecuzione, CodeMender crea un template commentato in ~/.codemender/command_policy.yaml. Puoi rimuovere il commento o aggiungere regole in due chiavi:

  • block: un elenco di nomi binari da bloccare in tutte le pipeline della shell, le subshell e le sostituzioni dei comandi (ad esempio curl, wget, ssh, sudo, rm).
  • block_patterns: un elenco di espressioni regolari corrispondenti a ogni segmento di comando (ad esempio, '\bgit\s+(push|commit|rebase|reset\s+--hard|clean)\b').

Per bypassare l'applicazione di command_policy.yaml per una singola chiamata di comando, passa il flag --allow-all-commands.

  • output: { plain: false }
    • Significato: controlla se l'interfaccia a riga di comando di CodeMender sostituisce emoji, simboli Unicode e colori del terminale con testo ASCII nell'output dell'interfaccia a riga di comando e nei report formattati.
    • Perché questa è l'impostazione predefinita: lo stile avanzato del terminale e le icone di stato semplificano l'analisi delle scansioni interattive e dei report esportati. Imposta plain su true per i log CI/CD, gli screen reader o i terminali minimi. Per le regole di precedenza e gli override dei flag, consulta Configura l'output di testo normale.

Sandboxing dell'esecuzione

Per proteggere la tua workstation da modifiche involontarie ai file o da effetti collaterali imprevisti degli strumenti, l'interfaccia a riga di comando di CodeMender viene eseguita per impostazione predefinita all'interno di una sandbox a livello di sistema operativo. Puoi disattivare il sandboxing in modo permanente nella configurazione o bypassarlo per ogni comando utilizzando i flag dell'interfaccia a riga di comando.

Google fornisce la sandbox CodeMender come funzionalità di sicurezza consigliata. L'esecuzione di CodeMender al di fuori di un ambiente sandbox è a rischio del Cliente ai sensi della Sezione 20(j) dei Termini di servizio specifici.

Sebbene questo sandboxing offra un livello iniziale di difesa sulla tua workstation, offre una protezione di sicurezza più debole rispetto all'esecuzione dell'agente in una macchina virtuale (VM) completamente isolata:

  • Linux: utilizza gli spazi dei nomi del kernel (CLONE_NEWNS, CLONE_NEWUSER e così via) e i filtri seccomp per isolare i punti di montaggio e limitare le chiamate di sistema.
  • macOS: utilizza il meccanismo sandbox-exec (Seatbelt) integrato.
  • Windows (sperimentale): utilizza l'isolamento AppContainer e gli elenchi di controllo dell'accesso (ACL). Il sandboxing su Windows è sperimentale e potrebbe richiedere privilegi amministrativi o essere incompatibile con alcune configurazioni di sistema.

Comportamento della sandbox

Quando la sandbox è attiva:

  1. Isolamento del file system: l'agente può accedere solo ai file all'interno delle directory consentite. Durante cm find, lo spazio di lavoro e le radici consentite vengono montati in sola lettura, quindi i comandi possono scrivere solo nella directory degli artefatti per sessione. In tutti i comandi (inclusi cm verify e cm fix), .git/hooks, .git/config, .hg/hgrc e .codemender sono montati in sola lettura, in modo che i comandi in sandbox non possano installare hook Git o Mercurial o modificare la configurazione di CodeMender.
  2. Isolamento della rete: la sandbox blocca l'accesso alla rete in uscita per impostazione predefinita (sandbox.network.profile: "permissive-closed"). In questo modo, l'agente (o gli strumenti di build che richiama) non può stabilire connessioni esterne impreviste o trasmettere dati al di fuori del workspace.
  3. Isolamento di credenziali e secret: la sandbox esclude le directory delle credenziali host comuni (~/.ssh, ~/.gnupg, ~/.aws, ~/.config/gcloud, ~/.config/gh, ~/.kube, ~/.docker e altre) e rimuove le variabili di ambiente corrispondenti ai pattern dei secret (*_TOKEN, *_SECRET, *_KEY, *_PASSWORD, *_CREDENTIALS e suffissi simili) prima di eseguire i comandi.

Accesso alla rete durante la creazione e la convalida

Poiché la sandbox attiva l'isolamento della rete per impostazione predefinita (sandbox.network.profile è impostato su permissive-closed per impostazione predefinita), l'agente non può accedere a internet durante l'esecuzione dello strumento.

Questo introduce limitazioni per i progetti che richiedono il recupero di dipendenze esterne durante i passaggi di build o verifica (ad esempio, l'esecuzione di npm install, pip install o go get come parte di build.command). Se il processo di compilazione tenta di accedere a servizi web esterni, non andrà a buon fine.

Gestione delle dipendenze di rete

Se il tuo progetto richiede l'accesso alla rete per build o test, hai le seguenti opzioni:

  • Precaricamento delle dipendenze: installa tutte le dipendenze richieste sul sistema host prima di eseguire i comandi cm, in modo che il comando di build non richieda l'accesso alla rete.
  • Attiva l'accesso alla rete nella sandbox: modifica il profilo di rete in config.yaml per consentire le connessioni in uscita:

    sandbox:
      network:
        profile: "permissive-open"
    
  • Disattiva la sandbox per un'esecuzione: esegui il comando con il flag --sandbox=false per disattivare la sandbox a livello di sistema operativo (incluso l'isolamento della rete) per l'esecuzione.

Configurazione della sandbox

Puoi configurare e controllare la sandbox e i confini di sicurezza utilizzando le seguenti opzioni:

  • Configurazione persistente (config.yaml e command_policy.yaml): personalizza il comportamento della sandbox, i montaggi del file system, l'accesso alla rete e le liste bloccate dei comandi in config.yaml e command_policy.yaml. Per maggiori dettagli, consulta Parametri di configurazione e Policy dei comandi.
  • Controlla la sandbox a livello di sistema operativo (--sandbox): attiva o disattiva esplicitamente la sandbox a livello di sistema operativo per una singola esecuzione passando --sandbox=true o --sandbox=false a cm find, cm verify, cm fix o cm session resume.
  • Ignora i limiti del percorso (--allow-all-paths): disattiva il controllo dei limiti del percorso dell'area di lavoro per una singola esecuzione, in modo che gli strumenti dell'agente possano accedere ai percorsi al di fuori della directory principale del progetto e del project_paths configurato (combina con --sandbox=false per accedere ai percorsi dell'host che non sono montati all'interno della sandbox).
  • Bypass command policy (--allow-all-commands): disattiva l'applicazione della lista bloccata command_policy.yaml per una singola esecuzione.

Scelta di un livello di isolamento

A seconda dei requisiti di sicurezza e dell'ambiente di sviluppo, puoi scegliere il livello di isolamento appropriato per l'esecuzione dell'interfaccia a riga di comando di CodeMender.

Metodo Descrizione Vantaggi Svantaggi
Sandbox integrata (a livello di sistema operativo) Attivato per impostazione predefinita; puoi disattivarlo nel file config.yaml o ignorarlo utilizzando i flag dell'interfaccia a riga di comando. Utilizza le funzionalità integrate del sistema operativo (spazi dei nomi/seccomp, sandbox-exec, AppContainer (sperimentale)) per isolare l'esecuzione. Leggero; overhead di avvio pari a zero; accesso diretto agli strumenti dell'area di lavoro locale con controllo granulare. Consigliata per lo sviluppo locale quotidiano. La sicurezza si basa sulle funzionalità del kernel del sistema operativo; meno isolato rispetto a una VM completa; il supporto di Windows è sperimentale e potrebbe richiedere privilegi amministrativi o essere incompatibile con alcune configurazioni.
Container Esecuzione dell'agente in un container (ad esempio Docker). Buon isolamento; ambiente standardizzato. Richiede il runtime del container; può essere pesante; non consente l'interazione diretta con gli strumenti sulla macchina locale.
VM complete Esecuzione dell'agente in una VM dedicata. Massima sicurezza; isolamento completo. Overhead elevato delle risorse; avvio lento; non consente l'interazione diretta con gli strumenti sulla macchina locale.

Configura l'output di testo normale

Per impostazione predefinita, l'interfaccia a riga di comando di CodeMender utilizza emoji, simboli Unicode e colori del terminale nell'output interattivo e nei report formattati. Per utilizzare l'output solo ASCII nei log CI/CD, negli screen reader o nei terminali minimi, attiva la modalità testo normale. L'interfaccia a riga di comando di CodeMender controlla queste impostazioni dalla precedenza più alta alla più bassa:

  1. Passa il flag --plain a qualsiasi comando cm per una singola esecuzione o passa --plain=false per eseguire l'override delle impostazioni di ambiente e configurazione:

    cm --plain find .
    
  2. Imposta la variabile di ambiente CM_PLAIN su true o 1 per attivare l'output di testo normale per tutti i comandi o su false o 0 per disattivarlo:

    export CM_PLAIN=true
    
  3. Imposta output.plain su true nel file ~/.codemender/config.yaml:

    output:
      plain: true
    
  4. Esegui una sessione interattiva in un terminale in cui TERM=dumb, che attiva automaticamente l'output di testo normale.

La modalità testo normale sostituisce le emoji di stato con tag ASCII come [OK], [INFO], [WARN], [ERROR], [PASS] e [FAIL]. CodeMender disattiva anche gli spinner animati e le riscritture delle righe in loco, oltre a eseguire il rendering dei bordi delle tabelle ASCII. In cm report, la modalità testo normale rimuove le emoji dell'interfaccia utente dai formati table, md e html senza modificare l'output o le differenze di codice di json o sarif.

I file reindirizzati e gli stream CI/CD non interattivi mantengono plain impostato su false per impostazione predefinita, in modo che i report Markdown e HTML esportati conservino le icone di stato. Per rimuovere emoji e simboli Unicode nei log CI/CD, imposta CM_PLAIN=true, passa --plain o imposta output.plain: true. I caratteri di escape dei colori del terminale vengono omessi automaticamente negli stream non interattivi e quando imposti la variabile di ambiente NO_COLOR.

Telemetria

Per aiutarci a monitorare e migliorare l'integrità del prodotto, l'interfaccia a riga di comando invia dati di telemetria sull'utilizzo a Google: un evento quando un comando viene avviato, un evento quando viene chiuso e un evento per ogni errore segnalato. Quando l'interfaccia a riga di comando è in grado di determinarli, gli eventi identificano l'Account Google o il account di servizio che esegue l'interfaccia a riga di comando e il progetto Google Cloud che utilizza.

Gli eventi di telemetria possono contenere quanto segue:

  • L'ID account del tuo Account Google o del account di servizio, l'ID progetto Google Cloud e l'ID team, se ne hai impostato uno.
  • Un ID casuale per ogni comando, il nome del comando, l'ID sessione del server, il modello selezionato e la versione dell'interfaccia a riga di comando.
  • La famiglia, la piattaforma e la versione del sistema operativo.
  • Se la sandbox è attiva e se -y (--yes) è impostato per ignorare i prompt di conferma.
  • All'uscita: la durata, il codice di uscita e il risultato; i conteggi dei token; il numero di righe, file e byte scansionati e i linguaggi rilevati; e il numero di risultati per gravità o il risultato di una verifica o di una correzione.
  • In caso di errore: la categoria e il motivo dell'errore e un'analisi dello stack del codice dell'interfaccia a riga di comando.

La telemetria non contiene codice sorgente, contenuti dei file, percorsi dei file, prompt, risultati, patch o testo dei messaggi di errore. La CLI invia i dati di telemetria a un endpoint Google globale. La telemetria è costituita da dati di servizio, come descritto nell'Informativa sulla privacy diGoogle Cloud .

Per impostazione predefinita, la telemetria è abilitata. Se vuoi disattivare la telemetria, imposta la variabile di ambiente CM_TELEMETRY_OPT_OUT su 1 o true.

Aggiornamento della CLI

CodeMender dispone di un meccanismo di aggiornamento integrato per aiutarti a mantenere la CLI aggiornata all'ultima versione.

Controlli degli aggiornamenti automatici

Per impostazione predefinita, l'interfaccia a riga di comando di CodeMender controlla automaticamente la presenza di aggiornamenti in background quando esegui i comandi:

  • Limitazione: per ridurre al minimo l'overhead, il controllo automatico viene eseguito al massimo una volta ogni 24 ore.
  • Terminale interattivo (TTY) obbligatorio: l'interfaccia a riga di comando controlla la presenza di aggiornamenti e ti chiede di eseguirli solo quando è in esecuzione in un terminale interattivo. In ambienti non interattivi (come pipeline o script CI/CD), il controllo viene saltato e viene registrato un avviso in stderr al massimo una volta al giorno.
  • Prompt: se è disponibile una nuova versione, ti verrà chiesto di confermare su stderr: none 🆕 A new CodeMender release is available: 1.1.0 Update now? (y/N): Se scegli di sì (y o yes), CodeMender scarica l'aggiornamento, sostituisce il file binario ed esce. Devi eseguire nuovamente il comando per eseguirlo con la nuova versione. Se scegli No, l'aggiornamento viene saltato e viene eseguito il comando originale.
  • Tolleranza offline: se sei offline o il repository della release non è raggiungibile, il controllo non va a buon fine senza messaggi e CodeMender continua a eseguire il comando.
  • Bypass: puoi bypassare il controllo degli aggiornamenti automatici passando il flag --yes o -y a qualsiasi comando.

Aggiornamenti manuali (cm update)

Puoi forzare CodeMender a verificare e applicare immediatamente gli aggiornamenti eseguendo il comando update:

cm update

Il comando cm update:

  • Ignora la limitazione di 24 ore.
  • Scarica e applica l'aggiornamento immediatamente senza chiedere conferma (non interattivo).
  • Non richiede un terminale interattivo (sicuro per gli script e la gestione delle configurazioni).

Se l'interfaccia a riga di comando è installata in una directory di sistema che richiede autorizzazioni elevate, esegui l'aggiornamento con sudo:

sudo cm update