Tài liệu ChatGPT
Tiếng Việt
Liên hệ goolvyouyou@gmail.com

Chạy Codex Security trong GitHub Actions

Quét pull request và kho mã bằng Codex Security Action, lưu báo cáo, tải lên SARIF và cấu hình việc thực thi chính sách.

Chạy Codex Security trong GitHub Actions để rà soát các thay đổi trong pull request hoặc quét kho mã theo lịch. Action cài đặt CLI, lưu các báo cáo có cấu trúc và thêm bản tóm tắt tác vụ cùng chú thích mã nguồn. Bắt đầu với các kết quả mang tính tham khảo, sau đó cấu hình việc thực thi chính sách sau khi rà soát phạm vi và chất lượng quét.

Chuẩn bị quy trình

Bạn cần có quyền truy cập Codex Security để chạy quét. Để thêm OpenAI API key:

  1. Trong kho mã GitHub, mở Cài đặt → Bí mật và biến → Actions.
  2. Chọn Bí mật kho mã mới.
  3. Nhập CODEX_SECURITY_API_KEY làm tên và dán OpenAI API key làm giá trị. Lưu bí mật.

Các ví dụ quy trình bên dưới tự động chuyển bí mật này đến Codex Security Action. Bạn không cần đặt API key trong tệp quy trình.

Chỉ chạy quy trình đối với các kho mã và pull request mà bạn tin cậy. Quá trình quét sử dụng quyền cục bộ của runner và không tạm dừng để chờ phê duyệt. Đặt các thông tin xác thực không liên quan và các bước triển khai trong những tác vụ riêng biệt.

Thêm quy trình GitHub Actions

Quét kho mã theo lịch

Quy trình dưới đây quét nhánh mặc định vào mỗi thứ Hai lúc 07:23 UTC. Bạn cũng có thể chạy thủ công từ thẻ Actions của GitHub. Quy trình sử dụng runner Ubuntu 24.04 x64 do GitHub cung cấp và tự động thiết lập môi trường cô lập cần thiết.

  1. Trong kho mã, chọn Thêm tệp → Tạo tệp mới.
  2. Đặt tên tệp là .github/workflows/codex-security-repository.yml.
  3. Dán quy trình bên dưới và commit vào nhánh mặc định.
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 }}

Điều chỉnh runner: Action cần Node.js 24 và Python 3.11 trở lên, đều có sẵn trên runner này. Bước thiết lập môi trường cô lập cài đặt gói bubblewrap và nạp hồ sơ AppArmor được cung cấp trước khi quét. Chỉ cài đặt gói là chưa đủ trên runner này.

Để chạy quy trình thủ công, mở Actions → Codex Security repository → Chạy quy trình. Mở một lần chạy đã hoàn tất để rà soát bản tóm tắt, chú thích và các báo cáo có thể tải xuống.

Các phát hiện chỉ được ghi vào báo cáo vì fail-on-severity là none. Lỗi trình quét và lỗi báo cáo bắt buộc vẫn khiến tác vụ thất bại.

Để quét các thư mục được chọn, thêm các đường dẫn nguyên văn, mỗi đường dẫn một dòng, vào khối with của bước quét:

paths: |
  src/api
  src/auth

Các đường dẫn yêu cầu scope: repository và không mở rộng mẫu glob. Đối với quét phần khác biệt, bỏ paths. Giữ persist-credentials: false và chạy quét ngay sau khi checkout.

Quét các thay đổi trong pull request

Sử dụng cùng bí mật đó, tạo .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 }}

Mở hoặc cập nhật một PR từ nhánh trong cùng kho mã. Action sử dụng toàn bộ lịch sử để tìm chính xác điểm gốc hợp nhất và quét các thay đổi đến đầu PR đã checkout. Xem mục kiểm tra Codex Security trong Kiểm tra của PR. Bắt đầu với các phát hiện mang tính tham khảo, sau đó chọn chính sách theo mức độ nghiêm trọng khi bạn sẵn sàng dùng kết quả để kiểm soát thay đổi.

Ví dụ này bỏ qua các PR từ fork và các PR do dependabot[bot] mở. Một tác vụ bị bỏ qua không phải bằng chứng cho việc rà soát bảo mật. Để bao gồm các PR từ bot này, hãy xóa điều kiện loại trừ tác nhân và đồng thời cấu hình CODEX_SECURITY_API_KEY làm bí mật cho dependabot[bot]. Action không hỗ trợ pull_request_target hoặc workflow_run.

Trình quét đọc hướng dẫn SECURITY.md áp dụng từ bản checkout, bao gồm cả các thay đổi chính sách trong PR. Rà soát những thay đổi đó cùng với mã.

Cấu hình quyền truy cập Daybreak tùy chọn

Daybreak là tùy chọn. Cả hai ví dụ quy trình đều sử dụng gpt-6-sol. Nếu tổ chức của bạn đã được phê duyệt tham gia Trusted Access for Cyber, hãy xóa # trước cyber-access-program trong khối with của bước quét:

model: gpt-6-sol
cyber-access-program: daybreak_blue

Sử dụng API key từ một dự án đã bật Daybreak Blue và có quyền truy cập gpt-6-sol.

Đầu vào chương trình cũng chấp nhận standard. Nếu không có quyền truy cập Daybreak, hãy sử dụng mô hình mà API key của bạn có thể truy cập theo các biện pháp bảo vệ tiêu chuẩn và bỏ cyber-access-program hoặc đặt thành standard. Việc chọn mô hình hoặc chương trình không cấp quyền truy cập. Xem hướng dẫn về quyền truy cập Daybreak của Action.

Việc từ chối hoặc chặn vì lý do an toàn làm hủy lần quét sẽ khiến Action thất bại, kể cả khi fail-on-severity là none. Đầu vào đó kiểm soát chính sách đối với phát hiện, không kiểm soát lỗi trình quét.

Đặt ngân sách quét tùy chọn

Cả hai ví dụ quy trình đều bỏ qua max-cost, nên không có ngưỡng dừng theo chi phí ước tính. Để đặt ngưỡng, thêm một số tiền USD dương bằng đầu vào max-cost. Khi quét trực tiếp bằng CLI, sử dụng --max-cost.

Giới hạn chi phí yêu cầu CLI hỗ trợ định giá cho mô hình đã chọn. Ngưỡng ước tính không phải giới hạn chi tiêu cứng: chi phí của các yêu cầu đang xử lý có thể vượt ngưỡng. Rà soát các phát hiện và coverage.json nếu lần quét dừng ở ngưỡng. Xem các tùy chọn đầu ra và chính sách để biết hành vi của giới hạn chi phí.

Lưu báo cáo và tải lên SARIF

Các ví dụ đặt upload-artifacts: "true" để lưu các báo cáo có thể tải xuống với thời hạn lưu giữ bảy ngày. Báo cáo có thể chứa đoạn mã nguồn, bằng chứng về lỗ hổng và chi tiết khắc phục. Chọn thời hạn lưu giữ và quyền truy cập kho mã phù hợp với mã của bạn. Action chỉ tải lên các báo cáo đã được xác thực trong danh sách cho phép; không tải lên đệ quy đầu ra results-directory của Action.

Tải lên SARIF là tùy chọn. Đối với kho mã riêng tư hoặc nội bộ, bật GitHub Code Security trước khi tải lên. Thay khối permissions của quy trình bằng:

permissions:
  contents: read
  security-events: write
  actions: read # Required for private repositories

Sau đó thêm bước này sau bước quét trong một trong hai quy trình:

- 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-repository

Đối với quy trình PR, sử dụng category: codex-security-pr để mỗi phạm vi có một danh mục riêng. Giữ id: security ở bước quét. Các báo cáo hoàn chỉnh, đã được xác thực vẫn có thể được tải lên khi các phát hiện khiến chính sách theo mức độ nghiêm trọng không được đáp ứng. SARIF không được tải lên đối với các lần quét thất bại hoặc bị gián đoạn, phần khác biệt rỗng hoặc lần chạy thử.

Xem tài liệu tham khảo về đầu vào và đầu ra của Action để biết tất cả thiết lập, trường trạng thái và đường dẫn báo cáo.

Chọn chính sách theo mức độ nghiêm trọng

Các quy trình GitHub bắt đầu với fail-on-severity: none. Để tác vụ thất bại khi có phát hiện ở mức cao hoặc đặc biệt nghiêm trọng từ một lần quét hoàn tất, thay đổi đầu vào của bước quét:

fail-on-severity: high

Đặt Codex Security làm mục kiểm tra trạng thái bắt buộc trong các quy tắc kho mã để chặn hợp nhất khi tác vụ PR thất bại. GitHub coi tác vụ bị bỏ qua theo điều kiện là thành công, kể cả với các mục kiểm tra bắt buộc. Các PR từ fork và PR từ dependabot[bot] vượt qua mục kiểm tra này mà không được quét. Để chặn những trường hợp bị bỏ qua đó, hãy yêu cầu một lần quét thành công và hoàn tất.

Action tuân theo kết quả của CLI:

  • Mã thoát 0 đặt scan-status: completed và policy-status: passed.
  • Mã thoát 1 đặt scan-status: completed và policy-status: failed; bước này thất bại khi có phát hiện ở mức bằng hoặc cao hơn mức độ nghiêm trọng đã cấu hình.
  • Mã thoát 2 hoặc một tiến trình bị gián đoạn đặt scan-status: failed và policy-status: not-evaluated; bước này thất bại.
  • Báo cáo bắt buộc không hợp lệ hoặc bị thiếu, bản checkout bị thay đổi, lỗi tải lên các tạo tác được yêu cầu và lỗi dọn dẹp môi trường chạy cũng khiến bước này thất bại.

Một lần quét hoàn tất có nghĩa là quá trình phân tích đã cấu hình tạo ra một kết quả hợp lệ. Các phần bị loại khỏi phạm vi, các cuộc điều tra hoãn lại và những ghi chú khác trong coverage.json không tạo ra một kết quả quét riêng biệt hoặc cho phép bỏ qua chính sách theo mức độ nghiêm trọng. Việc hoàn tất không chứng nhận rằng mọi lỗ hổng đều đã được tìm thấy. Rà soát coverage.json khi đánh giá kết quả.

Yêu cầu một lần quét thành công và hoàn tất

Để có chính sách nghiêm ngặt hơn, thêm một tác vụ kiểm soát riêng chạy ngay cả khi tác vụ quét thất bại hoặc bị GitHub bỏ qua. Một bước bên trong tác vụ quét không thể kiểm tra tác vụ bị bỏ qua vì không bước nào của tác vụ đó được chạy.

Trong quy trình PR, thêm ánh xạ outputs này vào tác vụ security hiện có, ở cùng mức thụt lề với runs-on và steps:

outputs:
  scan-status: ${{ steps.security.outputs.scan-status }}

Sau đó thêm tác vụ này bên dưới jobs, bên cạnh tác vụ security hiện có:

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

Đặt Codex Security gate làm mục kiểm tra trạng thái bắt buộc cho chính sách này. Tác vụ này yêu cầu cả tác vụ quét thành công lẫn scan-status: completed. Việc kiểm tra cả hai đảm bảo các lỗi từ chính sách theo mức độ nghiêm trọng, báo cáo và dọn dẹp vẫn được ghi nhận, ngay cả khi bản thân lần quét đã hoàn tất.

Với các điều kiện loại trừ của ví dụ, tác vụ kiểm soát này chặn các PR từ fork và PR từ dependabot[bot]. Nó cũng chặn phần khác biệt rỗng và các lần chạy thử, vốn được Action đánh dấu là skipped. Tác vụ kiểm soát không quét các PR bị loại trừ. Chỉ chọn chính sách này nếu những trường hợp đó cần ngăn việc hợp nhất.

Khắc phục sự cố khi quét

  • Tham chiếu Git không xác định hoặc phần khác biệt ngoài dự kiến: Checkout đầu PR bằng fetch-depth: 0.
  • Lỗi khởi động môi trường cô lập: Trên Ubuntu 24.04, cài đặt gói bubblewrap và nạp hồ sơ AppArmor trước Action. Chỉ cài đặt gói sẽ không nạp hồ sơ cần thiết.
  • Thiếu thông tin xác thực: Xác nhận rằng CODEX_SECURITY_API_KEY khả dụng cho quy trình đáng tin cậy và được ánh xạ tới biến môi trường OPENAI_API_KEY của bước quét.
  • Lỗi thiết lập Python: Action yêu cầu Python 3.11 trở lên.
  • Ghi chú về phạm vi quét: Rà soát các phần bị loại khỏi phạm vi và các cuộc điều tra hoãn lại trong coverage.json. Những ghi chú này không gây lỗi thực thi hoặc cho phép bỏ qua chính sách theo mức độ nghiêm trọng.
  • Thiếu SARIF: Kiểm tra scan-status, report-status và sarif-upload-ready. Nếu SARIF tùy chọn bị thiếu, Action đưa ra cảnh báo mà không thay đổi kết quả quét; lỗi tải lên tạo tác được yêu cầu vẫn khiến tác vụ thất bại.
  • Lỗi tải lên SARIF: Xác nhận rằng tổ chức của bạn đã bật GitHub Code Security cho kho mã và quy trình cấp actions: read, contents: read và security-events: write.

Để biết mọi lệnh, cờ, tạo tác và trường đầu ra, xem tài liệu tham khảo CLI. Đối với các nhà cung cấp khác, xem tổng quan về CI/CD.