Codex Security CLI 자주 묻는 질문

터미널에서 리포지터리를 스캔하고 보안 이슈를 관리할 때 자주 묻는 질문을 정리했습니다. 설치하고 첫 스캔을 실행하려면 CLI 빠른 시작을 참고하세요.

리포지터리 스캔

로그인한 뒤에도 스캔에서 API 키를 사용하는 이유는 무엇인가요?

환경에 OPENAI_API_KEY 또는 CODEX_API_KEY가 설정되어 있으면 대화형 터미널 없이 실행하는 스캔이나 JSON 또는 JSONL 형식으로 출력하는 스캔은 환경 변수의 API 키를 기본으로 사용합니다. ChatGPT나 액세스 토큰으로 로그인한 뒤에도 마찬가지입니다. 텍스트를 출력하는 대화형 스캔에서는 ChatGPT 로그인도 사용할 수 있으면 인증 방식을 선택하라는 메시지가 표시됩니다. 모의 실행에서는 인증 방식을 묻거나 자격 증명을 불러오지 않습니다.

저장된 자격 증명으로 스캔하려면 인증 방식을 명시적으로 선택하세요.

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

OPENAI_API_KEY 또는 CODEX_API_KEY의 API 키를 반드시 사용하려면 다음 명령어를 실행하세요.

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

저장된 자격 증명을 기본으로 사용하려면 unset OPENAI_API_KEY CODEX_API_KEY를 실행하세요. 지원되는 모든 인증 방식은 CLI 레퍼런스에서 확인할 수 있습니다.

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

네. 처음 사용한 CSV와 출력 디렉터리를 지정해 같은 일괄 스캔 명령어를 다시 실행하세요. 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"

취약점을 악용할 수 있는 경로가 차단되었고 정상적인 기능은 여전히 작동한다는 근거를 검토하세요. 기존 재현 코드나 회귀 테스트가 있으면 실행하세요. 검증을 실행할 수 없다면 무엇을 확인하지 못했는지 결과에 기록하세요.

스캔 비교를 통해 보안 이슈의 변화를 확인할 수 있지만, 결과에서 이슈가 사라졌다는 사실만으로 수정이 검증되지는 않습니다.

스캔 범위가 불완전하다는 것은 어떤 의미인가요?

scan-manifest.json에서 scan.status를 확인하면 스캔이 완료되었는지 알 수 있습니다. scan.scope에는 설정한 스캔 범위가 기록됩니다. scan.review.excludedPaths에는 스캔이 검토 대상에서 제외한 경로 패턴이 나열됩니다. 이전 버전의 매니페스트에 scan.coverageRef가 있으면 이 필드가 가리키는 파일을 열어 스캔 범위를 자세히 확인하세요.

검토하지 못한 영역이 있어도 완료된 스캔의 종료 코드는 바뀌지 않습니다. 종료 코드 0이 모든 파일을 검토했다는 뜻은 아닙니다. 후속 스캔이 기존 보안 이슈가 발견된 경로를 검토하지 않았다면 해당 이슈가 사라졌다고 판단할 수 없습니다.

자동화와 비용

심층 스캔의 시간 제한은 어떻게 적용되나요?

심층 스캔을 시작할 때 워커의 실행 시간 제한을 설정하세요.

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

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

설정을 계속 사용하거나 일괄 스캔에 적용하려면 max_time_hours를 [deep_scan] 섹션에 지정하세요. 자세한 내용은 심층 스캔 설정을 참고하세요.

스캔 비용 제한은 어떻게 적용되나요?

스캔을 시작하기 전에 예상 비용 한도를 미국 달러 단위로 설정하세요.

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

이 한도는 예상 비용을 기준으로 하므로 이미 진행 중인 요청이 완료되면서 실제 지출이 한도를 넘을 수 있습니다. 심층 스캔에서 Codex Security가 완료된 워커의 결과를 취합한 뒤 한도에 도달하면 CLI는 예산 경고와 함께 완료된 스캔 보고서를 저장할 수 있습니다. 이 경우 기본 종료 코드는 0이며, 설정한 심각도 기준을 충족하는 보안 이슈가 있으면 1을 반환합니다. 유효한 완료 결과를 생성할 수 없으면 2를 반환하고 그때까지 생성된 출력을 보존합니다.

GitHub Pull Request 검사와 예약된 리포지터리 스캔에는 Codex Security GitHub Action을 사용하세요. action-v0.3.0에서 스캔 완료는 설정한 분석이 유효한 결과를 생성했다는 뜻입니다. 일부 영역을 스캔 범위에서 제외하거나 조사를 보류해도 심각도 정책은 그대로 적용됩니다. 스캔 범위와 한계는 coverage.json에서 확인하세요. 변경 사항이 없는 diff와 모의 실행도 검사를 통과하지 못하게 하려면 GitHub Action의 scan-status 출력이 completed인 경우에만 검사를 통과하도록 설정하세요. 자세한 내용은 심각도 정책 선택을 참고하세요.

다른 CI/CD 제공업체를 사용하는 경우 CI/CD 개요를 참고하세요. 커밋할 때마다 사전 검사를 실행하려면 install-hook을 사용하세요.