CLI FAQ | Codex Security | ChatGPT 문서

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

저장소 스캔

CLI를 사용할 수 있는 대상

@openai/codex-security 패키지는 공개되어 있습니다. CLI와 SDK를 설치하세요.

npm install @openai/codex-security

스캔을 실행하려면 Codex Security 액세스 권한이 필요합니다. 최상의 결과를 얻으려면 Trusted Access for Cyber 인증을 받은 계정을 사용하세요.

로그인 후 스캔에서 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 참조에서 확인하세요.

저장소 일괄 스캔의 작동 방식

GitHub CLI로 로그인하세요.

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

GitHub 검색, CSV 형식, 캠페인 결과 및 사용 가능한 옵션은 보안 스캔 일괄 실행을 참조하세요.

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

예. 원본 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

스캔에서 아키텍처 및 보안 정책을 사용하는 방법

아키텍처 문서, 위협 모델 또는 보안 정책을 --knowledge-base과 함께 전달하세요.

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

Codex Security는 이러한 문서를 현재 스캔의 컨텍스트로 사용합니다. 지원되는 파일 형식과 디렉터리 동작은 보안 컨텍스트 추가를 참조하세요.

발견 사항 및 커버리지

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

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

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

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

npx @openai/codex-security scans show SCAN_ID

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

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

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

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

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

두 스캔에서 근본 원인이 같은 발견 사항을 매칭하세요.

npx @openai/codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID

매칭된 발견 사항을 비교하세요.

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 match BASELINE_SCAN_ID REPEAT_SCAN_ID

매칭된 결과를 비교하세요.

npx @openai/codex-security scans compare BASELINE_SCAN_ID REPEAT_SCAN_ID

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

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

수정을 적용한 후 원래 스캔을 다시 실행하세요.

npx @openai/codex-security scans rerun BEFORE_SCAN_ID

원래 발견 사항을 새 스캔과 매칭하세요.

npx @openai/codex-security scans match BEFORE_SCAN_ID AFTER_SCAN_ID

매칭된 발견 사항을 비교하세요.

npx @openai/codex-security scans compare BEFORE_SCAN_ID AFTER_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"

발견 사항이 없거나 스캔 비교 결과만으로는 수정이 제대로 적용되었다고 입증할 수 없습니다.

불완전한 커버리지의 의미

커버리지는 complete, partial 또는 unknown일 수 있습니다. 스캔을 검토의 근거로 간주하기 전에 제외된 경로, 보류된 영역 및 미해결 질문이 있는지 coverage.json을 검토하세요.

부분 또는 알 수 없는 커버리지의 스캔은 심각도 정책이 없어도 종료 코드 2을 반환합니다. 사용 가능한 발견 사항과 커버리지는 그대로 보관됩니다. 이후 스캔에서 이전 발견 사항의 원래 경로를 검사하지 않으면 해당 발견 사항이 더 이상 존재하지 않는다는 사실을 입증할 수 없습니다.

자동화 및 비용

스캔 비용 한도의 작동 방식

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

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

이 한도는 추정치이며 엄격한 지출 상한이 아닙니다. 이미 진행 중인 요청은 한도를 초과하여 완료될 수 있습니다. Codex Security는 스캔이 중지될 때까지 확보된 결과를 보관합니다.

스캔에서 커밋과 풀 리퀘스트를 검사할 수 있나요?

스테이징된 변경 사항과 스테이징되지 않은 변경 사항을 검사하는 pre-commit 보안 검사를 설치하세요.

npx @openai/codex-security install-hook

풀 리퀘스트 검사에서는 커밋된 변경 사항을 스캔하고 심각도 임곗값을 설정하세요.

npx @openai/codex-security scan . \
  --diff origin/main \
  --fail-on-severity high

완료된 스캔은 선택한 심각도 이상의 문제를 발견하면 종료 코드 1을 반환합니다. 전체 GitHub Actions 워크플로, 아티팩트 처리 및 SARIF 내보내기는 CI에서 스캔 실행을 참조하세요.

다른 애플리케이션에서 스캔을 직접 실행할 수 있나요?

예. TypeScript SDK를 사용하면 애플리케이션 또는 개발자 도구에서 스캔을 시작하고, 대상을 선택하고, 발견 사항과 커버리지를 살펴보고, 진행 상황을 추적하고, 비용 제어를 적용할 수 있습니다.

최근 검색

추천 검색

문서 탐색

Codex Security CLI FAQ