Chạy Codex Security trong GitLab CI/CD

Chạy Codex Security trong GitLab CI/CD để quét các thay đổi đã commit và các nhánh được bảo vệ, công bố phát hiện lên GitLab Security và tùy chọn đề xuất các bản sửa lỗi đã xác minh trong yêu cầu hợp nhất nháp.

Quy trình này tách riêng thông tin xác thực để quét khỏi quyền ghi vào kho lưu trữ. Mọi thay đổi được tạo đều phải được con người xem xét trước khi hợp nhất.

Hãy bắt đầu bằng báo cáo chỉ quét. Chỉ bật tính năng khắc phục sau khi bạn kiểm tra runner, các phát hiện và ranh giới thông tin xác thực của dự án.

Trước khi bắt đầu

Bạn cần:

• Một dự án GitLab có runner đáng tin cậy và hỗ trợ không gian tên người dùng mà môi trường cô lập của Codex yêu cầu.
• Vai trò Maintainer hoặc Owner trong dự án GitLab để bạn có thể cấu hình các biến CI/CD của dự án và tài nguyên được bảo vệ.
• Một OpenAI API key có quyền truy cập Codex Security. Các tổ chức sử dụng Platform API key có thể yêu cầu Trusted Access cho Cyber. Cá nhân sử dụng phương thức xác thực ChatGPT có thể dùng quy trình Trusted Access cá nhân. Một số tài khoản hoặc kho lưu trữ cần quyền truy cập này để quét toàn bộ kho lưu trữ.
• GitLab Ultimate 19.2 trở lên để nhập SARIF 2.1.0.
• Toàn bộ lịch sử Git để các tác vụ yêu cầu hợp nhất có thể tính toán merge base.

Ảnh pipeline cài đặt Node.js 26, Python 3, Git, rg và Codex Security CLI đã được cố định phiên bản. Tính năng khắc phục tự động còn yêu cầu một kiểm thử hồi quy hiện có và một runner có thể chạy các lệnh do kho lưu trữ kiểm soát mà không có thông tin xác thực được bảo vệ.

Bắt đầu với pipeline chỉ quét

Tạo một biến GitLab CI/CD được che, ẩn và bảo vệ có tên CODEX_SECURITY_API_KEY. Sử dụng OpenAI Platform API key có quyền truy cập Codex Security và đặt phạm vi môi trường của biến thành codex-security/openai. Xem các biến CI/CD theo phạm vi môi trường.

Trước tiên, hãy thêm pipeline tối thiểu này vào một dự án thử nghiệm. Pipeline quét các thay đổi đã commit trong những yêu cầu hợp nhất được bảo vệ đủ điều kiện, công bố SARIF từ tác vụ báo cáo thành công và khôi phục kết quả của trình quét trong một cổng kiểm soát riêng:

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)"

Xem xét mọi thay đổi đối với .gitlab-ci.yml trước khi chạy tác vụ có chứa bí mật. Ví dụ tối thiểu này chủ ý không bao gồm quét toàn bộ và khắc phục.

Áp dụng pipeline sản xuất

1. Tải pipeline GitLab hoàn chỉnh xuống và lưu dưới dạng .gitlab-ci.yml trong thư mục gốc của kho lưu trữ. Nếu kho lưu trữ đã có pipeline, hãy hợp nhất các giai đoạn, mẫu ẩn và tác vụ của ví dụ vào tệp hiện có.
2. Giữ nguyên các giai đoạn build, kiểm thử và triển khai hiện có. Nếu dự án sử dụng workflow: rules, hãy xác nhận rằng cấu hình đó cho phép các sự kiện pipeline mà bạn muốn quét.

Ví dụ thêm các giai đoạn security_scan, security_remediation, security_publish và security_gate. Báo cáo chỉ quét chỉ yêu cầu CODEX_SECURITY_API_KEY.

Theo mặc định, tác vụ quét chỉ chạy cho các yêu cầu hợp nhất trong cùng dự án giữa các nhánh được bảo vệ. Đặt CODEX_SECURITY_FULL_SCAN_DEFAULT_BRANCH=true để quét các lần push lên nhánh mặc định được bảo vệ và pipeline thủ công. Đặt CODEX_SECURITY_SCHEDULED_DEEP_SCAN=true và cấu hình rõ ngân sách thời gian cùng chi phí để bật quét sâu theo lịch trên nhánh mặc định được bảo vệ.

Pipeline yêu cầu hợp nhất chỉ có thể truy cập các biến và runner được bảo vệ khi:

• Bạn bảo vệ nhánh nguồn và nhánh đích trong cùng một dự án.
• Dự án cho phép pipeline yêu cầu hợp nhất truy cập các biến và runner được bảo vệ.
• Người dùng khởi chạy pipeline có thể push hoặc hợp nhất vào nhánh đích.

Pipeline từ fork và yêu cầu hợp nhất không được bảo vệ không nhận được thông tin xác thực để quét. Xem xét mọi thay đổi đối với .gitlab-ci.yml trước khi chạy tác vụ có chứa bí mật. Việc che và ẩn một biến không làm cho mã CI không đáng tin cậy trở nên an toàn.

Chạy quét và xem xét các phát hiện

Tạo một yêu cầu hợp nhất được bảo vệ đủ điều kiện hoặc chạy pipeline trên nhánh mặc định được bảo vệ. Hãy bắt đầu với một diff nhỏ trước khi chạy tác vụ quét toàn bộ kho lưu trữ có tính phí.

Mở tác vụ codex-security và xác nhận rằng các artifact của tác vụ bao gồm:

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

Sau đó, mở thẻ Security của pipeline, xem xét các cảnh báo khi nhập và xác nhận mã định danh phát hiện, mức độ nghiêm trọng cùng vị trí trong mã nguồn. Các lần quét nhánh mặc định cũng tạo hồ sơ lỗ hổng cho dự án. Phát hiện trong yêu cầu hợp nhất xuất hiện ở thẻ Security của pipeline hoặc tiện ích bảo mật của yêu cầu hợp nhất nhưng không tạo hồ sơ lỗ hổng trên toàn dự án.

Hạn chế quyền truy cập artifact vì kết quả quét có thể chứa các đoạn mã nguồn dễ bị tấn công, bằng chứng và thông tin chi tiết về biện pháp khắc phục.

Chọn hồ sơ quét

Pipeline chọn hồ sơ dựa trên nguồn kích hoạt:

Quét yêu cầu hợp nhất tập trung phản hồi vào thay đổi đã commit. Quét nhánh mặc định xem xét kho lưu trữ đã tích hợp. Quét sâu theo lịch cung cấp phạm vi bao phủ định kỳ rộng hơn. Một lần quét diff đã hoàn tất chỉ áp dụng cho thay đổi đó và không chứng minh rằng toàn bộ kho lưu trữ không có vấn đề.

Quy trình cài đặt CLI bên ngoài kho lưu trữ và chạy bằng đường dẫn tuyệt đối. Bước kiểm tra trước dry-run sử dụng API key theo phạm vi tiến trình nhưng không bắt đầu một lần quét có tính phí hay xác minh phương thức xác thực API, quyền truy cập Codex Security, hạn ngạch hoặc khả năng cung cấp model.

Quy trình ghi trạng thái và kết quả quét bên ngoài worktree, đồng thời giới hạn OPENAI_API_KEY trong tiến trình quét. CLI nhận một môi trường nhỏ và được chỉ định rõ thay vì kế thừa mọi biến GitLab. Đối với quét diff, quy trình tính toán merge base và ràng buộc lần quét với các bản sửa đổi base và head đã được xem xét.

Ví dụ cố định @openai/codex-security ở 0.1.20. Hãy kiểm thử lại phương thức xác thực, artifact, việc nhập SARIF và kiểm soát chính sách trước khi thay đổi phiên bản cố định.

Tách biệt báo cáo khỏi thực thi chính sách

GitLab nhập SARIF từ một tác vụ báo cáo thành công. Pipeline công bố báo cáo trước rồi khôi phục trạng thái thoát của trình quét trong một tác vụ codex-security-gate riêng.

Tác vụ báo cáo chấp nhận các phát hiện từ mã thoát 0 và 1. Tác vụ chỉ chấp nhận mã thoát 2 khi bản kê khai quét chứng minh rằng lần quét đã hoàn tất, phạm vi bao phủ được đặt rõ thành partial và có báo cáo SARIF không rỗng. Các lỗi khác về thời gian chạy, cấu hình hoặc xuất dữ liệu vẫn chặn pipeline.

Cổng kiểm soát cuối cùng giữ nguyên các mã thoát sau của trình quét:

Ví dụ tạm thời cho phép mã thoát 2 trong khi bạn hiệu chỉnh phạm vi bao phủ một phần. Hãy bỏ ngoại lệ đó khi phạm vi bao phủ không đầy đủ phải chặn pipeline.

Quá trình khắc phục và công bố chạy trước cổng kiểm soát chính sách cuối cùng. Một phát hiện đủ điều kiện có thể tạo yêu cầu hợp nhất nháp đã xác minh ngay cả khi cổng kiểm soát sau đó khiến pipeline thất bại.

Bật tính năng khắc phục đã xác minh

Khắc phục tự động là tùy chọn và chỉ chạy cho pipeline của nhánh mặc định được bảo vệ. Tiến trình khắc phục Codex và các lệnh xác minh do kho lưu trữ kiểm soát không nhận project access token của GitLab hoặc thông tin xác thực do runner đưa vào.

Quy chuẩn bảo mật gồm ba phần: các lệnh do kho lưu trữ kiểm soát không bao giờ nhận thông tin xác thực OpenAI hoặc GitLab, chỉ tác vụ công bố nhận quyền ghi vào kho lưu trữ và mọi thay đổi được tạo vẫn ở trạng thái nháp cho đến khi được con người xem xét và hợp nhất.

Quy trình:

1. Yêu cầu phạm vi quét đầy đủ và một phát hiện có mức độ nghiêm trọng high hoặc critical.
2. Xác nhận rằng kiểm thử hồi quy đã cấu hình thất bại trước khi vá.
3. Tạo một bản vá có trọng tâm và từ chối thay đổi đối với CI, thông tin xác thực, tệp nhị phân hoặc các tệp được bảo vệ khác.
4. Chạy kiểm thử hồi quy mà không có thông tin xác thực OpenAI, GitLab, registry, triển khai hoặc job-token.
5. Dùng verify-fix để trả về fixed, still_vulnerable hoặc inconclusive. Tác vụ chỉ công bố bản vá khi verify-fix trả về fixed và tiến trình xác minh không làm thay đổi bản vá.

Đặt các biến được bảo vệ sau để bật tính năng khắc phục:

• Đặt CODEX_SECURITY_ENABLE_REMEDIATION thành true.
• Đặt CODEX_SECURITY_VERIFICATION_COMMAND thành một kiểm thử hồi quy hiện có, thoát với 1 trước khi sửa và 0 sau khi sửa.
• Tùy chọn, đặt CODEX_SECURITY_SETUP_COMMAND thành một lệnh thiết lập phần phụ thuộc không tương tác.

Chọn một kiểm thử hồi quy thực thi bất biến bảo mật cốt lõi, không phải một cách triển khai cụ thể. Hãy xem xét kỹ các thay đổi được tạo cho mã nguồn và kiểm thử theo cùng tiêu chuẩn.

Công bố yêu cầu hợp nhất nháp

Tạo một GitLab project access token với vai trò Developer và các phạm vi api cùng write_repository. Lưu token dưới dạng GITLAB_REMEDIATION_TOKEN được bảo vệ, che và ẩn, chỉ giới hạn trong môi trường codex-security/publish.

Đặt CODEX_SECURITY_CREATE_MR=true để bật tính năng công bố. Đồng thời đặt biến không bí mật CODEX_SECURITY_MR_TEST_COMMAND thành kiểm thử hồi quy bảo mật dành riêng cho dự án mà mọi nhánh khắc phục được tạo đều phải vượt qua. Giữ biến này không được bảo vệ để yêu cầu hợp nhất không được bảo vệ đã tạo có thể đọc lệnh. Quy trình công bố:

• Nhận token có quyền ghi vào kho lưu trữ nhưng không nhận thông tin xác thực OpenAI.
• Tạo một nhánh codex-security/fix-<finding-hash>.
• Mở một yêu cầu hợp nhất nháp và sử dụng lại bản nháp đang mở thay vì tạo bản trùng lặp.
• Chạy kiểm thử hồi quy của nhánh khắc phục không được bảo vệ dưới một người dùng không đặc quyền trong bản sao chỉ chứa tệp được theo dõi và không có thông tin xác thực được bảo vệ.
• Không bao giờ tự động hợp nhất thay đổi được tạo.

Không thay CI_JOB_TOKEN cho project access token. Token đó không thể thực hiện thao tác tạo yêu cầu hợp nhất bắt buộc. Hãy xem xét bản vá được đề xuất, bằng chứng xác minh và phát hiện trước khi hợp nhất.

Cấu hình các biến tùy chọn

Chỉ cấu hình các biến cần thiết cho những tính năng bạn bật:

GitLab cung cấp các biến CI_*. Pipeline quản lý CODEX_SECURITY_BIN, CODEX_SECURITY_EFFORT, CODEX_SECURITY_MODE, CODEX_SECURITY_STATE_DIR và CODEX_SECURITY_TARGET; đừng cấu hình chúng thành biến dự án. Đối với quét diff, CLI suy ra danh tính đích chuẩn từ các bản sửa đổi base và head đã chuẩn hóa.

Tinh chỉnh việc thực thi và chi phí

Sử dụng quét diff tập trung để phản hồi về yêu cầu hợp nhất, quét kho lưu trữ tiêu chuẩn cho nhánh mặc định và quét sâu theo lịch để có phạm vi bao phủ rộng hơn. Cả hai hồ sơ quét toàn bộ kho lưu trữ đều tắt theo mặc định. Quét sâu theo lịch còn yêu cầu CODEX_SECURITY_DEEP_MAX_TIME_HOURS và CODEX_SECURITY_DEEP_MAX_COST; giữ ngân sách thời gian của CLI thấp hơn thời gian chờ tám giờ của tác vụ. Đo lường các lần chạy đại diện trước khi đặt ngân sách. Hãy xem --max-cost là giới hạn an toàn cho chi phí ước tính, không phải mức trần thanh toán cứng.

Hãy bắt đầu với các lần quét chỉ báo cáo. Thêm --fail-on-severity sau khi nhóm của bạn đã xem xét các phát hiện, phạm vi bao phủ, chi phí và thời gian chạy mang tính đại diện. Xem Chạy Codex Security trong CI để biết chính sách về mức độ nghiêm trọng và chi tiết mã thoát.

Khi một tác vụ thất bại:

• Thiếu artifact quét cho thấy có vấn đề về cấu hình hoặc runner.
• Có artifact nhưng phạm vi bao phủ một phần thì cần xem xét coverage.json.
• Không có phát hiện GitLab thì cần kiểm tra xem tác vụ báo cáo SARIF đã thành công và GitLab đã chấp nhận báo cáo hay chưa.
• Bước khắc phục bị bỏ qua thì cần kiểm tra nhánh được bảo vệ, phạm vi bao phủ đầy đủ, mức độ nghiêm trọng của phát hiện, lệnh xác minh và các biến chọn tham gia.
• Lỗi công bố thì cần kiểm tra vai trò, phạm vi và giới hạn môi trường của project token.

Đối với mọi lệnh, cờ và artifact, hãy xem tài liệu tham khảo Codex Security CLI.