CodeMender è un agente autonomo di sicurezza del codice basato sull'AI che esegue la scansione, la verifica e l'applicazione di patch per le vulnerabilità di cybersicurezza profonde nel tuo codebase. Prima di eseguire CodeMender, scarica la CLI e inizializza le opzioni dello spazio di lavoro.
Architettura e modello di sicurezza
CodeMender utilizza un modello di esecuzione locale:
- Motore di ragionamento ospitato: la logica di ragionamento, modellazione delle minacce e orchestrazione degli agenti viene eseguita in modo sicuro in Google Cloud su Gemini Enterprise Agent Platform.
- CLI di esecuzione locale: il codice sorgente non viene mai trasferito in blocco dalla workstation o dal container CI/CD. Lo strumento a riga di comando locale
cmesegue letture di file, controlli di build locali e verifiche di exploit proof-of-concept (PoC) nel tuo sandbox locale, inviando solo snippet di codice chirurgici e risultati di esecuzione dello strumento al backend cloud tramite l'API Interactions sulla piattaforma Gemini Enterprise Agent.
Configurazione dell'ambiente
Per iniziare a utilizzare CodeMender, configura il tuo progetto Google Cloud , scarica e installa la CLI, configura le tue credenziali e inizializza il tuo workspace.
Configurazione del progetto e autorizzazioni IAM
Prima di scaricare la CLI 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 Vertex AI (
aiplatform.googleapis.com): gestisce lo streaming e la gestione delle sessioni attive. - API Cloud Resource Manager (
cloudresourcemanager.googleapis.com): convalida gli stati di autenticazione utente e i metadati del progetto.
Ruolo IAM predefinito consigliato
Per eseguire i comandi della CLI, agli utenti deve essere assegnato il seguente ruolo IAM:
- Utente Vertex AI (
roles/aiplatform.user): consente agli utenti di creare, trasmettere in streaming e gestire sessioni attive.
Scaricare e installare CodeMender CLI
I file binari della CLI CodeMender sono ospitati in Artifact Registry. Scegli la scheda del tuo sistema operativo per scaricare e installare la CLI.
Linux x86_64
Per scaricare e installare CodeMender CLI per Linux (x86_64):
- Scarica il pacchetto utilizzando uno dei seguenti metodi:
- gcloud CLI: esegui questo 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 questo 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 CodeMender CLI per Linux (ARM64):
- Scarica il pacchetto utilizzando uno dei seguenti metodi:
- gcloud CLI: esegui questo 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 questo 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 CodeMender CLI per macOS (Intel):
- Scarica il pacchetto utilizzando uno dei seguenti metodi:
- gcloud CLI: esegui questo 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 questo comando:
- Installa l'interfaccia a riga di comando:
unzip cm-darwin-amd64.zip chmod +x cm mv cm /usr/local/bin/cm
macOS Apple Silicon
Per scaricare e installare CodeMender CLI per macOS (Apple Silicon):
- Scarica il pacchetto utilizzando uno dei seguenti metodi:
- gcloud CLI: esegui questo 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 questo 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 CodeMender CLI 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 CodeMender CLI 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)
Configurare le credenziali di Google Cloud
Poiché la CLI CodeMender interagisce con il motore di ragionamento ospitato sul cloud tramite l'API Interactions, devi configurare le Google Cloud credenziali predefinite dell'applicazione (ADC) nel tuo ambiente.
Per eseguire l'autenticazione, esegui questo comando e segui le istruzioni di accesso:
gcloud auth application-default login
Inizializza il workspace
Una volta eseguita l'autenticazione, il passaggio successivo consiste nell'inizializzare CodeMender nell'ambiente locale. L'inizializzazione di CodeMender prepara lo spazio di lavoro locale creando file di monitoraggio dello stato e stabilendo le impostazioni di connessione al motore di ragionamento ospitato sul cloud.
Esegui cm init dalla directory principale 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 sul cloud e verificare le impostazioni dello spazio di lavoro:
cm init --verify
Parametri di configurazione (config.yaml)
L'obiettivo principale di config.yaml è allineare i comportamenti dell'agente CodeMender ai requisiti di sicurezza, ai vincoli ambientali e alle esigenze di prestazioni del tuo sistema locale.
Poiché l'agente AI ospitato esegue comandi locali (come la creazione di codice, l'esecuzione di test o la modifica di file) utilizzando il client daemon locale, questo file di configurazione funge da limite che definisce cosa può e non può fare l'agente.
Utilizzo
- Posizione:per impostazione predefinita, la CLI cerca questo file nell'area di lavoro inizializzata (di solito
.codemender/config.yamlo una directory di configurazione globale come~/.config/codemender/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 i file o le directory da ignorare.
Impostazioni predefinite di base
Ecco il significato dei parametri predefiniti principali:
human_confirmation: true(orequire_confirmation: true)- Che cosa significa:per impostazione predefinita, CodeMender non può modificare alcun file sul disco o eseguire comandi shell senza chiederti esplicitamente una
[Y/n]conferma nel terminale. - Perché questa è l'impostazione predefinita: CodeMender potrebbe generare patch speculative o tentare di eseguire script di exploit per verificare una vulnerabilità. L'applicazione della conferma umana contribuisce a evitare modifiche accidentali del sistema o l'esecuzione di codice non autorizzato nell'ambiente locale.
- Bypass:per le pipeline CI/CD non interattive, questo valore può essere impostato su
false.
- Che cosa significa:per impostazione predefinita, CodeMender non può modificare alcun file sul disco o eseguire comandi shell senza chiederti esplicitamente una
confirm_writes: false- Che cosa significa: disabilita i prompt interattivi per le modifiche ai file, consentendo all'agente CodeMender di scrivere patch di sicurezza e modificare i file di origine direttamente sul disco locale senza attendere l'approvazione umana.
- Perché questo è il valore predefinito:per impostazione predefinita, CodeMender imposta questa protezione su
trueper applicare un flusso di lavoro "Human-in-the-Loop". Poiché CodeMender agisce sul tuo codebase locale, richiedere la conferma manuale (ad esempioWrite? [Y/n]) impedisce all'agente di apportare modifiche speculative, errate o distruttive ai tuoi file sorgente. Devi impostare questo valore sufalsesolo quando esegui l'applicazione in sandbox isolate e temporanee o in pipeline CI/CD automatizzate e headless.
include: [".py", ".java", ".go", ".js", ".ts", ".c", ".cc", ".cpp", ".h", ".rb", ".php"]- Significato:definisce l'elenco esplicito delle estensioni dei file che autorizzi CodeMender a importare e analizzare durante la scansione del tuo workspace. CodeMender ignora automaticamente qualsiasi file nel repository con un'estensione non specificata in questo elenco.
- Perché questa è l'impostazione predefinita:questo elenco include per impostazione predefinita i principali linguaggi di programmazione per massimizzare l'efficienza della scansione e impedire all'agente di sprecare tempo e token su file di testo, artefatti di build o file binari irrilevanti. Tuttavia, poiché le applicazioni moderne spesso incorporano vulnerabilità nelle configurazioni di deployment o negli strumenti di automazione, ti consigliamo vivamente di espandere manualmente questo elenco predefinito per includere file di configurazione, formati di script e file IaC (ad esempio script shell, file XML, YAML, properties e JSON) in modo che CodeMender non li ignori automaticamente.
exclude_paths: ["node_modules", "vendor", "dist", "bin"]- Che cosa significa:CodeMender ignorerà completamente queste directory durante la scansione dello spazio di lavoro e l'analisi del codice.
- Perché questa è l'impostazione predefinita: le cartelle di build o di dipendenze di grandi dimensioni attivano una latenza e una penalità di token massicce. La loro esclusione predefinita garantisce prestazioni elevate e tempi di risposta rapidi.
project_paths: []- Significato:un elenco di percorsi di directory a cui CodeMender può accedere (lettura/scrittura) durante l'esecuzione dello strumento.
- Perché è il valore predefinito:per impostazione predefinita, è vuoto, il che limita l'agente alla directory di destinazione della scansione, alla directory dello spazio di lavoro
.codemendere a/tmp. Se la procedura di build o test richiede l'accesso a file al di fuori di queste directory, devi aggiungere qui i relativi percorsi.
sandbox:- Che cosa significa:blocco di configurazione per l'ambiente sandbox a livello di processo.
- Parametri secondari:
enabled: true: (booleano) attiva o disattiva la sandbox. Se imposti questo valore sutrue(impostazione predefinita), l'agente esegue gli strumenti all'interno della sandbox locale. Se lo imposti sufalse, l'agente esegue gli strumenti direttamente sul sistema host senza isolamento.mounts: (Object)target_dir: ".": (stringa) La directory da montare come spazio di lavoro attivo all'interno della sandbox. La CLI risolve i percorsi relativi rispetto alla radice dello spazio di lavoro.
network: (Object)profile: "permissive-closed": (stringa) Profilo di accesso alla rete in uscita all'interno della sandbox. L'inserimento nella lista consentita granulare di domini o pattern URL specifici non è ancora supportato. Profili supportati:permissive-closed(impostazione predefinita): 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.
- Parametri secondari:
protected_files: []: (elenco di stringhe) file o directory sul sistema host che vuoi montare in sola lettura all'interno della sandbox per proteggerli da modifiche (ad es.["~/.ssh/*"]). Supporta l'espansione del percorso (~) e i caratteri jolly (*).
model: "gemini-3.5-flash"- Che cosa significa:il motore di intelligence predefinito che alimenta i cicli di ragionamento del backend.
- Perché è l'impostazione predefinita:
gemini-3.5-flashoffre il giusto equilibrio tra velocità, costi e ragionamento analitico necessario per suggerire le patch. Gli utenti possono ignorare questa impostazione e impostaregemini-3.1-proper un ragionamento più approfondito e complesso, se necessario.
vcs: { type: "git" }- Significato:definisce il tipo di sistema di controllo delle versioni utilizzato dal progetto tramite la chiave
vcs. Se non lo configuri, lo strumento tenta di identificare automaticamente i repository Git o Mercurial. Se impostivcssunone, la CLI restituisce 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 al codebase e integrarsi con il repository locale. - Perché questa è l'impostazione predefinita: CodeMender supporta Git, Mercurial o configurazioni VCS personalizzate. Git è l'impostazione predefinita in quanto è lo standard di settore per il monitoraggio del controllo della versione, garantendo un'integrazione differenziale e un rollback sicuri.
- Significato:definisce il tipo di sistema di controllo delle versioni utilizzato dal progetto tramite la chiave
build: { command: "make build && make test" }- Che 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 flusso di lavoro di verifica. Consente a CodeMender di compilare il progetto ed eseguire la suite di test esistente nell'ambiente sandbox isolato per dimostrare che la patch di sicurezza generata mitiga correttamente la vulnerabilità senza interrompere la logica dell'applicazione esistente.
Limitazione tramite sandbox dell'esecuzione
Per proteggere la workstation da modifiche involontarie ai file o da effetti collaterali imprevisti degli strumenti, la CLI 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 ignorarlo per comando utilizzando i flag della CLI.
Anche se questo sandboxing offre un livello iniziale di difesa sulla 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ò leggere e scrivere file solo all'interno delle directory consentite. La sandbox reindirizza qualsiasi scrittura al di fuori di queste directory a un file system temporaneo in memoria (tmpfs) senza influire sul sistema host.
- Isolamento di rete: per impostazione predefinita, la sandbox blocca l'accesso alla rete in uscita. In questo modo, l'agente (o gli strumenti di compilazione che richiama) non può effettuare connessioni esterne impreviste o trasmettere dati al di fuori dello spazio di lavoro.
Accesso alla rete durante la creazione e la convalida
Poiché la sandbox attiva l'isolamento di 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.
Ciò introduce limitazioni per i progetti che richiedono il recupero di dipendenze esterne durante i passaggi di compilazione o verifica (ad esempio, l'esecuzione di npm install, pip install o go get nell'ambito 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 le build o i 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 compilazione 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"Ignora la sandbox: esegui il comando con il flag
--unrestrictedper disattivare completamente la sandbox e i limiti del file system per l'esecuzione.
Configurazione della sandbox
Puoi configurare e controllare la sandbox utilizzando le seguenti opzioni:
- Configurazione persistente (
config.yaml): puoi personalizzare il comportamento della sandbox, i montaggi del file system, l'accesso alla rete e le norme di sicurezza aggiungendo i blocchisandbox,executionesecurityal fileconfig.yaml. Per maggiori dettagli, vedi Parametri di configurazione. - Controlla la sandbox utilizzando la CLI (
--sandbox): puoi attivare o disattivare esplicitamente la sandbox per una singola esecuzione passando--sandbox=trueo--sandbox=falseacm find,cm verifyocm fix. - Ignora l'isolamento utilizzando la CLI (
--unrestricted): puoi ignorare temporaneamente tutte le protezioni della sandbox per una singola esecuzione passando il flag--unrestricted. In questo modo vengono disabilitati i limiti del percorso del file system (consentendo all'agente di accedere a qualsiasi percorso sull'host) e l'isolamento dei container a livello di sistema operativo (incluso l'isolamento di rete).
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 della CLI 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 della CLI. Utilizza funzionalità del sistema operativo integrate (spazi dei nomi/seccomp, sandbox-exec, AppContainer (sperimentale)) per isolare l'esecuzione. |
Leggero: nessun sovraccarico di avvio; accesso diretto agli strumenti dello spazio di lavoro locale con controllo granulare. Consigliato per lo sviluppo locale quotidiano. | La sicurezza si basa sulle funzionalità del kernel del sistema operativo; meno isolato di 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 es. Docker). | Buon isolamento; ambiente standardizzato. | Richiede il runtime del contenitore; 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. |
Telemetria
Per aiutarci a monitorare e migliorare l'integrità del prodotto, raccogliamo dati di telemetria anonimi tramite l'interfaccia a riga di comando. Anonimizziamo completamente tutti i dati raccolti, incluse le metriche di utilizzo di base e la diagnostica delle prestazioni. La telemetria non raccoglie né trasmette codice sorgente, contenuti dei file, risultati, patch o identità degli utenti.
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 assicurarti di utilizzare l'ultima versione della CLI.
Controlli degli aggiornamenti automatici
Per impostazione predefinita, la CLI CodeMender verifica automaticamente la presenza di aggiornamenti in background quando esegui i comandi:
- Limitazione: per ridurre al minimo il sovraccarico, il controllo automatico viene eseguito al massimo una volta ogni 24 ore.
- Terminale interattivo (TTY) richiesto: la CLI controlla solo la presenza di aggiornamenti e ti chiede di eseguirli quando viene eseguita in un terminale interattivo. Negli ambienti non interattivi (come pipeline o script CI/CD), il controllo viene ignorato e un avviso viene registrato in
stderral massimo una volta al giorno. - Richiesta: se è disponibile una nuova versione, ti verrà chiesto su
stderr:none 🆕 A new CodeMender release is available: 1.1.0 Update now? (y/N):Se scegli Sì (yoyes), CodeMender scarica l'aggiornamento, sostituisce il file binario ed esce. Devi eseguire di nuovo il comando per eseguirlo con la nuova versione. Se scegli No, l'aggiornamento viene ignorato e viene eseguito il comando originale. - Tolleranza offline: se sei offline o il repository di rilascio non è raggiungibile, il controllo non va a buon fine e CodeMender continua a eseguire il comando.
- Ignorare: puoi ignorare 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 immediatamente l'aggiornamento senza richiedere l'intervento dell'utente (non interattivo).
- Non richiede un terminale interattivo (sicuro per script e gestione della configurazione).
Se la CLI è installata in una directory di sistema che richiede autorizzazioni elevate, esegui l'aggiornamento con sudo:
sudo cm update