Codex Security CLI 빠른 시작

Codex Security는 보안 및 엔지니어링 팀이 취약점을 찾고, 확인하고, 수정할 수 있도록 지원합니다. 명령줄 인터페이스(CLI)를 사용하여 소유하고 있거나 평가 권한이 있는 리포지토리를 스캔하고, 시간 경과에 따른 발견 항목을 검토하고, 변경 사항이 반영되기 전에 확인할 수 있습니다.

사전 요구 사항 확인

CLI를 사용하려면 Node.js 22 이상이 필요합니다. 스캔을 실행하거나 발견 항목을 내보내려면 Python 3.10 이상도 필요합니다. 자세한 내용은 인증 및 사전 요구 사항을 참조하세요.

CLI 설정 및 확인

게시된 패키지를 설치합니다.

npm install @openai/codex-security

사용 가능한 명령을 나열합니다.

npx @openai/codex-security --help

CLI 참조도 확인하세요.

스캔 준비

스캔할 리포지토리와 결과를 기록할 디렉터리를 선택합니다.

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

--output-dir을 생략하면 Codex Security는 자체 영구 상태 디렉터리에 결과를 저장합니다. 결과에는 소스 발췌문과 취약점 세부 정보가 포함될 수 있으므로 비공개 위치와 적절한 보존 정책을 선택하세요.

기본 상태 디렉터리에 쓸 수 없다면 스캔하는 리포지토리 외부에서 쓰기 가능한 디렉터리를 선택합니다.

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

스캔을 시작하기 전에 리포지토리, 대상, 출력 디렉터리를 확인합니다.

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

드라이 런은 Codex를 시작하거나 자격 증명을 불러오거나 플러그인의 Python 인터프리터를 확인하지 않고 로컬 입력을 검사합니다.

첫 스캔 실행

표준 스캔을 실행하고 선택한 디렉터리에 결과를 보관합니다.

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

기본적으로 CLI는 스캔 진행 상황과 완료 요약을 stderr에 기록합니다. 전체 스캔 결과를 stdout에 출력하지는 않습니다. 완료된 스캔은 다음과 같은 요약을 출력합니다.

codex-security: Findings: 2 (1 high, 1 medium). Coverage: complete.
codex-security: Elapsed: 42s.
codex-security: Report: /path/outside/repository/codex-security-results/report.md
codex-security: Results: /path/outside/repository/codex-security-results

사용 가능한 경우 토큰 사용량과 예상 비용이 표시됩니다. 전체 결과를 머신 판독 가능한 JSON으로 출력하려면 구조화된 출력을 명시적으로 요청합니다.

npx @openai/codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR" --json

스캔은 기본적으로 보고서만 생성하므로 발견 항목을 로컬에서 계속 검토할 수 있습니다. CI에서 스캔을 실행할 준비가 되면 심각도 임계값을 추가하는 것이 좋습니다.

모델 및 추론 노력 선택

스캔은 기본적으로 xhigh 추론 노력으로 gpt-5.6-sol을 사용합니다. 작업에 필요한 경우 다른 모델과 노력 수준을 선택합니다.

npx @openai/codex-security scan "$REPOSITORY" \
  --model gpt-5.6-terra \
  --effort high

지원되는 노력 수준은 minimal, low, medium, high, xhigh입니다.

결과 검토

읽기 쉬운 결과는 report.md에서 확인합니다. 스캔 디렉터리에는 자동화에 사용되는 구조화된 파일도 포함되어 있습니다.

codex-security-results/
├── scan-manifest.json
├── findings.json
├── coverage.json
├── report.md
├── artifacts/
└── exports/
    └── results.sarif       # when produced

scan-manifest.json에는 대상, 범위, 생성자, 봉인된 아티팩트가 기록됩니다.
findings.json에는 각 발견 항목의 심각도, 신뢰도, 위치, 증거, 해결 방법이 기록됩니다.
coverage.json에는 검토한 영역, 제외 사항, 보류된 작업, 미해결 질문, 검사 범위 완전성이 기록됩니다.

검사 범위는 complete, partial 또는 unknown일 수 있습니다. 스캔을 검토의 증거로 간주하기 전에 보류된 영역이나 미해결 질문을 모두 확인하세요. CLI 참조에서는 전체 아티팩트 및 출력 계약을 설명합니다.

다음 스캔 선택

리포지토리에 서로 분리된 서비스나 패키지가 있는 경우 경로 스캔을 사용합니다.

npx @openai/codex-security scan "$REPOSITORY" \
  --path services/billing \
  --path packages/auth

기준 리비전과 HEAD 사이에 커밋된 변경 사항을 검토합니다.

npx @openai/codex-security scan "$REPOSITORY" --diff origin/main --head HEAD

HEAD을 기준으로 스테이징된 변경 사항과 스테이징되지 않은 변경 사항을 검토합니다.

npx @openai/codex-security scan "$REPOSITORY" --working-tree --base HEAD

Diff 및 작업 트리 스캔에서는 리포지토리 인수가 Git worktree 루트여야 합니다. Diff 스캔을 시작하기 전에 선택한 리비전을 가져오세요.

리포지토리나 경로를 더 폭넓게 검토해야 할 때는 심층 모드를 사용합니다.

npx @openai/codex-security scan "$REPOSITORY" --mode deep

심층 모드는 리포지토리 및 경로 대상을 지원하지만 Diff 또는 작업 트리 스캔은 지원하지 않습니다.

아키텍처 및 보안 컨텍스트 추가

아키텍처 문서, 위협 모델 또는 보안 정책을 스캔 컨텍스트로 제공합니다. 그러면 Codex Security가 시스템의 실제 작동 방식에 비추어 발견 항목을 평가하는 데 도움이 됩니다.

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

스캔 예산 설정

예상 모델 비용이 USD 기준 한도를 초과하면 --max-cost을 사용하여 스캔을 중지합니다.

npx @openai/codex-security scan "$REPOSITORY" --max-cost 5

이미 진행 중인 요청은 한도를 초과해 완료될 수 있습니다. Codex Security는 스캔이 중지될 때까지 확보된 결과를 보관합니다.

각 커밋 전 변경 사항 스캔

리포지토리에 Git pre-commit 보안 검사를 설치합니다.

npx @openai/codex-security install-hook

이 검사는 각 커밋 전에 스테이징된 변경 사항과 스테이징되지 않은 변경 사항을 스캔합니다. 기존 pre-commit 스크립트를 대체하지 않으면서 심각도가 높은 발견 항목과 스캔 오류가 있으면 커밋을 차단합니다.

리포지토리 일괄 스캔

리포지토리를 검색하기 전에 GitHub에 로그인합니다.

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

기존 일괄 스캔을 재개하려면 같은 명령을 다시 실행합니다. 결과 아티팩트가 온전한 완료된 리포지토리는 다시 스캔하지 않습니다. 일시적인 리포지토리 또는 스캔 오류를 재시도하려면 --max-attempts 3을 추가합니다.

GitHub 검색, CSV 준비, 캠페인 결과, Docker 설정에 대해서는 일괄 보안 스캔 실행을 참조하세요.

Docker에서 일괄 스캔 실행

액세스 권한에 Codex Security Docker 이미지가 포함되어 있다면 Linux Docker 호스트에서 제공된 강화 Compose 구성 및 보안 프로필을 사용합니다. 호스트는 권한 없는 사용자 네임스페이스 생성을 지원해야 합니다. 리포지토리 CSV를 제공하고, 결과와 로그인 상태를 영구 마운트 디렉터리에 보관하고, 환경 또는 비밀 관리자에서 자격 증명을 제공합니다.

docker compose run --rm codex-security \
  bulk-scan /input/repositories.csv \
  --output-dir /output \
  --workers 4

컨테이너는 프롬프트 없이 일괄 스캔을 실행합니다. 대화형으로 리포지토리를 검색하려면 Docker 외부에서 CLI를 사용하세요. 비공개 리포지토리의 경우 환경 또는 비밀 관리자를 통해 GH_TOKEN 또는 GITHUB_TOKEN을 제공합니다. 계정 및 리포지토리 액세스를 포함한 로그인 요구 사항은 컨테이너화된 스캔에도 적용됩니다.

저장된 스캔 다시 확인

리포지토리에 저장된 스캔을 나열합니다.

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

결과에서 스캔 ID를 복사하여 발견 항목과 구성을 검사합니다.

npx @openai/codex-security scans show SCAN_ID

검토한 발견 항목을 오탐으로 표시하려면 해당 발견 항목이 적용되지 않는 이유를 설명합니다.

npx @openai/codex-security findings false-positive FINDING_OCCURRENCE_ID \
  --reason "The route already checks permissions"

이후 스캔에서는 해당 설명을 고려하지만 현재 코드를 계속 다시 검사합니다.

원래 구성을 사용하여 현재 체크아웃에서 같은 스캔을 실행합니다.

npx @openai/codex-security scans rerun SCAN_ID

두 스캔을 비교하려면 먼저 근본 원인이 같은 발견 항목을 매칭합니다.

npx @openai/codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID

그런 다음 새로 발생했거나, 지속되거나, 다시 발생했거나, 해결되었거나, 알 수 없는 발견 항목을 확인합니다.

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

일괄 스캔 CSV 형식, 스캔 기록 필터, 명령 옵션에 대해서는 CLI 참조를 확인하세요.

목표에 맞는 워크플로를 계속 진행하세요.

일괄 보안 스캔 실행을 통해 GitHub 리포지토리를 검색하거나 고정된 CSV 인벤토리를 스캔합니다.
스캔 기록, 오탐 피드백, 검사 범위, 수정 검증에 관한 답변은 CLI FAQ 읽기에서 확인합니다.
CI에서 스캔 실행을 통해 pull request를 검토하고, 결과를 보존하고, 심각도 정책을 설정합니다.
CLI 참조 사용을 통해 모든 플래그, 출력 형식, 아티팩트, 종료 코드를 확인합니다.
TypeScript SDK 통합을 통해 애플리케이션이나 개발자 도구에서 스캔을 실행합니다.

최근 검색

추천 검색

문서 탐색