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 một lượt quét cục bộ và xem xét báo cáo, các 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 các lỗ hổng. Sử dụng giao diện dòng lệnh (CLI) để quét các kho lưu trữ mà bạn sở hữu hoặc được phép đánh giá, theo dõi các phát hiện theo thời gian và kiểm tra các thay đổi trước khi chúng được hợp nhất.

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

CLI yêu cầu Node.js 22 trở lên. Việc chạy quét hoặc xuất các phát hiện 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

Cài đặt gói đã phát hành:

npm install @openai/codex-security

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

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 làm việc tự động khác, hãy đặt mộ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 .

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

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 vào tài khoản và kho lưu trữ của bạn, các lượt quét toàn bộ kho lưu trữ cũng có thể yêu cầu Trusted Access for Cyber.

Chuẩn bị một lượt quét

Chọn kho lưu trữ cần quét và thư mục để ghi kết quả.

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ể chứa các đoạn mã nguồn và chi tiết lỗ hổng, vì vậy hãy chọn vị trí riêng tư và chính sách lưu giữ phù hợp.

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

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

Kiểm tra kho lưu trữ, 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

Chạy thử sẽ kiểm tra đầu vào cục bộ 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ượt quét đầu tiên

Chạy một lượt 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"

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ượt quét hoàn tất sẽ in bản tóm tắt như sau:

codex-security: Findings: 2 (1 high, 1 medium). Coverage: complete.
codex-security: Elapsed: 42s.
codex-security: Report: /path/outside/repository/codex-security-results/report.md
codex-security: 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 rõ đầu ra có cấu trúc:

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

Theo mặc định, các lượt quét chỉ tạo báo cáo, vì vậy các phát hiện vẫn được lưu để 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, các lượt quét sử dụng gpt-5.6-sol với mức độ suy luận xhigh. Hãy chọn 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 và xhigh.

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 hoạt động tự động 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 tạo tác đã niêm phong.
  • findings.json ghi lại mức độ nghiêm trọng, độ tin cậy, vị trí, bằng chứng và cách khắc phục cho từng phát hiện.
  • coverage.json ghi lại các bề mặt đã xem xét, trường hợp 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 coi lượt quét là bằng chứng đã xem xét. Tài liệu tham khảo CLI mô tả đầy đủ hợp đồng về tạo tác và đầu ra.

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

Sử dụng quét theo đường dẫn khi kho lưu trữ 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 phần khác biệt và cây làm việc yêu cầu đối số kho lưu trữ 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 phần khác biệt.

Sử dụng chế độ chuyên sâu khi kho lưu trữ hoặc đường dẫn cần được xem xét rộng hơn:

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

Chế độ chuyên sâu hỗ trợ mục tiêu là kho lưu trữ và đường dẫn, không hỗ trợ quét phần khác biệt hoặc cây làm việc.

Bổ sung 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

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

Sử dụng --max-cost để dừng lượt 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 xử lý có thể hoàn tất với chi phí vượt giới hạn. Codex Security giữ lại các kết quả hiện có khi lượt quét dừng.

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 lưu trữ của bạn:

npx @openai/codex-security install-hook

Bước kiểm tra sẽ 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 có 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 lưu trữ

Đăng nhập vào GitHub trước khi khám phá các kho lưu trữ:

gh auth login

Khám phá và chọn các kho lưu trữ 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ừ các kho lưu trữ đã lưu trữ và các bản fork. Quy trình yêu cầu bạn xác nhận các kho lưu trữ đã chọn trước khi quét.

Để quét một danh sách kho lưu trữ đã 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ượt quét hàng loạt hiện có. Các kho lưu trữ đã hoàn tất và có đầy đủ tạo tác kết quả sẽ không bị quét lại. Thêm --max-attempts 3 khi bạn muốn thử lại các lỗi tạm thời của kho lưu trữ hoặc lượt quét.

Để biết về 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 của Codex Security, hãy sử dụng cấu hình Compose được gia cố và hồ sơ bảo mật được cung cấp trên máy chủ Docker chạy Linux. Máy chủ phải hỗ trợ tạo không gian tên người dùng không đặc quyền. Cung cấp tệp CSV kho lưu trữ, 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ý 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 hiển thị lời nhắc. Hãy sử dụng CLI bên ngoài Docker khi bạn muốn khám phá kho lưu trữ theo cách tương tác. Đối với kho lưu trữ 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ý bí mật. Các yêu cầu đăng nhập, bao gồm quyền truy cập tài khoản và kho lưu trữ, cũng áp dụng cho các lượt quét trong container.

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

Liệt kê các lượt quét đã lưu cho kho lưu trữ của bạn:

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

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

npx @openai/codex-security scans show SCAN_ID

Để đá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ượt 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ượt 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ượt quét, trước tiên hãy đối chiếu các phát hiện có cùng nguyên nhân gốc:

npx @openai/codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID

Sau đó kiểm tra các phát hiện nào là mới, vẫn tồn tại, tái xuất hiện, đã được giải quyết hoặc không xác định:

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

Để biết định dạng CSV cho quét hàng loạt, các 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: