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를 설치하세요. 일부 사이버 보안 요청을 처리하거나 보호 대상 보안 이슈를 확인하려면 Trusted Access for Cyber가 필요합니다.

CLI는 현재 사용자의 운영 체제 권한으로 실행되며 승인을 기다리지 않습니다. 스캔 프로세스가 환경 변수를 상속할 수 있으므로 시작하기 전에 스캔과 무관한 자격 증명을 환경에서 제거하세요. 자세한 내용은 로컬 스캔 권한을 참고하세요.

CLI 설치 및 확인

공개 패키지를 전역으로 설치한 뒤 버전을 확인하세요.

npm install -g @openai/codex-security
codex-security --version

이 패키지는 codex-security 명령어와 별칭 cs를 제공합니다. npm의 전역 실행 파일 디렉터리가 PATH에 포함되어 있는지 확인하세요.

전역 설치 없이 실행하려면 npx를 사용하세요.

npx @openai/codex-security --version

아래 예제에서는 npx @openai/codex-security를 사용합니다. 전역으로 설치했다면 codex-security로 대체할 수 있습니다.

위 명령어는 설치된 패키지 버전을 출력합니다. 패키지에 포함된 플러그인 버전을 확인하려면 info --json을, 명령어 목록을 보려면 --help를 사용하세요.

로그인

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

npx @openai/codex-security login

브라우저가 없는 컴퓨터에서는 워크스페이스에서 기기 인증을 허용하는 경우 --device-auth를 추가하고 화면에 표시되는 로그인 안내를 따르세요. 기기 인증이 비활성화되어 있다면 SSH 로그인 안내를 따르세요. 환경에 API 키가 있어도 ChatGPT 계정으로 인증하려면 아래 스캔 명령어에 --auth chatgpt를 지정하세요.

API 키와 다른 제공업체의 인증 방법은 스캔 인증 방식 선택을 참고하세요. Amazon Bedrock에서는 ChatGPT 로그인이나 OpenAI API 키 대신 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"

ChatGPT 워크스페이스에서 Daybreak Blue를 사용할 권한이 있다면 스캔 명령어에 --model gpt-6-sol --cyber-access-program daybreak_blue를 추가하세요.

대화형 터미널에는 실시간 대시보드가 표시됩니다. 비대화형 터미널에서는 진행 상황이 한 줄씩 출력됩니다. 대화형 터미널에서도 진행 상황을 한 줄씩 보려면 --headless를 추가하세요. 대시보드와 저장된 로그에는 소스 코드나 자격 증명이 포함될 수 있으므로 공유하기 전에 내용을 확인하세요.

스캔이 끝나면 stderr에 보고서 경로, 보안 이슈 수, 경과 시간이 다음과 같이 표시됩니다.

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

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

기본 설정에서는 보안 이슈의 심각도 때문에 스캔이 실패하지 않습니다. stdout을 기계가 읽을 수 있는 형식으로 출력하려면 --json을 추가하세요. 특정 심각도의 보안 이슈가 발견되면 CI 검사가 실패하도록 하려면 심각도 정책을 설정하세요.

결과 검토

결과 디렉터리에서 report.md를 여세요. 스캔 대상과 리비전을 확인한 뒤 보안 이슈를 검토하세요. 기록된 스캔 상태와 범위는 각각 scan.status와 scan.scope에 표시됩니다. 두 항목은 scan-manifest.json에서 확인할 수 있습니다.

스캔이 완료되면 종료 코드로 0을 반환합니다. 단, 보안 이슈의 심각도가 설정된 기준 이상이면 1을 반환합니다. 종료 코드 0이 모든 파일을 검토했다는 뜻은 아닙니다. 입력이나 실행에 문제가 있거나, 결과 무결성 검증에 실패하거나, 필수 출력을 생성하지 못하면 2를 반환합니다. 종료 코드에 대한 설명은 CLI 레퍼런스를 참고하세요.

각 보안 이슈에 대해 영향을 받는 코드, 공격에 필요한 조건, 검증 근거, 아직 확실하지 않은 점을 확인하세요. 소스 코드에서 발견한 보안 이슈에는 실행 환경에서 문제를 재현한 결과가 없을 수도 있습니다. 보고된 문제를 뒷받침하는 근거를 확인한 뒤에만 해당 보안 이슈를 수정 대상으로 선택하세요.

스캔 결과를 공유하거나 보관할 때는 스캔 디렉터리 전체를 함께 유지하세요. 이 디렉터리에는 scan-manifest.json과 findings.json, 보고서, 그리고 근거 자료가 들어 있습니다. 전체 디렉터리 구조는 스캔 산출물을 참고하세요.

저장된 위협 모델 내보내기

표준 스캔, 심층 스캔, diff 스캔은 위협 모델을 결과와 함께 저장합니다. 로그인하거나 모델을 추가로 호출하지 않고도 위협 모델을 Markdown으로 내보낼 수 있습니다.

npx @openai/codex-security export "$SCAN_DIR" \
  --artifact threat-model --output "$SCAN_DIR/exports/threatmodel.md"

저장된 위협 모델이 없으면 export는 오류를 반환합니다. 저장된 스캔을 선택하거나 다른 출력 형식을 지정하는 방법은 내보내기 레퍼런스를 참고하세요.

저장된 스캔 다시 확인

리포지터리의 스캔 목록을 확인하세요.

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

결과에서 스캔 ID를 복사해 다음 명령어에 넣으세요.

npx @openai/codex-security scans show SCAN_ID

대화형 스캔이 완료되고 보안 이슈가 발견되면 CLI에서 보안 이슈 탐색기도 사용할 수 있습니다. 수정 방법을 선택하기 전에 탐색기에서 근거를 검토하세요. 저장된 보안 이슈에는 검증 및 패치 명령어를 사용하세요.

다음 스캔 선택

인증 문제, 반복 스캔 시 결과 차이, 오탐에 대한 피드백 방법은 CLI FAQ를 참고하세요.