CLI 설치 및 구성

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

아키텍처 및 보안 모델

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

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

환경 설정

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

프로젝트 설정 및 IAM 권한

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

필수 API

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

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

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

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

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

CodeMender CLI 다운로드 및 설치

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

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

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

1. 인증하려면 다음 명령어를 실행하고 로그인 메시지를 따릅니다.

   gcloud auth application-default login
   

2. GOOGLE_CLOUD_PROJECT 환경 변수를 Cloud de Confiance 프로젝트 ID로 설정합니다.

   export GOOGLE_CLOUD_PROJECT="PROJECT_ID"
   

   또는 활성 gcloud CLI 프로젝트를 구성합니다.

   gcloud config set project PROJECT_ID
   

   PROJECT_ID를 Cloud de Confiance 프로젝트 ID로 바꿉니다.

작업공간 초기화

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

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

cm init

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

cm init --verify

구성 매개변수 (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과 같은 명령어를 실행하면 로컬 클라이언트가 이 파일을 읽어 안전 매개변수를 설정하고, 시스템 우회를 적용하고, 무시할 파일 또는 디렉터리를 지정합니다.

핵심 기본 설정

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

• human_confirmation: true (또는 require_confirmation: true)

  • 의미: 기본적으로 CodeMender는 터미널에서 [Y/n] 확인을 명시적으로 요청하지 않고는 디스크의 파일을 수정하거나 셸 명령어를 실행할 수 없습니다.
  • 이 설정이 기본값인 이유: CodeMender는 취약점을 확인하기 위해 추측성 패치를 생성하거나 익스플로잇 스크립트를 실행하려고 시도할 수 있습니다. 사람의 확인을 강제하면 로컬 환경에서 실수로 인한 시스템 변경 또는 승인되지 않은 코드 실행을 방지할 수 있습니다.
  • 우회: 비대화형 CI/CD 파이프라인의 경우 false로 설정할 수 있습니다.

• confirm_writes: false

  • 의미: 파일 수정에 대한 대화형 프롬프트를 사용 중지하여 CodeMender 에이전트가 사람의 승인을 기다리지 않고 보안 패치를 작성하고 소스 파일을 로컬 디스크에 직접 수정할 수 있습니다.
  • 기본값인 이유: 기본적으로 CodeMender는 '휴먼인더루프' 워크플로를 적용하기 위해 이 안전 가드레일을 true로 설정합니다. CodeMender는 로컬 코드베이스에서 작동하므로 수동 확인 (예: Write? [Y/n])을 요구하면 에이전트가 소스 파일을 추측하거나 잘못되거나 파괴적인 방식으로 수정하는 것을 방지할 수 있습니다. 격리된 일회용 샌드박스 또는 자동화된 헤드리스 CI/CD 파이프라인에서 실행하는 경우에만 false로 전환해야 합니다.

• include: [".py", ".java", ".go", ".js", ".jsx", ".mjs", ".cjs", ".ts", ".tsx", ".c", ".cc", ".cpp", ".cxx", ".h", ".hpp", ".cs", ".rs", ".kt", ".kts", ".rb", ".php"]

  • 의미: 작업공간을 스캔할 때 CodeMender가 처리하고 분석하도록 승인하는 파일 확장자의 명시적 목록을 정의합니다. CodeMender는 이 목록에 지정되지 않은 확장자가 있는 저장소의 모든 파일을 자동으로 건너뜁니다.
  • 이 설정이 기본값인 이유: 이 목록은 스캔 효율성을 극대화하고 에이전트가 관련 없는 텍스트 파일, 빌드 아티팩트 또는 바이너리 파일에 시간과 토큰을 낭비하지 않도록 주요 프로그래밍 언어를 기본값으로 설정합니다. 하지만 최신 애플리케이션은 배포 구성이나 자동화 도구에 취약점을 삽입하는 경우가 많으므로 config.yaml에서 이 기본 목록을 수동으로 확장하여 구성 파일, 스크립트 형식, IaC 파일 (예: 셸 스크립트, XML, YAML, 속성, JSON 파일)을 포함할 수 있습니다. 이렇게 하면 CodeMender가 이러한 파일을 자동으로 무시하지 않습니다.

• exclude_dirs: ["node_modules", "vendor", "dist", "bin", "target", "obj", "build", ".gradle"]

  • 의미: CodeMender는 작업공간 스캔 및 코드 분석 중에 이러한 디렉터리를 완전히 건너뜁니다.
  • 기본값인 이유: 대규모 종속 항목 또는 빌드 폴더는 대규모 지연 시간 및 토큰 페널티를 트리거합니다. 기본적으로 이러한 항목을 제외하면 높은 성능과 빠른 응답 시간을 보장할 수 있습니다. 프로젝트 구조에 따라 특정 디렉터리를 포함하거나 제외하도록 config.yaml에서 이 목록을 맞춤설정할 수 있습니다.

• project_paths: []

  • 의미: 도구 실행 중에 CodeMender가 액세스 (읽기/쓰기)할 수 있는 디렉터리 경로 목록입니다.
  • 기본값인 이유: 기본적으로 비어 있으므로 에이전트가 스캔 대상 디렉터리로 제한됩니다. 빌드 또는 테스트 프로세스에서 스캔 대상 디렉터리 외부의 파일에 액세스해야 하는 경우 여기에 해당 경로를 추가해야 합니다.
  • 아티팩트 디렉터리: 에이전트는 세션별 아티팩트 디렉터리 (~/.codemender/artifacts/<session_id>/ 또는 $CM_HOME의 상응하는 디렉터리)에 쓸 수도 있습니다.
  • 임시 파일: 샌드박스가 사용 설정된 경우 /tmp를 project_paths에 추가하더라도 호스트 /tmp 디렉터리는 항상 차단됩니다. TMPDIR을 따르는 도구는 대신 아티팩트 디렉터리 내의 임시 디렉터리를 사용합니다.

• sandbox:

  • 의미: 프로세스 수준 샌드박스 환경의 구성 블록입니다.
  • 하위 매개변수:
    • enabled: true: (불리언) 샌드박스를 사용 설정하거나 사용 중지합니다. 이를 true (기본값)로 설정하면 에이전트가 로컬 샌드박스 내에서 도구를 실행합니다. false로 설정하면 에이전트가 격리 없이 호스트 시스템에서 직접 도구를 실행합니다.
    • mounts: (객체)
      • target_dir: ".": (문자열) 샌드박스 내에서 활성 작업공간으로 마운트할 디렉터리입니다. CLI는 작업공간 루트를 기준으로 상대 경로를 확인합니다.
    • network: (객체)
      • profile: "permissive-closed": (문자열) 샌드박스 내의 아웃바운드 네트워크 액세스 프로필입니다. 특정 도메인 또는 URL 패턴의 세분화된 허용 목록은 아직 지원되지 않습니다. 지원되는 프로필:
        • permissive-closed (기본값): 완전한 네트워크 격리입니다. 샌드박스가 모든 아웃바운드 연결을 차단합니다.
        • permissive-open: 전체 아웃바운드 네트워크 액세스를 허용합니다.

• security:

  • 의미: 보안 정책의 구성 블록입니다.
  • 하위 매개변수:
    • protected_files: []: (문자열 목록) 수정되지 않도록 샌드박스 내에 읽기 전용으로 마운트하려는 호스트 시스템의 파일 또는 디렉터리입니다 (예: ["~/.ssh/*"]). 경로 확장 (~) 및 와일드 카드 (*)를 지원합니다.

• 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는 격리된 샌드박스 환경에서 프로젝트를 컴파일하고 기존 테스트 모음을 실행하여 생성된 보안 패치가 기존 애플리케이션 로직을 중단하지 않고 취약점을 성공적으로 완화한다는 것을 증명할 수 있습니다.

실행 샌드박스

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

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

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

샌드박스 동작

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

1. 파일 시스템 격리: 에이전트는 허용된 디렉터리 내에서만 파일을 읽고 쓸 수 있습니다. 샌드박스는 이러한 디렉터리 외부의 모든 쓰기를 호스트 시스템에 영향을 주지 않고 임시 인메모리 파일 시스템 (tmpfs)으로 리디렉션합니다.
2. 네트워크 격리: 샌드박스는 기본적으로 아웃바운드 네트워크 액세스를 차단합니다. 이렇게 하면 에이전트 (또는 에이전트가 호출하는 빌드 도구)가 예기치 않은 외부 연결을 설정하거나 작업공간 외부로 데이터를 전송하는 것을 방지할 수 있습니다.

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

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

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

네트워크 종속 항목 처리

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

• 종속 항목 프리패치: cm 명령어를 실행하기 전에 호스트 시스템에 필요한 모든 종속 항목을 설치하므로 빌드 명령어에 네트워크 액세스가 필요하지 않습니다.

• 샌드박스에서 네트워크 액세스 사용 설정: config.yaml에서 네트워크 프로필을 변경하여 아웃바운드 연결을 허용합니다.

  sandbox:
    network:
      profile: "permissive-open"
  

• 샌드박스 우회: --unrestricted 플래그를 사용하여 명령어를 실행하면 해당 실행에 대해 샌드박스 및 파일 시스템 경계가 완전히 사용 중지됩니다.

샌드박스 구성

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

• 영구 구성 (config.yaml): config.yaml 파일에 sandbox, execution, security 블록을 추가하여 샌드박스 동작, 파일 시스템 마운트, 네트워크 액세스, 보안 정책을 맞춤설정할 수 있습니다. 자세한 내용은 구성 매개변수를 참조하세요.
• CLI를 사용하여 샌드박스 제어 (--sandbox): --sandbox=true 또는 --sandbox=false를 cm find, cm verify 또는 cm fix에 전달하여 단일 실행에 대해 샌드박스를 명시적으로 사용 설정하거나 사용 중지할 수 있습니다.
• CLI (--unrestricted)를 사용하여 격리 우회: --unrestricted 플래그를 전달하여 단일 실행에 대해 모든 샌드박스 보호를 일시적으로 우회할 수 있습니다. 이렇게 하면 파일 시스템 경로 경계가 사용 중지되어 에이전트가 호스트의 모든 경로에 액세스할 수 있으며, 네트워크 격리를 포함한 OS 수준 컨테이너 격리가 완전히 사용 중지됩니다.

격리 수준 선택

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

원격 분석

제품 상태를 모니터링하고 개선하기 위해 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