초기 검토나 정기적인 레포지토리 또는 컴포넌트 평가에는 표준 Codex Security 스캔으로 시작하세요. 전체 스캔 워크플로우를 한 번 실행합니다.
더 철저하게 평가하려면 결과를 검토한 다음 심층 스캔을 실행하세요. 심층 스캔은 시간이 더 오래 걸리며 더 광범위하게 검색합니다.
스캔 영역 선택
데스크톱 앱에서 보안을 열고 스캔을 선택한 다음 + 스캔을 선택하세요. 기존 레포지토리나 다른 폴더를 선택한 다음 코드베이스를 선택하세요.
광범위한 커버리지가 필요하고 레포지토리 전체가 적절한 검토 단위라면 레포지토리 전체를 스캔하세요. 모노레포에서는 서비스, 패키지 또는 컴포넌트에 명확한 담당자와 보안 경계가 있다면 폴더 하나를 선택하세요.
Codex 대화에서도 스캔을 시작할 수 있습니다:
Use $codex-security:security-scan to scan this repository for security vulnerabilities.대화에서 특정 폴더에 집중하려면 컴포넌트를 명시하세요:
Use $codex-security:security-scan to scan this repository for security vulnerabilities, focusing on the services/billing component.대규모 모노레포에서는 의미 있는 제품 또는 서비스 경계 하나부터 시작하세요.
스캔 구성
최상의 스캔 품질을 얻으려면 gpt-5.6-sol
모델을 xhigh 추론 수준으로 사용하세요.
- 코드베이스를 선택하고 심층 스캔은 끈 상태로 두세요.
- 선택한 레포지토리, 현재 브랜치, 최신 리비전을 확인하세요.
- 스캔 영역을 레포지토리 전체로 설정하거나 폴더 하나를 선택하세요.
- 모델과 추론 수준을 선택하세요.
- 검토 결과에 영향을 줄 때만 추가 컨텍스트를 여세요. 유용한 컨텍스트에는 공격자가 제어하는 입력, 신뢰 경계, 민감한 작업 또는 우선적으로 검토할 특정 영역을 명시합니다.
- 스캔 시작을 선택하세요.
지속적으로 적용할 보안 지침을 제공하려면 레포지토리 루트에 SECURITY.md를 추가하세요.
위협 모델, 보안 불변 조건, 보고 대상 보안 이슈 기준,
제외 항목, 심각도 관련 컨텍스트를 설명하세요. 디렉터리별 지침이 필요하면 하위 디렉터리에 SECURITY.md 파일을
추가하세요. 정책이 충돌하면 코드와 가장 가까운 파일이
우선합니다. Codex Security는 이러한 파일을 실행 가능한 지침이 아니라
정책 컨텍스트로 취급합니다.
AGENTS.md에 지원되는 빌드 및 검증 명령어와
기타 레포지토리별 지침을 작성하세요.
각 단계가 완료될 때까지 기다리기
스캔은 다음 단계를 순서대로 실행합니다:
- 위협 모델링은 자산, 진입점, 신뢰 경계 및 보안 불변 조건을 식별합니다.
- 보안 이슈 탐색은 요청한 코드를 검토하여 보안 통제가 손상되었을 가능성이 있는 부분과 소스에서 싱크로 이어지는 경로를 확인합니다.
- 검증은 각 후보를 테스트하거나 다른 방식으로 확인하고 증거 또는 입증이 부족한 부분을 기록합니다.
- 영향 및 경로 분석은 각 후보의 현실적인 경로, 영향 및 심각도를 평가합니다.
- 보고 단계에서는 검증된 보안 이슈, 커버리지 및 스캔 메타데이터를 기록합니다. 요청하면 보안 이슈별 상세 보고서를 확인할 수 있습니다.
- 구조적 강화는 요청한 경우 보안 이슈 집합을 분석하고 설계 지침을 생성합니다.
- 마무리 단계에서는 구조화된 스캔 규약을 검증하고
상세 보고서나 강화 지침이 있다면 해당 링크를 포함한
report.md를 생성합니다.
워크벤치는 현재 진행 중인 스캔 단계와 플러그인이 보고하는 진행 상황을 표시합니다. Codex 작업을 확인하려면 활동 보기를 선택하세요. 초기 후보만으로 판단하거나 어떤 단계가 다른 단계보다 오래 걸린다는 이유로 중단하지 말고 전체 결과가 나올 때까지 기다리세요.
완료된 스캔 검토
다음 순서로 결과를 검토하세요:
- 대상, 리비전, 스캔 영역을 확인하세요.
- 검토된 영역과 명시적으로 보류되었거나 후속 검토가 필요한 모든 영역을 확인하세요.
- 각 보안 이슈에 대해 문제의 근원이 된 통제 지점 또는 싱크, 공격자가 제어하는 입력, 검증 방법, 남아 있는 불확실성, 현실적인 도달 가능성, 심각도 판단 근거, 제안된 해결 방법을 확인하세요.
- 증거가 주장된 경로나 영향을 뒷받침하지 못하는 보안 이슈는 기각하세요.
- 수정을 시작하기 전에 수용한 보안 이슈 하나를 선택하세요.
보안 이슈의 심각도, 검증 상태, 근본 원인, 공격 경로를 검토하세요.
첫 스캔 평가
스캔하기 전에 독립적인 발견, 증거 품질, 오탐, 해결 조치의 품질 등 평가 기준을 2~4개 선택하세요. 알려진 보안 이슈를 기준으로 테스트하는 경우 해당 이슈를 Codex에 제공했는지 아니면 스캔 시 제공하지 않았는지를 기록하세요.
레포지토리 리비전, 플러그인 버전, 모델, 추론 수준을 기록하세요. 코드, 보안 통제 또는 스캔 설정이 변경된 뒤 실행하는 후속 스캔을 비교할 때 이 기준선을 사용하세요.
스캔 주기 선택
레포지토리의 위험 수준과 팀이 보안 이슈를 처리할 수 있는 여력에 따라 스캔 주기를 정하세요. 다음 시점에 스캔하세요:
- 기준선: 레포지토리를 온보딩하거나 컴포넌트를 담당하게 될 때 또는 새 위협 모델을 위한 시작점이 필요할 때 표준 스캔을 실행하세요.
- 코드 변경: Pull Request 또는 커밋에서 보안에 민감한 코드나 외부 통합을 변경하는 경우 코드 변경 사항을 검토하세요.
- 정기 검토: 시스템의 노출 수준과 코드 변경 빈도에 따라 반복 검토 주기를 설정하세요. 팀이 보안 이슈를 처리할 수 있는 여력에 맞게 조정하세요.
- 수정 후: 보안 이슈 수정 및 검증을 완료하세요. 문제가 더 이상 재현되지 않는지 확인하고 비교를 위해 원래 스캔을 보관하세요.
이러한 스캔 트리거는 자동화된 스캔 일정을 생성하지 않습니다.
이전 스캔 다시 열기
보안을 연 다음 스캔에서 저장된 스캔을 선택하여 보안 이슈, 커버리지 및 사용 가능한 보고서 아티팩트를 검토하세요. 최신 코드를 평가하려면 동일한 레포지토리에서 새 스캔을 시작하세요. 새 스캔은 이전 스캔이나 그 아티팩트를 대체하지 않습니다.
결과 활용
원시 JSON을 직접 확인하지 않고 보안 워크벤치에서 보안 이슈, 커버리지 및
후속 검토 영역을 검토하세요. report.md가 있다면 이 파일을 열어
전체 스캔 디렉터리를 읽기 쉬운 형태로 확인하세요. 디렉터리를 공유하거나
보관할 때는 전체 내용을 함께 유지하세요. 선택적 아티팩트가 있다면 보고서에서 findings/의
상세 보고서와 hardening/의 구조적 강화 지침으로 연결되는 링크를
확인할 수 있습니다.
각 스캔은 워크스페이스 내부에서 자동화와 통합을 위해 scan-manifest.json, findings.json,
coverage.json 파일을 보존합니다. 일반적으로 이러한 파일을 직접
열 필요는 없습니다.
이식 가능한 아티팩트나 외부 이슈 추적에 관해서는 보안 이슈 내보내기 또는 추적을 참조하세요.
다음 단계
보안 이슈를 수용한 후 보안 이슈 수정 및 검증을 사용하여 범위가 제한된 패치 하나를 생성하고 검토하세요. 한 번의 채팅에서 Codex에 스캔의 모든 보안 이슈를 수정해 달라고 요청하지 마세요.