Befehlszeile installieren und konfigurieren

CodeMender ist ein autonomer KI-Codesicherheits-Agent, der tiefgreifende Cybersicherheitslücken in Ihrer Codebasis scannt, verifiziert und patcht. Bevor Sie CodeMender ausführen, müssen Sie die Befehlszeile herunterladen und die Arbeitsbereichsoptionen initialisieren.

Architektur- und Sicherheitsmodell

CodeMender verwendet ein lokales Ausführungsmodell:

  • Gehostete Reasoning Engine: Agentisches Reasoning, Bedrohungsmodellierung und Orchestrierungslogik werden sicher in Google Cloud auf der Gemini Enterprise Agent Platform ausgeführt.
  • Lokale Ausführungs-CLI: Der Quellcode wird nie in großen Mengen von Ihrer Workstation oder Ihrem CI/CD-Container übertragen. Das lokale cm-CLI-Tool führt Dateilesevorgänge, lokale Build-Prüfungen und PoC-Exploit-Verifizierungen in Ihrer lokalen Sandbox aus. Dabei werden nur ausgewählte Code-Snippets und Ergebnisse der Toolausführung über die Interactions API auf der Gemini Enterprise Agent Platform an das Cloud-Backend gesendet.

Umgebung einrichten

Wenn Sie CodeMender verwenden möchten, richten Sie Ihr Google Cloud -Projekt ein, laden Sie die Befehlszeile herunter und installieren Sie sie, konfigurieren Sie Ihre Anmeldedaten und Ihr Zielprojekt und initialisieren Sie Ihren Arbeitsbereich.

Projekteinrichtung und IAM-Berechtigungen

Bevor Sie die Befehlszeile herunterladen und Anmeldedaten konfigurieren, müssen Sie das Zielprojekt in Google Cloud mit den erforderlichen APIs und Berechtigungen einrichten.

Erforderliche APIs

Prüfen Sie, ob die folgenden Google Cloud APIs in Ihrem Projekt aktiviert sind:

  1. Agent Platform API (aiplatform.googleapis.com) – Ermöglicht das Streaming und die Verwaltung aktiver Sitzungen.
  2. Cloud Resource Manager API (cloudresourcemanager.googleapis.com): Validiert Nutzerauthentifizierungsstatus und Projektmetadaten.

Um die CLI-Befehle auszuführen, müssen Nutzern die folgenden IAM-Rollen zugewiesen werden:

  • Agent Platform User (roles/aiplatform.user): Ermöglicht Nutzern, aktive Sitzungen zu erstellen, zu streamen und zu verwalten.

CodeMender-Befehlszeile herunterladen und installieren

Die CodeMender-CLI-Binärdateien werden in Artifact Registry gehostet. Wählen Sie den Tab für Ihr Betriebssystem aus, um die Befehlszeile herunterzuladen und zu installieren.

Linux x86_64

So laden Sie die CodeMender-Befehlszeile für Linux (x86_64) herunter und installieren sie:

  1. Laden Sie das Paket mit einer der folgenden Methoden herunter:
    • gcloud CLI: Führen Sie den folgenden Befehl aus:
      gcloud artifacts generic download \
        --project=cmoc-prod \
        --location=us \
        --repository=codemender-cli-production \
        --package=cm \
        --version=stable \
        --name=cm-linux-amd64.zip \
        --destination=./
    • curl: Führen Sie den folgenden Befehl aus:
      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. Installieren Sie die Befehlszeile:
    unzip cm-linux-amd64.zip
    chmod +x cm
    sudo mv cm /usr/local/bin/cm

Linux ARM64

So laden Sie die CodeMender-Befehlszeile für Linux (ARM64) herunter und installieren sie:

  1. Laden Sie das Paket mit einer der folgenden Methoden herunter:
    • gcloud CLI: Führen Sie den folgenden Befehl aus:
      gcloud artifacts generic download \
        --project=cmoc-prod \
        --location=us \
        --repository=codemender-cli-production \
        --package=cm \
        --version=stable \
        --name=cm-linux-arm64.zip \
        --destination=./
    • curl: Führen Sie den folgenden Befehl aus:
      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. Installieren Sie die Befehlszeile:
    unzip cm-linux-arm64.zip
    chmod +x cm
    sudo mv cm /usr/local/bin/cm

macOS Intel

So laden Sie die CodeMender-Befehlszeile für macOS (Intel) herunter und installieren sie:

  1. Laden Sie das Paket mit einer der folgenden Methoden herunter:
    • gcloud CLI: Führen Sie den folgenden Befehl aus:
      gcloud artifacts generic download \
        --project=cmoc-prod \
        --location=us \
        --repository=codemender-cli-production \
        --package=cm \
        --version=stable \
        --name=cm-darwin-amd64.zip \
        --destination=./
    • curl: Führen Sie den folgenden Befehl aus:
      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. Installieren Sie die Befehlszeile:
    unzip cm-darwin-amd64.zip
    chmod +x cm
    mv cm /usr/local/bin/cm

macOS Apple Silicon

So laden Sie die CodeMender-Befehlszeile für macOS (Apple Silicon) herunter und installieren sie:

  1. Laden Sie das Paket mit einer der folgenden Methoden herunter:
    • gcloud CLI: Führen Sie den folgenden Befehl aus:
      gcloud artifacts generic download \
        --project=cmoc-prod \
        --location=us \
        --repository=codemender-cli-production \
        --package=cm \
        --version=stable \
        --name=cm-darwin-arm64.zip \
        --destination=./
    • curl: Führen Sie den folgenden Befehl aus:
      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. Installieren Sie die Befehlszeile:
    unzip cm-darwin-arm64.zip
    chmod +x cm
    mv cm /usr/local/bin/cm

Windows x86_64

So laden Sie die CodeMender-Befehlszeile für Windows (x86_64) herunter und installieren sie:

  1. Laden Sie das Paket mit einer der folgenden Methoden herunter:
    • gcloud CLI: Führen Sie den folgenden Befehl in PowerShell aus:
      gcloud artifacts generic download `
        --project=cmoc-prod `
        --location=us `
        --repository=codemender-cli-production `
        --package=cm `
        --version=stable `
        --name=cm-windows-amd64.zip `
        --destination=./
    • PowerShell: Führen Sie den folgenden Befehl aus:
      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. Installieren Sie die Befehlszeile:
    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

So laden Sie die CodeMender-Befehlszeile für Windows (ARM64) herunter und installieren sie:

  1. Laden Sie das Paket mit einer der folgenden Methoden herunter:
    • gcloud CLI: Führen Sie den folgenden Befehl in PowerShell aus:
      gcloud artifacts generic download `
        --project=cmoc-prod `
        --location=us `
        --repository=codemender-cli-production `
        --package=cm `
        --version=stable `
        --name=cm-windows-arm64.zip `
        --destination=./
    • PowerShell: Führen Sie den folgenden Befehl aus:
      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. Installieren Sie die Befehlszeile:
    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)

Anmeldedaten und Projekt für Google Cloud konfigurieren

Da die CodeMender-Befehlszeile über die Interactions API mit der in der Cloud gehosteten Reasoning Engine interagiert, müssen Sie Google Cloud -Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) konfigurieren und Ihr Zielprojekt in Ihrer Umgebung angeben.

  1. Führen Sie zur Authentifizierung den folgenden Befehl aus und folgen Sie den Anmeldeaufforderungen:

    gcloud auth application-default login
    
  2. Legen Sie die Umgebungsvariable GOOGLE_CLOUD_PROJECT auf Ihre Projekt-ID in Google Cloud fest:

    export GOOGLE_CLOUD_PROJECT="PROJECT_ID"
    

    Alternativ können Sie Ihr aktives gcloud CLI-Projekt konfigurieren:

    gcloud config set project PROJECT_ID
    

    Ersetzen Sie dabei PROJECT_ID durch die ID Ihres Projekts in Google Cloud .

Arbeitsbereich initialisieren

Nachdem Sie Ihre Anmeldedaten und das Zielprojekt konfiguriert haben, müssen Sie CodeMender in Ihrer lokalen Umgebung initialisieren. Durch die Initialisierung von CodeMender wird Ihr lokaler Arbeitsbereich vorbereitet. Dazu werden Dateien zur Statusverfolgung erstellt und Verbindungseinstellungen zur in der Cloud gehosteten Reasoning Engine eingerichtet.

Führen Sie cm init im Stammverzeichnis Ihrer Codebasis aus, um lokale Dateien zur Statusverfolgung zu erstellen und Baseline-Konfigurationen festzulegen:

cm init

Verwenden Sie das Flag --verify, um die Verbindung zur in der Cloud gehosteten Reasoning Engine zu testen und die Arbeitsbereichseinstellungen zu prüfen:

cm init --verify

Dienstverbindung und Berechtigungen prüfen

Führen Sie cm health aus, um Ihre Anmeldedaten, die Konfiguration, die Netzwerkreichweite und die IAM-Berechtigungen zu prüfen, ohne einen Scan zu starten oder Ihren Arbeitsbereich zu ändern:

cm health

Mit dem Befehl cm health werden vier aufeinanderfolgende Prüfungen ausgeführt. Er stoppt bei der ersten fehlerhaften Ebene. Sie können cm health von jedem beliebigen Verzeichnis aus ausführen, auch bevor Sie cm init ausführen. Es werden keine Daten auf das Laufwerk geschrieben und es wird kein Modellkontingent verbraucht.

Verwenden Sie für automatisierte CI/CD-Preflight-Prüfungen oder geplante synthetische Monitorings --strict, um einen Fehler auszugeben, wenn IAM-Prüfungen auf Projektebene übersprungen werden, und --json, um einen maschinenlesbaren JSON-Bericht auszugeben:

cm health --strict --json

In der folgenden Tabelle werden die cm health-Exit-Codes beschrieben:

Exit-Code Ebene Beschreibung
0 – Alle Systemdiagnosen bestanden.
10 credentials Die Befehlszeile konnte kein gültiges OAuth- oder Standardanmeldedaten-Token für Anwendungen abrufen oder der Server hat das Token abgelehnt (401 Unauthorized).
20 config Die lokale config.yaml-Datei, das Flag --team-id oder die Umgebungsvariable CM_TEAM_ID ist ungültig.
30 reachability Die Befehlszeile konnte den Agent Platform API-Endpunkt nicht erreichen (z. B. aufgrund von DNS-, TLS-, Proxy- oder VPC Service Controls-Einschränkungen).
40 authorization Der Server wurde erreicht, aber der Aufrufer oder das Projekt ist nicht berechtigt, CodeMender-Scans auszuführen (z. B. fehlen die Berechtigungen roles/aiplatform.user).
50 – Die Systemdiagnose hat die Dauer von --timeout (Standardwert: 30s) überschritten.

Die folgenden Flags werden von cm health unterstützt:

Flag Standardeinstellung Beschreibung
--json false Gibt ein einzelnes JSON-Objekt an die Standardausgabe aus, einschließlich status, exit_code, backend, endpoint, location, project_id, agent_id, duration_ms, layers und (falls vorhanden) warnings und error.
--strict false Behandelt Warnungen bei der Systemdiagnose (z. B. nicht verifizierte oder übersprungene IAM-Berechtigungsprüfungen auf Projektebene) als Fehler mit dem Exit-Code 40.
--timeout 30s Legt das Gesamtzeitlimit für die Systemdiagnoseprüfung fest.

Konfigurationsparameter (config.yaml)

Das Hauptziel von config.yaml besteht darin, das Verhalten des CodeMender-KI-Agenten an die Sicherheits-, Umgebungs- und Leistungsanforderungen Ihres lokalen Systems anzupassen.

Da der gehostete KI-Agent lokale Befehle (z. B. Code erstellen, Tests ausführen oder Dateien bearbeiten) über Ihren lokalen Daemon-Client ausführt, dient diese Konfigurationsdatei als Grenze, die definiert, was der Agent tun darf und was nicht.

Nutzung

  • Speicherort: Standardmäßig liest die Befehlszeile diese Datei aus ~/.codemender/config.yaml. Sie können das Arbeitsbereichs- und Konfigurationsverzeichnis überschreiben, indem Sie die Umgebungsvariable CM_HOME festlegen (z. B. CM_HOME=/path/to/custom/dir, die /path/to/custom/dir/config.yaml liest).
  • Ausführung: Wenn Sie Befehle wie cm find, cm verify oder cm fix ausführen, liest der lokale Client diese Datei, um Sicherheitsparameter einzurichten, Systemumgehungen anzuwenden und anzugeben, welche Dateien oder Verzeichnisse ignoriert werden sollen.

Standardeinstellungen für Core-Dienste

Das bedeuten die wichtigsten Standardparameter:

  • tools.confirm_commands: true

    • Bedeutung: Standardmäßig fordert CodeMender Sie im Terminal zur Bestätigung von [Y/n] auf, bevor Shell-Befehle (run_command) ausgeführt werden. Wenn cm find mit aktivierter Sandbox auf Betriebssystemebene (sandbox.enabled: true) und Standard-Netzwerkisolation (permissive-closed) ausgeführt wird, wird der Arbeitsbereich mit Lesezugriff bereitgestellt und die Bestätigungsaufforderungen für Befehle werden automatisch übersprungen.
    • Warum dies die Standardeinstellung ist: CodeMender kann während der Überprüfung und des Patchings Build-Befehle, Test-Suites oder Exploit-Skripts ausführen. Wenn Sie eine Bestätigung anfordern, wenn der Arbeitsbereich beschreibbar ist oder nicht in einer Sandbox ausgeführt wird, können Sie unbeabsichtigte Befehlsausführungen in Ihrer lokalen Umgebung verhindern.
    • Überspringen: Übergeben Sie -y (oder --yes) für eine einzelne Ausführung oder legen Sie tools.confirm_commands: false in config.yaml für nicht interaktive CI/CD-Pipelines fest.
  • tools.confirm_writes: true

    • Bedeutung: Sie werden im Terminal zur Bestätigung mit [Y/n] aufgefordert, bevor der CodeMender-Agent Dateien auf dem Laufwerk schreibt oder ändert (write_to_file und search_and_replace).
    • Warum ist das die Standardeinstellung? Wenn eine manuelle Bestätigung erforderlich ist, wird verhindert, dass der KI-Agent während cm fix oder cm verify spekulative oder unbeabsichtigte Änderungen an Ihren Quelldateien vornimmt. Legen Sie diesen Wert nur auf false fest (oder übergeben Sie -y/--yes), wenn Sie in isolierten, temporären Umgebungen oder automatisierten CI/CD-Pipelines arbeiten.
  • execution.interactive_mode: true

    • Bedeutung: Aktiviert interaktive Terminal-Eingabeaufforderungen während der Toolausführung. Legen Sie dafür false fest (oder übergeben Sie -y / --yes) in Headless-CI/CD-Umgebungen, in denen kein Terminal angehängt ist.
  • execution.duration: ""

    • Bedeutung: Legt eine standardmäßige maximale Ausführungsdauer pro Befehlsaufruf (z. B. "15m" oder "1h") für cm find, cm verify, cm fix und cm session resume fest. Lassen Sie dieses Feld leer oder legen Sie "0" fest, wenn Sie kein Zeitlimit festlegen möchten. Sie können diese Einstellung mit der Umgebungsvariablen CM_DURATION oder dem Flag --duration (oder --timeout) überschreiben. Wenn ein Befehl am Limit seiner Ausführungsdauer stoppt, werden alle abgeschlossenen Ergebnisse gespeichert und der Befehl wird mit dem Status 1 beendet, wenn ein cm find --diff-Scan mit --fail-on übereinstimmt, oder andernfalls mit dem Status 50.
  • execution.stall_detection: false

    • Bedeutung: Wenn auf true gesetzt (oder wenn CM_STALL_DETECTION=on), wird eine KI-Agentensitzung beendet, die über aufeinanderfolgende Tool-Runden hinweg keinen Fortschritt macht. Befehle für eine einzelne Sitzung (cm find --quick, cm verify, cm fix und cm session resume mit einem Durchlauf) werden mit dem Status 50 beendet. Bei Scans mit mehreren Sitzungen (--deep, --diff und --parallel) wird eine blockierte Sitzung als fehlgeschlagen aufgezeichnet und der Scan wird fortgesetzt.
  • 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"]

    • Bedeutung: Definiert die explizite Liste der Dateiendungen, die CodeMender beim Scannen Ihres Arbeitsbereichs aufnehmen und analysieren darf. CodeMender überspringt automatisch alle Dateien in Ihrem Repository, deren Erweiterung nicht in dieser Liste aufgeführt ist.
    • Warum dies die Standardeinstellung ist: Diese Liste enthält standardmäßig die wichtigsten Programmiersprachen, um die Scaneffizienz zu maximieren und zu verhindern, dass der Agent Zeit und Tokens für irrelevante Textdateien, Build-Artefakte oder Binärdateien verschwendet. Da moderne Anwendungen jedoch häufig Sicherheitslücken in Bereitstellungskonfigurationen oder Automatisierungstools einbetten, können Sie diese Standardliste in config.yaml manuell erweitern, um Konfigurationsdateien, Scriptformate und IaC-Dateien (z. B. Shell-Scripts, XML, YAML, Properties und JSON-Dateien) einzuschließen, damit CodeMender sie nicht stillschweigend ignoriert.
  • scan.exclude_dirs: ["node_modules", "vendor", "dist", "/target", "/obj", "/build", ".gradle"]

    • Bedeutung: CodeMender überspringt diese Verzeichnisse beim Scannen des Arbeitsbereichs und bei der Codeanalyse. Einträge mit einem führenden / (z. B. /target, /obj und /build) werden nur im Stammverzeichnis des Scans abgeglichen, sodass verschachtelte Quellpakete mit diesen Namen nicht übersprungen werden.
    • Warum dies die Standardeinstellung ist: Große Abhängigkeits- oder Build-Ordner führen zu einer massiven Latenz und Token-Strafe. Wenn diese standardmäßig ausgeschlossen bleiben, sorgt das für eine hohe Leistung und schnelle Reaktionszeiten. Sie können diese Liste in config.yaml anpassen, um bestimmte Verzeichnisse entsprechend Ihrer Projektstruktur ein- oder auszuschließen.
  • project_paths: []

    • Bedeutung: Eine Liste von Verzeichnispfaden, auf die CodeMender während der Toolausführung zugreifen (lesen/schreiben) kann.
    • Warum dies die Standardeinstellung ist: Standardmäßig ist dieses Feld leer, wodurch der Agent auf das übergeordnete Projektstammverzeichnis (oder das Scan-Zielverzeichnis) beschränkt wird. Wenn Ihr Build- oder Testprozess Zugriff auf Dateien außerhalb des Projektstammverzeichnisses erfordert, fügen Sie diese Pfade hier hinzu oder übergeben Sie --allow-all-paths für eine einzelne Ausführung. Schreibvorgänge in .git, .hg und .codemender werden immer blockiert.
    • Artefaktverzeichnis: Der KI-Agent kann auch in ein sitzungsspezifisches Artefaktverzeichnis (~/.codemender/artifacts/<session_id>/ oder das entsprechende Verzeichnis unter $CM_HOME) schreiben.
    • Temporäre Dateien: Wenn die Sandbox aktiviert ist, wird das Hostverzeichnis /tmp immer blockiert, auch wenn Sie /tmp zu project_paths hinzufügen. Tools, die TMPDIR berücksichtigen, verwenden stattdessen ein temporäres Verzeichnis im Artefaktverzeichnis.
  • sandbox:

    • Bedeutung: Konfigurationsblock für die Sandbox-Umgebung auf Prozessebene.
    • Unterparameter:
      • enabled: true: (boolesch) Aktiviert oder deaktiviert die Sandbox. Wenn Sie diesen Wert auf true (Standard) festlegen, führt der Agent Tools in der lokalen Sandbox aus. Wenn Sie den Wert auf false setzen (oder --sandbox=false übergeben), führt der Agent Tools direkt auf dem Hostsystem ohne Isolation auf Betriebssystemebene aus.
      • mounts: (Objekt)
        • target_dir: ".": (String) Das Verzeichnis, das als aktiver Arbeitsbereich in der Sandbox bereitgestellt werden soll. Die Befehlszeile löst relative Pfade im Verhältnis zum Stammverzeichnis des Arbeitsbereichs auf.
      • network: (Objekt)
        • profile: "permissive-closed": (String) Profil für den ausgehenden Netzwerkzugriff innerhalb der Sandbox. Eine detaillierte Zulassungsliste für bestimmte Domains oder URL-Muster wird noch nicht unterstützt. Unterstützte Profile:
          • permissive-closed (Standard): Vollständige Netzwerkisolation; die Sandbox blockiert alle ausgehenden Verbindungen.
          • permissive-open: Ermöglicht vollständigen ausgehenden Netzwerkzugriff.
  • security:

    • Bedeutung: Konfigurationsblock für Sicherheitsrichtlinien.
    • Unterparameter:
      • protected_files: []: (Liste von Strings) Zusätzliche Dateien oder Verzeichnisse auf dem Hostsystem, die Sie schreibgeschützt in der Sandbox bereitstellen möchten, um sie vor Änderungen zu schützen. Unterstützt Pfaderweiterung (~) und Platzhalter (*). Auch wenn protected_files leer ist, schützt die Sandbox immer .git/hooks, .git/config, .hg/hgrc und .codemender mit Lesezugriff und schließt gängige Verzeichnisse für Anmeldedaten aus (~/.ssh, ~/.gnupg, ~/.aws, ~/.config/gcloud, ~/.config/gh, ~/.kube, ~/.docker).
  • Modell: config.yaml legt das Modell nicht fest. Wenn Sie ein Modell auswählen möchten, übergeben Sie --model an cm find, cm verify oder cm fix. Informationen zu den unterstützten Modellen und zum Standardmodell finden Sie unter Modell angeben.

  • vcs: { type: "git" }

    • Bedeutung: Definiert den Typ des Versionsverwaltungssystems, das Ihr Projekt verwendet, über den Schlüssel vcs. Wenn Sie diese Option nicht konfigurieren, versucht das Tool, Git- oder Mercurial-Repositories automatisch zu identifizieren. Wenn Sie vcs auf none setzen, gibt die Befehlszeile eine Warnung aus, setzt die Ausführung aber ohne VCS-Funktionen fort. CodeMender benötigt diese Einstellung, um spekulative Sicherheitskorrekturen zu verwalten, Änderungen an der Codebasis zu verfolgen und sich in Ihr lokales Repository einzubinden.
    • Warum dies die Standardeinstellung ist: CodeMender unterstützt Git, Mercurial oder benutzerdefinierte VCS-Konfigurationen. Git ist die Standardoption, da es der Branchenstandard für die Versionsverwaltung ist und eine nahtlose Diff-Integration und Rollback-Sicherheit bietet.
  • build: { command: "make build && make test" }

    • Bedeutung: Definiert den genauen Shell-Befehl, den CodeMender ausführt, um Ihr Projekt zu kompilieren und zu erstellen sowie Ihre Unit- und Regressionstests auszuführen.
    • Warum dies die Standardeinstellung ist: Das Festlegen eines Build- und Testbefehls ist für den Bestätigungsworkflow entscheidend. Dadurch kann CodeMender Ihr Projekt kompilieren und Ihre vorhandene Test-Suite in der isolierten Sandbox-Umgebung ausführen, um zu prüfen, ob der generierte Sicherheitspatch die Sicherheitslücke erfolgreich behebt, ohne die vorhandene Anwendungslogik zu beeinträchtigen.

Bestätigungsaufforderungen

CodeMender bittet um Bestätigung, bevor ein Shell-Befehl ausgeführt (tools.confirm_commands) und eine Datei geschrieben wird (tools.confirm_writes). Die beiden Einstellungen sind unabhängig voneinander und standardmäßig auf true festgelegt. Mit den folgenden Einstellungen werden diese Aufforderungen deaktiviert (in der Reihenfolge ihrer Priorität):

  1. -y oder --yes: Genehmigt alle Befehls- und Dateischreibaufforderungen für eine Ausführung, unabhängig davon, was config.yaml sagt.
  2. execution.interactive_mode: false in config.yaml: Deaktiviert sowohl Befehls- als auch Dateischreibaufforderungen für jeden Durchlauf.
  3. tools.confirm_commands: false oder tools.confirm_writes: false in config.yaml: Deaktiviert die Eingabeaufforderungen oder die Aufforderungen zum Schreiben von Dateien für jede Ausführung, unabhängig voneinander.

Wenn keine dieser Einstellungen zutrifft und niemand die Aufforderung beantworten kann, z. B. in einem CI/CD-Job ohne Terminal, führt CodeMender den Befehl nicht aus und schreibt die Datei nicht.

Unabhängig von diesen Aufforderungen werden Sie von der Befehlszeile gewarnt, dass der Agent Dateien ändern und Befehle auf Ihrem System ausführen kann. Sie werden aufgefordert, die Warnung zu bestätigen. -y überspringt diese Warnung nicht. Wenn Sie ihn überspringen möchten, übergeben Sie --bypass-warning. In einer nicht interaktiven Umgebung ohne --bypass-warning schlägt cm mit warning not acknowledged fehl. cm find überspringt die Warnung, wenn die Sandbox mit dem Standardnetzwerkprofil permissive-closed aktiviert ist.

Befehlsrichtlinie (command_policy.yaml)

Zusätzlich zur Sandbox auf Betriebssystemebene können Sie eine Befehls-Sperrliste in ~/.codemender/command_policy.yaml (global) und <project>/.codemender/command_policy.yaml (projektspezifisch) definieren. Wenn beide Dateien vorhanden sind, führt CodeMender ihre Regeln zusammen.

Beim ersten Ausführen erstellt CodeMender eine auskommentierte Vorlage unter ~/.codemender/command_policy.yaml. Sie können Regeln unter zwei Schlüsseln auskommentieren oder hinzufügen:

  • block: Eine Liste von Binärnamen, die in allen Shell-Pipelines, Subshells und Befehlssubstitutionen blockiert werden sollen (z. B. curl, wget, ssh, sudo, rm).
  • block_patterns: Eine Liste regulärer Ausdrücke, die mit jedem Befehlssegment abgeglichen werden (z. B. '\bgit\s+(push|commit|rebase|reset\s+--hard|clean)\b').

Wenn Sie die Erzwingung von command_policy.yaml für einen einzelnen Befehlsaufruf umgehen möchten, übergeben Sie das Flag --allow-all-commands.

  • output: { plain: false }
    • Bedeutung: Steuert, ob die CodeMender-Befehlszeile Emojis, Unicode-Symbole und Terminalfarben in der Befehlszeilenausgabe und in formatierten Berichten durch ASCII-Text ersetzt.
    • Warum dies die Standardeinstellung ist: Durch die umfangreiche Terminalformatierung und Statussymbole sind interaktive Scans und exportierte Berichte leichter zu lesen. Legen Sie plain für CI/CD-Logs, Screenreader oder minimale Terminals auf true fest. Informationen zu Rangfolgeregeln und Flag-Überschreibungen finden Sie unter Nur-Text-Ausgabe konfigurieren.

Ausführungssandbox

Um Ihre Workstation vor unbeabsichtigten Dateiänderungen oder unerwarteten Nebenwirkungen von Tools zu schützen, wird die CodeMender-Befehlszeile standardmäßig in einer Sandbox auf Betriebssystemebene ausgeführt. Sie können das Sandboxing dauerhaft in der Konfiguration deaktivieren oder es pro Befehl mithilfe von CLI-Flags umgehen.

Google bietet die CodeMender-Sandbox als empfohlenes Sicherheitsfeature an. Die Ausführung von CodeMender außerhalb einer Sandbox-Umgebung erfolgt gemäß Paragraf 20(j) der dienstspezifischen Nutzungsbedingungen auf eigenes Risiko des Kunden.

Dieses Sandboxing bietet zwar eine erste Schutzebene auf Ihrer Workstation, aber einen schwächeren Sicherheitsschutz als die Ausführung des Agents in einer vollständig isolierten virtuellen Maschine (VM):

  • Linux: Verwendet Kernel-Namespaces (CLONE_NEWNS, CLONE_NEWUSER usw.) und seccomp-Filter, um Bereitstellungspunkte zu isolieren und Systemaufrufe einzuschränken.
  • macOS: Verwendet den integrierten sandbox-exec-Mechanismus (Seatbelt).
  • Windows (experimentell): Verwendet AppContainer-Isolierung und Access Control Lists (ACLs). Sandboxing unter Windows ist experimentell und erfordert möglicherweise Administratorberechtigungen oder ist mit einigen Systemkonfigurationen nicht kompatibel.

Sandbox-Verhalten

Wenn die Sandbox aktiv ist, gilt Folgendes:

  1. Dateisystemisolation: Der Agent kann nur auf Dateien in zulässigen Verzeichnissen zugreifen. Während cm find werden der Arbeitsbereich und die zulässigen Stammverzeichnisse schreibgeschützt bereitgestellt, sodass Befehle nur in das Artefaktverzeichnis pro Sitzung schreiben können. Bei allen Befehlen (einschließlich cm verify und cm fix) werden .git/hooks, .git/config, .hg/hgrc und .codemender mit Lesezugriff bereitgestellt, sodass Befehle in der Sandbox keine Git- oder Mercurial-Hooks installieren oder die CodeMender-Konfiguration ändern können.
  2. Netzwerkisolation: Die Sandbox blockiert standardmäßig den ausgehenden Netzwerkzugriff (sandbox.network.profile: "permissive-closed"). Dadurch wird verhindert, dass der KI-Agent (oder die von ihm aufgerufenen Build-Tools) unerwartete externe Verbindungen herstellt oder Daten außerhalb des Arbeitsbereichs überträgt.
  3. Isolierung von Anmeldedaten und Secrets: Die Sandbox schließt gängige Verzeichnisse für Host-Anmeldedaten (~/.ssh, ~/.gnupg, ~/.aws, ~/.config/gcloud, ~/.config/gh, ~/.kube, ~/.docker usw.) aus und entfernt Umgebungsvariablen, die Secret-Mustern entsprechen (*_TOKEN, *_SECRET, *_KEY, *_PASSWORD, *_CREDENTIALS und ähnliche Suffixe), bevor Befehle ausgeführt werden.

Netzwerkzugriff während der Erstellung und Validierung

Da die Sandbox standardmäßig die Netzwerkisolation aktiviert (sandbox.network.profile ist standardmäßig auf permissive-closed festgelegt), kann der Agent während der Toolausführung nicht auf das Internet zugreifen.

Dies führt zu Einschränkungen für Projekte, die während der Build- oder Überprüfungsschritte externe Abhängigkeiten abrufen müssen (z. B. Ausführen von npm install, pip install oder go get als Teil von build.command). Wenn Ihr Build-Prozess versucht, auf externe Webdienste zuzugreifen, schlägt er fehl.

Umgang mit Netzwerkabhängigkeiten

Wenn Ihr Projekt Netzwerkzugriff für Builds oder Tests erfordert, haben Sie die folgenden Optionen:

  • Abhängigkeiten vorab abrufen: Installieren Sie alle erforderlichen Abhängigkeiten auf dem Hostsystem, bevor Sie cm-Befehle ausführen, damit der Build-Befehl keinen Netzwerkzugriff benötigt.
  • Netzwerkzugriff in der Sandbox aktivieren: Ändern Sie das Netzwerkprofil in Ihrer config.yaml, um ausgehende Verbindungen zuzulassen:

    sandbox:
      network:
        profile: "permissive-open"
    
  • Sandbox für eine Ausführung deaktivieren: Führen Sie den Befehl mit dem Flag --sandbox=false aus, um die Sandbox auf Betriebssystemebene (einschließlich Netzwerkisolation) für diese Ausführung zu deaktivieren.

Sandbox-Konfiguration

Sie können die Sandbox und die Sicherheitsgrenzen mit den folgenden Optionen konfigurieren und steuern:

  • Dauerhafte Konfiguration (config.yaml und command_policy.yaml): Passen Sie das Sandbox-Verhalten, die Dateisystembereitstellungen, den Netzwerkzugriff und die Befehls-Sperrlisten in config.yaml und command_policy.yaml an. Weitere Informationen finden Sie unter Konfigurationsparameter und Befehlsrichtlinie.
  • Sandbox auf Betriebssystemebene steuern (--sandbox): Sie können die Sandbox auf Betriebssystemebene für eine einzelne Ausführung explizit aktivieren oder deaktivieren, indem Sie --sandbox=true oder --sandbox=false an cm find, cm verify, cm fix oder cm session resume übergeben.
  • Pfadgrenzen umgehen (--allow-all-paths): Deaktiviert die Prüfung der Pfadgrenzen des Arbeitsbereichs für einen einzelnen Durchlauf, sodass Agent-Tools auf Pfade außerhalb des Projektstammverzeichnisses und des konfigurierten project_paths zugreifen können (kombinieren Sie dies mit --sandbox=false, um auf Hostpfade zuzugreifen, die nicht in der Sandbox bereitgestellt sind).
  • Befehlsrichtlinie umgehen (--allow-all-commands): Deaktivieren Sie die Erzwingung der command_policy.yaml-Sperrliste für eine einzelne Ausführung.

Isolationsebene auswählen

Je nach Ihren Sicherheitsanforderungen und Ihrer Entwicklungsumgebung können Sie die geeignete Isolationsstufe für die Ausführung der CodeMender-Befehlszeile auswählen.

Methode Beschreibung Vorteile Nachteile
Integrierte Sandbox (auf Betriebssystemebene) Standardmäßig aktiviert. Sie können es in der Datei config.yaml deaktivieren oder mit CLI-Flags umgehen. Verwendet integrierte Betriebssystemfunktionen (Namespaces/seccomp, sandbox-exec, AppContainer (experimentell)), um die Ausführung zu isolieren. Leichtgewichtig; kein Startaufwand; direkter Zugriff auf lokale Workspace-Tools mit detaillierter Steuerung. Empfohlen für die tägliche lokale Entwicklung. Die Sicherheit hängt von den Funktionen des Betriebssystemkernels ab. Sie sind weniger isoliert als eine vollständige VM. Die Windows-Unterstützung ist experimentell und erfordert möglicherweise Administratorberechtigungen oder ist mit einigen Konfigurationen nicht kompatibel.
Container Ausführen des Agents in einem Container (z. B. Docker). Gute Isolation; standardisierte Umgebung. Erfordert Containerlaufzeit; kann ressourcenintensiv sein; lässt keine direkte Interaktion mit Tools auf dem lokalen Computer zu.
Vollständige VMs Ausführen des Agents auf einer dedizierten VM. Maximale Sicherheit; vollständige Isolierung. Hoher Ressourcenaufwand; langsamer Start; keine direkte Interaktion mit Tools auf dem lokalen Computer möglich.

Nur-Text-Ausgabe konfigurieren

Standardmäßig verwendet die CodeMender-Befehlszeile Emojis, Unicode-Symbole und Terminalfarben in interaktiven Ausgaben und formatierten Berichten. Wenn Sie in CI/CD-Logs, Screenreadern oder minimalen Terminals nur ASCII-Ausgaben verwenden möchten, aktivieren Sie den Nur-Text-Modus. Die CodeMender-Befehlszeile prüft diese Einstellungen in der Reihenfolge ihrer Priorität (von der höchsten zur niedrigsten):

  1. Übergeben Sie das Flag --plain an einen beliebigen cm-Befehl für eine einzelne Ausführung oder übergeben Sie --plain=false, um Umgebungs- und Konfigurationseinstellungen zu überschreiben:

    cm --plain find .
    
  2. Setzen Sie die Umgebungsvariable CM_PLAIN auf true oder 1, um die Nur-Text-Ausgabe für alle Befehle zu aktivieren, oder auf false oder 0, um sie zu deaktivieren:

    export CM_PLAIN=true
    
  3. Legen Sie in der Datei ~/.codemender/config.yaml für output.plain den Wert true fest:

    output:
      plain: true
    
  4. Führen Sie eine interaktive Sitzung in einem Terminal aus, in dem TERM=dumb, wodurch die Nur-Text-Ausgabe automatisch aktiviert wird.

Im Nur-Text-Modus werden Status-Emojis durch ASCII-Tags wie [OK], [INFO], [WARN], [ERROR], [PASS] und [FAIL] ersetzt. CodeMender deaktiviert auch animierte Spinner und das Ersetzen von Zeilen an Ort und Stelle und rendert ASCII-Tabellenrahmen. In cm report werden im Nur-Text-Modus UI-Emojis aus den Formaten table, md und html entfernt, ohne dass sich die Ausgabe von json oder sarif oder die Code-Diffs ändern.

Bei umgeleiteten Dateien und nicht interaktiven CI/CD-Streams bleibt plain standardmäßig auf false gesetzt, damit Statussymbole in exportierten Markdown- und HTML-Berichten erhalten bleiben. Wenn Sie Emojis und Unicode-Symbole aus CI/CD-Logs entfernen möchten, legen Sie CM_PLAIN=true fest, übergeben Sie --plain oder legen Sie output.plain: true fest. Terminal-Farb-Escapes werden bei nicht interaktiven Streams und beim Festlegen der Umgebungsvariablen NO_COLOR automatisch weggelassen.

Telemetrie

Damit wir den Zustand des Produkts im Blick behalten und verbessern können, sendet die Befehlszeile Nutzungstelemetriedaten an Google: ein Ereignis, wenn ein Befehl gestartet wird, ein Ereignis, wenn er beendet wird, und ein Ereignis für jeden gemeldeten Fehler. Wenn die CLI sie ermitteln kann, identifizieren Ereignisse das Google-Konto oder Dienstkonto, das die CLI ausführt, und das verwendete Google Cloud -Projekt.

Telemetrieereignisse können Folgendes enthalten:

  • Ihre Google-Konto-ID oder Dienstkonto-ID, die Google Cloud -Projekt-ID und die Team-ID, falls Sie eine festgelegt haben.
  • Eine zufällige ID für jeden Befehl, den Befehlsnamen, die Serversitzungs-ID, das ausgewählte Modell und die CLI-Version.
  • Die Betriebssystemfamilie, die Plattform und die Version.
  • Ob die Sandbox aktiviert ist und ob -y (--yes) so eingestellt ist, dass Bestätigungsaufforderungen übersprungen werden.
  • Beim Beenden: Dauer, Exit-Code und Ergebnis; Tokenanzahl; Anzahl der gescannten Zeilen, Dateien und Bytes sowie die erkannten Sprachen; Anzahl der Ergebnisse nach Schweregrad oder das Ergebnis einer Überprüfung oder Korrektur.
  • Bei einem Fehler: die Fehlerkategorie und der Grund sowie ein Stacktrace des eigenen Codes der Befehlszeile.

Telemetriedaten enthalten keinen Quellcode, keine Dateiinhalte, keine Dateipfade, keine Prompts, keine Ergebnisse, keine Patches und keinen Fehlermeldungstext. Die Befehlszeile sendet Telemetriedaten an einen globalen Google-Endpunkt. Telemetriedaten sind Dienstdaten, wie in den Datenschutzhinweisen fürGoogle Cloud beschrieben.

Die Telemetrie ist standardmäßig aktiviert. Wenn Sie die Telemetrie deaktivieren möchten, setzen Sie die Umgebungsvariable CM_TELEMETRY_OPT_OUT auf 1 oder true.

Befehlszeile aktualisieren

CodeMender hat einen integrierten Aktualisierungsmechanismus, mit dem Sie Ihre Befehlszeile auf dem neuesten Stand halten können.

Automatische Updateprüfungen

Standardmäßig sucht die CodeMender-Befehlszeile automatisch im Hintergrund nach Updates, wenn Sie Befehle ausführen:

  • Drosselung: Um den Aufwand zu minimieren, wird die automatische Prüfung höchstens einmal alle 24 Stunden ausgeführt.
  • Interaktives Terminal (TTY) erforderlich: Die Befehlszeile sucht nur nach Updates und fordert Sie auf, diese zu installieren, wenn sie in einem interaktiven Terminal ausgeführt wird. In nicht interaktiven Umgebungen (z. B. CI/CD-Pipelines oder Skripts) wird die Prüfung übersprungen und höchstens einmal pro Tag eine Warnung in stderr protokolliert.
  • Aufforderung: Wenn eine neue Version verfügbar ist, werden Sie in stderr aufgefordert: none 🆕 A new CodeMender release is available: 1.1.0 Update now? (y/N): Wenn Sie „Ja“ (y oder yes) auswählen, lädt CodeMender das Update herunter, ersetzt die Binärdatei und wird beendet. Sie müssen den Befehl noch einmal ausführen, um ihn mit der neuen Version auszuführen. Wenn Sie „Nein“ auswählen, wird die Aktualisierung übersprungen und der ursprüngliche Befehl ausgeführt.
  • Offline-Toleranz: Wenn Sie offline sind oder das Release-Repository nicht erreichbar ist, schlägt die Prüfung ohne Fehlermeldung fehl und CodeMender führt Ihren Befehl weiter aus.
  • Überspringen: Sie können die automatische Updateprüfung überspringen, indem Sie das Flag --yes oder -y an einen beliebigen Befehl übergeben.

Manuelle Updates (cm update)

Sie können CodeMender mit dem Befehl update zwingen, sofort nach Updates zu suchen und diese anzuwenden:

cm update

Führen Sie den Befehl cm update aus:

  • Die 24-Stunden-Drosselung wird ignoriert.
  • Das Update wird sofort heruntergeladen und angewendet, ohne dass der Nutzer dazu aufgefordert wird (nicht interaktiv).
  • Erfordert kein interaktives Terminal (sicher für Scripts und Konfigurationsverwaltung).

Wenn die Befehlszeile in einem Systemverzeichnis installiert ist, für das erhöhte Berechtigungen erforderlich sind, führen Sie das Update mit sudo aus:

sudo cm update