Codex Security CLI 빠른 시작

독립 실행형 Codex Security CLI로 로컬 저장소에 대한 표준 스캔을 실행하세요. 이 빠른 시작을 마치면 검토하고 다시 열어 볼 수 있는 보고서가 저장됩니다. Codex 대화 내에서 스캔하려면 Codex Security 플러그인을 사용하세요.

사전 요구 사항 확인

Node.js 24 또는 26을 사용하거나, Node.js 22의 경우 22.13.0 이상을 사용하세요. Python 3.10 이상도 필요합니다. Python 3.10에는 tomli도 필요합니다. OpenAI 추론을 사용하는 스캔에는 Codex Security 액세스 권한이 필요합니다. 계정과 저장소에 따라 전체 저장소 스캔에는 Trusted Access for Cyber도 필요할 수 있습니다.

CLI는 사용자의 운영 체제 권한으로 실행되며 승인을 기다리기 위해 일시 중지하지 않습니다. 스캔 프로세스가 사용자 환경을 상속할 수 있으므로 관련 없는 자격 증명을 시작 전에 제거하세요. 로컬 스캔 권한을 참조하세요.

CLI 설정 및 확인

npx 명령으로 공개 패키지를 실행하세요.

npx @openai/codex-security --version

이 명령은 설치된 패키지 버전을 출력합니다. info --json 명령으로 번들로 제공되는 플러그인 버전을 확인하거나, --help 명령으로 명령어 목록을 확인하세요. 패키지 변경 사항은 CLI 및 SDK 릴리스에 나와 있습니다.

로그인

ChatGPT 계정으로 로그인하세요:

npx @openai/codex-security login

브라우저가 없는 컴퓨터에서는 --device-auth를 추가하고 화면에 표시되는 로그인 지침을 따르세요. 환경에 API key도 있는 경우에도 해당 로그인을 선택하려면 아래 스캔 명령에 --auth chatgpt를 사용하세요.

API key와 기타 제공업체에 대해서는 스캔 인증 선택을 참조하세요. Amazon Bedrock의 경우 ChatGPT 로그인이나 OpenAI API key 대신 AWS 자격 증명 및 모델 액세스를 사용하세요.

검사 준비

아래 경로를 저장소 경로와 해당 Git 작업 트리 외부에 있는 새 결과 디렉터리 경로로 바꾸세요.

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

결과에는 소스 코드 발췌문과 취약점 세부 정보가 포함될 수 있습니다. 비공개 위치를 선택하세요. --output-dir를 생략하면 CLI는 영구 상태 디렉터리를 사용합니다.

대상과 출력 위치를 확인하세요.

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

시험 실행에 성공하면 로컬 입력이 확인된 것입니다. 스캔을 시작하거나 자격 증명을 로드하거나 플러그인의 Python 인터프리터를 확인하지는 않으므로, 인증과 런타임 설정이 성공할 것임을 보장하지는 않습니다.

첫 검사 실행

--dry-run을 제거하여 스캔을 시작하세요.

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

대화형 터미널에는 실시간 대시보드가 표시됩니다. 비대화형 터미널에는 진행 상황이 줄 단위로 표시됩니다. 대화형 터미널에서도 줄 단위로 표시하려면 --headless를 추가하세요. 대시보드와 저장된 로그에는 소스 코드나 자격 증명이 포함될 수 있습니다. 공유하기 전에 검토하세요.

스캔이 완료되면 stderr에 보고서 경로, 발견 사항 수, 경과 시간이 표시됩니다. 예를 들면 다음과 같습니다.

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

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

기본적으로 발견 사항의 심각도 때문에 스캔이 실패하지는 않습니다. 기계가 읽을 수 있는 stdout 출력을 얻으려면 --json을 추가하세요. 발견 사항에 따라 CI 검사가 실패하도록 하려면 심각도 정책을 설정하세요.

결과 검토

안내된 디렉터리에서 report.md를 여세요. 대상과 리비전을 확인한 후, 개별 발견 사항을 검토하기 전에 검사 범위를 읽어 보세요.

scan.status를 scan-manifest.json에서 확인하여 스캔이 완료되었는지 확인합니다. 검토한 영역, 제외된 경로, 보류된 작업, 미해결 질문은 coverage.json에서 확인합니다.

완료된 스캔은 발견 사항이 설정된 심각도 임계값에 도달하지 않으면 0으로 종료하고, 도달하면 1을 반환합니다. 검사 범위의 누락은 종료 코드를 바꾸지 않으므로, 종료 코드 0이 모든 파일을 검토했다는 의미는 아닙니다. 입력, 실행, 결과 무결성, 필수 출력에 오류가 있으면 2를 반환합니다. CLI 참조에서 종료 코드를 설명합니다.

각 발견 사항에 대해 영향을 받는 코드, 공격에 필요한 사전 조건, 검증 근거, 남아 있는 불확실성을 확인합니다. 소스 코드에 기반한 발견 사항에 반드시 성공적인 런타임 재현이 포함되는 것은 아닙니다. 근거가 제기된 문제를 뒷받침하는지 확인한 후에만 수정할 발견 사항을 선택합니다.

스캔 디렉터리를 공유하거나 보관할 때는 내용물을 함께 유지합니다. 이 디렉터리에는 보고서와 함께 scan-manifest.json, findings.json, coverage.json 및 관련 산출물이 들어 있습니다. 전체 구조는 스캔 산출물을 참조하세요.

저장된 검사 다시 확인

저장소의 스캔 목록을 표시합니다:

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

결과에서 스캔 ID를 복사합니다:

npx @openai/codex-security scans show SCAN_ID

발견 사항이 있는 대화형 스캔이 완료되면 CLI에서 발견 사항 탐색기도 제공합니다. 수정 방법을 선택하기 전에 탐색기에서 근거를 검토합니다. 저장된 발견 사항에는 validate 및 patch 명령을 사용합니다.

다음 스캔 선택

인증 문제, 반복 스캔 간 차이 또는 오탐 피드백은 CLI FAQ를 참조하세요.