대규모 보안 스캔 실행

하나의 캠페인에서 저장소를 검토하려면 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가 없는 행에 심층 스캔을 선택하려면 --mode deep을 사용하세요. 각 CSV 행에서 스캔 모드와 저장소 범위를 개별적으로 선택할 수도 있습니다.

캠페인의 각 심층 스캔에서 작업자 실행을 제한하려면 [deep_scan].max_time_hours를 설정하세요. --max-time-hours 플래그는 bulk-scan이 아니라 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 사용 가능 여부를 확인하세요.

npx @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

사용 가능한 추론 수준은 선택한 모델에 따라 다릅니다. 일괄 스캔은 minimal, low, medium, high, xhigh 및 max를 지원하며, GPT-6.1 Sol은 최소 low 수준이 필요합니다.

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
    │       ├── 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를 참조하세요.