Tài liệu tham khảo Codex Security CLI

Sử dụng tài liệu tham khảo này để kiểm tra các lệnh codex-security được hỗ trợ, các cờ, định dạng đầu ra và hành vi thoát. Để thực hiện lượt quét đầu tiên theo hướng dẫn, hãy bắt đầu với hướng dẫn bắt đầu nhanh về CLI.

Cài đặt gói đã phát hành trong dự án của bạn:

npm install @openai/codex-security

Gọi gói đã cài đặt bằng npx @openai/codex-security. Bạn có thể dùng trực tiếp codex-security khi tệp thực thi có sẵn trên PATH của bạn.

Tổng quan về lệnh

usage: codex-security [--version] <command> [options]

CLI cung cấp các lệnh sau:

CLI cũng cung cấp các lệnh tích hợp sau:

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

npx @openai/codex-security --help

Thêm --help vào một lệnh để xem các đối số và tùy chọn của lệnh đó:

npx @openai/codex-security scan --help

codex-security --version in phiên bản đã cài đặt rồi thoát. codex-security info --json báo cáo phiên bản SDK và plugin đi kèm. Cả hai lệnh đều không yêu cầu Python.

Khám phá lệnh và kết nối các agent

In bản kê khai lệnh mà agent có thể đọc:

npx @openai/codex-security --llms

Kiểm tra lược đồ đối số quét dưới dạng JSON:

npx @openai/codex-security scan --schema --format json

Tạo tính năng hoàn thành lệnh shell cho Bash:

npx @openai/codex-security completions bash

Thay bash bằng zsh hoặc fish cho các shell tương ứng.

Kết quả quét hỗ trợ --format toon|json|yaml|jsonl và --full-output. --format ở cấp framework này tách biệt với --export-format, tùy chọn dùng để chọn định dạng của tạo tác được xuất từ một lượt quét đã hoàn tất. Phần trợ giúp lệnh toàn cục cũng liệt kê md, nhưng kết quả quét không hỗ trợ đầu ra Markdown.

Đăng ký CLI làm máy chủ MCP:

npx @openai/codex-security mcp add

Đồng bộ các kỹ năng Codex Security với các agent của bạn:

npx @openai/codex-security skills add

MCP chỉ cung cấp lệnh siêu dữ liệu chỉ đọc info. Các thao tác quét, xuất, xác thực, kiểm định và vá vẫn chỉ thực hiện được qua CLI.

codex-security scan

Chạy quét trên một kho lưu trữ, các đường dẫn đã chọn, các thay đổi đã commit hoặc cây làm việc.

usage: codex-security scan [-h] [--auth {auto,chatgpt,api-key}]
                           [--provider {openai,openrouter,fireworks,amazon-bedrock}]
                           [--path PATH | --diff BASE | --working-tree]
                           [--head HEAD] [--base BASE]
                           [--knowledge-base PATH]
                           [--mode {standard,deep}] [--model MODEL]
                           [--effort {minimal,low,medium,high,xhigh}]
                           [--output-dir DIR]
                           [--archive-existing]
                           [--plugin-path PATH] [--python PATH]
                           [--codex KEY=VALUE] [--fail-on-severity LEVEL]
                           [--max-cost USD] [--dry-run] [--verbose]
                           [--json] [--format {toon,json,yaml,jsonl}]
                           [--full-output] [repository]

repository mặc định là thư mục hiện tại.

Chọn phương thức xác thực quét

Sử dụng --auth auto, giá trị mặc định, để tự động chọn thông tin xác thực. Khi có cả thông tin đăng nhập ChatGPT và OPENAI_API_KEY hoặc CODEX_API_KEY, các lượt quét tương tác với đầu ra văn bản sẽ hỏi thông tin xác thực cần dùng. CI, các lượt quét JSON và JSONL cùng những lượt quét khác không có terminal tương tác sẽ sử dụng API key trong môi trường. Chạy thử không hiển thị lời nhắc hoặc tải thông tin xác thực.

Để sử dụng thông tin xác thực đã lưu, hãy truyền --auth chatgpt:

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

Để sử dụng API key trong môi trường, hãy truyền --auth api-key:

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

Để đặt thông tin xác thực đã lưu làm lựa chọn tự động mặc định, hãy chạy unset OPENAI_API_KEY CODEX_API_KEY.

Sử dụng Amazon Bedrock

Chọn Amazon Bedrock bằng --provider amazon-bedrock và chỉ định rõ mô hình Bedrock bằng --model:

npx @openai/codex-security scan . \
  --provider amazon-bedrock \
  --model openai.gpt-5.6-sol

Đặt AWS_REGION và xác thực bằng AWS_BEARER_TOKEN_BEDROCK, khóa truy cập AWS tiêu chuẩn, hồ sơ AWS, danh tính web, thông tin xác thực container hoặc chuỗi thông tin xác thực AWS mặc định. Các lượt quét Bedrock sử dụng thông tin xác thực AWS thay cho --auth, thông tin đăng nhập ChatGPT hoặc OpenAI API key. Cả scan và bulk-scan đều hỗ trợ --provider.

Chọn mục tiêu quét

Chọn một loại mục tiêu cho mỗi lượt quét.

--path, --diff và --working-tree loại trừ lẫn nhau. --head yêu cầu --diff, còn --base yêu cầu --working-tree. Chế độ chuyên sâu hỗ trợ mục tiêu là kho lưu trữ và đường dẫn.

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. Các ref đã chọn phải tồn tại trong bản checkout đó.

Quét toàn bộ kho lưu trữ:

npx @openai/codex-security scan .

Quét các đường dẫn đã chọn:

npx @openai/codex-security scan . --path src --path tests

Quét các thay đổi đã commit:

npx @openai/codex-security scan . --diff origin/main --head HEAD

Quét các thay đổi đã và chưa được đưa vào vùng tạm:

npx @openai/codex-security scan . --working-tree --base HEAD

Xem xét kho lưu trữ chuyên sâu hơn:

npx @openai/codex-security scan . --mode deep

Bổ sung ngữ cảnh bảo mật

Sử dụng --knowledge-base PATH để 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ặp lại tùy chọn để thêm tệp hoặc thư mục:

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

Các tài liệu được hỗ trợ gồm tệp .md, .markdown, .txt, .pdf và .docx. CLI tìm kiếm đệ quy trong các thư mục, từ chối đường dẫn đầu vào liên kết, bỏ qua các mục thư mục liên kết và giữ nội dung tài liệu đã trích xuất bên ngoài kết quả quét đã lưu.

Đặt tùy chọn đầu ra và chính sách

Sử dụng các tùy chọn này để lưu tạo tác, bảo toàn kết quả trước đó hoặc tạo kết quả mà máy có thể đọc.

Giới hạn chi phí là ước tính, không phải mức trần chi tiêu cứng. 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 và kết quả quét một phần vẫn được giữ lại.

Khi bạn bỏ qua --output-dir, kết quả được lưu bền vững trong $CODEX_HOME/state/plugins/codex-security/scans/<repository>. CODEX_HOME mặc định là ~/.codex. Đặt CODEX_SECURITY_STATE_DIR để lưu kết quả trong $CODEX_SECURITY_STATE_DIR/scans/<repository>. Các thư mục này có thể chứa đoạn mã nguồn và chi tiết lỗ hổng, vì vậy hãy quản lý quyền truy cập và thời gian lưu giữ cho phù hợp.

Workbench lưu lịch sử quét trong $CODEX_HOME/state/plugins/codex-security/workbench.sqlite3. Việc đặt CODEX_SECURITY_STATE_DIR cũng di chuyển cơ sở dữ liệu workbench.

Thư mục đầu ra phải nằm ngoài thư mục được quét và mọi Git worktree bao quanh. Một lượt quét có thể thay thế thư mục kết quả hiện có bằng --archive-existing.

Để bảo toàn kết quả trước đó trước khi dùng lại thư mục đầu ra:

npx @openai/codex-security scan . \
  --output-dir /path/outside/repository/results \
  --archive-existing

Theo mặc định, lượt quét chỉ tạo báo cáo. Thêm --fail-on-severity để đánh giá chính sách mức độ nghiêm trọng trong CI:

npx @openai/codex-security scan . \
  --diff origin/main \
  --output-dir /path/outside/repository/results \
  --json \
  --fail-on-severity high \
  > /path/outside/repository/codex-security.json

Chạy thử kiểm tra đầu vào cục bộ mà không tải thông tin xác thực, khởi động Codex hoặc thăm dò trình thông dịch Python của plugin:

npx @openai/codex-security scan . \
  --output-dir /path/outside/repository/results \
  --dry-run

Cấu hình môi trường chạy

Sử dụng các tùy chọn môi trường chạy khi bạn cần chỉ định rõ mô hình, trình thông dịch, plugin hoặc giá trị cấu hình Codex.

Để chọn mô hình và mức độ suy luận khác mà không ghi TOML:

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

Đặt các giá trị chuỗi được truyền qua --codex trong dấu ngoặc kép để trình phân tích TOML nhận được một chuỗi:

npx @openai/codex-security scan . --codex 'model="gpt-5.6-terra"'

codex-security install-hook

Cài đặt bước kiểm tra bảo mật Git pre-commit cho kho lưu trữ hiện tại:

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 và chặn các phát hiện có mức độ nghiêm trọng cao hoặc lỗi quét. Bước này tôn trọng core.hooksPath và không thay thế tập lệnh pre-commit hiện có. Đặt ngưỡng mức độ nghiêm trọng khác khi cần:

npx @openai/codex-security install-hook . --fail-on-severity medium

codex-security bulk-scan

Khám phá và quét các kho lưu trữ GitHub hoặc chạy một lượt quét có thể tiếp tục từ tệp CSV kho lưu trữ:

Để xem hướng dẫn đầy đủ về khám phá GitHub, danh mục CSV, kết quả chiến dịch và quét trong container, hãy xem Chạy quét bảo mật hàng loạt.

usage: codex-security bulk-scan [input] [--output-dir DIR]
                                [--workers N] [--mode {standard,deep}]
                                [--provider {openai,openrouter,fireworks,amazon-bedrock}]
                                [--model MODEL]
                                [--effort {minimal,low,medium,high,xhigh}]
                                [--max-attempts N] [--plugin-path PATH]
                                [--python PATH] [--codex KEY=VALUE]

Chạy npx @openai/codex-security bulk-scan mà không có đối số để chọn các kho lưu trữ theo cách tương tác. Quy trình này yêu cầu đăng nhập GitHub CLI.

Để chọn mô hình và mức độ suy luận trong quá trình khám phá tương tác:

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

Đối với danh sách kho lưu trữ đã chuẩn bị, hãy cung cấp tệp CSV và --output-dir:

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

Tệp CSV yêu cầu các cột id, repository và revision. Các bản sửa đổi phải là hash commit đầy đủ. Các cột scope và mode không bắt buộc dùng để cấu hình từng kho lưu trữ:

id,repository,revision,scope,mode
service,https://github.com/example/service.git,0123456789abcdef0123456789abcdef01234567,src,standard

--workers giới hạn số lượt quét đồng thời và mặc định là 4. --mode mặc định là standard, còn --max-attempts mặc định là 1. Đặt --max-attempts khi bạn muốn thử lại một kho lưu trữ sau lỗi. Chạy lại cùng lệnh để tiếp tục lượt quét hàng loạt từ thư mục đầu ra hiện có. CLI chỉ bỏ qua các kho lưu trữ đã hoàn tất khi các tạo tác kết quả được ghi nhận vẫn còn tồn tại.

Đối với các chiến dịch trong container, hãy xem Chạy quét hàng loạt trong Docker.

codex-security scans

Tìm các lượt quét đã lưu

Liệt kê các lượt quét đã lưu cho thư mục hiện tại:

npx @openai/codex-security scans

Liệt kê các lượt quét cho một kho lưu trữ khác:

npx @openai/codex-security scans list /path/to/repository

Tìm các lượt quét được lưu trong một thư mục đầu ra cụ thể:

npx @openai/codex-security scans list --scan-root /path/outside/repository/results

Kiểm tra hoặc lặp lại một lượt quét

Hiển thị kết quả và cấu hình của một lượt quét đã lưu:

npx @openai/codex-security scans show SCAN_ID

Chạy lại 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

Đối chiếu và so sánh các phát hiện

Đối chiếu các phát hiện có cùng nguyên nhân gốc giữa hai lượt quét:

npx @openai/codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID

So sánh các lượt quét đã đối chiếu để tìm các phát hiện mới, vẫn tồn tại, tái xuất hiện, đã giải quyết và không xác định:

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

Một phát hiện được coi là không xác định khi lượt quét sau có phạm vi bao phủ không đầy đủ hoặc không bao phủ vị trí ban đầu của phát hiện. Thêm --force vào match khi bạn cần tính toán lại một kết quả đối chiếu hiện có.

Để đối chiếu tất cả lượt quét đã hoàn tất cho kho lưu trữ hiện tại, bao gồm cả lượt quét từ các bản checkout khác:

npx @openai/codex-security scans match --all

Kết quả quét có thể khác nhau ngay cả khi bạn chạy lại cùng một cấu hình. Việc đối chiếu và so sánh theo dõi các thay đổi; chúng không làm cho kết quả trở nên tất định hoặc chứng minh rằng một lỗ hổng không còn tồn tại. Sử dụng validate để kiểm tra lại một phát hiện quan trọng về bảo mật trên mã hiện tại.

codex-security findings

Ghi nhận một phát hiện đã xem xét là dương tính giả:

usage: codex-security findings false-positive OCCURRENCE_ID
                       --reason REASON

Kiểm tra lượt quét đã lưu để xác định lần xuất hiện của phát hiện:

npx @openai/codex-security scans show SCAN_ID

Ghi lại lời giải thích cụ thể cho trường hợp dương tính giả:

npx @openai/codex-security findings false-positive FINDING_OCCURRENCE_ID \
  --reason "The framework escapes this input before it reaches the query"

Lý do không được để trống. Codex Security lưu quyết định cho kho lưu trữ và cung cấp quyết định đó làm ngữ cảnh cho các lượt quét sau. Mỗi lượt quét sẽ độc lập kiểm tra lại mã nguồn, biện pháp kiểm soát và khả năng tiếp cận hiện tại. Quyết định trước đó không loại bỏ một quy tắc, đường dẫn hoặc lớp lỗ hổng.

codex-security export

Xuất CSV, JSON hoặc SARIF từ một lượt quét đã hoàn tất và được niêm phong. Thao tác xuất xác thực các tạo tác quét trước khi ghi đầu ra và không tác động đến môi trường chạy Codex cũng như thông tin xác thực.

usage: codex-security export [--export-format {csv,json,sarif}]
                             [--output FILE|-] [--source-root PATH]
                             [--python PATH] scan_dir

scan_dir là thư mục của lượt quét đã hoàn tất.

--source-root chỉ hoạt động với --export-format sarif. JSON giữ nguyên tài liệu phát hiện đã niêm phong. CSV chứa các cột phát hiện có tính di động và không bao gồm trạng thái phân loại của workbench cục bộ.

Nếu không có --output, CLI ghi SARIF vào results.sarif, JSON vào findings.json và CSV vào findings.csv trong thư mục làm việc hiện tại. Dữ liệu xuất có thể chứa đoạn mã nguồn và chi tiết lỗ hổng. Hãy chạy lệnh bên ngoài kho lưu trữ hoặc truyền --output với một đường dẫn riêng tư nằm ngoài bản checkout được quét.

Ghi SARIF vào một tệp:

npx @openai/codex-security export /path/to/scan \
  --export-format sarif \
  --source-root /path/to/repository \
  --output /path/outside/repository/exports/results.sarif

Ghi SARIF vào stdout:

npx @openai/codex-security export /path/to/scan \
  --export-format sarif \
  --source-root . \
  --output -

Xuất các phát hiện dưới dạng JSON:

npx @openai/codex-security export /path/to/scan \
  --export-format json \
  --output /path/outside/repository/exports/findings.json

Xuất các phát hiện dưới dạng CSV:

npx @openai/codex-security export /path/to/scan \
  --export-format csv \
  --output /path/outside/repository/exports/findings.csv

codex-security validate và codex-security patch

Kiểm tra xem một phát hiện ứng viên có hợp lệ hay không:

npx @openai/codex-security validate findings.json \
  "Possible SQL injection in src/query.ts:42"

Tạo bản sửa lỗi bằng kỹ năng khắc phục đi kèm:

npx @openai/codex-security patch findings.json \
  "Missing authorization check in src/routes.ts:18"

Mỗi đối số có thể chứa văn bản thuần túy hoặc trỏ đến một tệp. Cả hai lệnh đều hoạt động trên thư mục hiện tại. Sử dụng validate để trực tiếp kiểm tra lại một phát hiện ban đầu sau khi sửa hoặc khi lượt quét sau không còn báo cáo phát hiện đó. Chỉ riêng việc so sánh lượt quét không chứng minh rằng bản sửa lỗi đã có hiệu quả. Các công cụ bên ngoài có thể sử dụng những lệnh này mà không cần xây dựng lại trình quét.

Sử dụng --effort để chọn mức độ suy luận cho một trong hai lệnh:

npx @openai/codex-security validate "Possible SQL injection" --effort high

codex-security login, logout và info

Đăng nhập theo cách tương tác:

npx @openai/codex-security login

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

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

Kiểm tra thông tin đăng nhập hiện tại:

npx @openai/codex-security login status

Xóa thông tin đăng nhập đã lưu:

npx @openai/codex-security logout

Lưu API key bằng cách truyền qua stdin:

printenv OPENAI_API_KEY | npx @openai/codex-security login --with-api-key

Lưu token truy cập doanh nghiệp:

printenv CODEX_ACCESS_TOKEN | npx @openai/codex-security login --with-access-token

Kiểm tra siêu dữ liệu SDK và plugin đi kèm ở chế độ chỉ đọc:

npx @openai/codex-security info --json

Khi bạn cung cấp CLI dưới dạng máy chủ MCP, info là lệnh duy nhất có sẵn. Các thao tác quét, xuất, đăng nhập, kiểm định và vá vẫn chỉ thực hiện được qua CLI.

Đọc đầu ra quét

Theo mặc định, các lượt quét gửi tiến trình, bản tóm tắt hoàn tất và lỗi đến stderr mà không ghi toàn bộ kết quả quét vào stdout. Yêu cầu --json, --format hoặc --full-output để gửi kết quả quét có cấu trúc đến stdout.

Thông tin chẩn đoán chi tiết

Thêm --verbose để in thông tin chẩn đoán đã che dữ liệu về vòng đời, xác thực, tiến trình và chi phí vào stderr:

npx @openai/codex-security scan . --verbose

Đặt CODEX_SECURITY_LOG_LEVEL=debug để bật cùng loại thông tin chẩn đoán mà không cần cờ. LOG_LEVEL=debug cũng bật thông tin chẩn đoán khi CODEX_SECURITY_LOG_LEVEL chưa được đặt.

Các tùy chọn ghi nhật ký này chỉ áp dụng cho CLI. Thông tin xác thực và mã định danh nhà cung cấp vẫn được che, còn kết quả quét có cấu trúc vẫn nằm trên stdout.

Bản tóm tắt hoàn tất

Một lượt quét hoàn tất ghi số lượng phát hiện, phân bố mức độ nghiêm trọng, phạm vi bao phủ, thời gian đã dùng, đường dẫn báo cáo và thư mục kết quả vào stderr. Thông tin này bao gồm mức sử dụng token và chi phí ước tính khi có dữ liệu:

codex-security: Findings: 4 (1 critical, 2 high, 1 informational). Coverage: complete.
codex-security: Elapsed: 1s.
codex-security: Tokens: 1,250 input, 200 cached, 30 output.
codex-security: Report: /path/to/scan/report.md
codex-security: Results: /path/to/scan

Các phát hiện mang tính thông tin được tính vào tổng số trong bản tóm tắt. Chính sách mức độ nghiêm trọng chỉ đánh giá các phát hiện critical, high, medium và low.

Đầu ra JSON

scan --json ghi một tài liệu JSON hoàn chỉnh vào stdout. Cấu trúc cấp cao nhất của tài liệu là:

manifest
findings
coverage
scanDir
threadId
reportPath
artifactsDir
sarifPath
turn
  id
  status
  durationMs
  finalResponse
  usage

Tiến trình, bản tóm tắt hoàn tất, thông báo lưu trữ và lỗi vẫn nằm trên stderr. Một lượt quét hoàn tất vẫn in toàn bộ kết quả JSON khi chính sách mức độ nghiêm trọng trả về mã thoát 1 hoặc phạm vi bao phủ không đầy đủ trả về mã thoát 2.

Tạo tác quét

Một lượt quét hoàn tất lưu báo cáo dễ đọc và các tạo tác có cấu trúc cùng nhau:

<scan-directory>/
├── scan-manifest.json
├── findings.json
├── coverage.json
├── report.md
├── artifacts/
└── exports/
    └── results.sarif       # when produced

Các tệp có cấu trúc phục vụ những mục đích khác nhau:

Mức độ hoàn chỉnh của phạm vi bao phủ có ba giá trị:

• complete: Lượt quét ghi nhận phạm vi bao phủ hoàn chỉnh cho phạm vi đã chọn.
• partial: Lượt quét ghi nhận công việc hoãn lại hoặc các giới hạn khác về phạm vi bao phủ.
• unknown: Lượt quét báo cáo mức độ hoàn chỉnh của phạm vi bao phủ là không xác định.

Hãy xem xét các bề mặt bị hoãn, trường hợp loại trừ rõ ràng và câu hỏi còn bỏ ngỏ trước khi sử dụng phạm vi bao phủ làm bằng chứng cho một quyết định bảo mật.

Mã thoát và tín hiệu

CLI sử dụng các mã thoát sau:

Mọi lượt quét có phạm vi bao phủ partial hoặc unknown đều trả về 2, ngay cả khi không có chính sách mức độ nghiêm trọng. Khi bạn yêu cầu đầu ra có cấu trúc, các lượt quét hoàn tất vẫn ghi kết quả hiện có vào stdout. CLI in vị trí của mọi đầu ra một phần sau khi bị ngắt hoặc gặp lỗi môi trường chạy.

Xác thực và điều kiện tiên quyết

Đặt OPENAI_API_KEY hoặc CODEX_API_KEY, đăng nhập bằng npx @openai/codex-security login hoặc sử dụng thông tin đăng nhập Codex dựa trên tệp hiện có. Đối với Amazon Bedrock, hãy sử dụng Bedrock API key hoặc chuỗi thông tin xác thực AWS tiêu chuẩn.

Để biết cách chọn thông tin xác thực, hãy xem Chọn phương thức xác thực quét.

Đối với CI, hãy giới hạn API key trong bước quét và sử dụng một quy trình làm việc đáng tin cậy.

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. Python 3.10 cũng yêu cầu tomli. Sử dụng --python hoặc PYTHON để chọn trình thông dịch khi cơ chế tự động phát hiện không phù hợp.

Tiếp tục với hướng dẫn bắt đầu nhanh về CLI, hướng dẫn quét hàng loạt, câu hỏi thường gặp về CLI, hướng dẫn CI hoặc hướng dẫn TypeScript SDK.

Bí danh văn bản thuần túy

• --output FILE|-