Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

CLI 설치 및 구성

CodeMender는 코드베이스의 심층적인 사이버 보안 취약점을 스캔, 검증, 패치하는 자율적인 AI 코드 보안 에이전트입니다. CodeMender를 실행하기 전에 CLI를 다운로드하고 작업공간 옵션을 초기화합니다.

아키텍처 및 보안 모델

CodeMender는 로컬 우선 실행 모델을 사용합니다.

호스팅된 추론 엔진: 에이전트 추론, 위협 모델링, 조정 로직이 Gemini Enterprise Agent Platform의 Google Cloud 에서 안전하게 실행됩니다.
로컬 실행 CLI: 소스 코드가 워크스테이션 또는 CI/CD 컨테이너에서 대량으로 유출되지 않습니다. 로컬 cm CLI 도구는 로컬 샌드박스에서 파일 읽기, 로컬 빌드 검사, 개념 증명 (PoC) 익스플로잇 확인을 실행하며, Gemini Enterprise Agent Platform의 Interactions API를 통해 정밀한 코드 스니펫과 도구 실행 결과만 클라우드 백엔드로 전송합니다.

환경 설정

CodeMender를 사용하려면 Google Cloud 프로젝트를 설정하고, CLI를 다운로드하여 설치하고, 사용자 인증 정보와 대상 프로젝트를 구성하고, 작업공간을 초기화합니다.

프로젝트 설정 및 IAM 권한

CLI를 다운로드하고 사용자 인증 정보를 구성하기 전에 대상 Google Cloud 프로젝트가 필요한 API 및 권한으로 올바르게 설정되어 있는지 확인합니다.

필수 API

프로젝트에 다음 Google Cloud API가 사용 설정되어 있는지 확인합니다.

Agent Platform API (aiplatform.googleapis.com) — 활성 세션의 스트리밍 및 관리를 지원합니다.
Cloud Resource Manager API (cloudresourcemanager.googleapis.com) — 사용자 인증 상태 및 프로젝트 메타데이터를 검증합니다.

권장되는 사전 정의된 IAM 역할

CLI 명령어를 실행하려면 사용자에게 다음 IAM 역할이 할당되어야 합니다.

Agent Platform 사용자 (roles/aiplatform.user) — 사용자가 활성 세션을 만들고, 스트리밍하고, 관리할 수 있습니다.

CodeMender CLI 다운로드 및 설치

CodeMender CLI 바이너리는 Artifact Registry에서 호스팅됩니다. 운영체제에 맞는 탭을 선택하여 CLI를 다운로드하고 설치합니다.

Linux x86_64

Linux (x86_64)용 CodeMender CLI를 다운로드하고 설치하려면 다음 안내를 따르세요.

다음 방법 중 하나를 사용하여 패키지를 다운로드합니다.

gcloud CLI: 다음 명령어를 실행합니다.

gcloud artifacts generic download \
  --project=cmoc-prod \
  --location=us \
  --repository=codemender-cli-production \
  --package=cm \
  --version=stable \
  --name=cm-linux-amd64.zip \
  --destination=./

curl: 다음 명령어를 실행합니다.

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"

CLI를 설치합니다.

unzip cm-linux-amd64.zip
chmod +x cm
sudo mv cm /usr/local/bin/cm

Linux ARM64

Linux용 CodeMender CLI (ARM64)를 다운로드하고 설치하려면 다음 안내를 따르세요.

다음 방법 중 하나를 사용하여 패키지를 다운로드합니다.

gcloud CLI: 다음 명령어를 실행합니다.

gcloud artifacts generic download \
  --project=cmoc-prod \
  --location=us \
  --repository=codemender-cli-production \
  --package=cm \
  --version=stable \
  --name=cm-linux-arm64.zip \
  --destination=./

curl: 다음 명령어를 실행합니다.

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"

CLI를 설치합니다.

unzip cm-linux-arm64.zip
chmod +x cm
sudo mv cm /usr/local/bin/cm

macOS Intel

macOS (Intel)용 CodeMender CLI를 다운로드하고 설치하려면 다음 안내를 따르세요.

다음 방법 중 하나를 사용하여 패키지를 다운로드합니다.

gcloud CLI: 다음 명령어를 실행합니다.

gcloud artifacts generic download \
  --project=cmoc-prod \
  --location=us \
  --repository=codemender-cli-production \
  --package=cm \
  --version=stable \
  --name=cm-darwin-amd64.zip \
  --destination=./

curl: 다음 명령어를 실행합니다.

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"

CLI를 설치합니다.

unzip cm-darwin-amd64.zip
chmod +x cm
mv cm /usr/local/bin/cm

macOS Apple Silicon

macOS (Apple Silicon)용 CodeMender CLI를 다운로드하고 설치하려면 다음 안내를 따르세요.

다음 방법 중 하나를 사용하여 패키지를 다운로드합니다.

gcloud CLI: 다음 명령어를 실행합니다.

gcloud artifacts generic download \
  --project=cmoc-prod \
  --location=us \
  --repository=codemender-cli-production \
  --package=cm \
  --version=stable \
  --name=cm-darwin-arm64.zip \
  --destination=./

curl: 다음 명령어를 실행합니다.

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"

CLI를 설치합니다.

unzip cm-darwin-arm64.zip
chmod +x cm
mv cm /usr/local/bin/cm

Windows x86_64

Windows (x86_64)용 CodeMender CLI를 다운로드하고 설치하려면 다음 안내를 따르세요.

다음 방법 중 하나를 사용하여 패키지를 다운로드합니다.

gcloud CLI: 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: 다음 명령어를 실행합니다.

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

CLI를 설치합니다.

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

Windows (ARM64)용 CodeMender CLI를 다운로드하고 설치하려면 다음 안내를 따르세요.

다음 방법 중 하나를 사용하여 패키지를 다운로드합니다.

gcloud CLI: 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: 다음 명령어를 실행합니다.

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

CLI를 설치합니다.

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)

Google Cloud 사용자 인증 정보 및 프로젝트 구성

CodeMender CLI는 Interactions API를 통해 클라우드 호스팅 추론 엔진과 상호작용하므로 Google Cloud 애플리케이션 기본 사용자 인증 정보 (ADC)를 구성하고 환경에서 대상 프로젝트를 지정해야 합니다.

인증하려면 다음 명령어를 실행하고 로그인 메시지를 따릅니다.
```
gcloud auth application-default login
```
GOOGLE_CLOUD_PROJECT 환경 변수를 Google Cloud 프로젝트 ID로 설정합니다.
```
export GOOGLE_CLOUD_PROJECT="PROJECT_ID"
```
또는 활성 gcloud CLI 프로젝트를 구성합니다.
```
gcloud config set project PROJECT_ID
```
PROJECT_ID를 Google Cloud 프로젝트 ID로 바꿉니다.

작업공간 초기화

사용자 인증 정보와 대상 프로젝트를 구성한 후 다음 단계는 로컬 환경에서 CodeMender를 초기화하는 것입니다. CodeMender를 초기화하면 상태 추적 파일을 만들고 클라우드 호스팅 추론 엔진에 대한 연결 설정을 설정하여 로컬 작업공간을 준비합니다.

코드베이스의 루트 디렉터리에서 cm init를 실행하여 로컬 상태 추적 파일을 만들고 기준 구성을 설정합니다.

cm init

--verify 플래그를 사용하여 클라우드 호스팅 추론 엔진에 대한 연결을 테스트하고 작업공간 설정을 확인합니다.

cm init --verify

서비스 연결 및 권한 확인

스캔을 시작하거나 작업공간을 수정하지 않고 사용자 인증 정보, 구성, 네트워크 도달 가능성, IAM 권한을 확인하려면 cm health를 실행합니다.

cm health

cm health 명령어는 4개의 순차적 검사를 실행하고 첫 번째 실패 레이어에서 중지됩니다. cm init를 실행하기 전에도 모든 디렉터리에서 cm health를 실행할 수 있습니다. 디스크에 쓰거나 모델 할당량을 소비하지 않습니다.

자동화된 CI/CD 프리플라이트 검사 또는 예약된 합성 모니터링의 경우 프로젝트 수준 IAM 검사를 건너뛸 때 실패하도록 --strict를 사용하고, 기계가 읽을 수 있는 JSON 보고서를 출력하려면 --json를 사용합니다.

cm health --strict --json

다음 표에서는 cm health 종료 코드를 설명합니다.

종료 코드	레이어	설명
`0`	—	모든 상태 점검을 통과했습니다.
`10`	`credentials`	CLI가 유효한 OAuth 또는 애플리케이션 기본 사용자 인증 정보 토큰을 가져올 수 없거나 서버에서 토큰을 거부했습니다 (`401 Unauthorized`).
`20`	`config`	로컬 `config.yaml` 파일, `--team-id` 플래그 또는 `CM_TEAM_ID` 환경 변수가 잘못되었습니다.
`30`	`reachability`	CLI가 Agent Platform API 엔드포인트에 연결할 수 없습니다 (예: DNS, TLS, 프록시 또는 VPC 서비스 제어 제한사항).
`40`	`authorization`	서버에 연결되었지만 호출자 또는 프로젝트에 CodeMender 스캔을 실행할 권한이 없습니다 (예: `roles/aiplatform.user` 권한 누락).
`50`	—	상태 점검이 `--timeout` 기간 (기본값 `30s`)을 초과했습니다.

cm health에서 지원하는 플래그는 다음과 같습니다.

플래그	기본값	설명
`--json`	`false`	`status`, `exit_code`, `backend`, `endpoint`, `location`, `project_id`, `agent_id`, `duration_ms`, `layers`, `warnings`(있는 경우), `error`를 포함하여 단일 JSON 객체를 표준 출력으로 출력합니다.
`--strict`	`false`	상태 점검 경고 (예: 확인되지 않거나 건너뛴 프로젝트 수준 IAM 권한 확인)를 종료 코드 `40` 실패로 처리합니다.
`--timeout`	`30s`	상태 점검 프로브의 전체 제한 시간을 설정합니다.

구성 매개변수 (`config.yaml`)

config.yaml의 주요 목표는 CodeMender 에이전트 동작을 로컬 시스템의 보안, 환경 제약 조건, 성능 요구사항에 맞추는 것입니다.

호스팅된 AI 에이전트는 로컬 데몬 클라이언트를 사용하여 로컬 명령어 (예: 코드 빌드, 테스트 실행, 파일 수정)를 실행하므로 이 구성 파일은 에이전트가 수행할 수 있는 작업과 수행할 수 없는 작업을 정의하는 경계 역할을 합니다.

사용

위치: 기본적으로 CLI는 ~/.codemender/config.yaml에서 이 파일을 읽습니다. CM_HOME 환경 변수 (예: /path/to/custom/dir/config.yaml를 읽는 CM_HOME=/path/to/custom/dir)를 설정하여 작업공간 및 구성 디렉터리를 재정의할 수 있습니다.
실행: cm find, cm verify, cm fix과 같은 명령어를 실행하면 로컬 클라이언트가 이 파일을 읽어 안전 매개변수를 설정하고, 시스템 우회를 적용하고, 무시할 파일 또는 디렉터리를 지정합니다.

핵심 기본 설정

핵심 기본 매개변수의 의미는 다음과 같습니다.

tools.confirm_commands: true
- 의미: 기본적으로 CodeMender는 셸 명령어 (run_command)를 실행하기 전에 터미널에서 [Y/n] 확인을 요청합니다. OS 수준 샌드박스가 사용 설정되고 (sandbox.enabled: true) 기본 네트워크 격리 (permissive-closed)가 적용된 상태에서 cm find가 실행되면 작업공간이 읽기 전용으로 마운트되고 명령어 확인 메시지가 자동으로 건너뛰어집니다.
- 기본값인 이유: CodeMender는 검증 및 패치 중에 빌드 명령어, 테스트 모음 또는 익스플로잇 스크립트를 실행할 수 있습니다. 작업공간이 쓰기 가능하거나 샌드박스 처리되지 않은 경우 확인을 요구하면 로컬 환경에서 의도하지 않은 명령어 실행을 방지할 수 있습니다.
- 우회: 단일 실행에 -y (또는 --yes)를 전달하거나 비대화형 CI/CD 파이프라인의 config.yaml에 tools.confirm_commands: false를 설정합니다.
tools.confirm_writes: true
- 의미: CodeMender 에이전트가 디스크에 파일을 쓰거나 수정하기 전에 터미널에서 [Y/n] 확인을 요청합니다 (write_to_file 및 search_and_replace).
- 이것이 기본값인 이유: 수동 확인을 요구하면 에이전트가 cm fix 또는 cm verify 중에 소스 파일을 추측하거나 의도하지 않게 수정하는 것을 방지할 수 있습니다. 격리된 일회용 환경 또는 자동화된 CI/CD 파이프라인에서 실행하는 경우에만 false로 설정하거나 -y/--yes를 전달하세요.
execution.interactive_mode: true
- 의미: 도구 실행 중에 대화형 터미널 프롬프트를 사용 설정합니다. 터미널이 연결되지 않은 헤드리스 CI/CD 환경에서는 이 값을 false로 설정하거나 -y/--yes를 전달합니다.
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"]
- 의미: 작업공간을 스캔할 때 CodeMender가 처리하고 분석하도록 승인하는 파일 확장자의 명시적 목록을 정의합니다. CodeMender는 이 목록에 지정되지 않은 확장자가 있는 저장소의 모든 파일을 자동으로 건너뜁니다.
- 이 설정이 기본값인 이유: 이 목록은 스캔 효율성을 극대화하고 에이전트가 관련 없는 텍스트 파일, 빌드 아티팩트 또는 바이너리 파일에 시간과 토큰을 낭비하지 않도록 주요 프로그래밍 언어를 기본값으로 설정합니다. 하지만 최신 애플리케이션은 배포 구성이나 자동화 도구에 취약점을 삽입하는 경우가 많으므로 config.yaml에서 이 기본 목록을 수동으로 확장하여 구성 파일, 스크립트 형식, IaC 파일 (예: 셸 스크립트, XML, YAML, 속성, JSON 파일)을 포함할 수 있습니다. 이렇게 하면 CodeMender가 이러한 파일을 자동으로 무시하지 않습니다.
scan.exclude_dirs: ["node_modules", "vendor", "dist", "/target", "/obj", "/build", ".gradle"]
- 의미: CodeMender는 작업공간 스캔 및 코드 분석 중에 이러한 디렉터리를 건너뜁니다. /로 시작하는 항목(예: /target, /obj, /build)은 스캔 루트에서만 일치하므로 해당 이름의 중첩된 소스 패키지는 건너뛰지 않습니다.
- 기본값인 이유: 대규모 종속 항목 또는 빌드 폴더는 대규모 지연 시간 및 토큰 페널티를 유발합니다. 기본적으로 이러한 항목을 제외하면 높은 성능과 빠른 응답 시간을 보장할 수 있습니다. 프로젝트 구조에 따라 특정 디렉터리를 포함하거나 제외하도록 config.yaml에서 이 목록을 맞춤설정할 수 있습니다.
project_paths: []
- 의미: 도구 실행 중에 CodeMender가 액세스 (읽기/쓰기)할 수 있는 디렉터리 경로 목록입니다.
- 기본값인 이유: 기본적으로 비어 있으므로 에이전트가 둘러싸는 프로젝트 루트 (또는 스캔 대상 디렉터리)로 제한됩니다. 빌드 또는 테스트 프로세스에서 프로젝트 루트 외부의 파일에 액세스해야 하는 경우 여기에 해당 경로를 추가하거나 단일 실행에 --allow-all-paths를 전달하세요. .git, .hg, .codemender에 대한 쓰기는 항상 차단됩니다.
- 아티팩트 디렉터리: 에이전트는 세션별 아티팩트 디렉터리 (~/.codemender/artifacts/<session_id>/ 또는 $CM_HOME의 상응하는 디렉터리)에 쓸 수도 있습니다.
- 임시 파일: 샌드박스가 사용 설정되면 /tmp를 project_paths에 추가하더라도 호스트 /tmp 디렉터리가 항상 차단됩니다. TMPDIR를 준수하는 도구는 대신 아티팩트 디렉터리 내의 임시 디렉터리를 사용합니다.
sandbox:
- 의미: 프로세스 수준 샌드박스 환경의 구성 블록입니다.
- 하위 매개변수:
  - enabled: true: (불리언) 샌드박스를 사용 설정하거나 사용 중지합니다. 이를 true (기본값)로 설정하면 에이전트가 로컬 샌드박스 내에서 도구를 실행합니다. false로 설정하거나 --sandbox=false를 전달하면 에이전트가 OS 수준 격리 없이 호스트 시스템에서 직접 도구를 실행합니다.
  - mounts: (객체)
    - target_dir: ".": (문자열) 샌드박스 내에서 활성 작업공간으로 마운트할 디렉터리입니다. CLI는 작업공간 루트를 기준으로 상대 경로를 확인합니다.
  - network: (객체)
    - profile: "permissive-closed": (문자열) 샌드박스 내의 아웃바운드 네트워크 액세스 프로필입니다. 특정 도메인 또는 URL 패턴의 세분화된 허용 목록은 아직 지원되지 않습니다. 지원되는 프로필:
      - permissive-closed (기본값): 완전한 네트워크 격리. 샌드박스가 모든 아웃바운드 연결을 차단합니다.
      - permissive-open: 전체 아웃바운드 네트워크 액세스를 허용합니다.
security:
- 의미: 보안 정책의 구성 블록입니다.
- 하위 매개변수:
  - protected_files: []: (문자열 목록) 수정되지 않도록 보호하기 위해 샌드박스 내에 읽기 전용으로 마운트하려는 호스트 시스템의 추가 파일 또는 디렉터리입니다. 경로 확장 (~) 및 와일드 카드 (*)를 지원합니다. protected_files가 비어 있는 경우에도 샌드박스는 항상 .git/hooks, .git/config, .hg/hgrc, .codemender를 읽기 전용으로 보호하고 일반 사용자 인증 정보 디렉터리 (~/.ssh, ~/.gnupg, ~/.aws, ~/.config/gcloud, ~/.config/gh, ~/.kube, ~/.docker)를 제외합니다.
model: "gemini-3.8-flash"
- 의미: 백엔드 추론 루프를 구동하는 기본 인텔리전스 엔진입니다.
- 기본값인 이유: gemini-3.8-flash는 패치를 제안하는 데 필요한 속도, 비용, 분석 추론의 최적의 균형을 제공합니다. (사용자는 필요에 따라 더 심층적이고 복잡한 추론을 위해 gemini-4-argon (Gemini 4 Argon)으로 재정의할 수 있습니다.)
vcs: { type: "git" }
- 의미: vcs 키를 통해 프로젝트에서 사용하는 버전 제어 시스템의 유형을 정의합니다. 구성하지 않으면 도구에서 Git 또는 Mercurial 저장소를 자동으로 식별하려고 시도합니다. vcs를 none로 설정하면 CLI에서 경고를 출력하지만 VCS 기능 없이 실행을 계속합니다. CodeMender는 이 설정을 사용하여 추측성 보안 수정사항을 관리하고, 코드베이스 수정사항을 추적하고, 로컬 저장소와 통합합니다.
- 기본값인 이유: CodeMender는 Git, Mercurial 또는 커스텀 VCS 구성을 지원합니다. Git은 버전 제어 추적의 업계 표준으로, 원활한 차이 통합과 롤백 안전성을 보장하므로 기본값으로 사용됩니다.
build: { command: "make build && make test" }
- 의미: CodeMender가 프로젝트를 컴파일하고 빌드하며 단위 및 회귀 테스트를 실행하기 위해 실행하는 정확한 셸 명령어를 정의합니다.
- 기본값인 이유: 빌드 및 테스트 명령어를 설정하는 것은 인증 워크플로에 매우 중요합니다. 이를 통해 CodeMender는 프로젝트를 컴파일하고 격리된 샌드박스 환경에서 기존 테스트 모음을 실행하여 생성된 보안 패치가 기존 애플리케이션 로직을 손상시키지 않고 취약점을 성공적으로 완화하는지 증명할 수 있습니다.

명령어 정책 (`command_policy.yaml`)

OS 수준 샌드박스 외에도 ~/.codemender/command_policy.yaml (전역) 및 <project>/.codemender/command_policy.yaml (프로젝트별)에서 명령어 차단 목록을 정의할 수 있습니다. 두 파일이 모두 있으면 CodeMender가 규칙을 병합합니다.

처음 실행하면 CodeMender가 ~/.codemender/command_policy.yaml에 주석 처리된 템플릿을 만듭니다. 다음 두 키에서 규칙의 주석 처리를 삭제하거나 규칙을 추가할 수 있습니다.

block: 모든 셸 파이프라인, 하위 셸, 명령어 대체에서 차단할 바이너리 이름 목록입니다 (예: curl, wget, ssh, sudo, rm).
block_patterns: 각 명령어 세그먼트와 일치하는 정규 표현식 목록입니다 (예: '\bgit\s+(push|commit|rebase|reset\s+--hard|clean)\b').

단일 명령어 호출에 대한 command_policy.yaml 시행을 우회하려면 --allow-all-commands 플래그를 전달합니다.

명령어 정책 (`command_policy.yaml`)

block: 모든 셸 파이프라인, 하위 셸, 명령어 대체에서 차단할 바이너리 이름 목록입니다 (예: curl, wget, ssh, sudo, rm).
block_patterns: 각 명령어 세그먼트와 일치하는 정규 표현식 목록입니다 (예: '\bgit\s+(push|commit|rebase|reset\s+--hard|clean)\b').

단일 명령어 호출에 대한 command_policy.yaml 시행을 우회하려면 --allow-all-commands 플래그를 전달합니다.

실행 샌드박스

의도하지 않은 파일 수정이나 예기치 않은 도구 부작용으로부터 워크스테이션을 보호하기 위해 CodeMender CLI는 기본적으로 OS 수준 샌드박스 내에서 실행됩니다. 구성에서 샌드박스를 영구적으로 사용 중지하거나 CLI 플래그를 사용하여 명령어별로 우회할 수 있습니다.

이 샌드박스는 워크스테이션에 초기 방어 레이어를 제공하지만 완전히 격리된 가상 머신 (VM)에서 에이전트를 실행하는 것보다 보안 보호 기능이 약합니다.

Linux: 커널 네임스페이스 (CLONE_NEWNS, CLONE_NEWUSER 등)와 seccomp 필터를 사용하여 마운트 지점을 격리하고 시스템 호출을 제한합니다.
macOS: 내장된 sandbox-exec (Seatbelt) 메커니즘을 사용합니다.
Windows (실험용): AppContainer 격리 및 액세스 제어 목록 (ACL)을 사용합니다. Windows의 샌드박스는 실험적인 기능이며 관리자 권한이 필요하거나 일부 시스템 구성과 호환되지 않을 수 있습니다.

샌드박스 동작

샌드박스가 활성 상태인 경우:

파일 시스템 격리: 에이전트는 허용된 디렉터리 내의 파일에만 액세스할 수 있습니다. cm find 중에는 작업공간과 허용된 루트가 읽기 전용으로 마운트되므로 명령어는 세션별 아티팩트 디렉터리에만 쓸 수 있습니다. 모든 명령어(cm verify 및 cm fix 포함)에서 .git/hooks, .git/config, .hg/hgrc, .codemender는 읽기 전용으로 마운트되므로 샌드박스 처리된 명령어는 Git 또는 Mercurial 후크를 설치하거나 CodeMender 구성을 수정할 수 없습니다.
네트워크 격리: 샌드박스는 기본적으로 아웃바운드 네트워크 액세스를 차단합니다 (sandbox.network.profile: "permissive-closed"). 이렇게 하면 에이전트 (또는 에이전트가 호출하는 빌드 도구)가 예기치 않은 외부 연결을 만들거나 작업공간 외부로 데이터를 전송하는 것을 방지할 수 있습니다.
사용자 인증 정보 및 보안 비밀 격리: 샌드박스는 일반적인 호스트 사용자 인증 정보 디렉터리 (~/.ssh, ~/.gnupg, ~/.aws, ~/.config/gcloud, ~/.config/gh, ~/.kube, ~/.docker 등)를 제외하고 명령어를 실행하기 전에 보안 비밀 패턴 (*_TOKEN, *_SECRET, *_KEY, *_PASSWORD, *_CREDENTIALS 및 유사한 서픽스)과 일치하는 환경 변수를 삭제합니다.

빌드 및 검증 중 네트워크 액세스

샌드박스는 기본적으로 네트워크 격리를 사용 설정하므로 (sandbox.network.profile의 기본값은 permissive-closed) 도구 실행 중에 에이전트가 인터넷에 액세스할 수 없습니다.

이로 인해 빌드 또는 확인 단계 중에 외부 종속 항목을 가져와야 하는 프로젝트에 제한이 발생합니다 (예: build.command의 일부로 npm install, pip install 또는 go get 실행). 빌드 프로세스에서 외부 웹 서비스에 액세스하려고 하면 실패합니다.

네트워크 종속 항목 처리

프로젝트에서 빌드 또는 테스트를 위해 네트워크 액세스가 필요한 경우 다음 옵션을 사용할 수 있습니다.

종속 항목 프리패치: cm 명령어를 실행하기 전에 호스트 시스템에 필요한 모든 종속 항목을 설치하므로 빌드 명령어에 네트워크 액세스가 필요하지 않습니다.
샌드박스에서 네트워크 액세스 사용 설정: config.yaml에서 네트워크 프로필을 변경하여 아웃바운드 연결을 허용합니다.
```
sandbox:
  network:
    profile: "permissive-open"
```
참고: 특정 도메인 또는 URL 패턴의 세분화된 허용 목록 (예: npmjs.org만 허용 목록에 추가)은 아직 지원되지 않습니다. permissive-open는 샌드박스에 대한 전체 아웃바운드 액세스 권한을 부여합니다.
실행을 위해 샌드박스 사용 중지: --sandbox=false 플래그를 사용하여 명령어를 실행하면 해당 실행에 대해 OS 수준 샌드박스 (네트워크 격리 포함)가 사용 중지됩니다.

샌드박스 구성

다음 옵션을 사용하여 샌드박스 및 보안 경계를 구성하고 제어할 수 있습니다.

영구 구성 (config.yaml 및 command_policy.yaml): config.yaml 및 command_policy.yaml에서 샌드박스 동작, 파일 시스템 마운트, 네트워크 액세스, 명령어 차단 목록을 맞춤설정합니다. 자세한 내용은 구성 매개변수 및 명령어 정책을 참조하세요.
OS 수준 샌드박스 제어 (--sandbox): --sandbox=true 또는 --sandbox=false를 cm find, cm verify, cm fix 또는 cm session resume에 전달하여 단일 실행에 대해 OS 수준 샌드박스를 명시적으로 사용 설정 또는 사용 중지합니다.
경로 경계 우회 (--allow-all-paths): 단일 실행에 대해 작업공간 경로 경계 검사를 사용 중지하여 에이전트 도구가 프로젝트 루트 및 구성된 project_paths 외부의 경로에 액세스할 수 있도록 합니다(--sandbox=false와 결합하여 샌드박스 내에 마운트되지 않은 호스트 경로에 액세스).
명령어 정책 우회 (--allow-all-commands): 단일 실행에 대해 command_policy.yaml 차단 목록 시행을 사용 중지합니다.

격리 수준 선택

보안 요구사항과 개발 환경에 따라 CodeMender CLI를 실행하는 데 적합한 격리 수준을 선택할 수 있습니다.

메서드	설명	장점	단점
기본 제공 샌드박스 (OS 수준)	기본적으로 사용 설정되어 있습니다. `config.yaml` 파일에서 사용 중지하거나 CLI 플래그를 사용하여 우회할 수 있습니다. 기본 제공 OS 기능 (네임스페이스/seccomp, `sandbox-exec`, `AppContainer` (실험용))을 사용하여 실행을 격리합니다.	가벼움, 시작 오버헤드 없음, 세분화된 제어를 통해 로컬 작업공간 도구에 직접 액세스 일상적인 로컬 개발에 권장됩니다.	보안은 OS 커널 기능에 의존하며, 전체 VM보다 격리 수준이 낮습니다. Windows 지원은 실험적이며 관리자 권한이 필요하거나 일부 구성과 호환되지 않을 수 있습니다.
컨테이너	컨테이너 (예: Docker)에서 에이전트 실행	격리 우수, 표준화된 환경	컨테이너 런타임이 필요하며, 무거울 수 있고, 로컬 머신의 도구와 직접 상호작용할 수 없습니다.
전체 VM	전용 VM에서 에이전트 실행	최대 보안, 완전한 격리	리소스 오버헤드가 높고, 시작이 느리며, 로컬 머신의 도구와 직접 상호작용할 수 없습니다.

원격 분석

제품 상태를 모니터링하고 개선하기 위해 CLI를 통해 익명 원격 분석 데이터를 수집합니다. Google은 기본 사용량 측정항목 및 성능 진단을 포함하여 수집된 모든 데이터를 완전히 익명 처리합니다. 원격 분석은 소스 코드, 파일 콘텐츠, 발견 항목, 패치 또는 사용자 ID를 수집하거나 전송하지 않습니다.

기본적으로 원격 분석은 사용 설정되어 있습니다. 원격 분석을 사용 중지하려면 CM_TELEMETRY_OPT_OUT 환경 변수를 1 또는 true로 설정합니다.

CLI 업데이트

CodeMender에는 최신 버전의 CLI를 실행할 수 있도록 하는 업데이트 메커니즘이 내장되어 있습니다.

자동 업데이트 확인

기본적으로 CodeMender CLI는 명령어를 실행할 때 백그라운드에서 업데이트를 자동으로 확인합니다.

제한: 오버헤드를 최소화하기 위해 자동 검사는 최대 24시간마다 한 번 실행됩니다.
대화형 터미널 (TTY) 필요: CLI는 대화형 터미널에서 실행될 때만 업데이트를 확인하고 메시지를 표시합니다. 비대화형 환경 (예: CI/CD 파이프라인 또는 스크립트)에서는 검사가 건너뛰어지고 경고가 하루에 최대 한 번 stderr에 로깅됩니다.
프롬프트: 새 버전을 사용할 수 있는 경우 stderr에 메시지가 표시됩니다. none 🆕 A new CodeMender release is available: 1.1.0 Update now? (y/N): 예 (y 또는 yes)를 선택하면 CodeMender가 업데이트를 다운로드하고 바이너리를 교체한 후 종료됩니다. 새 버전으로 실행하려면 명령어를 다시 실행해야 합니다. '아니요'를 선택하면 업데이트를 건너뛰고 원래 명령어가 실행됩니다.
오프라인 허용: 오프라인 상태이거나 출시 저장소에 연결할 수 없는 경우 검사가 자동으로 실패하고 CodeMender가 명령어를 계속 실행합니다.
우회: --yes 또는 -y 플래그를 명령어에 전달하여 자동 업데이트 확인을 우회할 수 있습니다.

수동 업데이트 (`cm update`)

update 명령어를 실행하여 CodeMender가 업데이트를 즉시 확인하고 적용하도록 강제할 수 있습니다.

cm update

cm update 명령어:

24시간 제한을 무시합니다.
메시지를 표시하지 않고 즉시 업데이트를 다운로드하고 적용합니다 (비대화형).
대화형 터미널이 필요하지 않습니다 (스크립트 및 구성 관리에 안전함).

CLI가 높은 권한이 필요한 시스템 디렉터리에 설치된 경우 sudo를 사용하여 업데이트를 실행합니다.

sudo cm update

CLI 설치 및 구성 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

아키텍처 및 보안 모델

환경 설정

프로젝트 설정 및 IAM 권한

필수 API

권장되는 사전 정의된 IAM 역할

CodeMender CLI 다운로드 및 설치

Linux x86_64

Linux ARM64

macOS Intel

macOS Apple Silicon

Windows x86_64

Windows ARM64

Google Cloud 사용자 인증 정보 및 프로젝트 구성

작업공간 초기화

서비스 연결 및 권한 확인

구성 매개변수 (config.yaml)

사용

핵심 기본 설정

명령어 정책 (command_policy.yaml)

명령어 정책 (command_policy.yaml)

실행 샌드박스

샌드박스 동작

빌드 및 검증 중 네트워크 액세스

네트워크 종속 항목 처리

샌드박스 구성

격리 수준 선택

원격 분석

CLI 업데이트

자동 업데이트 확인

수동 업데이트 (cm update)

CLI 설치 및 구성

구성 매개변수 (`config.yaml`)

명령어 정책 (`command_policy.yaml`)

명령어 정책 (`command_policy.yaml`)

수동 업데이트 (`cm update`)