일괄 보안 스캔 실행

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,prompt
payments,https://github.com/example/payments.git,0123456789abcdef0123456789abcdef01234567,services/api,standard,Review payment authorization and refunds.
identity,https://github.com/example/identity.git,fedcba9876543210fedcba9876543210fedcba98,,deep,Review session and identity boundaries.

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입니다. 각 심층 스캔에서 표준 스캔을 독립적으로 실행하는 워커 수는 [deep_scan]에서 별도로 설정하세요. --mode deep을 지정하면 mode 값이 없는 행에 심층 스캔을 적용합니다. CSV의 각 행에서 스캔 모드와 리포지터리 내 스캔 범위를 따로 지정할 수도 있습니다.

[deep_scan].max_time_hours를 설정하면 캠페인의 각 심층 스캔에서 워커 실행 시간을 제한할 수 있습니다. --max-time-hours 플래그는 scan에서 사용할 수 있으며 bulk-scan에서는 사용할 수 없습니다.

CLI는 지정한 리비전을 체크아웃하고 선택한 대상을 스캔한 뒤 결과를 기록하고 임시 체크아웃을 삭제합니다. 스캔의 매니페스트 상태가 completed이고 필수 결과 아티팩트가 유효하면 해당 리포지터리의 스캔이 완료된 것으로 처리합니다. 스캔 범위에 검토하지 못한 부분이 있어도 스캔 실패로 처리하지 않습니다.

보안 컨텍스트와 지침 공유

--knowledge-base로 모든 스캔에 아키텍처 문서, 위협 모델 또는 보안 정책을 추가하세요. 파일이나 디렉터리를 여러 개 추가하려면 플래그를 반복해서 지정하세요.

npx @openai/codex-security bulk-scan repositories.csv \
  --output-dir /path/outside/repositories/security-scans \
  --knowledge-base /path/to/architecture.md \
  --knowledge-base /path/to/security-policies

공통 스캔 지침을 추가하거나 각 스캔 후에 후속 작업을 실행하려면 프롬프트 파일을 지정하세요.

npx @openai/codex-security bulk-scan repositories.csv \
  --output-dir /path/outside/repositories/security-scans \
  --scan-prompt-file scan-instructions.md \
  --post-scan-prompt-file follow-up.md

CLI는 공통 스캔 지침 뒤에 각 리포지터리의 CSV prompt 값을 덧붙입니다. 스캔이 성공하거나 스캔 오류가 발생하면 동일한 인증 세션에서 후속 지침을 실행합니다. 스캔이 취소되거나 비용 한도에 도달하면 후속 지침을 실행하지 않습니다. 프롬프트 파일 경로는 현재 디렉터리를 기준으로 해석합니다.

모델과 추론 수준 선택

일괄 스캔은 기본적으로 gpt-5.6-sol 모델과 xhigh 추론 수준을 사용합니다. CSV 캠페인에서 모델과 추론 수준을 변경하려면 현재 자격 증명으로 액세스할 수 있는 모델을 선택하세요. ChatGPT로 로그인했다면 다음 예시를 사용하기 전에 GPT-6.1 Sol 사용 가능 여부를 확인하세요.

1
2
3
4
5npx @openai/codex-security bulk-scan repositories.csv \
--output-dir /path/outside/repositories/security-scans \
--workers 4 \
--model gpt-6.1-sol \
--effort medium

대화형 리포지터리 탐색에서도 같은 옵션을 사용할 수 있습니다.

npx @openai/codex-security bulk-scan --model gpt-6.1-sol --effort medium

--effort에는 사용 중인 모델, 공급자, Codex 버전이 모두 지원하는 값을 지정하세요.

OpenRouter 또는 Fireworks를 사용하려면 공급자에 따라 각각 OPENROUTER_API_KEY 또는 FIREWORKS_API_KEY를 설정하고 --provider와 --model을 지정하세요. 자격 증명과 사용 예시는 OpenRouter 또는 Fireworks 설정이나 Amazon Bedrock 설정을 참고하세요.

캠페인 결과 검토

출력 디렉터리에는 캠페인 설정, 시도별 기록, 리포지터리별 결과가 저장됩니다.

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

• manifest.json에는 캠페인에 포함된 리포지터리, 지정된 리비전, 스캔 범위와 모드, 공통 지침 또는 리포지터리별 지침이 기록됩니다.
• results.jsonl에는 각 리포지터리의 스캔 시도별로 상태와 아티팩트 디렉터리가 기록되며, 비용이나 오류 세부 정보가 있으면 함께 기록됩니다.
• report.md에서는 한 리포지터리의 스캔 시도 한 건에 대한 결과를 보고서 형식으로 확인할 수 있습니다.
• 해당 시도에서 발견한 보안 이슈를 확인하려면 findings.json을 여세요. 해당 시도에 설정된 스캔 범위와 검토 제외 항목을 확인하려면 scan-manifest.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를 참고하세요.