Cortex Code CLI 샌드박스¶

Cortex Code CLI는 샌드박스 내에서 셸 명령을 실행하여 파일 시스템 액세스, 네트워크 액세스 및 프로세스 기능을 제한할 수 있습니다. 샌드박싱은 에이전트가 실수로 파일을 수정하거나 프로젝트 외부의 리소스에 액세스할 수 없도록 격리 계층을 추가합니다.

중요

이 기능에 대한 지원은 실험적 단계에 있으며 변경될 수 있습니다.

플랫폼 지원¶

샌드박스는 운영 체제의 기본 제공 격리 기능을 사용하여 명령을 제한합니다.


플랫폼	구현	종속성
macOS	``sandbox-exec``(기본 제공)	`ripgrep`
Linux	`bubblewrap`	`bubblewrap`, `socat`, `ripgrep`
Windows	네이티브 제한 토큰	없음

종속성 설치하기¶

macOS:

brew install ripgrep

Debian / Ubuntu:

sudo apt-get install bubblewrap socat ripgrep

Fedora/RHEL:

sudo dnf install bubblewrap socat ripgrep

샌드박스 활성화하기¶

Cortex Code CLI에서 /sandbox 슬래시 명령을 사용합니다.

/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

설정 파일에서 샌드박스를 활성화할 수도 있습니다. sandbox 오브젝트를 ``~/.snowflake/cortex/settings.json``(사용자 수준) 또는 ``.snowflake/cortex/settings.json``(프로젝트 수준)에 추가합니다.

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

기본 권한 모드는 ``”regular”``입니다. 자동 허용 모드를 사용하려면 ``”mode”: “autoAllow”``를 명시적으로 설정합니다. 권한 모드 섹션을 참조하십시오.

권한 모드¶

샌드박스에는 명령이 승인되는 방식을 제어하는 두 가지 권한 모드가 있습니다.


모드	설정 값	동작
자동 허용	`"autoAllow"`	샌드박스 처리할 수 있는 명령은 메시지를 표시하지 않고 자동으로 실행됩니다. 샌드박스 처리할 수 없는 명령(예: 허용되지 않는 도메인에 대한 네트워크 액세스가 필요한 명령)은 일반 권한 흐름으로 대체됩니다.
일반	`"regular"`	모든 명령은 샌드박스 내에서 실행 중일 때도 승인을 요청하는 메시지를 표시합니다.

/sandbox 명령으로 또는 설정에서 모드를 설정합니다.

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

파일 시스템 제한 사항¶

샌드박스는 명령이 읽고 쓸 수 있는 경로를 제어합니다.

기본 동작¶

작업 디렉터리: 읽기 및 쓰기에 항상 허용됩니다.
**스킬 디렉터리**(~/.snowflake/cortex/skills): 허용됩니다.
**컨텍스트 디렉터리**(~/.snowflake/cortex/.ctx): ``ctxAvailable``이 활성화된 경우 허용됩니다.

보호된 경로(쓰기에 대해 항상 거부됨)¶

다음 경로는 구성에 관계없이 항상 보호됩니다.

셸 구성 파일: ~/.bashrc, ~/.bash_profile, ~/.zshrc, ~/.zprofile, ~/.profile, ~/.bash_login, ~/.bash_logout
Git 후크: ~/.git/hooks, .git/hooks
SSH 구성: ~/.ssh/authorized_keys, ~/.ssh/config
관리 설정 디렉터리 및 파일: ``/Library/Application Support/Cortex/``(macOS), ``/etc/cortex/``(Linux), ``%ProgramData%Cortex``(Windows)

사용자 지정 파일 시스템 규칙¶

설정에서 파일 시스템 액세스를 구성합니다.

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


설정	기본값	설명
`allowRead`	``[]``(모두 허용)	샌드박스가 읽을 수 있는 경로입니다. 빈 배열은 모든 경로가 허용됨을 의미합니다(``denyRead``에 있는 경로 제외).
`denyRead`	`[]`	샌드박스가 읽을 수 없는 경로입니다. ``allowRead``보다 우선합니다.
`allowWrite`	``[]``(작업 디렉터리만 해당)	샌드박스가 쓸 수 있는 경로입니다.
`denyWrite`	`[]`	샌드박스가 쓸 수 없는 경로입니다. ``allowWrite``보다 우선합니다.

중요

거부 규칙은 항상 허용 규칙보다 우선합니다. 경로가 allowWrite 및 denyWrite 모두와 일치하는 경우 경로가 거부됩니다.

네트워크 제한 사항¶

샌드박스는 명령이 네트워크를 통해 액세스할 수 있는 도메인을 제한할 수 있습니다.

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


설정	기본값	설명
`allowedDomains`	``[]``(모두 허용)	샌드박스가 액세스할 수 있는 도메인입니다. 빈 배열은 모든 도메인이 허용됨을 의미합니다(deniedDomains``에 있는 도메인 제외). 와일드카드(``*.example.com)를 지원합니다.
`deniedDomains`	`[]`	샌드박스가 액세스할 수 없는 도메인입니다. ``allowedDomains``보다 우선합니다. 와일드카드를 지원합니다.
`allowLocalBinding`	`false`	샌드박스 처리된 명령이 로컬 포트에 바인딩할 수 있는지 여부입니다.

샌드박스 처리되지 않은 명령 대체¶

일부 명령은 샌드박스와 호환되지 않을 수 있습니다. allowUnsandboxedCommands 설정은 샌드박스 내에서 명령을 실행할 수 없을 때 발생하는 동작을 제어합니다.


설정	동작
`true` (기본값)	에이전트가 호스트에서 명령 실행을 요청할 수 있습니다. 승인하라는 메시지가 표시됩니다.
`false`	명령이 샌드박스 내에서 실행되거나 ``excludedCommands``에 나열되어야 합니다. 둘 다 적용되지 않으면 명령이 실패합니다.

제외된 명령¶

샌드박스 외부의 호스트에서 항상 실행해야 하는 명령을 지정할 수 있습니다.

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

제외된 명령은 샌드박스를 우회하고 일반적인 권한 흐름을 따릅니다.

설정 참조¶

전체 sandbox 설정 오브젝트는 다음과 같습니다.

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


설정	기본값	설명
`enabled`	`false`	샌드박스를 활성화하거나 비활성화합니다.
`mode`	`"regular"`	권한 모드: `"regular"` 또는 ``”autoAllow”``입니다.
`allowUnsandboxedCommands`	`true`	명령을 샌드박스 처리할 수 없는 경우 호스트 실행에 대한 대체를 허용합니다.
`excludedCommands`	`[]`	샌드박스 외부의 호스트에서 항상 실행되는 명령입니다.
`permissions.allow`	`[]`	상위 수준 권한 허용 규칙입니다. `WebFetch(domain:example.com)`, `Edit(path)`, `Read(path)`, ``Bash(command)``와 같은 패턴을 지원합니다.
`permissions.deny`	`[]`	상위 수준 권한 거부 규칙입니다. ``permissions.allow``와 동일한 패턴 구문입니다. 허용 규칙보다 우선합니다.
`network.allowedDomains`	`[]`	네트워크 도메인 허용 목록입니다(비어 있음 = 모두 허용). 와일드카드를 지원합니다.
`network.deniedDomains`	`[]`	네트워크 도메인 거부 목록입니다. 허용 목록보다 우선합니다.
`network.allowLocalBinding`	`false`	샌드박스 처리된 명령이 로컬 포트에 바인딩되도록 허용합니다.
`filesystem.allowRead`	`[]`	허용 목록을 읽습니다(비어 있음 = 거부를 제외하고 모두 허용).
`filesystem.denyRead`	`[]`	거부 목록을 읽습니다. 우선합니다.
`filesystem.allowWrite`	`[]`	허용 목록을 작성합니다.
`filesystem.denyWrite`	`[]`	거부 목록을 작성합니다. 우선합니다.
`ctxAvailable`	`true`	대화 컨텍스트 및 세션 데이터를 저장하는 데 사용되는 컨텍스트 디렉터리(`~/.snowflake/cortex/.ctx`)에 대한 샌드박스 액세스를 허용합니다.

구성 범위¶

샌드박스 설정은 다른 Cortex Code 설정과 동일한 우선 순위를 따릅니다.

**프로젝트 수준**(최고 우선 순위): .snowflake/cortex/settings.json
사용자 수준: ~/.snowflake/cortex/settings.json
관리/적용: 관리자는 관리 설정 파일을 통해 샌드박스 정책을 적용할 수 있습니다. 관리형 설정(조직 정책) 섹션을 참조하십시오.