Bắt đầu nhanh với Codex Security CLI

Chạy lượt quét tiêu chuẩn cho kho lưu trữ cục bộ bằng Codex Security CLI độc lập. Hướng dẫn bắt đầu nhanh này kết thúc bằng một báo cáo được lưu để bạn xem xét và tra cứu lại. Để quét trong cuộc trò chuyện với Codex, hãy dùng plugin Codex Security .

Kiểm tra điều kiện tiên quyết

Sử dụng Node.js 24 hoặc 26, hoặc Node.js 22 từ phiên bản 22.13.0 trở lên. Bạn cũng cần Python 3.10 trở lên. Python 3.10 còn cần tomli. Các lượt quét sử dụng suy luận của OpenAI yêu cầu quyền truy cập Codex Security. Tùy thuộc vào tài khoản và kho lưu trữ của bạn, việc quét toàn bộ kho lưu trữ cũng có thể cần Trusted Access for Cyber.

CLI chạy với quyền của bạn trên hệ điều hành và không tạm dừng để chờ phê duyệt. Các tiến trình quét có thể kế thừa môi trường của bạn, vì vậy hãy loại bỏ thông tin xác thực không liên quan trước khi bắt đầu. Xem Quyền quét cục bộ.

Thiết lập và xác minh CLI

Chạy gói công khai bằng npx:

npx @openai/codex-security --version

Lệnh này in ra phiên bản gói đã cài đặt. Dùng info --json để kiểm tra phiên bản plugin đi kèm hoặc --help để liệt kê các lệnh. Những thay đổi của gói được liệt kê trong Các bản phát hành CLI và SDK.

Đăng nhập

Đăng nhập bằng tài khoản ChatGPT của bạn:

npx @openai/codex-security login

Trên máy không có trình duyệt, hãy thêm --device-auth và làm theo hướng dẫn đăng nhập được hiển thị. Dùng --auth chatgpt trong các lệnh quét bên dưới để chọn phương thức đăng nhập đó ngay cả khi môi trường của bạn cũng có API key.

Đối với API key và các nhà cung cấp khác, xem Chọn phương thức xác thực cho lượt quét. Đối với Amazon Bedrock, hãy dùng Thông tin xác thực AWS và quyền truy cập mô hình thay cho phương thức đăng nhập ChatGPT hoặc API key của OpenAI.

Chuẩn bị quét

Thay các đường dẫn này bằng đường dẫn đến kho lưu trữ của bạn và một thư mục kết quả mới nằm ngoài Git worktree của kho lưu trữ:

REPOSITORY=/path/to/repository
SCAN_DIR=/path/outside/repository/codex-security-results

Kết quả có thể bao gồm các trích đoạn mã nguồn và chi tiết về lỗ hổng. Hãy chọn một vị trí riêng tư. Nếu bạn bỏ qua --output-dir, CLI sẽ dùng thư mục trạng thái được lưu lâu dài của nó.

Kiểm tra mục tiêu và vị trí đầu ra:

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

Một lần chạy thử thành công xác nhận các đầu vào cục bộ. Lần chạy này không bắt đầu quét, nạp thông tin xác thực hay kiểm tra trình thông dịch Python của plugin, nên không xác nhận rằng việc xác thực và thiết lập môi trường chạy sẽ thành công.

Chạy lần quét đầu tiên

Bỏ --dry-run để bắt đầu quét:

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

Terminal tương tác hiển thị bảng điều khiển trực tiếp. Terminal không tương tác hiển thị các dòng tiến trình. Thêm --headless để cũng dùng các dòng tiến trình trong terminal tương tác. Bảng điều khiển và nhật ký đã lưu có thể chứa mã nguồn hoặc thông tin xác thực. Hãy xem xét chúng trước khi chia sẻ.

Khi lượt quét kết thúc, stderr hiển thị đường dẫn báo cáo, số lượng phát hiện và thời gian đã trôi qua. Ví dụ:

  REPORT    /path/outside/repository/codex-security-results/report.md

  FINDINGS  2 (2 confirmed this scan; 0 previously found; 1 high, 1 medium)
  ELAPSED   42s
  RESULTS   /path/outside/repository/codex-security-results

Theo mặc định, mức độ nghiêm trọng của một phát hiện không khiến lượt quét thất bại. Để stdout có định dạng máy có thể đọc được, hãy thêm --json. Để các phát hiện khiến bước kiểm tra CI thất bại, hãy đặt chính sách về mức độ nghiêm trọng.

Xem xét kết quả

Mở report.md trong thư mục được thông báo. Xác nhận mục tiêu và bản sửa đổi, sau đó đọc phạm vi bao phủ trước khi xem xét từng phát hiện.

Kiểm tra scan.status trong scan-manifest.json để xác nhận lượt quét đã hoàn tất. Xem coverage.json để biết các phạm vi đã được rà soát, đường dẫn bị loại trừ, công việc hoãn lại, và các câu hỏi còn bỏ ngỏ.

Lượt quét hoàn tất sẽ thoát với mã 0, trừ khi các phát hiện đạt ngưỡng mức độ nghiêm trọng đã cấu hình; khi đó mã trả về là 1. Những phần chưa được rà soát không làm thay đổi mã thoát, nên mã thoát 0 không có nghĩa là mọi tệp đều đã được rà soát. Lỗi đầu vào, thực thi, tính toàn vẹn của kết quả, hoặc đầu ra bắt buộc sẽ trả về 2. Tài liệu tham khảo CLI giải thích các mã thoát.

Với mỗi phát hiện, hãy kiểm tra mã bị ảnh hưởng, các điều kiện tiên quyết để kẻ tấn công khai thác, bằng chứng xác minh và những điểm còn chưa chắc chắn. Phát hiện dựa trên mã nguồn không nhất thiết đi kèm với việc tái hiện thành công khi chạy. Chỉ chọn một phát hiện để khắc phục khi bằng chứng của phát hiện đó đủ cơ sở cho vấn đề được nêu.

Giữ nguyên toàn bộ thư mục quét khi chia sẻ hoặc lưu trữ. Thư mục này chứa scan-manifest.json, findings.json và coverage.json cùng với báo cáo và các tệp hỗ trợ. Xem Các tệp đầu ra của lượt quét để biết cấu trúc đầy đủ.

Xem lại một lần quét đã lưu

Liệt kê các lượt quét của kho lưu trữ:

npx @openai/codex-security scans list "$REPOSITORY"

Sao chép ID của một lượt quét từ kết quả:

npx @openai/codex-security scans show SCAN_ID

Sau khi một lượt quét tương tác hoàn tất và có phát hiện, CLI cũng cung cấp trình duyệt phát hiện. Xem xét bằng chứng tại đó trước khi chọn cách khắc phục. Với các phát hiện đã lưu, hãy dùng các lệnh xác minh và tạo bản vá.

Chọn lượt quét tiếp theo

Nếu gặp vấn đề xác thực, khác biệt giữa các lần quét lại hoặc muốn phản hồi về phát hiện dương tính giả, hãy xem Câu hỏi thường gặp về CLI.