GitHub Actions에서 Codex Security를 실행하면 pull request의 변경 사항을 검토하거나 정해진 일정에 따라 리포지터리를 스캔할 수 있습니다. 이 액션은 CLI를 설치하고 구조화된 보고서를 저장하며 작업 요약과 소스 코드 주석을 추가합니다. 처음에는 스캔 결과를 참고용으로 사용하세요. 스캔 범위와 품질을 검토한 뒤 병합을 차단할 조건을 설정하세요.
워크플로우 준비하기
스캔을 실행하려면 Codex Security 액세스 권한이 필요합니다. 다음 절차에 따라 OpenAI API 키를 추가하세요.
- GitHub 리포지터리에서 Settings → Secrets and variables → Actions로 이동하세요.
- New repository secret을 선택하세요.
- 이름에
CODEX_SECURITY_API_KEY를 입력하고 값에 OpenAI API 키를 붙여넣은 뒤 시크릿을 저장하세요.
아래 워크플로우 예제는 이 시크릿을 Codex Security Action에 자동으로 전달합니다. 워크플로우 파일에 API 키를 직접 입력할 필요가 없습니다.
신뢰할 수 있는 리포지터리와 pull request에서만 워크플로우를 실행하세요. 스캔은 러너의 로컬 권한으로 실행되며 승인을 기다리지 않습니다. 스캔과 무관한 자격 증명이나 배포 단계는 별도 작업에 두세요.
GitHub Actions 워크플로우 추가하기
스캔 비용: 이 워크플로우는 사용자의 API 키를 사용하므로 요금이 발생할 수 있습니다. 두 예제 모두 max-cost를 생략하므로 예상 비용을 기준으로 스캔을 중단하지 않습니다. 스캔당 중단 기준을 5달러로 설정하려면 max-cost: "5"를 Codex Security Action의 with 블록에 추가하세요. 이미 진행 중인 요청으로 인해 실제 비용은 이 금액을 초과할 수 있습니다. 모델 가격 정보 지원 요건은 스캔 예산 설정하기(선택 사항)를 참고하세요.
정해진 일정에 따라 리포지터리 스캔하기
아래 워크플로우는 매주 월요일 07:23 UTC에 기본 브랜치를 스캔합니다. GitHub의 Actions 탭에서 수동으로 실행할 수도 있습니다. GitHub에서 호스팅하는 x64 Ubuntu 24.04 러너를 사용하며 필요한 샌드박스를 자동으로 설정합니다.
- 리포지터리에서 Add file → Create new file을 선택하세요.
- 파일 이름을
.github/workflows/codex-security-repository.yml로 지정하세요. - 아래 워크플로우를 붙여넣고 기본 브랜치에 커밋하세요.
name: Codex Security repository
on:
workflow_dispatch:
schedule:
- cron: "23 7 * * 1" # Mondays at 07:23 UTC
permissions:
contents: read
jobs:
security:
runs-on: ubuntu-24.04
timeout-minutes: 120
steps:
- name: Set up the Ubuntu sandbox
run: |
sudo apt-get update
sudo apt-get install --yes bubblewrap apparmor-profiles
sudo apparmor_parser -r /usr/share/apparmor/extra-profiles/bwrap-userns-restrict
- name: Check out the repository
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- name: Scan the repository
id: security
uses: openai/codex-security@3f61e5150981a5087c32e4395bbaa8ce5ce0c3e3 # action-v0.3.0
with:
scope: repository
model: gpt-6-sol
# For approved Daybreak Blue access, uncomment the next input.
# cyber-access-program: daybreak_blue
effort: high
fail-on-severity: none
upload-artifacts: "true"
env:
OPENAI_API_KEY: ${{ secrets.CODEX_SECURITY_API_KEY }}버전 정보: 두 예제 모두 Codex Security Action을 커밋 3f61e5150981a5087c32e4395bbaa8ce5ce0c3e3으로 고정합니다. 이 커밋에 해당하는 action-v0.3.0 릴리스는 CLI 0.3.0을 설치합니다. 고정한 커밋을 업데이트하기 전에 새 액션 릴리스의 내용을 검토하세요.
다른 러너 사용 시: 액션을 실행하려면 Node.js 24와 Python 3.11 이상이 필요합니다. 예제의 러너에는 두 가지 모두 설치되어 있습니다. 샌드박스 설정 단계에서는 스캔 전에 bubblewrap 패키지를 설치하고 함께 제공되는 AppArmor 프로필을 로드합니다. 이 러너에서는 패키지를 설치하는 것만으로는 충분하지 않습니다.
워크플로우를 수동으로 실행하려면 Actions → Codex Security repository → Run workflow를 선택하세요. 실행이 완료되면 해당 실행을 열어 요약, 주석, 다운로드 가능한 보고서를 확인하세요.
보안 이슈는 fail-on-severity가 none이므로 보고만 합니다. 스캐너에서 오류가 발생하거나 필수 보고서를 처리하는 과정에서 오류가 발생하면 작업은 실패합니다.
특정 폴더만 스캔하려면 스캔 단계의 with 블록에 각 폴더의 경로를 한 줄에 하나씩 그대로 입력하세요.
paths: |
src/api
src/auth경로를 지정하려면 scope: repository를 설정해야 하며, 글로브 패턴은 확장되지 않습니다. 변경 사항을 스캔할 때는 paths를 생략하세요. persist-credentials: false 설정을 유지하고 체크아웃 직후에 스캔을 실행하세요.
pull request 변경 사항 스캔하기
같은 시크릿을 사용해 .github/workflows/codex-security-pr.yml 파일을 다음과 같이 작성하세요.
name: Codex Security PR
on:
pull_request:
types: [opened, synchronize, reopened, ready_for_review]
permissions:
contents: read
concurrency:
group: codex-security-pr-${{ github.event.pull_request.number }}
cancel-in-progress: true
jobs:
security:
if: github.event.pull_request.head.repo.full_name == github.repository && github.actor != 'dependabot[bot]'
name: Codex Security
runs-on: ubuntu-24.04
timeout-minutes: 60
steps:
- name: Set up the Ubuntu sandbox
run: |
sudo apt-get update
sudo apt-get install --yes bubblewrap apparmor-profiles
sudo apparmor_parser -r /usr/share/apparmor/extra-profiles/bwrap-userns-restrict
- name: Check out the pull request
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
ref: ${{ github.event.pull_request.head.sha }}
fetch-depth: 0
persist-credentials: false
- name: Scan PR changes
id: security
uses: openai/codex-security@3f61e5150981a5087c32e4395bbaa8ce5ce0c3e3 # action-v0.3.0
with:
scope: diff
model: gpt-6-sol
# For approved Daybreak Blue access, uncomment the next input.
# cyber-access-program: daybreak_blue
effort: high
fail-on-severity: none
upload-artifacts: "true"
env:
OPENAI_API_KEY: ${{ secrets.CODEX_SECURITY_API_KEY }}같은 리포지터리의 브랜치에서 PR을 열거나 업데이트하세요. 액션은 전체 커밋 기록에서 정확한 병합 기준 커밋을 찾아 해당 커밋부터 체크아웃한 PR 헤드까지의 변경 사항을 스캔합니다. Codex Security 검사 결과는 PR의 Checks 탭에서 확인하세요. 처음에는 보안 이슈를 참고용으로 검토하고, 변경 사항의 병합을 제한할 준비가 되면 심각도 정책을 선택하세요.
이 예제는 포크에서 생성한 PR과 dependabot[bot]이 연 PR을 건너뜁니다. 작업을 건너뛰었다면 보안 검토를 거쳤다고 볼 수 없습니다. 이 봇의 PR도 스캔하려면 작업 실행 조건에서 해당 봇을 제외하는 조건을 삭제하고 CODEX_SECURITY_API_KEY를 봇 전용 시크릿으로 설정해 dependabot[bot]도 사용할 수 있게 하세요. 액션은 pull_request_target과 workflow_run을 지원하지 않습니다.
스캐너는 체크아웃한 코드에서 해당 범위에 적용되는 SECURITY.md 지침을 읽습니다. PR에서 정책을 변경했다면 변경된 지침이 적용되므로 코드와 함께 검토하세요.
Daybreak 액세스 설정하기(선택 사항)
Daybreak 사용은 선택 사항입니다. 두 워크플로우 예제 모두 gpt-6-sol을 사용합니다. 조직이 Trusted Access for Cyber 승인을 받았다면 주석 기호 #를 제거하세요. 제거할 기호는 cyber-access-program 앞에 있으며, 해당 줄은 스캔 단계의 with 블록에 있습니다.
model: gpt-6-sol
cyber-access-program: daybreak_blueDaybreak Blue가 활성화되어 있고 gpt-6-sol에 액세스할 수 있는 프로젝트의 API 키를 사용하세요.
프로그램 입력값으로 standard도 사용할 수 있습니다. Daybreak 액세스 권한이 없다면 표준 보호 조치가 적용되는 환경에서 API 키로 액세스할 수 있는 모델을 사용하고, cyber-access-program을 생략하거나 standard로 설정하세요. 모델이나 프로그램을 선택하는 것만으로는 액세스 권한이 부여되지 않습니다. 액션의 Daybreak 액세스 안내를 참고하세요.
모델이 요청을 거부하거나 안전 조치로 요청이 차단되어 스캔이 중단되면 액션은 실패합니다. fail-on-severity가 none이어도 마찬가지입니다. 이 입력값은 보안 이슈를 처리하는 정책에만 적용되며 스캐너 오류 처리에는 영향을 주지 않습니다.
스캔 예산 설정하기(선택 사항)
두 워크플로우 예제 모두 max-cost를 생략하므로 예상 비용을 기준으로 스캔을 중단하지 않습니다. 중단 기준을 설정하려면 max-cost 입력값에 0보다 큰 금액을 미국 달러 단위로 지정하세요. CLI에서 직접 스캔할 때는 --max-cost를 사용하세요.
비용 제한을 사용하려면 CLI가 선택한 모델의 가격 정보를 지원해야 합니다. 중단 여부는 예상 비용을 기준으로 판단하며, 이미 진행 중인 요청으로 인해 실제 지출은 기준 금액을 초과할 수 있습니다. 예상 비용이 기준에 도달해 스캔이 중단되면 보안 이슈와 coverage.json을 검토하세요. 비용 제한이 어떻게 적용되는지는 출력 및 정책 옵션을 참고하세요.
보고서 저장 및 SARIF 업로드하기
예제에서는 upload-artifacts: "true"를 설정해 다운로드 가능한 보고서를 7일간 보관합니다. 보고서에는 소스 코드 일부, 취약점을 뒷받침하는 증거, 수정 방법이 포함될 수 있습니다. 코드에 적합한 보관 기간과 리포지터리 액세스 권한을 설정하세요. 액션은 허용 목록에 있고 검증을 통과한 보고서만 업로드합니다. results-directory 출력값이 가리키는 디렉터리를 재귀적으로 업로드하지 마세요.
SARIF 업로드는 선택 사항입니다. 비공개 또는 내부 리포지터리에서는 업로드하기 전에 GitHub Code Security를 활성화하세요. 워크플로우의 permissions 블록을 다음 내용으로 교체하세요.
permissions:
contents: read
security-events: write
actions: read # Required for private repositories그런 다음 사용할 워크플로우에서 스캔 단계 뒤에 다음 단계를 추가하세요.
- name: Upload security findings
if: ${{ always() && steps.security.outputs.sarif-upload-ready == 'true' }}
uses: github/codeql-action/upload-sarif@b96794f015dfd88f77b49b1c93e0fa7110f94c63 # v4.38.0
with:
sarif_file: ${{ steps.security.outputs.sarif-path }}
sha: ${{ steps.security.outputs.scanned-sha }}
ref: ${{ steps.security.outputs.analysis-ref }}
category: codex-security-repositoryPR 워크플로우에는 category: codex-security-pr를 사용해 스캔 범위별로 카테고리를 구분하세요. 스캔 단계의 id: security 설정은 유지하세요. 보안 이슈로 인해 심각도 정책을 통과하지 못해도 완전한 보고서가 검증을 통과했다면 업로드할 수 있습니다. 스캔이 실패하거나 중단된 경우, 변경 사항이 없는 경우, 모의 실행인 경우에는 SARIF를 업로드하지 않습니다.
전체 설정, 상태 필드, 보고서 경로는 액션의 입출력 레퍼런스를 참고하세요.
심각도 정책 선택하기
GitHub 워크플로우의 초기 설정은 fail-on-severity: none입니다. 완료된 스캔에서 심각도가 ‘높음’ 또는 ‘치명적’인 보안 이슈가 발견될 때 작업을 실패로 처리하려면 스캔 단계의 입력값을 다음과 같이 변경하세요.
fail-on-severity: highPR 작업이 실패하면 병합을 차단하도록 리포지터리 규칙에서 Codex Security를 필수 상태 검사로 지정하세요. GitHub는 필수 검사라도 조건에 따라 건너뛴 작업을 성공으로 처리합니다. 포크에서 생성한 PR과 dependabot[bot]의 PR은 스캔 없이 이 검사를 통과합니다. 이렇게 스캔을 건너뛰었을 때도 병합을 차단하려면 스캔이 성공적으로 완료되어야 병합할 수 있도록 설정하세요.
액션은 CLI 실행 결과에 따라 다음과 같이 동작합니다.
- 종료 코드가
0이면scan-status: completed와policy-status: passed가 설정됩니다. - 종료 코드가
1이면scan-status: completed와policy-status: failed가 설정됩니다. 설정한 심각도 이상의 보안 이슈가 발견되어 단계가 실패합니다. - 종료 코드가
2이거나 프로세스가 중단되면scan-status: failed와policy-status: not-evaluated가 설정되고 단계가 실패합니다. - 필수 보고서가 유효하지 않거나 누락된 경우, 체크아웃 상태가 변경된 경우, 요청한 아티팩트 업로드에 실패한 경우, 런타임 정리에 실패한 경우에도 단계가 실패합니다.
스캔이 완료되었다는 것은 설정한 분석에서 유효한 결과가 나왔다는 뜻입니다. 스캔 범위에서 제외된 항목, 보류된 조사 등 coverage.json에 기록된 사항은 별도의 스캔 상태로 처리되지 않으며 심각도 정책을 우회하지도 않습니다. 스캔을 완료했다고 해서 모든 취약점을 발견했다는 보장은 없습니다. 결과를 평가할 때 coverage.json을 검토하세요.
스캔이 성공적으로 완료되어야 병합할 수 있도록 설정하기
더 엄격한 정책을 적용하려면 스캔 작업이 실패하거나 GitHub가 작업을 건너뛰더라도 실행되는 별도의 검사 작업을 추가하세요. 작업을 건너뛰면 그 안의 단계가 하나도 실행되지 않으므로 스캔 작업 내부에서는 건너뛰기 여부를 검사할 수 없습니다.
PR 워크플로우에 다음 outputs 매핑을 추가하세요. 기존 security 작업 안에서 runs-on 및 steps와 같은 수준으로 들여쓰세요.
outputs:
scan-status: ${{ steps.security.outputs.scan-status }}그런 다음 jobs 아래에 기존 security 작업과 같은 수준으로 다음 작업을 추가하세요.
security-gate:
name: Codex Security gate
needs: security
if: ${{ always() }}
runs-on: ubuntu-24.04
steps:
- name: Require a successful, completed scan
env:
SCAN_RESULT: ${{ needs.security.result }}
SCAN_STATUS: ${{ needs.security.outputs.scan-status }}
run: test "$SCAN_RESULT" = success && test "$SCAN_STATUS" = completed이 정책을 적용하려면 Codex Security gate를 필수 상태 검사로 지정하세요. 검사를 통과하려면 스캔 작업이 성공하고 scan-status: completed가 설정되어야 합니다. 두 조건을 모두 확인하므로 스캔 자체가 완료되었더라도 심각도 정책, 보고서 처리 또는 런타임 정리로 인해 작업이 실패하면 검사를 통과할 수 없습니다.
예제의 제외 조건을 그대로 사용하면 이 검사는 포크에서 생성한 PR과 dependabot[bot]의 PR 병합을 차단합니다. 변경 사항이 없거나 모의 실행인 경우에도 액션이 스캔 상태를 skipped로 표시하므로 병합이 차단됩니다. 검사 작업이 제외된 PR을 스캔하지는 않습니다. 이런 경우에 병합을 차단해야 할 때만 이 정책을 선택하세요.
스캔 문제 해결하기
- Git 참조를 찾을 수 없거나 예상과 다른 변경 사항이 표시되는 경우: PR 헤드를 체크아웃할 때
fetch-depth: 0을 설정하세요. - 샌드박스 시작 오류: Ubuntu 24.04에서는 액션을 실행하기 전에
bubblewrap패키지를 설치하고 AppArmor 프로필을 로드하세요. 패키지를 설치하는 것만으로는 필요한 프로필이 로드되지 않습니다. - 자격 증명 누락: 신뢰할 수 있는 워크플로우에서
CODEX_SECURITY_API_KEY를 사용할 수 있고 이 시크릿이 스캔 단계의OPENAI_API_KEY환경 변수에 매핑되어 있는지 확인하세요. - Python 설정 오류: 액션을 실행하려면 Python 3.11 이상이 필요합니다.
- 스캔 범위 참고 사항: 스캔 범위에서 제외된 항목과 보류된 조사 내역을
coverage.json에서 검토하세요. 이러한 사항으로 인해 실행이 실패하거나 심각도 정책이 우회되지는 않습니다. - SARIF 누락:
scan-status,report-status,sarif-upload-ready를 확인하세요. 선택 사항인 SARIF가 누락되면 액션은 경고를 표시하며 스캔 결과는 그대로 유지합니다. 요청한 아티팩트 업로드가 실패하면 작업도 실패합니다. - SARIF 업로드 오류: 조직에서 해당 리포지터리에 GitHub Code Security를 활성화했는지, 워크플로우에
actions: read,contents: read,security-events: write권한을 부여했는지 확인하세요.
전체 명령어, 플래그, 아티팩트, 출력 필드는 CLI 레퍼런스를 참고하세요. 다른 CI/CD 제공업체에 관한 내용은 CI/CD 개요를 참고하세요.