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

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

Thiết lập Codex Security, chạy quét cục bộ và xem xét báo cáo, phát hiện cũng như phạm vi bao phủ.

Codex Security giúp các nhóm bảo mật và kỹ thuật tìm, xác nhận và khắc phục lỗ hổng. Sử dụng giao diện dòng lệnh (CLI) để quét các kho mã nguồn mà bạn sở hữu hoặc được phép đánh giá, xem xét phát hiện theo thời gian và kiểm tra thay đổi trước khi chúng được hợp nhất.

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

CLI yêu cầu Node.js 22 (22.13.0 trở lên), 24 hoặc 26. Hoạt động quét, quét hàng loạt, xuất dữ liệu, lịch sử quét và các phát hiện đã lưu cũng yêu cầu Python 3.10 trở lên. Để biết thêm chi tiết, hãy xem Xác thực và điều kiện tiên quyết.

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

Chạy CLI bằng npx và kiểm tra phiên bản:

npx @openai/codex-security --version

Để xem cả phiên bản gói và phiên bản plugin đi kèm, hãy chạy:

npx @openai/codex-security info --json

Xem Các bản phát hành CLI và SDK để biết những thay đổi của gói.

Liệt kê các lệnh hiện có:

npx @openai/codex-security --help

Xem thêm Tài liệu tham khảo CLI.

Đăng nhập

Để sử dụng cục bộ, hãy đăng nhập bằng tài khoản ChatGPT của bạn:

npx @openai/codex-security login

Trên máy từ xa hoặc không có giao diện, hãy sử dụng xác thực thiết bị:

npx @openai/codex-security login --device-auth

Đối với CI và các quy trình tự động khác, hãy đặt OpenAI API key:

export OPENAI_API_KEY="<your-api-key>"

Đối với thông tin xác thực AWS, hãy xem Thiết lập Amazon Bedrock. Đối với OpenRouter hoặc Fireworks, hãy đặt API key của nhà cung cấp và chọn mô hình bằng --provider và --model.

Để sử dụng thông tin đăng nhập ChatGPT khi API key cũng đã được đặt, hãy chọn rõ ràng:

npx @openai/codex-security scan . --auth chatgpt

Để bắt buộc sử dụng API key trong môi trường, hãy chọn xác thực bằng API key:

npx @openai/codex-security scan . --auth api-key

Tùy thuộc vào tài khoản và kho mã nguồn, hoạt động quét toàn bộ kho mã nguồn cũng có thể yêu cầu Trusted Access for Cyber.

Chuẩn bị quét

Chọn một kho mã nguồn mà bạn tin cậy và được phép đánh giá. Hoạt động quét sử dụng quyền của hệ điều hành cục bộ và không tạm dừng để xin phê duyệt. Tiến trình quét có thể kế thừa môi trường của bạn, vì vậy hãy xóa các 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ộ.

Chọn một thư mục bên ngoài kho mã nguồn để lưu kết quả quét:

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

Nếu bạn bỏ qua --output-dir, Codex Security sẽ lưu kết quả trong thư mục trạng thái bền vững riêng. Kết quả có thể bao gồm đoạn mã nguồn và chi tiết lỗ hổng, vì vậy hãy chọn một vị trí riêng tư và chính sách lưu giữ phù hợp.

Nếu không thể ghi vào thư mục trạng thái mặc định, hãy chọn một thư mục có thể ghi bên ngoài kho mã nguồn được quét:

export CODEX_SECURITY_STATE_DIR=/path/outside/repository/codex-security-state

Kiểm tra kho mã nguồn, mục tiêu và thư mục đầu ra trước khi bắt đầu quét:

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

Lần chạy thử kiểm tra dữ liệu đầu vào cục bộ, bao gồm mọi đường dẫn --knowledge-base, mà không khởi động Codex, tải thông tin xác thực hoặc thăm dò trình thông dịch Python của plugin.

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

Chạy một lần quét tiêu chuẩn và lưu kết quả trong thư mục đã chọn:

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

Thiết bị đầu cuối tương tác hiển thị bảng điều khiển quét trực tiếp. Thêm --headless để hiển thị các dòng tiến trình dạng văn bản thuần túy. CI và thiết bị đầu cuối không có phiên tương tác sẽ tự động sử dụng tiến trình dạng văn bản thuần túy.

Bảng điều khiển cũng hiển thị chi tiết phiên theo thời gian thực. Các chi tiết này có thể chứa mã nguồn hoặc thông tin xác thực, vì vậy hãy xem xét chúng trước khi chia sẻ.

Theo mặc định, CLI ghi tiến trình quét và bản tóm tắt hoàn tất vào stderr. CLI không in toàn bộ kết quả quét ra stdout. Một lần quét hoàn tất sẽ in bản tóm tắt như sau:

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

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

Mức sử dụng token và chi phí ước tính sẽ xuất hiện khi có dữ liệu. Để in toàn bộ kết quả dưới dạng JSON mà máy có thể đọc, hãy yêu cầu đầu ra có cấu trúc một cách rõ ràng:

npx @openai/codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR" --json

Theo mặc định, hoạt động quét chỉ tạo báo cáo, vì vậy các phát hiện vẫn có sẵn để xem xét cục bộ. Bạn có thể thêm ngưỡng mức độ nghiêm trọng khi đã sẵn sàng chạy quét trong CI.

Chọn mô hình và mức độ suy luận

Theo mặc định, hoạt động quét sử dụng gpt-5.6-sol với mức độ suy luận xhigh. Hãy chọn một mô hình và mức độ khác khi tác vụ yêu cầu:

npx @openai/codex-security scan "$REPOSITORY" \
  --model gpt-5.6-terra \
  --effort high

Các mức độ được hỗ trợ là minimal, low, medium, high, xhigh và max.

Xem xét kết quả

Mở report.md để xem kết quả dễ đọc. Thư mục quét cũng chứa các tệp có cấu trúc được tự động hóa sử dụng:

codex-security-results/
├── scan-manifest.json
├── findings.json
├── coverage.json
├── report.md
├── artifacts/
└── exports/
    └── results.sarif       # when produced
  • scan-manifest.json ghi lại mục tiêu, phạm vi, trình tạo và các cấu phần đã niêm phong.
  • findings.json ghi lại mức độ nghiêm trọng, độ tin cậy, vị trí, bằng chứng và biện pháp khắc phục cho từng phát hiện.
  • coverage.json ghi lại các bề mặt đã xem xét, phần loại trừ, công việc hoãn lại, câu hỏi còn bỏ ngỏ và mức độ hoàn chỉnh của phạm vi bao phủ.

Phạm vi bao phủ có thể là complete, partial hoặc unknown. Hãy đọc mọi khu vực bị hoãn hoặc câu hỏi còn bỏ ngỏ trước khi xem lần quét là bằng chứng cho việc rà soát. Tài liệu tham khảo CLI mô tả đầy đủ hợp đồng về cấu phần và đầu ra.

Xem xét và vá các phát hiện

Sau một lần quét tương tác hoàn chỉnh có phát hiện, CLI sẽ cung cấp một trình duyệt phát hiện. Hãy xem xét bằng chứng và chọn những phát hiện cần sửa. Bạn có thể tìm các tác vụ đã lưu trong ứng dụng Codex dành cho máy tính.

Để vá các phát hiện mức cao và nghiêm trọng mà không dùng trình duyệt:

npx @openai/codex-security scan "$REPOSITORY" \
  --patch --patch-severity high --json

Thêm --create-pr để commit các bản vá đã xác minh và mở một pull request trên GitHub.

Bạn cũng có thể vá các phát hiện đã lưu hoặc nhập vấn đề Linear. Xem tài liệu tham khảo về validate và patch.

Chọn lần quét tiếp theo

Sử dụng quét theo đường dẫn khi kho mã nguồn chứa các dịch vụ hoặc gói riêng biệt:

npx @openai/codex-security scan "$REPOSITORY" \
  --path services/billing \
  --path packages/auth

Xem xét các thay đổi đã commit giữa bản sửa đổi cơ sở và HEAD:

npx @openai/codex-security scan "$REPOSITORY" --diff origin/main --head HEAD

Xem xét các thay đổi đã và chưa được đưa vào vùng tạm so với HEAD:

npx @openai/codex-security scan "$REPOSITORY" --working-tree --base HEAD

Quét diff và cây làm việc yêu cầu đối số kho mã nguồn là thư mục gốc của Git worktree. Hãy tìm nạp các bản sửa đổi đã chọn trước khi bắt đầu quét diff.

Sử dụng chế độ sâu khi một kho mã nguồn hoặc đường dẫn cần được rà soát rộng hơn:

npx @openai/codex-security scan "$REPOSITORY" --mode deep

Để kiểm soát worker, tác nhân phụ và thời điểm dừng quét:

npx @openai/codex-security scan "$REPOSITORY" \
  --mode deep \
  --workers 2 \
  --subagents 0 \
  --stop-after-no-new 3 \
  --max-discovery-runs 10 \
  --max-time-hours 1.5

Các tùy chọn này yêu cầu chế độ sâu, hỗ trợ mục tiêu kho mã nguồn và đường dẫn, nhưng không hỗ trợ quét diff hoặc cây làm việc. Ở đây, --workers kiểm soát các worker quét tiêu chuẩn độc lập trong một lần quét; bulk-scan --workers kiểm soát các lần quét kho mã nguồn đồng thời. --max-time-hours chấp nhận một số dương tối đa là 96, kể cả số giờ dạng thập phân. Khi đạt giới hạn, lần quét dừng các worker chưa hoàn thành, bảo toàn kết quả quét đã hoàn tất và tổng hợp chúng vào báo cáo cuối cùng.

Thêm ngữ cảnh kiến trúc và bảo mật

Cung cấp tài liệu kiến trúc, mô hình mối đe dọa hoặc chính sách bảo mật làm ngữ cảnh quét. Điều này giúp Codex Security đánh giá các phát hiện dựa trên cách hệ thống của bạn thực sự hoạt động:

npx @openai/codex-security scan "$REPOSITORY" \
  --knowledge-base /path/to/architecture.md \
  --knowledge-base /path/to/security-policies

Thêm hướng dẫn quét tùy chỉnh

Thêm hướng dẫn tập trung lần quét vào các ưu tiên bảo mật của bạn. Sử dụng một tệp thứ hai cho hướng dẫn tiếp theo:

npx @openai/codex-security scan "$REPOSITORY" \
  --scan-prompt-file /path/to/scan.md \
  --post-scan-prompt-file /path/to/follow-up.md

Bước tiếp theo chạy trong cùng phiên đã xác thực sau các lần quét thành công và các lần quét có phạm vi bao phủ không đầy đủ hoặc gặp lỗi. Nếu bước tiếp theo thất bại, CLI sẽ báo cảnh báo và giữ lại lần quét đã hoàn tất. Bước này không chạy sau khi hủy hoặc sau một lần quét đạt giới hạn chi phí. Cả hai tùy chọn cũng hoạt động với bulk-scan; cột prompt trong CSV bổ sung hướng dẫn riêng cho từng kho mã nguồn.

Đặt ngân sách quét

Sử dụng --max-cost để dừng lần quét khi chi phí mô hình ước tính vượt quá giới hạn tính bằng USD:

npx @openai/codex-security scan "$REPOSITORY" --max-cost 5

Các yêu cầu đang được xử lý có thể hoàn tất và khiến chi phí vượt nhẹ giới hạn. Nếu một lần quét sâu đạt giới hạn sau khi Codex Security tổng hợp kết quả của các worker đã hoàn tất, CLI sẽ lưu báo cáo hoàn chỉnh, đánh dấu phạm vi bao phủ là partial và trả về mã thoát 2. Nếu lần quét không thể tạo báo cáo hoàn chỉnh, mọi kết quả một phần hiện có vẫn được lưu trên đĩa.

Quét thay đổi trước mỗi commit

Cài đặt bước kiểm tra bảo mật Git pre-commit cho kho mã nguồn của bạn:

npx @openai/codex-security install-hook

Bước kiểm tra quét các thay đổi đã và chưa được đưa vào vùng tạm trước mỗi commit. Bước này chặn các phát hiện mức độ nghiêm trọng cao và lỗi quét mà không thay thế tập lệnh pre-commit hiện có.

Quét hàng loạt kho mã nguồn

Đăng nhập GitHub trước khi khám phá kho mã nguồn:

gh auth login

Khám phá và chọn kho mã nguồn từ tài khoản hoặc tổ chức GitHub của bạn:

npx @openai/codex-security bulk-scan

Quy trình tương tác loại trừ kho mã nguồn đã lưu trữ và fork. Quy trình sẽ yêu cầu bạn xác nhận các kho mã nguồn đã chọn trước khi quét.

Để quét một danh sách kho mã nguồn đã chuẩn bị, hãy cung cấp tệp CSV và thư mục đầu ra:

npx @openai/codex-security bulk-scan repositories.csv \
  --output-dir /path/outside/repositories/security-scans \
  --workers 4

Chạy lại cùng lệnh để tiếp tục một lần quét hàng loạt hiện có. Codex Security bỏ qua các kho mã nguồn đã hoàn tất. Thêm --max-attempts 3 khi bạn muốn thử lại các lỗi tạm thời của kho mã nguồn hoặc lần quét.

Đối với khám phá GitHub, chuẩn bị CSV, kết quả chiến dịch và thiết lập Docker, hãy xem Chạy quét bảo mật hàng loạt.

Chạy quét hàng loạt trong Docker

Nếu quyền truy cập của bạn bao gồm image Docker Codex Security, hãy sử dụng cấu hình Compose được tăng cường bảo mật và hồ sơ bảo mật đi kèm trên máy chủ Docker Linux. Máy chủ phải hỗ trợ tạo không gian tên người dùng không đặc quyền. Hãy cung cấp tệp CSV kho mã nguồn, lưu kết quả và trạng thái đăng nhập trong các thư mục gắn kết bền vững, đồng thời cung cấp thông tin xác thực qua môi trường hoặc trình quản lý thông tin bí mật:

docker compose run --rm codex-security \
  bulk-scan /input/repositories.csv \
  --output-dir /output \
  --workers 4

Container chạy quét hàng loạt mà không có lời nhắc tương tác. Hãy dùng CLI bên ngoài Docker khi bạn muốn khám phá kho mã nguồn theo cách tương tác. Đối với kho mã nguồn riêng tư, hãy cung cấp GH_TOKEN hoặc GITHUB_TOKEN qua môi trường hoặc trình quản lý thông tin bí mật. Yêu cầu đăng nhập, bao gồm quyền truy cập tài khoản và kho mã nguồn, cũng áp dụng cho các lần quét trong container.

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

Liệt kê các lần quét đã lưu cho kho mã nguồn của bạn:

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

Sao chép ID lần quét từ kết quả để kiểm tra các phát hiện và cấu hình của lần quét:

npx @openai/codex-security scans show SCAN_ID

Để kiểm tra các sự kiện đã lưu từ một lần quét và các worker của nó:

npx @openai/codex-security scans logs SCAN_ID

Nhật ký đã lưu không được che dữ liệu và 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ẻ.

Liệt kê các phát hiện đang mở trong những lần quét kho mã nguồn:

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

Một phát hiện trước đó vẫn ở trạng thái mở khi lần quét mới nhất không xác nhận phát hiện đó.

Để đánh dấu một phát hiện đã xem xét là dương tính giả, hãy giải thích lý do phát hiện đó không áp dụng:

npx @openai/codex-security findings false-positive FINDING_OCCURRENCE_ID \
  --reason "The route already checks permissions"

Các lần quét sau sẽ cân nhắc lời giải thích đó nhưng vẫn kiểm tra lại mã hiện tại.

Chạy lại cùng lần quét trên bản checkout hiện tại bằng cấu hình ban đầu:

npx @openai/codex-security scans rerun SCAN_ID

So sánh hai lần quét để tìm các phát hiện mới, còn tồn tại, được mở lại, đã giải quyết hoặc không xác định:

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

Quá trình so sánh tự động đối sánh phát hiện theo nguyên nhân gốc và tái sử dụng các kết quả đối sánh đã lưu.

Đối với định dạng CSV của quét hàng loạt, bộ lọc lịch sử quét và tùy chọn lệnh, hãy xem Tài liệu tham khảo CLI.

Tiếp tục với quy trình phù hợp với mục tiêu của bạn: