Menjalankan Codex Security di GitLab CI/CD

Jalankan Codex Security di GitLab CI/CD untuk memindai perubahan yang telah di-commit dan cabang yang dilindungi, memublikasikan temuan ke GitLab Security, serta secara opsional mengusulkan perbaikan terverifikasi dalam merge request draf.

Alur kerja ini memisahkan kredensial pemindaian dari akses tulis repositori. Perubahan yang dihasilkan selalu memerlukan peninjauan manusia sebelum digabungkan.

Mulailah dengan pelaporan khusus pemindaian. Aktifkan remediasi hanya setelah Anda memeriksa runner, temuan, dan batas kredensial untuk proyek Anda.

Sebelum memulai

Anda memerlukan:

• Proyek GitLab dengan runner tepercaya yang mendukung namespace pengguna sandbox Codex.
• Peran Maintainer atau Owner dalam proyek GitLab agar Anda dapat mengonfigurasi variabel CI/CD proyek dan sumber daya yang dilindungi.
• API key OpenAI dengan akses Codex Security. Organisasi yang menggunakan Platform API key dapat meminta Trusted Access untuk Cyber. Individu yang menggunakan autentikasi ChatGPT dapat memakai alur Trusted Access pribadi. Beberapa akun atau repositori memerlukan akses ini untuk pemindaian seluruh repositori.
• GitLab Ultimate 19.2 atau versi lebih baru untuk penyerapan SARIF 2.1.0.
• Riwayat Git lengkap agar job merge request dapat menghitung basis penggabungan.

Image pipeline menginstal Node.js 26, Python 3, Git, rg, dan Codex Security CLI yang versinya dikunci. Remediasi otomatis juga memerlukan pengujian regresi yang sudah ada dan runner yang dapat menjalankan perintah yang dikendalikan repositori tanpa kredensial yang dilindungi.

Memulai dengan pipeline khusus pemindaian

Buat variabel GitLab CI/CD yang disamarkan, disembunyikan, dan dilindungi bernama CODEX_SECURITY_API_KEY. Gunakan OpenAI Platform API key dengan akses Codex Security, dan atur cakupan lingkungannya ke codex-security/openai. Lihat variabel CI/CD dengan cakupan lingkungan.

Tambahkan pipeline minimal ini terlebih dahulu ke proyek pengujian. Pipeline ini memindai perubahan yang telah di-commit dalam merge request terlindungi yang memenuhi syarat, memublikasikan SARIF dari job laporan yang berhasil, dan memulihkan hasil pemindai dalam gerbang terpisah:

stages:
  - security_scan
  - security_gate

.codex-security-merge-request:
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_SOURCE_PROJECT_ID == $CI_PROJECT_ID && $CI_MERGE_REQUEST_SOURCE_BRANCH_PROTECTED == "true" && $CI_MERGE_REQUEST_TARGET_BRANCH_PROTECTED == "true"'

codex-security:
  extends: .codex-security-merge-request
  stage: security_scan
  image: node:26-bookworm-slim
  environment:
    name: codex-security/openai
    action: access
  variables:
    GIT_DEPTH: "0"
  before_script:
    - npm install --prefix /tmp/codex-security-cli --ignore-scripts --no-audit --no-fund @openai/codex-security@0.1.20
  script:
    - |
      set -eu
      test -n "${CODEX_SECURITY_API_KEY:-}"

      CODEX_SECURITY_BIN="/tmp/codex-security-cli/node_modules/.bin/codex-security"
      RESULTS_DIR="/tmp/codex-security-results-$CI_JOB_ID"
      ARTIFACT_DIR="codex-security-artifacts"
      BASE_REVISION="$(git merge-base \
        "$CI_MERGE_REQUEST_DIFF_BASE_SHA" "$CI_COMMIT_SHA")"
      install -d -m 700 "$RESULTS_DIR" "$ARTIFACT_DIR/results"

      codex_security_api_key="$CODEX_SECURITY_API_KEY"
      unset CODEX_SECURITY_API_KEY
      set +e
      OPENAI_API_KEY="$codex_security_api_key" \
        "$CODEX_SECURITY_BIN" scan . \
          --diff "$BASE_REVISION" \
          --head "$CI_COMMIT_SHA" \
          --auth api-key \
          --output-dir "$RESULTS_DIR" \
          --json
      scan_exit="$?"
      set -e
      unset codex_security_api_key

      case "$scan_exit" in
        0|1|2) ;;
        *) exit "$scan_exit" ;;
      esac

      "$CODEX_SECURITY_BIN" export "$RESULTS_DIR" \
        --export-format sarif \
        --source-root "$CI_PROJECT_DIR" \
        --output "$ARTIFACT_DIR/results.sarif"
      test -s "$ARTIFACT_DIR/results.sarif"
      cp -R "$RESULTS_DIR"/. "$ARTIFACT_DIR/results/"
      printf '%s\n' "$scan_exit" > "$ARTIFACT_DIR/scan-exit-code.txt"
      exit 0
  artifacts:
    when: always
    access: maintainer
    expire_in: 7 days
    paths:
      - codex-security-artifacts/
    reports:
      sarif: codex-security-artifacts/results.sarif

codex-security-gate:
  extends: .codex-security-merge-request
  stage: security_gate
  image: alpine:3.20
  needs:
    - job: codex-security
      artifacts: true
  script:
    - exit "$(cat codex-security-artifacts/scan-exit-code.txt)"

Tinjau setiap perubahan pada .gitlab-ci.yml sebelum menjalankan job yang membawa rahasia. Contoh minimal ini sengaja tidak menyertakan pemindaian penuh dan remediasi.

Mengadopsi pipeline produksi

1. Unduh pipeline GitLab lengkap dan simpan sebagai .gitlab-ci.yml di root repositori. Jika repositori Anda sudah memiliki pipeline, gabungkan tahapan, templat tersembunyi, dan job dari contoh tersebut ke file yang ada.
2. Pertahankan tahapan build, pengujian, dan deployment yang sudah ada. Jika proyek menggunakan workflow: rules, pastikan konfigurasi tersebut mengizinkan peristiwa pipeline yang ingin Anda pindai.

Contoh ini menambahkan tahapan security_scan, security_remediation, security_publish, dan security_gate. Pelaporan khusus pemindaian hanya memerlukan CODEX_SECURITY_API_KEY.

Secara default, job pemindaian hanya berjalan untuk merge request dalam proyek yang sama di antara cabang yang dilindungi. Atur CODEX_SECURITY_FULL_SCAN_DEFAULT_BRANCH=true untuk memindai push ke cabang default yang dilindungi dan pipeline manual. Atur CODEX_SECURITY_SCHEDULED_DEEP_SCAN=true serta konfigurasikan anggaran waktu dan biaya secara eksplisit untuk mengaktifkan pemindaian mendalam terjadwal pada cabang default yang dilindungi.

Pipeline merge request hanya dapat mengakses variabel dan runner yang dilindungi jika:

• Anda melindungi cabang sumber dan target dalam proyek yang sama.
• Proyek mengizinkan pipeline merge request mengakses variabel dan runner yang dilindungi.
• Pengguna yang memulai pipeline dapat melakukan push atau penggabungan ke cabang target.

Pipeline fork dan merge request yang tidak dilindungi tidak menerima kredensial pemindaian. Tinjau setiap perubahan pada .gitlab-ci.yml sebelum menjalankan job yang membawa rahasia. Menyamarkan dan menyembunyikan variabel tidak membuat kode CI yang tidak tepercaya menjadi aman.

Menjalankan pemindaian dan meninjau temuan

Buat merge request terlindungi yang memenuhi syarat atau jalankan pipeline pada cabang default yang dilindungi. Mulailah dengan diff kecil sebelum menjalankan pemindaian seluruh repositori berbayar.

Buka job codex-security dan pastikan artefaknya mencakup:

• scan-manifest.json
• findings.json
• coverage.json
• results.sarif
• scan-exit-code.txt

Kemudian buka tab Security pada pipeline, tinjau peringatan penyerapan, dan pastikan pengenal temuan, tingkat keparahan, serta lokasi sumber. Pemindaian cabang default juga membuat catatan kerentanan proyek. Temuan merge request muncul di tab Security pipeline atau widget keamanan merge request, tetapi tidak membuat catatan kerentanan di seluruh proyek.

Batasi akses artefak karena hasil pemindaian dapat memuat cuplikan sumber yang rentan, bukti, dan detail remediasi.

Memilih profil pemindaian

Pipeline memilih profil berdasarkan pemicu:

Pemindaian merge request memusatkan umpan balik pada perubahan yang telah di-commit. Pemindaian cabang default meninjau repositori terintegrasi. Pemindaian mendalam terjadwal memberikan cakupan berkala yang lebih luas. Pemindaian diff yang selesai hanya berlaku untuk perubahan tersebut dan tidak menunjukkan bahwa seluruh repositori bersih.

Alur kerja menginstal CLI di luar repositori dan menjalankannya melalui path absolut. Prapemeriksaan dry-run menggunakan API key dengan cakupan proses, tetapi tidak memulai pemindaian berbayar atau memverifikasi autentikasi API, akses Codex Security, kuota, maupun ketersediaan model.

Alur kerja menulis status dan hasil pemindaian di luar worktree serta membatasi OPENAI_API_KEY pada proses pemindaian. CLI menerima lingkungan kecil yang eksplisit, bukan mewarisi setiap variabel GitLab. Untuk pemindaian diff, alur kerja menghitung basis penggabungan dan mengikat pemindaian ke revisi basis dan head yang ditinjau.

Contoh ini mengunci @openai/codex-security ke 0.1.20. Uji ulang autentikasi, artefak, penyerapan SARIF, dan pembatasan kebijakan sebelum mengubah versi yang dikunci.

Memisahkan pelaporan dari penerapan kebijakan

GitLab menyerap SARIF dari job laporan yang berhasil. Pipeline memublikasikan laporan terlebih dahulu, lalu memulihkan status keluar pemindai dalam job codex-security-gate terpisah.

Job laporan menerima temuan dari kode keluar 0 dan 1. Job ini menerima kode keluar 2 hanya jika manifes pemindaian membuktikan pemindaian telah selesai, cakupan secara eksplisit adalah partial, dan terdapat laporan SARIF yang tidak kosong. Kegagalan runtime, konfigurasi, atau ekspor lainnya tetap memblokir.

Gerbang akhir mempertahankan kode keluar pemindai berikut:

Contoh ini untuk sementara mengizinkan kode keluar 2 selagi Anda mengkalibrasi cakupan parsial. Hapus izin tersebut jika cakupan tidak lengkap harus memblokir pipeline.

Remediasi dan publikasi berjalan sebelum gerbang kebijakan akhir. Temuan yang memenuhi syarat dapat menghasilkan merge request draf terverifikasi meskipun gerbang kemudian menggagalkan pipeline.

Mengaktifkan remediasi terverifikasi

Remediasi otomatis bersifat opsional dan hanya berjalan untuk pipeline cabang default yang dilindungi. Proses remediasi Codex dan perintah verifikasi yang dikendalikan repositori tidak menerima token akses proyek GitLab maupun kredensial yang disuntikkan runner.

Kontrak keamanan memiliki tiga bagian: perintah yang dikendalikan repositori tidak pernah menerima kredensial OpenAI atau GitLab, hanya job publikasi yang menerima akses tulis repositori, dan setiap perubahan yang dihasilkan tetap berupa draf hingga ditinjau dan digabungkan oleh manusia.

Alur kerja ini:

1. Memerlukan cakupan pemindaian lengkap dan temuan dengan tingkat keparahan high atau critical.
2. Memastikan pengujian regresi yang dikonfigurasi gagal sebelum patch diterapkan.
3. Menghasilkan patch terfokus dan menolak perubahan pada CI, kredensial, file biner, atau file terlindungi lainnya.
4. Menjalankan pengujian regresi tanpa kredensial OpenAI, GitLab, registry, deployment, atau job-token.
5. Menggunakan verify-fix untuk mengembalikan fixed, still_vulnerable, atau inconclusive. Job hanya memublikasikan patch jika verify-fix mengembalikan fixed dan proses verifikasi tidak mengubah patch.

Atur variabel terlindungi berikut untuk mengaktifkan remediasi:

• Atur CODEX_SECURITY_ENABLE_REMEDIATION ke true.
• Atur CODEX_SECURITY_VERIFICATION_COMMAND ke pengujian regresi yang sudah ada dan menghasilkan kode keluar 1 sebelum perbaikan serta 0 setelahnya.
• Secara opsional, atur CODEX_SECURITY_SETUP_COMMAND ke perintah penyiapan dependensi noninteraktif.

Pilih pengujian regresi yang menguji invarian keamanan yang mendasarinya, bukan implementasi tertentu. Terapkan ketelitian yang sama pada perubahan pengujian dan sumber yang dihasilkan.

Memublikasikan merge request draf

Buat token akses proyek GitLab dengan peran Developer dan cakupan api serta write_repository. Simpan sebagai GITLAB_REMEDIATION_TOKEN yang dilindungi, disamarkan, dan disembunyikan serta hanya dicakupkan ke lingkungan codex-security/publish.

Atur CODEX_SECURITY_CREATE_MR=true untuk mengaktifkan publikasi. Atur juga CODEX_SECURITY_MR_TEST_COMMAND yang nonrahasia ke pengujian regresi keamanan khusus proyek yang harus dilalui setiap cabang remediasi yang dihasilkan. Biarkan variabel ini tidak dilindungi agar merge request tidak terlindungi yang dihasilkan dapat membaca perintah tersebut. Alur kerja publikasi:

• Menerima token akses tulis repositori, tetapi tidak menerima kredensial OpenAI.
• Membuat cabang codex-security/fix-<finding-hash>.
• Membuka merge request draf dan menggunakan kembali draf terbuka yang sudah ada, alih-alih membuat duplikat.
• Menjalankan pengujian regresi cabang remediasi yang tidak dilindungi sebagai pengguna tanpa hak istimewa dalam salinan yang hanya berisi file terlacak tanpa kredensial yang dilindungi.
• Tidak pernah menggabungkan perubahan yang dihasilkan secara otomatis.

Jangan mengganti token akses proyek dengan CI_JOB_TOKEN. Token tersebut tidak dapat menjalankan operasi pembuatan merge request yang diperlukan. Tinjau patch yang diusulkan, bukti verifikasi, dan temuan sebelum menggabungkannya.

Mengonfigurasi variabel opsional

Konfigurasikan hanya variabel yang diperlukan untuk fitur yang Anda aktifkan:

GitLab menyediakan variabel CI_*. Pipeline mengelola CODEX_SECURITY_BIN, CODEX_SECURITY_EFFORT, CODEX_SECURITY_MODE, CODEX_SECURITY_STATE_DIR, dan CODEX_SECURITY_TARGET; jangan konfigurasikan variabel tersebut sebagai variabel proyek. Untuk pemindaian diff, CLI memperoleh identitas target kanonis dari revisi basis dan head yang telah dinormalisasi.

Menyetel penerapan kebijakan dan biaya

Gunakan pemindaian diff terfokus untuk umpan balik merge request, pemindaian repositori standar untuk cabang default, dan pemindaian mendalam terjadwal untuk cakupan yang lebih luas. Kedua profil seluruh repositori dinonaktifkan secara default. Pemindaian mendalam terjadwal juga memerlukan CODEX_SECURITY_DEEP_MAX_TIME_HOURS dan CODEX_SECURITY_DEEP_MAX_COST; pertahankan anggaran waktu CLI di bawah batas waktu delapan jam job. Ukur eksekusi yang representatif sebelum menetapkan anggaran. Perlakukan --max-cost sebagai batas pengaman estimasi biaya, bukan batas keras penagihan.

Mulailah dengan pemindaian khusus laporan. Tambahkan --fail-on-severity setelah tim Anda meninjau temuan, cakupan, biaya, dan runtime yang representatif. Lihat Jalankan Codex Security di CI untuk kebijakan tingkat keparahan dan detail kode keluar.

Saat job gagal:

• Artefak pemindaian yang hilang menunjukkan masalah konfigurasi atau runner.
• Artefak yang ada dengan cakupan parsial mengharuskan Anda meninjau coverage.json.
• Temuan GitLab yang hilang mengharuskan Anda memeriksa apakah job laporan SARIF berhasil dan apakah GitLab menerima laporan tersebut.
• Remediasi yang dilewati mengharuskan Anda memeriksa cabang yang dilindungi, cakupan lengkap, tingkat keparahan temuan, perintah verifikasi, dan variabel aktivasi.
• Kesalahan publikasi mengharuskan Anda memeriksa peran, cakupan, dan pembatasan lingkungan token proyek.

Untuk setiap perintah, flag, dan artefak, lihat referensi Codex Security CLI.