Sandbox für Cortex Code-CLI¶

Die Cortex Code-CLI kann Shell-Befehle innerhalb einer Sandbox ausführen, um den Zugriff auf das Dateisystem, den Netzwerkzugriff und die Verarbeitungsmöglichkeiten einzuschränken. Sandboxing fügt eine Isolationsebene hinzu, sodass der Agent nicht versehentlich Dateien ändern oder auf Ressourcen außerhalb Ihres Projekts zugreifen kann.

Wichtig

Die Unterstützung dieses Features ist experimentell und kann sich ändern.

Plattformunterstützung¶

Die Sandbox verwendet die integrierten Isolationsfeatures des Betriebssystems, um Befehle einzuschränken.


Plattform	Implementierung	Abhängigkeiten
macOS	`sandbox-exec` (integriert)	`ripgrep`
Linux	`bubblewrap`	`bubblewrap`, `socat` und `ripgrep`
Windows	Native eingeschränkte Token	Keine

Installieren von Abhängigkeiten¶

macOS:

brew install ripgrep

Debian / Ubuntu:

sudo apt-get install bubblewrap socat ripgrep

Fedora / RHEL:

sudo dnf install bubblewrap socat ripgrep

Aktivieren der Sandbox¶

Verwenden Sie den Schrägstrich-Befehl /sandbox in der Cortex Code-CLI:

/sandbox                          # Interactive selector
/sandbox runtime on               # Enable sandbox
/sandbox runtime off              # Disable sandbox
/sandbox runtime status           # Show sandbox status
/sandbox status                   # Show current sandbox status

Sie können die Sandbox auch in Ihrer Einstellungsdatei aktivieren. Fügen Sie ein sandbox-Objekt in ~/.snowflake/cortex/settings.json (Benutzerebene) oder .snowflake/cortex/settings.json (Projektebene) ein:

{
  "sandbox": {
    "enabled": true
  }
}

Der Standardberechtigungsmodus ist "regular". Um den automatischen Zulassungsmodus zu verwenden, legen Sie "mode": "autoAllow" explizit fest. Siehe Berechtigungsmodi.

Berechtigungsmodi¶

Die Sandbox verfügt über zwei Berechtigungsmodi, die steuern, wie Befehle genehmigt werden:


Modus	Einstellungswert	Verhalten
Automatisches Zulassen	`"autoAllow"`	Befehle, die in einer Sandbox ausgeführt werden können, werden automatisch ohne Aufforderung ausgeführt. Befehle, die nicht in einer Sandbox ausgeführt werden können (z. B. solche, die den Netzwerkzugriff auf nicht zulässige Domänen erfordern), greifen auf den normalen Berechtigungsablauf zurück.
Regulär	`"regular"`	Alle Befehle erfordern eine Genehmigung, auch wenn sie innerhalb der Sandbox ausgeführt werden.

Legen Sie den Modus mit dem /sandbox-Befehl oder in den Einstellungen fest:

/sandbox mode auto                # Set auto-allow mode
/sandbox mode regular             # Set regular mode

Dateisystemeinschränkungen¶

Die Sandbox steuert, auf welche Pfade Befehle zugreifen und in welche sie schreiben dürfen.

Standardverhalten¶

Arbeitsverzeichnis: Für Lese- und Schreibvorgänge immer zulässig.
Skills-Verzeichnis (~/.snowflake/cortex/skills): Zulässig.
Kontextverzeichnis (~/.snowflake/cortex/.ctx): Zulässig, wenn ctxAvailable aktiviert ist.

Geschützte Pfade (für Schreibvorgänge immer verweigert)¶

Die folgenden Pfade sind immer geschützt, unabhängig von Ihrer Konfiguration:

Shell-Konfigurationsdateien: ~/.bashrc, ~/.bash_profile, ~/.zshrc, ~/.zprofile, ~/.profile, ~/.bash_login, ~/.bash_logout
Git-Hooks: ~/.git/hooks, .git/hooks
SSH-Konfiguration: ~/.ssh/authorized_keys, ~/.ssh/config
Verzeichnisse und Dateien für verwaltete Einstellungen: /Library/Application Support/Cortex/ (macOS), /etc/cortex/ (Linux), %ProgramData%\Cortex\ (Windows)

Kundenspezifische Dateisystemregeln¶

Konfigurieren Sie den Dateisystemzugriff in den Einstellungen:

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowRead": [],
      "denyRead": ["/private/secrets"],
      "allowWrite": ["/tmp", "~/projects"],
      "denyWrite": ["/etc", "/var"]
    }
  }
}


Einstellung	Standard	Beschreibung
`allowRead`	`[]` (alle zulassen)	Pfade, die die Sandbox lesen kann. Ein leeres Array bedeutet, dass alle Pfade zulässig sind (außer die in``denyRead``).
`denyRead`	`[]`	Pfade, die die Sandbox nicht lesen kann. Hat Vorrang vor `allowRead`.
`allowWrite`	`[]` (nur Arbeitsverzeichnis)	Pfade, in die die Sandbox schreiben kann.
`denyWrite`	`[]`	Pfade, in die die Sandbox nicht schreiben kann. Hat Vorrang vor `allowWrite`.

Wichtig

Ablehnungsregeln haben immer Vorrang vor Zulassungsregeln. Wenn ein Pfad sowohl allowWrite als auch denyWrite entspricht, wird der Pfad abgelehnt.

Netzwerkeinschränkungen¶

Die Sandbox kann einschränken, auf welche Domänen Befehle über das Netzwerk zugreifen können.

{
  "sandbox": {
    "enabled": true,
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org", "registry.yarnpkg.com"],
      "deniedDomains": ["*.internal.company.com"],
      "allowLocalBinding": false
    }
  }
}


Einstellung	Standard	Beschreibung
`allowedDomains`	`[]` (alle zulassen)	Domänen, auf die die Sandbox zugreifen kann. Ein leeres Array bedeutet, dass alle Domänen zulässig sind (außer die in``deniedDomains``). Unterstützt Platzhalter (`*.example.com`).
`deniedDomains`	`[]`	Domänen, auf die die Sandbox nicht zugreifen kann. Hat Vorrang vor `allowedDomains`. Unterstützt Platzhalter.
`allowLocalBinding`	`false`	Gibt an, ob Sandbox-Befehle lokale Ports binden können.

Fallback für Befehle, die außerhalb der Sandbox ausgeführt werden¶

Einige Befehle sind möglicherweise nicht mit der Sandbox kompatibel. Die Einstellung allowUnsandboxedCommands steuert, was passiert, wenn ein Befehl nicht innerhalb der Sandbox ausgeführt werden kann.


Einstellung	Verhalten
`true` (Standard)	Der Agent kann anfordern, dass der Befehl auf dem Host ausgeführt wird. Sie werden aufgefordert, dies zu genehmigen.
`false`	Die Befehle müssen innerhalb der Sandbox ausgeführt werden oder in `excludedCommands` aufgeführt sein. Wenn keines von beiden zutrifft, schlägt der Befehl fehl.

Ausgeschlossene Befehle¶

Sie können Befehle angeben, die immer auf dem Host außerhalb der Sandbox ausgeführt werden sollen:

{
  "sandbox": {
    "enabled": true,
    "allowUnsandboxedCommands": true,
    "excludedCommands": ["docker", "kubectl"]
  }
}

Ausgeschlossene Befehle umgehen die Sandbox und folgen dem normalen Berechtigungsablauf.

Einstellungsreferenz¶

Die vollständige sandbox-Einstellungsobjekt:

{
  "sandbox": {
    "enabled": false,
    "mode": "regular",
    "allowUnsandboxedCommands": true,
    "excludedCommands": [],
    "permissions": {
      "allow": [],
      "deny": []
    },
    "network": {
      "allowedDomains": [],
      "deniedDomains": [],
      "allowLocalBinding": false
    },
    "filesystem": {
      "allowRead": [],
      "denyRead": [],
      "allowWrite": [],
      "denyWrite": []
    },
    "ctxAvailable": true
  }
}


Einstellung	Standard	Beschreibung
`enabled`	`false`	Aktivieren oder Deaktivieren der Sandbox.
`mode`	`"regular"`	Berechtigungsmodus: `"regular"` oder `"autoAllow"`.
`allowUnsandboxedCommands`	`true`	Zulassen des Fallbacks für eine Ausführung auf dem Host, wenn ein Befehl nicht in einer Sandbox ausgeführt werden kann.
`excludedCommands`	`[]`	Befehle, die immer auf dem Host außerhalb der Sandbox ausgeführt werden.
`permissions.allow`	`[]`	Zulassungsregeln für allgemeine Berechtigungen. Unterstützt Muster wie `WebFetch(domain:example.com)`, `Edit(path)`, `Read(path)`, `Bash(command)`.
`permissions.deny`	`[]`	Ablehnungsregeln für allgemeine Berechtigungen. Gleiche Mustersyntax wie `permissions.allow`. Hat Vorrang vor Zulassungsregeln.
`network.allowedDomains`	`[]`	Zulassungsliste für Netzwerkdomänen (leer = alle zulassen). Unterstützt Platzhalter.
`network.deniedDomains`	`[]`	Ablehnungsliste für Netzwerkdomänen Hat Vorrang vor Zulassungsliste.
`network.allowLocalBinding`	`false`	Zulassen, dass Sandbox-Befehle lokale Ports binden können.
`filesystem.allowRead`	`[]`	Lesen der Zulassungsliste (leer = alle zulassen außer ‚deny‘).
`filesystem.denyRead`	`[]`	Lesen der Ablehnungsliste. Hat Vorrang.
`filesystem.allowWrite`	`[]`	Schreiben der Zulassungsliste.
`filesystem.denyWrite`	`[]`	Schreiben der Ablehnungsliste. Hat Vorrang.
`ctxAvailable`	`true`	Erlauben des Sandbox-Zugriffs auf das Kontextverzeichnis (`~/.snowflake/cortex/.ctx`), das zum Speichern des Konversationskontexts und der Sitzungsdaten verwendet wird.

Konfigurationsbereiche¶

Sandbox-Einstellungen folgen der gleichen Priorität wie andere Cortex Code-Einstellungen:

Projektebene (höchste Priorität): .snowflake/cortex/settings.json
Benutzerebene: ~/.snowflake/cortex/settings.json
Verwaltet/erzwungen: Admins können die Sandbox-Richtlinie über die Datei für verwaltete Einstellungen durchsetzen. Siehe Verwaltete Einstellungen (Organisationsrichtlinie).