Dùng Codex Security CLI để quét repo và phân loại lỗ hổng cho nhóm

Một báo cáo ghi “hai lỗi mức cao” chưa đủ để quyết định sửa gì trước. Bạn cần biết phạm vi quét và bằng chứng cho từng lỗi. Hướng dẫn này giúp chạy Codex Security CLI trên repo được phép đánh giá, rồi chia kết quả thành việc cần xử lý, cần xác minh và vùng chưa được quét. Dành khoảng 30 phút thiết lập và đọc báo cáo; thời gian quét tùy repo.

Đây là quy trình cho đánh giá lỗ hổng trong mã nguồn. Nó khác với cách giới hạn quyền và sandbox cho Codex khi nhóm sửa mã. Hai việc bổ sung cho nhau: một bên tìm rủi ro trong sản phẩm, một bên kiểm soát quyền của công cụ trong lúc làm việc.

Chuẩn bị

Theo Codex Security CLI quickstart của OpenAI, gói @openai/codex-security là gói công khai, nhưng chạy quét cần tài khoản có quyền dùng Codex Security. Tùy tài khoản và repo, quét toàn bộ repo có thể còn cần Trusted Access for Cyber. Đừng hiểu cài được CLI là chắc chắn dùng được lượt quét. Kiểm tra quyền trước khi lập lịch cho cả nhóm.

CLI yêu cầu Node.js 22 từ 22.13.0 trở lên, hoặc Node.js 24 hay 26. Quét và xem kết quả lưu còn cần Python 3.10 trở lên. Dùng repo được phép đánh giá, biết nhánh hiện tại và người phụ trách kết quả. Người mới dùng terminal có thể xem quy trình Codex CLI trước.

Kết quả quét có thể chứa đoạn mã và chi tiết lỗ hổng, nên chuẩn bị thư mục riêng tư ở ngoài repo, cùng chính sách ai được đọc và khi nào xóa. Theo OpenAI, tiến trình quét dùng quyền hệ điều hành của bạn và không dừng để hỏi phê duyệt; nó cũng có thể kế thừa biến môi trường. Trước khi bắt đầu, gỡ các thông tin đăng nhập không liên quan ra khỏi môi trường chạy. Đừng dùng tài khoản đặc quyền cao chỉ để tránh lỗi quyền.

Làm từng bước

1. Kiểm tra phiên bản và đăng nhập

Đầu tiên kiểm tra phiên bản Node.js, Python và CLI. Các lệnh dưới đây chỉ để kiểm tra môi trường, chưa quét mã:

node --version
python3 --version
npx @openai/codex-security --version
npx @openai/codex-security info --json
npx @openai/codex-security --help

info --json cho biết phiên bản gói và plugin. Nếu Node.js không được hỗ trợ, sửa môi trường trước. Trên máy tương tác, đăng nhập bằng tài khoản ChatGPT có quyền:

npx @openai/codex-security login
npx @openai/codex-security login status

Máy không có giao diện dùng được login --device-auth. CI thường dùng khóa API trong biến môi trường, nhưng vẫn cần quyền quét. Nếu có cả đăng nhập ChatGPT và OPENAI_API_KEY hoặc CODEX_API_KEY, chọn rõ --auth chatgpt hay --auth api-key; chế độ auto có thể chọn khác giữa terminal và CI. Đừng in khóa ra terminal.

2. Chốt repo, nơi lưu kết quả và chạy thử cấu hình

Thay hai đường dẫn mẫu bên dưới bằng đường dẫn tuyệt đối phù hợp trên máy của bạn. SCAN_DIR phải nằm ngoài REPOSITORY và chỉ người phụ trách được đọc:

REPOSITORY=/path/to/authorized-repository
SCAN_DIR=/path/outside-repository/security-results
npx @openai/codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR" --dry-run

Theo CLI reference của OpenAI, --dry-run kiểm tra đầu vào cục bộ, gồm đường dẫn tài liệu làm ngữ cảnh nếu có. Nó không nạp thông tin đăng nhập, không khởi chạy Codex và không kiểm tra Python của plugin. Vì vậy dry run thành công không chứng minh tài khoản có quyền quét hoặc bản quét thật sẽ thành công. Nó chỉ giúp bắt lỗi đường dẫn và cấu hình sớm.

Trong repo nhiều dịch vụ, thêm --path services/billing để giới hạn vùng quét có người phụ trách. Có thể dùng --knowledge-base đưa sơ đồ kiến trúc hoặc chính sách bảo mật vào ngữ cảnh, sau khi kiểm tra bí mật. AGENTS.md cho nhóm Codex là tài liệu về quy tắc làm việc; nó không chứng minh bộ quét hiểu đầy đủ ranh giới tin cậy của sản phẩm.

3. Chạy lượt quét tiêu chuẩn, giữ nguyên báo cáo

Sau khi dry run đúng repo và thư mục đầu ra, chạy lượt tiêu chuẩn. Ví dụ sau chọn rõ thông tin đăng nhập ChatGPT; nếu bạn dùng khóa API hợp lệ thì đổi thành --auth api-key:

npx @openai/codex-security scan "$REPOSITORY" \
  --output-dir "$SCAN_DIR" \
  --auth chatgpt

Theo quickstart, quét mặc định là chỉ lập báo cáo, không tự sửa mã. Terminal tương tác có bảng tiến độ; đầu ra thông thường ghi tóm tắt và đường dẫn báo cáo lên stderr, không in toàn bộ kết quả ra stdout. Đừng chia sẻ ảnh màn hình bảng tiến độ khi chưa rà: nó có thể chứa mã nguồn hoặc thông tin đăng nhập trong chi tiết phiên. Dùng --json nếu quy trình thực sự cần một tài liệu JSON đầy đủ, thay vì tự đoán cấu trúc từ dòng tiến độ.

Trong thư mục quét hoàn tất, mở report.md, findings.json, coverage.json và scan-manifest.json. report.md dễ đọc cho người phụ trách. findings.json có mức độ, độ tin cậy, vị trí, bằng chứng và hướng khắc phục. coverage.json ghi phần đã xem, phần loại trừ, việc hoãn và câu hỏi còn mở. scan-manifest.json giúp đối chiếu repo, phạm vi, trạng thái và dấu vết của bộ hiện vật. Giữ bộ tệp gốc trước khi tạo bản tóm tắt cho nhóm.

4. Phân loại kết quả theo bằng chứng và phạm vi

Trước tiên đọc coverage. OpenAI định nghĩa complete, partial và unknown. Nếu trạng thái là partial hoặc unknown, ghi rõ đường dẫn hoặc bề mặt chưa được xem. Một báo cáo ít lỗi nhưng bỏ sót khu vực xử lý thanh toán chưa thể dùng để tuyên bố khu vực đó an toàn. Với complete, vẫn phải xem các phần bị loại trừ, câu hỏi mở và phạm vi đã chọn trước khi diễn giải kết quả.

Tiếp theo xem từng finding như một giả thuyết cần xác minh. Nhóm có thể dùng bảng ba cột trong công cụ công việc đang có: phát hiện và bằng chứng, quyết định tạm thời, người phụ trách và bước xác minh. Các quyết định hữu ích là “cần sửa và tái kiểm”, “cần xác minh thêm”, “không áp dụng, có lý do cụ thể”. Mức độ nghiêm trọng giúp ưu tiên, nhưng không thay thế việc xem đường dữ liệu, khả năng bị khai thác, cấu hình thật và tác động tới người dùng.

Nếu nghi báo động giả, lấy ID lần xuất hiện trong báo cáo rồi ghi lý do cụ thể qua findings false-positive. Đừng đánh dấu cả loại lỗi là giả vì một trường hợp. Theo CLI FAQ, quyết định được lưu cho repo, nhưng lượt sau vẫn kiểm tra lại mã và khả năng đi tới lỗi. Thiếu bằng chứng thì giữ trạng thái “cần xác minh thêm”.

5. Xác minh bản sửa bằng lượt quét mới

Một finding biến mất khỏi báo cáo mới không đủ chứng minh lỗi đã được sửa. OpenAI nói finding cũ có thể vẫn mở cho tới khi được giải quyết hoặc loại bỏ, và so sánh hai scan có thể cho biết lỗi mới, còn tồn tại hoặc chưa rõ. Sau khi người có trách nhiệm sửa mã, chạy lại cấu hình ban đầu và so sánh:

npx @openai/codex-security scans list "$REPOSITORY"
npx @openai/codex-security scans rerun BEFORE_SCAN_ID
npx @openai/codex-security scans compare BEFORE_SCAN_ID AFTER_SCAN_ID

Thay BEFORE_SCAN_ID và AFTER_SCAN_ID bằng ID thật. Kiểm tra scan mới phủ đường dẫn lỗi cũ và không để vùng đó thành partial hoặc unknown. Dùng validate kiểm lại finding trên checkout hiện tại. Nếu để Codex tạo bản vá, xem diff và chạy test; --patch không thuộc lượt quét tiêu chuẩn.

Kết quả mẫu

Giả sử repo có finding về tải tệp thiếu kiểm tra quyền và cảnh báo truy vấn có thể là báo động giả. Phần webhook chưa được quét hết. Nhóm giao lỗi tải tệp cho người phụ trách, giữ cảnh báo truy vấn ở trạng thái cần kiểm tra và mở việc quét lại webhook. Chỉ đóng lỗi đầu sau khi tái quét và validate xác nhận. Đây là tình huống minh họa, không phải kết quả scan thật.

Mẹo để kết quả tốt hơn

Bắt đầu bằng quét tiêu chuẩn trên một repo hoặc một dịch vụ có chủ sở hữu rõ ràng. Sau đó mới mở rộng sang deep scan, quét diff hoặc kiểm tra trước commit. Trong monorepo, --path giúp nhóm đối chiếu đúng ranh giới trách nhiệm. Với pull request, --diff origin/main --head HEAD quét thay đổi đã commit; --working-tree --base HEAD xem thay đổi chưa commit. Hai chế độ này yêu cầu đối số repo là gốc Git worktree, và --path, --diff, --working-tree loại trừ nhau.

Đặt ngưỡng chi phí nếu nhóm có giới hạn ngân sách. --max-cost dừng khi chi phí mô hình ước tính vượt mức đặt ra, nhưng yêu cầu đang chạy có thể vượt nhẹ; lượt quét sâu dừng giữa chừng có thể chỉ cho coverage partial. Lưu ID, ngày, nhánh, commit, phạm vi và người phân loại của mỗi lượt để lần sau so được đúng cùng một mục tiêu. Báo cáo là đầu vào cho quyết định kỹ thuật, không thay thế review mã hay test bảo mật phù hợp.

Giới hạn cần biết

Quét phụ thuộc quyền truy cập Codex Security và có thể bị giới hạn bởi Trusted Access for Cyber. CLI có thể đọc những gì tài khoản hệ điều hành đọc được, và không tạm dừng để xin phê duyệt trong lượt quét. Vì vậy chọn repo được ủy quyền, bỏ thông tin đăng nhập không liên quan, giữ thư mục kết quả riêng tư. Không đưa mã hoặc báo cáo lỗ hổng lên kênh công khai. Nếu môi trường có quy định dữ liệu, kiểm tra chúng trước khi dùng nhà cung cấp mô hình hoặc nơi lưu trữ mới.

AI có thể bỏ sót hoặc đánh giá sai finding, và kết quả có thể khác giữa các lượt quét. Coverage complete là mô tả phạm vi của lượt quét, không phải chứng nhận repo an toàn tuyệt đối. Một lỗi bảo mật quan trọng cần người hiểu hệ thống xác nhận luồng khai thác và tác động thực tế. Mã lệnh trong bài được đối chiếu với tài liệu OpenAI hiện hành; chưa chạy scan thật, vì không có repo và quyền truy cập được chỉ định cho ví dụ.

Câu hỏi thường gặp

Cài được gói CLI có nghĩa là quét được ngay không? Không. Gói công khai nhưng chạy quét cần quyền Codex Security; một số lượt quét toàn repo có thể cần thêm Trusted Access for Cyber.

Dry run có dùng token hoặc kiểm tra đăng nhập không? Theo OpenAI, --dry-run kiểm tra đầu vào cục bộ, không nạp thông tin đăng nhập, không khởi chạy Codex và không kiểm tra Python của plugin.

Không có finding nào có nghĩa repo an toàn không? Không. Đọc coverage.json, phạm vi, phần loại trừ và câu hỏi mở. Ngay cả coverage complete cũng không phải cam kết không còn lỗ hổng.

Có thể tự động sửa ngay trong lệnh quét không? Có tùy chọn --patch, nhưng lượt quét mặc định chỉ tạo báo cáo. Nên xem bằng chứng, phê duyệt phạm vi, review diff và chạy test trước khi chấp nhận bản sửa.

Một lỗi biến mất ở scan sau đã được sửa chưa? Chưa chắc. So sánh scan, kiểm tra coverage của vùng mã liên quan và dùng validate để xác minh finding cũ trên mã hiện tại.

Nguồn chính thức: Codex Security CLI quickstart, CLI reference và CLI FAQ, OpenAI Learn, đối chiếu ngày 5/10/2026. #CodexSecurity #BaoMatMaNguon #CodexCLI #AIChoLapTrinh #VibeCoding