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
cmesegue 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:
- API Agent Platform (
aiplatform.googleapis.com): gestisce lo streaming e la gestione delle sessioni attive. - API Cloud Resource Manager (
cloudresourcemanager.googleapis.com): convalida gli stati di autenticazione degli utenti e i metadati dei progetti.
Ruolo IAM predefinito consigliato
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):
- 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"
- gcloud CLI: esegui il seguente comando:
- 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):
- 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"
- gcloud CLI: esegui il seguente comando:
- 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):
- 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"
- gcloud CLI: esegui il seguente comando:
- 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):
- 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"
- gcloud CLI: esegui il seguente comando:
- 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):
- 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
- gcloud CLI: esegui il seguente comando in PowerShell:
- 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):
- 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
- gcloud CLI: esegui il seguente comando in PowerShell:
- 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.
Per eseguire l'autenticazione, esegui questo comando e segui le istruzioni di accesso:
gcloud auth application-default loginImposta la variabile di ambiente
GOOGLE_CLOUD_PROJECTsul tuo ID progetto Google Cloud :export GOOGLE_CLOUD_PROJECT="PROJECT_ID"In alternativa, configura il progetto gcloud CLI attivo:
gcloud config set project PROJECT_IDSostituisci
PROJECT_IDcon 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 ambienteCM_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 verifyocm 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). Quandocm findviene 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 impostatools.confirm_commands: falseinconfig.yamlper le pipeline CI/CD non interattive.
- Cosa significa: per impostazione predefinita, CodeMender ti chiede una conferma
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_fileesearch_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 fixocm verify. Imposta questo valore sufalse(o passa-y/--yes) solo se l'esecuzione avviene in ambienti isolati e usa e getta o in pipeline CI/CD automatizzate.
- Significato: ti chiede una conferma
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.
- Cosa significa: attiva i prompt del terminale interattivo durante l'esecuzione dello strumento. Imposta questo valore su
execution.duration: ""- Significato: imposta una durata massima predefinita del tempo di esecuzione per ogni chiamata di comando (ad esempio
"15m"o"1h") incm find,cm verify,cm fixecm 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 ambienteCM_DURATIONo il flag--duration(o--timeout). Quando un comando si interrompe al raggiungimento del limite di durata, salva i risultati completati ed esce con lo stato1se una scansionecm find --diffcorrisponde a--fail-on, altrimenti con lo stato50.
- Significato: imposta una durata massima predefinita del tempo di esecuzione per ogni chiamata di comando (ad esempio
execution.stall_detection: false- Che cosa significa: se impostato su
true(o seCM_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 fixecm session resumea passaggio singolo) terminano con lo stato50; nelle scansioni--deep,--diffe--parallelmultisessione, una sessione bloccata viene registrata come non riuscita e la scansione continua.
- Che cosa significa: se impostato su
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.yamlper 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,/obje/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.yamlper includere o escludere directory specifiche in base alla struttura del progetto.
- Cosa significa: CodeMender ignora queste directory durante la scansione del workspace e l'analisi del codice. Le voci con un
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-pathsper una singola esecuzione. Le scritture su.git,.hge.codemendersono 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/tmpaproject_paths. Gli strumenti che rispettanoTMPDIRutilizzano 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 sutrue(predefinito), l'agente esegue gli strumenti all'interno della sandbox locale. Se lo imposti sufalse(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 quandoprotected_filesè vuoto, la sandbox protegge sempre.git/hooks,.git/config,.hg/hgrce.codemendercome di sola lettura ed esclude le directory delle credenziali comuni (~/.ssh,~/.gnupg,~/.aws,~/.config/gcloud,~/.config/gh,~/.kube,~/.docker).
Modello:
config.yamlnon imposta il modello. Per scegliere un modello, passa--modelacm find,cm verifyocm 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 impostivcssunone, 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.
- Significato: definisce il tipo di sistema di controllo della versione utilizzato dal progetto tramite la chiave
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:
-yo--yes: approva tutti i prompt di comando e di scrittura dei file per un'esecuzione, indipendentemente da ciò che diceconfig.yaml.execution.interactive_mode: falseinconfig.yaml: disattiva i prompt dei comandi e di scrittura dei file per ogni esecuzione.tools.confirm_commands: falseotools.confirm_writes: falseinconfig.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 esempiocurl,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
plainsutrueper 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_NEWUSERe così via) e i filtriseccompper isolare i punti di montaggio e limitare le chiamate di sistema. - macOS: utilizza il meccanismo
sandbox-exec(Seatbelt) integrato. - Windows (sperimentale): utilizza l'isolamento
AppContainere 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:
- 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 (inclusicm verifyecm fix),.git/hooks,.git/config,.hg/hgrce.codemendersono montati in sola lettura, in modo che i comandi in sandbox non possano installare hook Git o Mercurial o modificare la configurazione di CodeMender. - 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. - Isolamento di credenziali e secret: la sandbox esclude le directory delle credenziali host comuni (
~/.ssh,~/.gnupg,~/.aws,~/.config/gcloud,~/.config/gh,~/.kube,~/.dockere altre) e rimuove le variabili di ambiente corrispondenti ai pattern dei secret (*_TOKEN,*_SECRET,*_KEY,*_PASSWORD,*_CREDENTIALSe 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.yamlper consentire le connessioni in uscita:sandbox: network: profile: "permissive-open"Disattiva la sandbox per un'esecuzione: esegui il comando con il flag
--sandbox=falseper 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.yamlecommand_policy.yaml): personalizza il comportamento della sandbox, i montaggi del file system, l'accesso alla rete e le liste bloccate dei comandi inconfig.yamlecommand_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=trueo--sandbox=falseacm find,cm verify,cm fixocm 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 delproject_pathsconfigurato (combina con--sandbox=falseper accedere ai percorsi dell'host che non sono montati all'interno della sandbox). - Bypass command policy (
--allow-all-commands): disattiva l'applicazione della lista bloccatacommand_policy.yamlper 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:
Passa il flag
--plaina qualsiasi comandocmper una singola esecuzione o passa--plain=falseper eseguire l'override delle impostazioni di ambiente e configurazione:cm --plain find .Imposta la variabile di ambiente
CM_PLAINsutrueo1per attivare l'output di testo normale per tutti i comandi o sufalseo0per disattivarlo:export CM_PLAIN=trueImposta
output.plainsutruenel file~/.codemender/config.yaml:output: plain: trueEsegui 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
stderral 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ì (yoyes), 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
--yeso-ya 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