Codex Security CLI FAQ

터미널에서 저장소를 스캔하고 보안 발견 사항을 관리하는 방법에 관한 일반적인 질문의 답을 확인하세요. 설치하고 첫 스캔을 실행하려면 CLI 빠른 시작부터 살펴보세요.

저장소 스캔

로그인 후 스캔에서 API key를 사용하는 이유

환경에 OPENAI_API_KEY 또는 CODEX_API_KEY가 포함되어 있으면, 대화형 터미널이 없는 스캔과 JSON 및 JSONL 스캔은 ChatGPT 또는 액세스 토큰으로 성공적으로 로그인한 후에도 기본적으로 환경의 API key를 사용합니다. 텍스트를 출력하는 대화형 스캔에서는 ChatGPT 로그인도 사용할 수 있을 때 사용할 인증 방식을 선택하라는 메시지가 표시됩니다. 드라이런은 메시지를 표시하거나 자격 증명을 불러오지 않습니다.

스캔에 저장된 자격 증명을 사용하려면 해당 자격 증명을 명시적으로 선택하세요.

npx @openai/codex-security scan . --auth chatgpt

OPENAI_API_KEY 또는 CODEX_API_KEY의 API key를 필수로 사용하려면 다음을 실행하세요.

npx @openai/codex-security scan . --auth api-key

저장된 자격 증명을 자동 기본값으로 설정하려면 unset OPENAI_API_KEY CODEX_API_KEY를 실행하세요. 지원되는 모든 인증 모드는 CLI 참조에서 확인하세요.

중단된 일괄 스캔을 재개할 수 있나요?

예. 원본 CSV와 출력 디렉터리를 사용하여 같은 bulk-scan 명령을 실행합니다. Codex Security는 완료된 저장소를 건너뜁니다.

일시적인 저장소 또는 스캔 오류를 다시 시도하려면 --max-attempts 3을 추가하세요.

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

완료된 스캔은 검사 범위에 공백이 남아 있어도 결과를 유지하며 재시도하지 않습니다. 검사 범위의 공백으로 인해 캠페인이 코드 2로 종료되지는 않습니다.

발견 사항 및 커버리지

팀에서 이전 스캔 결과를 찾을 수 있는 위치

저장소에 저장된 스캔을 나열하세요.

npx @openai/codex-security scans list /path/to/repository

결과의 스캔 ID를 사용하여 발견 사항을 살펴보세요.

npx @openai/codex-security scans show SCAN_ID

완료된 각 스캔은 보고서, 발견 사항, 커버리지 및 관련 아티팩트를 함께 보관합니다. 전체 구조는 스캔 아티팩트를 참조하세요.

저장된 검사 및 작업자 이벤트를 검토하려면 scans logs SCAN_ID를 실행합니다. 이러한 로그는 민감한 정보가 가려지지 않으므로 소스 코드나 자격 증명이 포함될 수 있습니다.

CLI에서 스캔 기록을 저장할 수 없는 경우

Codex Security는 워크벤치 데이터베이스에 스캔 기록을 보관합니다. 기본 상태 디렉터리에 쓸 수 없다면 저장소 외부의 비공개 디렉터리를 선택하세요.

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

스캔에서 새로운 발견 사항과 기존 발견 사항을 구분하는 방법

저장소의 모든 검사에서 열린 발견 사항을 나열합니다:

npx @openai/codex-security findings list /path/to/repository

이 목록에는 최신 검사에서 확인된 발견 사항과 해당 검사에서 확인되지 않은 이전의 열린 발견 사항이 표시됩니다.

두 스캔의 발견 사항을 비교합니다:

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

비교 시 근본 원인을 기준으로 발견 사항을 자동으로 연결하고, 저장된 연결을 재사용하며, 신규, 지속, 재개, 미관찰, 해결, 알 수 없음 상태의 발견 사항을 식별합니다. 후속 스캔이 검사한 코드에서 이전 발견 사항을 찾지 못하면 해당 발견 사항은 미관찰 상태가 됩니다. 이미 수정된 것으로 명시적으로 종료한 경우에만 해결된 것으로 간주합니다. 제외된 경로와 불확실한 연결은 알 수 없음 상태로 남습니다.

오탐 피드백의 작동 방식

저장된 스캔을 살펴보고 발생 ID를 찾으세요.

npx @openai/codex-security scans show SCAN_ID

해당 발견 사항이 적용되지 않는 이유를 기록하세요.

npx @openai/codex-security findings false-positive FINDING_OCCURRENCE_ID \
  --reason "The framework escapes this input before it reaches the query"

이후 동일한 저장소를 스캔할 때 해당 설명이 컨텍스트로 제공됩니다. 하지만 현재 소스, 제어 수단 및 도달 가능성은 계속 독립적으로 검사됩니다. 발견 사항을 기각해도 규칙, 경로 또는 취약점 클래스가 억제되지는 않습니다.

명령에 관한 자세한 내용은 발견 사항 참조를 확인하세요.

반복 스캔에서 서로 다른 발견 사항이 반환될 수 있는 이유

AI 지원 스캔은 동일한 스캔 구성에서도 결과가 달라질 수 있습니다. 먼저 기준 스캔을 다시 실행하세요.

npx @openai/codex-security scans rerun BASELINE_SCAN_ID

재실행 시 원래 스캔 구성이 유지되며 동일한 플러그인 버전이 필요합니다. 설치된 플러그인이 변경되었다면 명령이 중지됩니다.

기준 스캔과 새 스캔을 비교합니다:

npx @openai/codex-security scans compare BASELINE_SCAN_ID REPEAT_SCAN_ID

컨텍스트 부족이 결과 차이에 영향을 줄 수 있다면 공통 아키텍처 및 보안 지침을 제공하세요. 매칭을 사용하면 여러 실행에서 동일한 근본 발견 사항을 식별할 수 있지만 스캔이 결정론적으로 바뀌지는 않습니다. 사라진 중요한 발견 사항은 직접 다시 검사하세요.

수정이 제대로 적용되었는지 팀에서 확인하는 방법

변경된 체크아웃을 대상으로 원래 발견 사항을 다시 확인하세요. 해당 체크아웃에서 보고서와 검증할 이슈를 전달하세요.

npx @openai/codex-security validate /path/to/original/findings.json \
  "Recheck the SQL injection in src/orders.ts:42 against the current code"

취약한 경로가 차단되었고 정상적인 동작이 여전히 작동한다는 근거를 검토하세요. 원래 재현 코드나 회귀 테스트가 있으면 실행하세요. 검사를 실행할 수 없다면 결과에 남아 있는 불확실성을 기록하세요.

스캔 비교를 통해 발견 사항의 변화를 확인할 수 있지만, 발견 사항이 사라졌다는 사실만으로 수정이 검증되지는 않습니다.

불완전한 커버리지의 의미

제외된 경로, 보류된 영역, 미해결 질문은 coverage.json에서 확인하세요. 새 결과에는 검사 범위의 완전성을 나타내는 필드가 포함되지 않습니다. 실행 상태는 scan.status를 scan-manifest.json에서 확인하세요.

검사 범위의 공백은 완료된 스캔의 종료 코드를 바꾸지 않습니다. 종료 코드 0이 모든 파일을 검토했다는 뜻은 아닙니다. 후속 스캔이 이전 발견 사항의 원래 경로를 검사하지 않으면 해당 발견 사항이 더 이상 존재하지 않는다고 입증할 수 없습니다.

자동화 및 비용

딥 스캔 시간 제한은 어떻게 작동하나요

딥 스캔을 시작할 때 작업자 마감 시간을 설정하세요.

npx @openai/codex-security scan . --mode deep --max-time-hours 1.5

기본값은 96시간입니다. 소수를 포함하여 96 이하의 양수를 사용할 수 있습니다. 제한 시간에 도달하면 Codex Security는 완료되지 않은 워커를 중지하고, 완료된 표준 스캔 결과를 유지하며, 이를 최종 보고서로 집계합니다. 검토된 영역과 보류된 작업은 보고서에서 확인하세요. 제한 시간만으로 종료 코드가 결정되지는 않으며, 실행 상태와 심각도 정책에 따라 결정됩니다.

설정을 유지하거나 일괄 캠페인에 적용하려면 딥 스캔 구성의 [deep_scan] 아래에 max_time_hours를 설정하세요.

스캔 비용 한도의 작동 방식

스캔을 시작하기 전에 예상 비용 한도를 USD로 설정하세요.

npx @openai/codex-security scan . --max-cost 5

이 한도는 예상치이며 엄격한 지출 상한이 아닙니다. 이미 진행 중인 요청이 완료되면 한도를 초과할 수 있습니다. Codex Security가 완료된 워커 결과를 집계한 후 심층 스캔이 한도에 도달하면 CLI는 완료된 보고서를 예산 경고와 함께 저장할 수 있습니다. 0을 반환하거나, 발견 사항이 설정된 심각도 기준을 충족하면 1을 반환합니다. 유효한 완료 결과를 생성할 수 없으면 2를 반환하고 사용 가능한 출력을 보존합니다.

GitHub 풀 리퀘스트 검사와 예약된 저장소 스캔에는 Codex Security GitHub Action을 사용하세요. action-v0.3.0에서 스캔 완료는 구성된 분석이 유효한 결과를 생성했음을 의미합니다. 범위 제외와 보류된 조사는 심각도 정책을 우회하지 않습니다. 스캔의 범위와 한계를 평가하려면 coverage.json을 검토하세요. 빈 diff와 드라이 런도 거부하려면 Action의 scan-status 출력이 completed여야 한다는 조건을 설정하세요. 심각도 정책 선택을 참조하세요.

다른 공급자는 CI/CD 개요를 참조하세요. 매번 커밋하기 전에 검사하려면 install-hook를 사용하세요.