Codex Security CLI 빠른 시작

Codex Security는 보안 및 엔지니어링 팀이 취약점을 찾고 확인하며 수정하도록 지원합니다. 명령줄 인터페이스(CLI)를 사용하여 소유하고 있거나 평가 권한이 있는 저장소를 검사하고, 시간 경과에 따른 발견 항목을 검토하며, 변경 사항이 반영되기 전에 확인하세요.

사전 요구 사항 확인

CLI를 사용하려면 Node.js 22(22.13.0 이상), 24 또는 26이 필요합니다. 검사, 대량 검사, 내보내기, 검사 기록 및 저장된 발견 항목을 사용하려면 Python 3.10 이상도 필요합니다. 자세한 내용은 인증 및 사전 요구 사항을 참조하세요.

CLI 설정 및 확인

npx로 CLI를 실행하고 버전을 확인합니다.

npx @openai/codex-security --version

패키지 버전과 번들 플러그인 버전을 모두 확인하려면 다음을 실행합니다.

npx @openai/codex-security info --json

패키지 변경 사항은 CLI 및 SDK 릴리스를 참조하세요.

사용 가능한 명령을 나열합니다.

npx @openai/codex-security --help

CLI 참조도 확인하세요.

검사 준비

신뢰하며 평가 권한이 있는 저장소를 선택하세요. 검사는 로컬 운영 체제 권한을 사용하며 승인을 기다리지 않습니다. 검사 프로세스가 환경을 상속할 수 있으므로 시작하기 전에 관련 없는 자격 증명을 제거하세요. 로컬 검사 권한을 참조하세요.

검사 결과를 저장할 저장소 외부의 디렉터리를 선택합니다.

REPOSITORY=/path/to/repository
SCAN_DIR=/path/outside/repository/codex-security-results

--output-dir을 생략하면 Codex Security는 자체 영구 상태 디렉터리에 결과를 저장합니다. 결과에는 소스 발췌문과 취약점 세부 정보가 포함될 수 있으므로 비공개 위치와 적절한 보존 정책을 선택하세요.

기본 상태 디렉터리에 쓸 수 없다면 검사 대상 저장소 외부에서 쓰기 가능한 디렉터리를 선택합니다.

export CODEX_SECURITY_STATE_DIR=/path/outside/repository/codex-security-state

검사를 시작하기 전에 저장소, 대상 및 출력 디렉터리를 확인합니다.

npx @openai/codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR" --dry-run

시험 실행은 Codex를 시작하거나 자격 증명을 불러오거나 플러그인의 Python 인터프리터를 조사하지 않고 모든 --knowledge-base 경로를 포함한 로컬 입력을 확인합니다.

첫 검사 실행

표준 검사를 실행하고 선택한 디렉터리에 결과를 보관합니다.

npx @openai/codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR"

대화형 터미널에는 실시간 검사 대시보드가 표시됩니다. 대신 일반 진행률 줄을 표시하려면 --headless을 추가하세요. CI 및 대화형 세션이 없는 터미널은 자동으로 일반 진행률을 사용합니다.

대시보드에는 실시간 세션 세부 정보도 표시됩니다. 여기에는 소스 코드나 자격 증명이 포함될 수 있으므로 공유하기 전에 검토하세요.

기본적으로 CLI는 검사 진행률과 완료 요약을 stderr에 기록합니다. 전체 검사 결과를 stdout에 출력하지 않습니다. 완료된 검사는 다음과 같은 요약을 출력합니다.

  REPORT    /path/outside/repository/codex-security-results/report.md

  FINDINGS  2 (2 confirmed this scan; 0 previously found; 1 high, 1 medium)
  COVERAGE  complete
  ELAPSED   42s
  RESULTS   /path/outside/repository/codex-security-results

사용 가능한 경우 토큰 사용량과 예상 비용이 표시됩니다. 전체 결과를 기계 판독 가능한 JSON으로 출력하려면 구조화된 출력을 명시적으로 요청하세요.

npx @openai/codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR" --json

기본적으로 검사는 보고서만 생성하므로 발견 항목은 로컬 검토에 계속 사용할 수 있습니다. CI에서 검사 실행을 시작할 준비가 되면 심각도 임계값을 추가하는 것이 좋습니다.

모델 및 추론 노력 선택

검사는 기본적으로 xhigh 추론 노력으로 gpt-5.6-sol을 사용합니다. 작업에 필요하면 다른 모델과 노력 수준을 선택하세요.

npx @openai/codex-security scan "$REPOSITORY" \
  --model gpt-5.6-terra \
  --effort high

지원되는 노력 수준은 minimal, low, medium, high, xhigh 및 max입니다.

결과 검토

읽기 쉬운 결과를 보려면 report.md을 여세요. 검사 디렉터리에는 자동화에 사용되는 구조화된 파일도 포함됩니다.

codex-security-results/
├── scan-manifest.json
├── findings.json
├── coverage.json
├── report.md
├── artifacts/
└── exports/
    └── results.sarif       # when produced

scan-manifest.json에는 대상, 범위, 생성자 및 봉인된 아티팩트가 기록됩니다.
findings.json에는 각 발견 항목의 심각도, 신뢰도, 위치, 증거 및 해결 방법이 기록됩니다.
coverage.json에는 검토한 영역, 제외 항목, 보류된 작업, 미해결 질문 및 검사 범위의 완전성이 기록됩니다.

검사 범위는 complete, partial 또는 unknown일 수 있습니다. 검사를 검토의 증거로 취급하기 전에 보류된 영역이나 미해결 질문을 확인하세요. CLI 참조에서는 전체 아티팩트 및 출력 계약을 설명합니다.

발견 항목 검토 및 패치

발견 항목이 있는 전체 대화형 검사가 끝나면 CLI가 발견 항목 브라우저를 제공합니다. 증거를 검토하고 수정할 발견 항목을 선택하세요. 저장된 작업은 Codex 데스크톱 앱에서 찾을 수 있습니다.

브라우저를 사용하지 않고 높음 및 치명적 발견 항목을 패치하려면 다음을 실행합니다.

npx @openai/codex-security scan "$REPOSITORY" \
  --patch --patch-severity high --json

검증된 패치를 커밋하고 GitHub 풀 리퀘스트를 열려면 --create-pr을 추가하세요.

저장된 발견 항목을 패치하거나 Linear 이슈를 가져올 수도 있습니다. validate 및 patch 참조를 확인하세요.

다음 검사 선택

저장소에 별도의 서비스나 패키지가 포함되어 있다면 경로 검사를 사용합니다.

npx @openai/codex-security scan "$REPOSITORY" \
  --path services/billing \
  --path packages/auth

기준 리비전과 HEAD 사이에서 커밋된 변경 사항을 검토합니다.

npx @openai/codex-security scan "$REPOSITORY" --diff origin/main --head HEAD

HEAD을 기준으로 스테이징된 변경 사항과 스테이징되지 않은 변경 사항을 검토합니다.

npx @openai/codex-security scan "$REPOSITORY" --working-tree --base HEAD

차이 및 작업 트리 검사에서는 저장소 인수가 Git 작업 트리 루트여야 합니다. 차이 검사를 시작하기 전에 선택한 리비전을 가져오세요.

저장소나 경로를 더 광범위하게 검토해야 한다면 심층 모드를 사용합니다.

npx @openai/codex-security scan "$REPOSITORY" --mode deep

작업자, 하위 에이전트 및 검사 중단 시점을 제어하려면 다음을 실행합니다.

npx @openai/codex-security scan "$REPOSITORY" \
  --mode deep \
  --workers 2 \
  --subagents 0 \
  --stop-after-no-new 3 \
  --max-discovery-runs 10 \
  --max-time-hours 1.5

이 옵션에는 저장소 및 경로 대상을 지원하지만 차이 또는 작업 트리 검사는 지원하지 않는 심층 모드가 필요합니다. 여기서 --workers은 한 검사 내의 독립적인 표준 검사 작업자를 제어하고 bulk-scan --workers는 동시 저장소 검사를 제어합니다. --max-time-hours는 소수 시간 값을 포함하여 96 이하의 양수를 허용합니다. 제한에 도달하면 검사는 완료되지 않은 작업자를 중단하고, 완료된 검사 결과를 보존하며, 이를 최종 보고서로 집계합니다.

아키텍처 및 보안 컨텍스트 추가

아키텍처 문서, 위협 모델 또는 보안 정책을 검사 컨텍스트로 제공하세요. 이를 통해 Codex Security가 시스템의 실제 작동 방식을 기준으로 발견 항목을 평가할 수 있습니다.

npx @openai/codex-security scan "$REPOSITORY" \
  --knowledge-base /path/to/architecture.md \
  --knowledge-base /path/to/security-policies

사용자 지정 검사 지침 추가

검사에서 보안 우선순위에 집중하도록 지침을 추가하세요. 후속 지침에는 두 번째 파일을 사용합니다.

npx @openai/codex-security scan "$REPOSITORY" \
  --scan-prompt-file /path/to/scan.md \
  --post-scan-prompt-file /path/to/follow-up.md

후속 작업은 성공한 검사와 검사 범위가 불완전하거나 오류가 있는 검사 후에 동일한 인증 세션에서 실행됩니다. 후속 작업이 실패하면 CLI는 경고를 보고하고 완료된 검사를 유지합니다. 취소된 검사나 비용 한도에 도달한 검사 후에는 실행되지 않습니다. 두 옵션 모두 bulk-scan에서도 작동하며 CSV의 prompt 열에는 저장소별 지침이 추가됩니다.

검사 예산 설정

예상 모델 비용이 USD 한도를 초과할 때 검사를 중단하려면 --max-cost를 사용합니다.

npx @openai/codex-security scan "$REPOSITORY" --max-cost 5

이미 진행 중인 요청은 한도를 약간 초과하여 완료될 수 있습니다. Codex Security가 완료된 작업자 결과를 집계한 후 심층 검사가 한도에 도달하면 CLI는 완료된 보고서를 저장하고 검사 범위를 partial으로 표시하며 종료 코드 2을 반환합니다. 검사가 완료된 보고서를 생성할 수 없다면 사용 가능한 부분 출력은 디스크에 남습니다.

커밋 전마다 변경 사항 검사

저장소에 Git 사전 커밋 보안 검사를 설치합니다.

npx @openai/codex-security install-hook

이 검사는 각 커밋 전에 스테이징된 변경 사항과 스테이징되지 않은 변경 사항을 검사합니다. 기존 사전 커밋 스크립트를 대체하지 않으면서 심각도가 높은 발견 항목과 검사 오류를 차단합니다.

저장소 대량 검사

저장소를 검색하기 전에 GitHub에 로그인합니다.

gh auth login

GitHub 계정 또는 조직에서 저장소를 검색하고 선택합니다.

npx @openai/codex-security bulk-scan

대화형 흐름에서는 보관된 저장소와 포크를 제외합니다. 검사하기 전에 선택한 저장소를 확인하도록 요청합니다.

준비된 저장소 목록을 검사하려면 CSV와 출력 디렉터리를 제공합니다.

npx @openai/codex-security bulk-scan repositories.csv \
  --output-dir /path/outside/repositories/security-scans \
  --workers 4

기존 대량 검사를 재개하려면 동일한 명령을 다시 실행하세요. Codex Security는 완료된 저장소를 건너뜁니다. 일시적인 저장소 또는 검사 오류를 다시 시도하려면 --max-attempts 3을 추가하세요.

GitHub 검색, CSV 준비, 캠페인 결과 및 Docker 설정은 대량 보안 검사 실행을 참조하세요.

Docker에서 대량 검사 실행

액세스 권한에 Codex Security Docker 이미지가 포함되어 있다면 Linux Docker 호스트에서 제공된 강화 Compose 구성과 보안 프로필을 사용하세요. 호스트는 권한 없는 사용자 네임스페이스 생성을 지원해야 합니다. 저장소 CSV를 제공하고, 결과와 로그인 상태는 영구 마운트 디렉터리에 보관하며, 자격 증명은 환경 또는 비밀 관리자에서 제공하세요.

docker compose run --rm codex-security \
  bulk-scan /input/repositories.csv \
  --output-dir /output \
  --workers 4

컨테이너는 대화형 프롬프트 없이 대량 검사를 실행합니다. 저장소를 대화형으로 검색하려면 Docker 외부에서 CLI를 사용하세요. 비공개 저장소의 경우 환경 또는 비밀 관리자를 통해 GH_TOKEN 또는 GITHUB_TOKEN을 제공하세요. 계정 및 저장소 액세스를 포함한 로그인 요구 사항은 컨테이너화된 검사에도 적용됩니다.

저장된 검사 다시 확인

저장소에 저장된 검사를 나열합니다.

npx @openai/codex-security scans list "$REPOSITORY"

결과에서 검사 ID를 복사하여 발견 항목과 구성을 살펴봅니다.

npx @openai/codex-security scans show SCAN_ID

검사 및 해당 작업자에서 저장된 이벤트를 살펴보려면 다음을 실행합니다.

npx @openai/codex-security scans logs SCAN_ID

저장된 로그는 민감 정보가 제거되지 않으며 소스 코드나 자격 증명을 포함할 수 있습니다. 공유하기 전에 검토하세요.

저장소 검사 전반의 미해결 발견 항목을 나열합니다.

npx @openai/codex-security findings list "$REPOSITORY"

최신 검사에서 확인되지 않았더라도 이전 발견 항목은 미해결 상태로 유지됩니다.

검토한 발견 항목을 거짓 양성으로 표시하려면 해당 발견 항목이 적용되지 않는 이유를 설명하세요.

npx @openai/codex-security findings false-positive FINDING_OCCURRENCE_ID \
  --reason "The route already checks permissions"

후속 검사에서는 해당 설명을 고려하지만 현재 코드는 계속 다시 확인합니다.

원래 구성을 사용하여 현재 체크아웃에서 동일한 검사를 실행합니다.

npx @openai/codex-security scans rerun SCAN_ID

두 검사를 비교하여 신규, 지속, 재발, 해결 또는 알 수 없는 발견 항목을 찾습니다.

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

비교 과정에서는 근본 원인을 기준으로 발견 항목을 자동으로 일치시키고 저장된 일치 결과를 재사용합니다.

대량 검사 CSV 형식, 검사 기록 필터 및 명령 옵션은 CLI 참조를 확인하세요.

목표에 맞는 워크플로를 계속 진행하세요.

대량 보안 검사 실행으로 GitHub 저장소를 검색하거나 고정된 CSV 목록을 검사합니다.
CLI FAQ 읽기에서 검사 기록, 거짓 양성 피드백, 검사 범위 및 수정 검증에 관한 답변을 확인합니다.
CI에서 검사 실행으로 풀 리퀘스트를 검토하고 결과를 보존하며 심각도 정책을 설정합니다.
CLI 참조 사용으로 모든 플래그, 출력 형식, 아티팩트 및 종료 코드를 확인합니다.
TypeScript SDK 통합으로 애플리케이션이나 개발자 도구에서 검사를 실행합니다.

최근 검색

추천 검색

문서 탐색