시작하기 전에

CLI 빠른 시작 가이드에 따라 Codex Security를 설치하고 인증하세요. 보안 스캔을 실행할 권한이 있는지, 소유하거나 보안 점검을 허가받은 리포지터리에 Git으로 접근할 수 있는지 확인하세요. 스캔은 사용자의 로컬 권한으로 실행되며 승인을 기다리지 않습니다. 스캔 권한 안내를 확인하세요.

리포지터리 목록 준비

먼저 리포지터리 몇 개로 시작하세요. 다음 내용을 repositories.csv로 저장한 뒤 예시 URL과 커밋 자리표시자를 실제 값으로 바꾸세요.

id,repository,revision
payments,https://github.com/YOUR-ORG/payments.git,REPLACE_WITH_FULL_COMMIT_SHA
identity,https://github.com/YOUR-ORG/identity.git,REPLACE_WITH_FULL_COMMIT_SHA

각 리포지터리에 고유한 id와 전체 커밋 SHA를 지정하세요. 다음 명령어로 로컬에 체크아웃한 리포지터리의 SHA를 확인할 수 있습니다.

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

각 스캔은 지정한 커밋 시점의 리포지터리 전체를 검사합니다. 이 워크플로우에서는 브랜치 이름이나 축약된 해시를 사용하지 않으며, 커밋하지 않은 변경 사항은 검사 대상에서 제외됩니다. 스캔 범위를 폴더 단위로 지정하거나 리포지터리별 지침을 설정하는 방법은 CSV 옵션을 참고하세요.

스캔 실행

repositories.csv가 있는 디렉터리에서 아래 명령어의 출력 경로를 스캔 대상 리포지터리 외부의 비공개 디렉터리 경로로 바꾼 뒤 명령어를 실행하세요.

npx @openai/codex-security bulk-scan repositories.csv \
  --output-dir /path/outside/repositories/security-scans \
  --workers 2 \
  --mode standard \
  --max-attempts 1 \
  --max-cost 5

이 명령어는 표준 모드로 스캔 두 개를 동시에 실행하며, 리포지터리마다 한 번씩 시도합니다. --max-cost 5를 지정하면 각 시도의 예상 비용이 5달러를 넘을 때 해당 시도가 중단됩니다. 이미 진행 중인 작업에는 예상보다 많은 비용이 들 수 있습니다. 따라서 이 값은 엄격한 비용 상한이 아니며, 전체 실행에 적용되는 공동 예산도 아닙니다. 실행 전에 각 옵션의 값을 정하세요.

CLI는 security-scans/artifacts/ 아래에 리포지터리별로 폴더를 만들어 결과를 저장합니다. 결과에는 소스 코드 일부와 취약점의 세부 정보가 포함될 수 있으므로 비공개로 보관하세요.

결과 검토

결과 디렉터리를 열고 다음 항목을 확인하세요.

1. 리포지터리 목록: manifest.json에서 리포지터리와 커밋을 확인하세요.
2. 상태: results.jsonl에서 각 시도의 상태와 산출물 위치를 확인하세요.
3. 검사 범위와 보안 이슈: 각 시도의 폴더에서 coverage.json을 열어 검사 누락 및 제외 항목을 확인한 뒤, report.md와 findings.json에서 보안 이슈와 그 근거를 검토하세요.

종료 코드 0은 모든 리포지터리의 스캔이 성공적으로 완료되었다는 뜻입니다. 취약점이 없다는 뜻은 아닙니다. 종료 코드 2는 검사 범위를 모두 확인하지 못했거나, 스캔을 완료하지 못한 리포지터리가 있거나, 입력 또는 런타임 오류가 발생했음을 나타냅니다. 검사 범위가 불완전하다면 보안 이슈 목록이 비어 있어도 코드가 안전하다고 판단할 수 없습니다.

각 리포지터리에서 다음에 할 일을 기록하세요. 보안 이슈를 조사하거나, 검토 후 수용한 보안 이슈를 수정하거나, 검사가 누락된 부분을 후속 점검하세요. 담당 팀에 작업을 인계할 때는 스캔한 커밋과 판단 근거를 함께 전달하세요.

중단된 실행을 재개하려면 동일한 CSV, 지침, 출력 디렉터리를 사용해 같은 명령어를 다시 실행하세요. CLI는 완료된 스캔을 건너뛰며 검사 범위가 불완전한 스캔을 자동으로 재시도하지 않습니다. 리포지터리 목록, 리비전, 검사 범위, 모드 또는 지침을 변경할 때는 새 출력 디렉터리를 사용하세요. 자세한 복구 절차는 재개 및 재시도 안내를 참고하세요.