심층 스캔은 같은 리포지터리나 폴더에서 여러 표준 스캔을 독립적으로 실행한 뒤 각 스캔에서 발견한 보안 이슈를 종합합니다. 같은 범위를 여러 차례 검토하고 싶고 실행 시간과 토큰을 더 쓸 수 있을 때 사용하세요.
먼저 표준 스캔을 실행해 검토 범위와 보안 컨텍스트가 목표에 맞는지 확인하세요. 검토를 반복하면 앞선 검토에서 놓친 보안 이슈를 발견할 수 있지만, 모든 이슈를 찾아내거나 매번 같은 결과가 나온다고 보장할 수는 없습니다.
표준 스캔과 심층 스캔 중 선택하기
| 표준 스캔 | 심층 스캔 | |
|---|---|---|
| 검토 방식 | 표준 스캔 1회 | 표준 스캔을 여러 차례 실행한 뒤 보안 이슈 종합 |
| 용도 | 첫 스캔 또는 범위가 정해진 검토 | 같은 범위를 독립적으로 추가 검토 |
| 범위 | 리포지터리 또는 폴더 | 리포지터리 또는 폴더 |
| 변경 사항 | 변경 사항 검토 워크플로우 사용 | 지원하지 않음 |
심층 스캔 시작하기
최상의 스캔 품질을 얻으려면 gpt-5.6-sol 모델을 사용하고 추론 수준을 xhigh로 설정하세요.
- 보안 > 스캔을 열고 + 스캔을 선택하세요.
- 리포지터리나 폴더를 고른 뒤 코드베이스를 선택하고 심층 스캔을 켜세요. 스캔은 선택한 리포지터리나 폴더 전체를 검토합니다.
- 모델과 추론 수준을 선택하세요. 추가 컨텍스트에 위협 모델이나 배포 환경에 관한 정보를 입력하세요.
- 스캔 시작을 선택하세요.
Codex 대화에서도 다음과 같이 심층 스캔을 시작할 수 있습니다.
$codex-security:deep-security-scan을 사용해 이 리포지터리에 대한 심층 보안 스캔을 실행해 주세요.특정 컴포넌트만 스캔하려면 위 요청에서 “이 리포지터리”를 해당 컴포넌트의 폴더 경로로 바꾸세요.
심층 스캔 워커는 사용자가 선택한 모델과 추론 설정을 그대로 사용합니다. 각 워커는 표준 스캔을 처음부터 끝까지 실행하고, Codex Security는 완료된 스캔 결과를 종합합니다. 스캔에서 저장된 스캔의 진행 상황을 확인하거나 활동 보기를 선택해 해당 Codex 작업을 살펴보세요. 동시 실행 수나 실행 시간을 제한하려면 스캔을 시작하기 전에 실행 제한을 설정하세요.
최종 결과를 검토하기 전에 심층 스캔이 어느 단계까지 진행됐는지 확인하고 해당 Codex 활동을 살펴보세요.
결과 검토하기
마무리 단계가 성공해 report.md가 생성되어야 스캔이 완료됩니다. 결과 집계가 끝났다는 메시지나 scan-manifest.json 파일만으로는 스캔 완료를 확인할 수 없습니다.
심층 스캔에서도 표준 스캔과 마찬가지로 저장된 스캔 세부 정보와 전체 스캔 디렉터리를 확인할 수 있습니다. 스캔에서 완료된 스캔을 열거나 보안 이슈에서 발견된 내용을 검토하세요. 상세 취약점 보고서나 코드 구조의 보안을 강화하는 방법을 요청했다면 생성된 report.md에 해당 문서 링크가 포함됩니다. 결과를 공유하거나 보관할 때는 보고서에서 링크한 findings/ 및 hardening/ 디렉터리도 함께 보관하세요.
보안 이슈를 살펴보기 전에 검토 범위 요약을 확인하세요. 심층 스캔에도 한계가 있으므로 결론을 내리기 전에 검토를 보류한 영역과 아직 근거가 부족한 부분을 확인하세요. 보안 이슈가 타당하다고 판단하면 보안 이슈 수정 및 검증하기에 따라 진행하세요.
pull request, 커밋, 브랜치 범위 또는 로컬 패치를 검토하려면 코드 변경 사항 검토하기를 참조하세요. 심층 스캔은 diff를 스캔 대상으로 지원하지 않습니다.
심층 스캔 실행 설정하기
심층 스캔의 동시 실행 수와 실행 시간을 조정하려면 ~/.codex/codex-security/config.toml을 만들거나 수정하세요. CODEX_HOME을 설정했다면 $CODEX_HOME/codex-security/config.toml을 사용하세요.
다음은 동시 실행 수를 제한하고 스캔 시간을 단축하는 설정 예시입니다.
[deep_scan]
workers = 2
subagents = 0
stop_after_no_new = 3
max_discovery_runs = 10
max_time_hours = 1.5| 설정 | 기본값 | 설명 |
|---|---|---|
workers |
4 |
독립적인 표준 스캔을 동시에 실행할 수 있는 최대 워커 수입니다. 이전 설정값인 "auto"도 4로 처리됩니다. |
subagents |
3 |
각 워커가 시작할 수 있는 하위 에이전트 수입니다. 0으로 설정하면 하위 에이전트를 사용하지 않습니다. |
stop_after_no_new |
4 |
새 보안 이슈 없이 완료된 워커 스캔이 지정한 횟수만큼 연속되면 심층 스캔을 중지합니다. |
stop_after_consecutive_errors |
3 |
워커 오류가 지정한 횟수만큼 연속으로 발생하면 심층 스캔을 중지합니다. |
max_discovery_runs |
40 |
결과를 집계하기 전에 실행할 수 있는 독립 표준 스캔의 횟수를 제한합니다. |
max_time_hours |
96 |
워커의 실행 제한 시간을 시간 단위로 지정합니다. 0보다 크고 96 이하인 값을 사용하며, 필요한 경우 소수로 지정할 수 있습니다. |
값을 낮추면 스캔 시간과 토큰 사용량을 줄일 수 있지만 일부 보안 이슈를 놓칠 수 있습니다. 변경한 설정은 새로 시작하는 심층 스캔에만 적용됩니다.
제한 시간에 도달하면 Codex Security는 아직 실행 중인 워커를 중지하고, 완료된 스캔 결과를 보존해 최종 보고서로 종합합니다. 기한 내에 소스 코드 검토를 마친 워커가 하나도 없으면 보고서에는 일부 범위만 검토했다고 기록됩니다.
max_time_hours를 설정하려면 플러그인 버전 0.1.19 이상이 필요합니다. 릴리스 세부 정보는 플러그인 변경 로그를 참조하세요.
중단 또는 실패에 대처하기
다른 스캔을 시작하기 전에 저장된 스캔의 상태를 확인하세요. 데스크톱 앱에서는 스캔에서 해당 스캔을 여세요. Codex 대화에서는 Codex에 기존 스캔의 상태를 확인해 달라고 요청하세요.
- 스캔이 진행 중인데 대기가 끝났다면 같은 스캔이나 대화로 돌아가 Codex에 스캔을 계속해 달라고 요청하세요. 응답이 끝나거나 대기 시간이 초과되어도 스캔은 취소되지 않습니다.
- 스캔이 오류로 종료되었거나 취소되었다면 오류 내용과 저장된 스캔 디렉터리를 보관하세요. 저장된 보안 이슈와 아직 확인되지 않은 후보를 구분해 검토하세요. 검토 범위가 불완전하므로 보안 이슈 목록이 비어 있어도 코드에 취약점이 없다고 단정할 수 없습니다.
도움을 요청할 때는 실패한 스캔에 사용한 Codex CLI 또는 데스크톱 앱의 버전과 플러그인 버전을 알려 주세요. 제공업체, 모델, 스캔 상태, 정확한 오류 내용도 포함하세요. 업데이트 후 확인한 버전은 스캔 실행 당시 버전과 다를 수 있습니다. 버전 및 업데이트 확인하기를 참조하세요.