대규모 보안 스캔 실행

하나의 캠페인에서 리포지토리를 검토하려면 npx @openai/codex-security bulk-scan을 사용하세요. 개인 GitHub 계정 또는 조직에서 리포지토리를 검색하거나, 모든 리포지토리를 정확한 Git 리비전에 고정하는 CSV를 제공할 수 있습니다.

리포지토리 소스 선택

두 워크플로 모두 진행 상황을 저장하고 리포지토리별 결과를 보존하며, 중단된 후에도 캠페인을 재개할 수 있습니다.

GitHub 리포지토리 검색

GitHub CLI로 로그인합니다.

gh auth login

대화형 대규모 스캔을 시작합니다.

npx @openai/codex-security bulk-scan

CLI가 다음 단계를 안내합니다.

1. 개인 GitHub 계정 또는 조직을 선택합니다.
2. 최근 90일 이내에 활동이 있었던 리포지토리를 검토합니다.
3. 리포지토리 목록을 검색하고 스캔할 리포지토리를 선택합니다.
4. 스캔 결과를 저장할 디렉터리를 선택합니다.
5. 선택한 리포지토리를 검토하고 캠페인을 확인합니다.

검색 시 보관된 리포지토리와 포크는 제외됩니다. CLI는 선택한 각 리포지토리의 정확한 기본 브랜치 커밋을 <output-directory>/repositories.csv에 기록합니다. 선택 사항을 확인하기 전까지는 스캔이 시작되지 않습니다.

GitHub Enterprise Server를 사용하려면 먼저 GitHub 호스트에 로그인합니다.

gh auth login --hostname github.example.com

리포지토리 검색을 시작할 때 GH_HOST을 설정합니다.

GH_HOST=github.example.com npx @openai/codex-security bulk-scan

대화형 검색에는 터미널이 필요합니다. CI, 컨테이너 또는 미리 준비된 리포지토리 목록에는 CSV 인벤토리를 사용하세요.

리포지토리 CSV 만들기

각 리포지토리와 고정된 리비전마다 하나의 행이 포함된 CSV를 만듭니다.

id,repository,revision,scope,mode
payments,https://github.com/example/payments.git,0123456789abcdef0123456789abcdef01234567,services/api,standard
identity,https://github.com/example/identity.git,fedcba9876543210fedcba9876543210fedcba98,,deep

CSV는 다음 열을 지원합니다.

로컬 리포지토리의 전체 커밋 SHA를 확인하려면 다음을 실행합니다.

git -C /path/to/repository rev-parse HEAD

CSV에서 캠페인 실행

CSV와 리포지토리 외부의 비공개 출력 디렉터리를 전달합니다.

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

--workers은 동시에 실행할 리포지토리 스캔 수를 제어하며 기본값은 4입니다. 자체 mode이 없는 행에 심층 스캔을 선택하려면 --mode deep을 사용하세요. 각 CSV 행에서는 개별적으로 스캔 모드와 리포지토리 범위를 선택할 수 있습니다.

CLI는 고정된 각 리비전을 체크아웃하고 선택한 대상을 스캔한 후 결과를 기록하고 임시 리포지토리 체크아웃을 제거합니다. 스캔 범위가 완전하고 필요한 모든 결과 아티팩트가 존재할 때만 리포지토리가 완료된 것으로 간주됩니다.

모델 및 추론 노력 선택

대규모 스캔은 기본적으로 gpt-5.6-sol을 xhigh 추론 노력으로 사용합니다. CSV 캠페인에 다른 모델과 노력 수준을 선택하려면 다음을 실행합니다.

npx @openai/codex-security bulk-scan repositories.csv \
  --output-dir /path/outside/repositories/security-scans \
  --workers 4 \
  --model gpt-5.6-terra \
  --effort high

대화형 리포지토리 검색에서도 동일한 옵션을 사용할 수 있습니다.

npx @openai/codex-security bulk-scan --model gpt-5.6-terra --effort high

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

캠페인 결과 검토

출력 디렉터리에는 고정된 캠페인, 추가 전용 결과 원장, 각 리포지토리와 시도별 아티팩트가 포함됩니다.

security-scans/
├── manifest.json
├── results.jsonl
├── checkouts/
└── artifacts/
    ├── payments/
    │   └── attempt-1/
    │       ├── scan-manifest.json
    │       ├── findings.json
    │       ├── coverage.json
    │       └── report.md
    └── identity/
        └── attempt-1/
            ├── scan-manifest.json
            ├── findings.json
            ├── coverage.json
            └── report.md

• manifest.json은 캠페인의 리포지토리, 고정된 리비전, 범위 및 스캔 모드를 기록합니다.
• results.jsonl은 각 리포지토리 시도, 상태, 아티팩트 디렉터리 및 사용 가능한 비용 또는 오류 세부 정보를 기록합니다.
• report.md은 하나의 리포지토리 시도에 대한 읽기 쉬운 보고서를 제공합니다.
• findings.json과 coverage.json은 해당 시도의 발견 사항과 검토된 범위를 기록합니다.

이식 가능한 결과가 필요하면 완료된 리포지토리 스캔 하나를 내보냅니다.

npx @openai/codex-security export \
  /path/outside/repositories/security-scans/artifacts/payments/attempt-1 \
  --export-format sarif \
  --output /path/outside/repositories/payments.sarif

결과에는 소스 코드 발췌문과 취약점 세부 정보가 포함될 수 있습니다. 출력 디렉터리를 스캔된 리포지토리 외부에 비공개로 유지하고 적절한 보존 정책을 적용하세요.

캠페인 재개

동일한 CSV와 출력 디렉터리를 사용하여 원래 명령을 실행합니다.

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

CLI는 아직 작업이 필요한 리포지토리를 재개합니다. 해당 영수증과 필요한 모든 스캔 아티팩트가 여전히 존재하는 경우에만 완료된 리포지토리를 건너뜁니다.

기존 출력 디렉터리의 리포지토리 인벤토리는 변경하지 마세요. CLI는 고정된 매니페스트를 확인하고 다른 캠페인을 거부합니다. 리포지토리, 리비전, 범위 또는 스캔 모드를 변경할 때는 새 출력 디렉터리를 사용하세요.

리포지토리 오류 재시도

일시적인 체크아웃 또는 스캔 오류 후 리포지토리를 재시도하려면 --max-attempts을 사용하세요.

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

기본값은 리포지토리당 한 번의 시도입니다. 모든 시도에는 자체 영수증과 아티팩트 디렉터리가 할당됩니다.

대규모 스캔은 다음 종료 코드를 사용합니다.

Docker에서 대규모 스캔 실행

Codex Security 리포지토리에는 Linux Docker 호스트에서 자동화된 CSV 캠페인을 실행하기 위한 강화된 Compose 구성이 포함되어 있습니다. 호스트는 권한 없는 사용자 네임스페이스 생성을 지원해야 합니다.

리포지토리 CSV, 스캔 결과 및 로그인 상태를 영구 디렉터리에 마운트된 상태로 유지하세요. OpenAI 자격 증명은 환경 또는 비밀 관리자를 통해 제공하세요. 비공개 GitHub 리포지토리의 경우 GH_TOKEN 또는 GITHUB_TOKEN도 같은 방식으로 제공하세요.

마운트된 CSV와 출력 디렉터리를 사용하여 이미지를 실행합니다.

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

동일하게 마운트된 CSV와 출력 디렉터리를 사용하여 캠페인을 재개하세요. GitHub Enterprise Server의 경우 CODEX_SECURITY_GIT_HOST을 GitHub 호스트로 설정합니다.

사용 가능한 모든 플래그는 bulk-scan 명령 참조를 확인하세요. 스캔 범위와 발견 사항에 관한 일반적인 질문은 CLI FAQ를 확인하세요.