Chạy quét bảo mật hàng loạt

Sử dụng npx @openai/codex-security bulk-scan để đánh giá các kho lưu trữ trong một chiến dịch. Khám phá kho lưu trữ từ tài khoản GitHub cá nhân hoặc một tổ chức, hoặc cung cấp tệp CSV ghim từng kho lưu trữ vào một bản sửa đổi Git chính xác.

Chọn nguồn kho lưu trữ

Cả hai quy trình đều lưu tiến trình, bảo toàn kết quả của từng kho lưu trữ và cho phép bạn tiếp tục chiến dịch sau khi bị gián đoạn.

Khám phá các kho lưu trữ GitHub

Đăng nhập bằng GitHub CLI:

gh auth login

Bắt đầu một lượt quét hàng loạt tương tác:

npx @openai/codex-security bulk-scan

CLI hướng dẫn bạn thực hiện các bước sau:

1. Chọn tài khoản GitHub cá nhân hoặc một tổ chức.
2. Xem xét các kho lưu trữ có hoạt động trong vòng 90 ngày qua.
3. Tìm kiếm trong danh sách kho lưu trữ và chọn các kho cần quét.
4. Chọn thư mục lưu kết quả quét.
5. Xem xét các kho lưu trữ đã chọn và xác nhận chiến dịch.

Quá trình khám phá loại trừ các kho lưu trữ đã lưu trữ và các bản fork. CLI ghi lại commit chính xác của nhánh mặc định cho từng kho lưu trữ đã chọn trong <output-directory>/repositories.csv. Không lượt quét nào bắt đầu cho đến khi bạn xác nhận lựa chọn.

Để sử dụng GitHub Enterprise Server, trước tiên hãy đăng nhập vào máy chủ GitHub của bạn:

gh auth login --hostname github.example.com

Đặt GH_HOST khi bạn bắt đầu khám phá kho lưu trữ:

GH_HOST=github.example.com npx @openai/codex-security bulk-scan

Khám phá tương tác yêu cầu terminal. Đối với CI, container hoặc danh sách kho lưu trữ đã chuẩn bị sẵn, hãy sử dụng danh mục CSV.

Tạo tệp CSV kho lưu trữ

Tạo tệp CSV với một hàng cho mỗi kho lưu trữ và bản sửa đổi đã ghim:

id,repository,revision,scope,mode,prompt
payments,https://github.com/example/payments.git,0123456789abcdef0123456789abcdef01234567,services/api,standard,Review payment authorization and refunds.
identity,https://github.com/example/identity.git,fedcba9876543210fedcba9876543210fedcba98,,deep,Review session and identity boundaries.

Tệp CSV hỗ trợ các cột sau:

Để tìm SHA commit đầy đủ của một kho lưu trữ cục bộ, hãy chạy:

git -C /path/to/repository rev-parse HEAD

Chạy chiến dịch từ CSV

Truyền tệp CSV và một thư mục đầu ra riêng tư nằm ngoài các kho lưu trữ:

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

--workers kiểm soát các lượt quét kho lưu trữ đồng thời và mặc định là 4. Tùy chọn này không đặt số lượng worker quét tiêu chuẩn độc lập bên trong mỗi lượt quét sâu; hãy cấu hình các giới hạn đó thông qua [deep_scan]. Sử dụng --mode deep để chọn quét sâu cho các hàng không có mode riêng. Mỗi hàng CSV vẫn có thể chọn chế độ quét và phạm vi kho lưu trữ riêng.

Đặt [deep_scan].max_time_hours để giới hạn việc thực thi worker cho từng lượt quét sâu trong chiến dịch. Cờ --max-time-hours hoạt động với scan, không phải bulk-scan.

CLI checkout từng bản sửa đổi đã ghim, quét mục tiêu đã chọn, ghi lại kết quả và xóa bản checkout kho lưu trữ tạm thời. Một kho lưu trữ chỉ được tính là hoàn tất khi lượt quét có độ bao phủ đầy đủ và tất cả thành phần kết quả bắt buộc đều tồn tại.

Chia sẻ ngữ cảnh và hướng dẫn bảo mật

Thêm 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 vào mọi lượt quét bằng --knowledge-base. Lặp lại cờ này để thêm nhiều tệp hoặc thư mục:

npx @openai/codex-security bulk-scan repositories.csv \
  --output-dir /path/outside/repositories/security-scans \
  --knowledge-base /path/to/architecture.md \
  --knowledge-base /path/to/security-policies

Để thêm hướng dẫn quét dùng chung hoặc chạy tác vụ tiếp theo sau mỗi lượt quét, hãy cung cấp các tệp prompt:

npx @openai/codex-security bulk-scan repositories.csv \
  --output-dir /path/outside/repositories/security-scans \
  --scan-prompt-file scan-instructions.md \
  --post-scan-prompt-file follow-up.md

CLI nối thêm prompt trong CSV của từng kho lưu trữ sau phần hướng dẫn quét dùng chung. Hướng dẫn tiếp theo chạy trong cùng phiên đã xác thực sau các lượt quét thành công và các lượt quét có độ bao phủ không đầy đủ hoặc gặp lỗi, nhưng không chạy sau khi hủy hoặc khi lượt quét đạt giới hạn chi phí. Đường dẫn tệp prompt được phân giải từ thư mục hiện tại của bạn.

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

Theo mặc định, các lượt quét hàng loạt sử dụng gpt-5.6-sol với mức độ suy luận xhigh. Để chọn mô hình và mức độ khác cho chiến dịch CSV:

npx @openai/codex-security bulk-scan repositories.csv \
  --output-dir /path/outside/repositories/security-scans \
  --workers 4 \
  --model gpt-5.6-terra \
  --effort high

Các tùy chọn tương tự cũng hoạt động trong quá trình khám phá kho lưu trữ tương tác:

npx @openai/codex-security bulk-scan --model gpt-5.6-terra --effort high

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

Để sử dụng OpenRouter hoặc Fireworks, hãy lần lượt đặt OPENROUTER_API_KEY hoặc FIREWORKS_API_KEY, và chỉ định --provider cùng --model. Để biết thông tin xác thực và ví dụ, hãy xem phần thiết lập OpenRouter hoặc Fireworks hoặc thiết lập Amazon Bedrock.

Xem xét kết quả chiến dịch

Thư mục đầu ra chứa chiến dịch đã ghim, sổ cái kết quả chỉ cho phép nối thêm và các thành phần riêng biệt cho từng kho lưu trữ và lần thử:

security-scans/
├── manifest.json
├── results.jsonl
├── checkouts/
└── artifacts/
    ├── payments/
    │   └── attempt-1/
    │       ├── scan-manifest.json
    │       ├── findings.json
    │       ├── coverage.json
    │       └── report.md
    └── identity/
        └── attempt-1/
            ├── scan-manifest.json
            ├── findings.json
            ├── coverage.json
            └── report.md

• manifest.json ghi lại các kho lưu trữ, bản sửa đổi đã ghim, phạm vi, chế độ quét và hướng dẫn dùng chung hoặc dành riêng cho kho lưu trữ trong chiến dịch.
• results.jsonl ghi lại từng lần thử của kho lưu trữ, trạng thái, thư mục thành phần và mọi chi tiết hiện có về chi phí hoặc lỗi.
• report.md cung cấp báo cáo dễ đọc cho một lần thử của kho lưu trữ.
• findings.json và coverage.json ghi lại các phát hiện và phạm vi đã xem xét của lần thử đó.

Xuất một lượt quét kho lưu trữ đã hoàn tất khi bạn cần kết quả có thể di chuyển:

npx @openai/codex-security export \
  /path/outside/repositories/security-scans/artifacts/payments/attempt-1 \
  --export-format sarif \
  --output /path/outside/repositories/payments.sarif

Kết quả có thể chứa các đoạn trích mã nguồn và chi tiết về lỗ hổng. Giữ thư mục đầu ra ở chế độ riêng tư, bên ngoài các kho lưu trữ được quét và tuân theo chính sách lưu giữ phù hợp.

Tiếp tục chiến dịch

Chạy lệnh ban đầu với cùng 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

CLI tiếp tục các lượt quét kho lưu trữ chưa hoàn tất và bỏ qua các lượt đã hoàn tất. Các lượt quét có độ bao phủ không đầy đủ sẽ không được thử lại. Kết quả của chúng vẫn khả dụng và lệnh thoát với mã 2.

Không thay đổi danh mục kho lưu trữ hoặc hướng dẫn quét và hướng dẫn tiếp theo đối với thư mục đầu ra hiện có. CLI kiểm tra tệp kê khai đã ghim và từ chối một chiến dịch khác. Hãy sử dụng thư mục đầu ra mới khi bạn thay đổi kho lưu trữ, bản sửa đổi, phạm vi, chế độ quét hoặc hướng dẫn dùng chung hay dành riêng cho kho lưu trữ.

Thử lại khi kho lưu trữ gặp lỗi

Sử dụng --max-attempts để thử lại một kho lưu trữ sau lỗi checkout hoặc lỗi quét tạm thời:

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

Mặc định là một lần thử cho mỗi kho lưu trữ. Mỗi lần thử có biên nhận và thư mục thành phần riêng. Việc thử lại áp dụng cho lỗi checkout, lỗi quét và trường hợp thiếu thành phần bắt buộc. Các lượt quét đã hoàn tất nhưng có độ bao phủ không đầy đủ sẽ không được thử lại.

Các lượt quét hàng loạt sử dụng những mã thoát sau:

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

Kho lưu trữ Codex Security bao gồm cấu hình Compose được gia cố bảo mật dành cho các chiến dịch CSV tự động 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.

Duy trì việc gắn tệp CSV kho lưu trữ, kết quả quét và trạng thái đăng nhập vào các thư mục lưu trữ bền vững. Cung cấp thông tin xác thực OpenAI qua môi trường hoặc trình quản lý bí mật. Đối với các kho lưu trữ GitHub riêng tư, hãy cung cấp GH_TOKEN hoặc GITHUB_TOKEN theo cách tương tự.

Chạy image với tệp CSV và thư mục đầu ra đã gắn:

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

Sử dụng cùng tệp CSV và thư mục đầu ra đã gắn để tiếp tục chiến dịch. Đối với GitHub Enterprise Server, hãy đặt CODEX_SECURITY_GIT_HOST thành máy chủ GitHub của bạn.

Để xem mọi cờ khả dụng, hãy tham khảo tài liệu tham chiếu lệnh bulk-scan . Để biết câu trả lời cho các câu hỏi thường gặp về độ bao phủ và phát hiện của lượt quét, hãy xem Câu hỏi thường gặp về CLI .