커밋하지 않은 로컬 변경 사항 검토

CLI에 리포지터리와 보안 정책에 관한 컨텍스트를 미리 제공하면 커밋하지 않은 로컬 변경 사항을 검토할 수 있습니다.

Git으로 체크아웃한 리포지터리에서 같은 셸을 사용해 아래 예제를 실행하세요. 예제에서는 보안 정책이 SECURITY.md에 있고 관련 문서가 docs/security/에 있다고 가정합니다. 다음 준비 단계에서 스캔 결과를 저장할 임시 디렉터리를 만듭니다.

northstar_repo="$(git rev-parse --show-toplevel)"
northstar_kb="$northstar_repo/docs/security"
northstar_results="$(mktemp -d)"

npx @openai/codex-security scan "$northstar_repo" \
  --working-tree \
  --base HEAD \
  --knowledge-base "$northstar_repo/SECURITY.md" \
  --knowledge-base "$northstar_kb" \
  --output-dir "$northstar_results/working-tree"

이 명령어는 HEAD를 기준으로 스테이징한 변경 사항과 스테이징하지 않은 변경 사항을 모두 검토합니다.

시작하기 전에 검토하려는 변경 사항이 작업 트리에 있는지 꼭 확인하세요. 관련 없는 변경 사항이 섞여 있으면 조사 범위가 넓어져 발견한 보안 이슈가 처음에 확인하려던 문제와 어떤 관련이 있는지 판단하기 어려울 수 있습니다.

PR 또는 브랜치 커밋 검토

PR이나 브랜치에 보안 이슈가 있는지 검토할 수도 있습니다. 검토할 브랜치를 체크아웃하고 병합 대상 브랜치를 가져오세요. 이 예제에서는 origin/main을 사용합니다.

northstar_pr_base="$(git -C "$northstar_repo" merge-base origin/main HEAD)"

npx @openai/codex-security scan "$northstar_repo" \
  --diff "$northstar_pr_base" \
  --head HEAD \
  --knowledge-base "$northstar_repo/SECURITY.md" \
  --knowledge-base "$northstar_kb" \
  --output-dir "$northstar_results/branch"

diff 스캔은 리포지터리 전체가 아닌 제안된 변경 사항만 검토합니다. 스캔이 끝나면 출력 디렉터리에 다음 파일이 생성됩니다.

• report.md는 사람이 읽기 쉽게 정리한 검토 보고서입니다.

• scan-manifest.json에서 스캔에 사용한 정확한 베이스와 헤드, 스캔 대상, 생성된 결과물을 확인할 수 있습니다.

• findings.json에는 보안 이슈별 심각도, 신뢰도, 위치, 해결 방법이 담깁니다.

• coverage.json에서 검토한 영역, 제외 항목, 보류한 작업, 검토 완료 정도를 확인할 수 있습니다.

모노레포 스캔

모노레포에서는 공유 라이브러리를 변경하면 여러 서비스가 영향을 받을 수 있습니다. Codex가 라이브러리와 서비스 간의 상호작용을 검토할 수 있도록 충분한 컨텍스트를 제공하세요. 어떤 컴포넌트를 검토하고 어떤 검사를 실행해야 하는지는 CI에서 결정합니다.

리포지터리 컨텍스트

공통 개발 지침은 AGENTS.md에, 보안 요구 사항은 SECURITY.md에 기록하세요. 일반적인 리포지터리 구조의 예는 다음과 같습니다.

monorepo/
├── AGENTS.md
├── SECURITY.md
├── docs/security/
│   ├── architecture.md
│   └── threat-model.md
├── packages/auth/
└── services/
    ├── billing/
    └── reporting/

기존 담당자 정보와 빌드 메타데이터를 활용해 각 컴포넌트를 해당 종속성, 이 컴포넌트를 사용하는 코드, 관련 테스트와 연결하세요. 예를 들어 packages/auth를 변경하면 두 서비스의 파일을 수정하지 않았더라도 두 서비스 모두 검토해야 할 수 있습니다. 검토 범위를 정하는 이 연결 관계는 조직에서 관리하며, Codex를 추가해도 자동으로 설정되지 않습니다.

컴포넌트 검토

규모가 큰 리포지터리에서는 PR마다 코드베이스 전체를 스캔할 필요가 없을 수 있습니다. 모노레포가 개별 서비스나 패키지로 나뉘어 있다면 경로별로 스캔할 수 있습니다. 공유 라이브러리와 이를 사용하는 컴포넌트를 함께 검토하려면 –path 옵션을 여러 번 지정하세요.

npx @openai/codex-security scan "$northstar_repo" \
  --path packages/auth \
  --path services/billing \
  --path services/reporting \
  --knowledge-base "$northstar_repo/SECURITY.md" \
  --knowledge-base "$northstar_kb" \
  --output-dir "$northstar_results/paths"

이 명령어는 리포지터리에서 선택한 경로만 스캔합니다.

PR 및 diff 스캔

PR을 스캔할 때는 인증을 거쳐 GitHub에서 가져온 메타데이터에 기록된 해당 PR의 정확한 베이스 커밋 해시와 헤드 커밋 해시를 사용하세요. 체크아웃한 리포지터리에서 두 커밋과 각각의 이력에 접근할 수 있어야 합니다. 다음 예제는 앞에서 설정한 변수를 재사용하고 diff 스캔 결과를 별도로 저장합니다.

BASE_SHA="<full PR base commit SHA>"
HEAD_SHA="<full PR head commit SHA>"

BASE_REVISION="$(
  git -C "$northstar_repo" merge-base "$BASE_SHA" "$HEAD_SHA"
)" || exit

npx @openai/codex-security scan "$northstar_repo" \
  --diff "$BASE_REVISION" \
  --head "$HEAD_SHA" \
  --knowledge-base "$northstar_kb" \
  --auth chatgpt \
  --output-dir "$northstar_results/pr"

diff 스캔은 제안된 변경 사항을 중심으로 검토합니다. 공유 라이브러리 변경으로 인해 이를 사용하는 컴포넌트까지 검토 범위를 넓혀야 한다면, 해당 PR의 헤드 커밋을 체크아웃하고 로컬 변경 사항이 없는 상태에서 컴포넌트 검토도 실행하세요. 결과는 따로 보관하세요. --diff와 --path는 서로 다른 스캔 모드이므로 함께 사용할 수 없습니다.

GitHub 경고 스캔

Codex Security CLI를 사용하면 기본 브랜치의 코드 스캔 경고도 검토할 수 있습니다.

northstar_github_repository="example/northstar"
northstar_github_alerts="$northstar_results/github-alerts.json"

# Import all open alerts as complete JSON.
npx @openai/codex-security import github "$northstar_github_repository" \
  --format json \
  > "$northstar_github_alerts"

# Or import a selected subset.
npx @openai/codex-security import github "$northstar_github_repository" \
  --github-alert 12 \
  --github-alert 18 \
  --format json \
  > "$northstar_github_alerts"

# Run from the corresponding local repository; imported contents are data.
cd "$northstar_repo"
npx @openai/codex-security validate "$northstar_github_alerts"