Tham chiếu CLI Codex Security

Sử dụng tài liệu tham chiếu này để kiểm tra các lệnh codex-security được hỗ trợ, cờ, định dạng đầu ra và hành vi thoát. Để thực hiện lần 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.

Chạy CLI bằng npx @openai/codex-security.

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 tác nhân

In bản kê khai lệnh mà tác nhân 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 phần 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ệp kết quả được xuất từ một lần 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 MCP server:

npx @openai/codex-security mcp add

Đồng bộ skills Codex Security với các tác nhân 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. Việ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 đối với một kho lưu trữ, các đường dẫn đã chọn, 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] [--scan-prompt-file FILE]
                           [--post-scan-prompt-file FILE]
                           [--mode {standard,deep}] [--workers N]
                           [--subagents N] [--stop-after-no-new N]
                           [--max-discovery-runs N] [--max-time-hours HOURS]
                           [--model MODEL]
                           [--effort {minimal,low,medium,high,xhigh,max}]
                           [--output-dir DIR]
                           [--archive-existing]
                           [--plugin-path PATH] [--python PATH]
                           [--codex KEY=VALUE] [--fail-on-severity LEVEL]
                           [--patch] [--patch-severity {critical,high,medium,low}]
                           [--create-pr]
                           [--max-cost USD] [--dry-run] [--headless] [--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 khi quét

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

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

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

Để dùng API key từ 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 OpenRouter hoặc Fireworks

Chọn OpenRouter bằng API key của dịch vụ này và một mô hình được chỉ định rõ:

export OPENROUTER_API_KEY="your-openrouter-api-key"
npx @openai/codex-security scan . \
  --provider openrouter \
  --model anthropic/claude-sonnet-4.5

Chọn Fireworks bằng API key của dịch vụ này và một mô hình được chỉ định rõ:

export FIREWORKS_API_KEY="your-fireworks-api-key"
npx @openai/codex-security scan . \
  --provider fireworks \
  --model accounts/fireworks/models/qwen3-235b-a22b

Cả hai nhà cung cấp cũng hỗ trợ bulk-scan.

Sử dụng Amazon Bedrock

Sử dụng --provider amazon-bedrock và ID mô hình Bedrock với scan hoặc bulk-scan. Sau khi AWS cấp quyền truy cập mô hình, các lượt quét sử dụng thông tin xác thực AWS mà không cần --auth, đăng nhập OpenAI hoặc API key OpenAI.

Daybreak Blue và Daybreak Red

Daybreak Blue và Daybreak Red yêu cầu được phê duyệt Trusted Access for Cyber. Để yêu cầu quyền truy cập, hãy gửi đơn đăng ký quyền truy cập dành cho doanh nghiệp hoặc liên hệ với nhóm phụ trách tài khoản OpenAI của bạn. Sau khi được phê duyệt, hãy làm việc với nhóm phụ trách tài khoản AWS để cấp quyền truy cập mô hình trên Amazon Bedrock.

Việc được phê duyệt Daybreak Red không bao gồm quyền truy cập GPT-5.6-Cyber. GPT-5.6-Cyber yêu cầu phê duyệt riêng của chính phủ Hoa Kỳ (USG). Hãy nhờ nhóm phụ trách tài khoản OpenAI của bạn yêu cầu phê duyệt bổ sung này trước khi cấp quyền truy cập GPT-5.6-Cyber trên Amazon Bedrock. Xem các yêu cầu về quyền truy cập Daybreak.

Để biết thông tin về khả năng cung cấp, hãy xem thẻ mô hình AWS cho Daybreak Blue và Daybreak Red.

Để quét bằng Daybreak Blue, hãy thay <aws-profile-name> bằng một hồ sơ AWS có quyền truy cập mô hình Daybreak Blue:

export AWS_PROFILE="<aws-profile-name>"
export AWS_REGION="us-east-2"
npx @openai/codex-security scan . \
  --provider amazon-bedrock \
  --model openai.gpt-daybreak-blue-5.6-sol --effort high

Để quét bằng Daybreak Red, hãy chọn một hồ sơ AWS có quyền truy cập GPT-5.6-Cyber. Hồ sơ này có thể khác với hồ sơ bạn dùng cho Daybreak Blue:

export AWS_PROFILE="<aws-profile-name>"
export AWS_REGION="us-east-2"
npx @openai/codex-security scan . \
  --provider amazon-bedrock \
  --model openai.gpt-5.6-cyber --effort high

Bạn cũng có thể xác thực bằng AWS_BEARER_TOKEN_BEDROCK hoặc chuỗi thông tin xác thực AWS tiêu chuẩn. Khóa truy cập tạm thời yêu cầu AWS_SESSION_TOKEN. Hãy thiết lập thông tin xác thực và AWS_REGION trong cùng shell hoặc tác vụ CI chạy quá trình quét.

Kết quả cục bộ và kiểm tra quyền truy cập

Báo cáo đã lưu cục bộ, scans show và export hoạt động mà không cần thông tin xác thực đám mây. Để tải các phát hiện lên Codex Security Cloud, bạn cần đăng nhập ChatGPT riêng và có quyền truy cập vào đích đến.

info và scan --dry-run không kiểm tra thông tin xác thực AWS hay quyền truy cập mô hình. Hãy chạy một lượt quét để kiểm tra quyền truy cập. Khi gặp lỗi xác thực AWS hoặc bị từ chối truy cập, hãy kiểm tra thông tin xác thực, khu vực và quyền truy cập mô hình của bạn.

Trạng thái phát hành Bedrock

@openai/codex-security@0.1.31 hỗ trợ quét qua Amazon Bedrock. Phiên bản này không cung cấp ước tính chi phí hoặc hỗ trợ --max-cost cho các ID mô hình Daybreak Blue và Daybreak Red ở trên.

Kiểm tra phiên bản gói đã cài đặt và phiên bản Codex đi kèm:

npx @openai/codex-security --version
npx @openai/codex-security info --json

Dùng npx @openai/codex-security scan --help để kiểm tra các tùy chọn có sẵn trong phiên bản bạn đã cài đặt.

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

Chọn một loại mục tiêu cho mỗi lần 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ế độ quét sâu hỗ trợ mục tiêu là kho lưu trữ và đường dẫn.

Các lần quét diff và cây làm việc yêu cầu đối số kho lưu trữ phải là thư mục gốc của Git worktree. Các ref được chọn phải tồn tại trong 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 đưa vào vùng chờ:

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

Thực hiện đánh giá sâu hơn đối với kho lưu trữ:

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

Cấu hình quét sâu

Sử dụng các tùy chọn này với --mode deep để kiểm soát số worker chạy đồng thời và thời gian chạy:

--subagents chấp nhận số 0 hoặc số nguyên dương. --max-time-hours chấp nhận một số dương không lớn hơn 96. Các tùy chọn còn lại yêu cầu số nguyên dương. Những tùy chọn này không dùng được cho quét tiêu chuẩn.

Ví dụ: dùng hai worker, cho phép tối đa mười lượt chạy và dừng thực thi worker sau 1,5 giờ:

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

Khi hết thời gian giới hạn, lượt quét dừng các worker chưa hoàn tất, giữ lại 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. Kiểm tra báo cáo để biết các khu vực đã được rà soát và công việc hoãn lại. Việc hết thời hạn không tự quyết định mã thoát; mã thoát phụ thuộc vào trạng thái thực thi và chính sách về mức độ nghiêm trọng.

Đặt giá trị mặc định lâu dài trong ~/.codex/codex-security/config.toml, hoặc trong $CODEX_HOME/codex-security/config.toml khi bạn đặt CODEX_HOME:

[deep_scan]
workers = 2
subagents = 0
stop_after_no_new = 3
max_discovery_runs = 10
max_time_hours = 1.5

Các tùy chọn dòng lệnh ghi đè những giá trị mặc định này. scan --workers kiểm soát các worker quét tiêu chuẩn độc lập trong một lần quét sâu; bulk-scan --workers kiểm soát các lần quét kho lưu trữ chạy đồng thời. Chỉ đặt stop_after_consecutive_errors trong tệp TOML; giá trị mặc định là 3.

Thêm 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 thư mục, từ chối đường dẫn đầu vào là liên kết, bỏ qua các mục thư mục là 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.

Thêm hướng dẫn quét

Để thêm chỉ dẫn quét, hãy cung cấp một tệp văn bản hoặc Markdown bằng --scan-prompt-file. Dùng --post-scan-prompt-file để chạy các chỉ dẫn tiếp nối 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 gặp lỗi:

npx @openai/codex-security scan . \
  --scan-prompt-file security-focus.md \
  --post-scan-prompt-file follow-up.md

Ví dụ: dùng lời nhắc quét để tập trung vào ranh giới ủy quyền và yêu cầu bước tiếp theo ghi một post-scan-summary.md mới trong thư mục quét. 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 tiếp theo không chạy sau khi hủy hoặc khi lần quét đạt giới hạn chi phí.

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

Sử dụng các tùy chọn này để giữ lại tệp kết quả, 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à con số ướ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 một chút. Nếu một lượt quét chuyên sâu chạm 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 có thể chốt kết quả hoàn tất và đưa ra cảnh báo ngân sách. CLI trả về 0, hoặc 1 nếu các phát hiện đạt ngưỡng mức độ nghiêm trọng đã cấu hình. Nếu không thể tạo ra kết quả hoàn tất hợp lệ, CLI trả về 2 và giữ lại mọi đầu ra hiện có trên đĩa.

Khi bạn bỏ qua --output-dir, kết quả được lưu lâu dài trong $CODEX_HOME/state/plugins/codex-security/scans/<repository>. CODEX_HOME mặc định là ~/.codex. Đặt CODEX_SECURITY_STATE_DIR để thay vào đó giữ kết quả trong $CODEX_SECURITY_STATE_DIR/scans/<repository>. Các thư mục này có thể chứa đoạn trích 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ần 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 tái sử dụng thư mục đầu ra:

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

Theo mặc định, các lần 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ộ, bao gồm tài liệu cơ sở tri thức, 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 thực thi

Sử dụng các tùy chọn môi trường thực thi 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 cần viết TOML, hãy chọn mô hình mà thông tin xác thực của bạn có thể truy cập. Nếu đăng nhập bằng ChatGPT, hãy kiểm tra tính khả dụng của GPT-6.1 Sol trước khi sử dụng các ví dụ này:

npx @openai/codex-security scan . --model gpt-6.1-sol --effort medium

Đặt 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-6.1-sol"'

codex-security install-hook

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

npx @openai/codex-security install-hook

Quy trình kiểm tra sẽ quét các thay đổi đã và chưa đưa vào vùng chờ trước mỗi commit, đồng thời chặn các phát hiện mức độ nghiêm trọng cao hoặc lỗi quét. Quy trình này tôn trọng core.hooksPath và không thay thế tập lệnh pre-commit hiện có. Hãy đặ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

Tìm và quét các kho lưu trữ GitHub, hoặc chạy lượt quét có thể tiếp tục từ một tệp CSV liệt kê 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 vùng chứa, 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}]
                                [--knowledge-base PATH]
                                [--scan-prompt-file FILE]
                                [--post-scan-prompt-file FILE]
                                [--max-attempts N] [--plugin-path PATH]
                                [--python PATH] [--codex KEY=VALUE]

Chạy npx @openai/codex-security bulk-scan không có đối số để chọn kho lưu trữ theo cách tương tác. Luồng 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, hãy sử dụng mô hình mà thông tin xác thực của bạn có thể truy cập. Xem tính khả dụng của GPT-6.1 Sol khi đăng nhập bằng ChatGPT :

npx @openai/codex-security bulk-scan --model gpt-6.1-sol --effort medium

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

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

CSV yêu cầu các cột id, repository và revision. Bản sửa đổi phải là hash commit đầy đủ. Các cột tùy chọn scope, mode và prompt cấu hình từng kho lưu trữ:

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

Dùng --knowledge-base PATH để chia sẻ tài liệu bảo mật cho mọi kho lưu trữ. Dùng --scan-prompt-file FILE để thêm chỉ dẫn quét dùng chung; cột prompt trong CSV thêm chỉ dẫn riêng cho từng kho lưu trữ sau chỉ dẫn dùng chung đó. --post-scan-prompt-file FILE chạy các chỉ dẫn tiếp nối sau mỗi lượt quét, kể cả lượt quét gặp lỗi. Các chỉ dẫn này không chạy sau khi hủy hoặc khi lượt quét chạm giới hạn chi phí.

--workers giới hạn số lượt quét kho lưu trữ đồ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 để thử lại khi có lỗi kho lưu trữ hoặc lỗi quét. Các lượt quét đã hoàn tất không được thử lại chỉ vì còn phần chưa được rà soát hoặc vi phạm chính sách về mức độ nghiêm trọng. Kết quả của chúng vẫn có thể truy cập.

Chạy lại cùng lệnh để tiếp tục từ thư mục đầu ra hiện có. CLI bỏ qua các lượt quét đã hoàn tất, kể cả các lượt quét còn phần chưa được rà soát.

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

codex-security scans

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

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

npx @openai/codex-security scans

Liệt kê các lần quét cho kho lưu trữ khác:

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

Tìm các lần 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ần quét

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

npx @openai/codex-security scans show SCAN_ID

Thêm --show-linked-findings để bao gồm liên kết phát hiện từ các lần quét trước.

Chạy lại lần quét đối với checkout hiện tại bằng cấu hình ban đầu:

npx @openai/codex-security scans rerun SCAN_ID

Việc chạy lại yêu cầu phiên bản plugin được lần quét ban đầu ghi nhận. Nếu phiên bản đã cài đặt khác, lệnh sẽ dừng thay vì chạy với plugin khác.

Kiểm tra nhật ký quét đã lưu

Đọc toàn bộ sự kiện phiên đã lưu cho một lần quét và các worker của nó. Những nhật ký này không được che thông tin nhạy cảm và có thể chứa mã nguồn hoặc thông tin xác thực, vì vậy hãy xem xét trước khi chia sẻ:

npx @openai/codex-security scans logs SCAN_ID

Thêm --json để nhận đầu ra có cấu trúc.

Ghép khớp và so sánh các phát hiện

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

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

Quá trình so sánh tự động ghép khớp các phát hiện có cùng nguyên nhân gốc và tái sử dụng các kết quả ghép đã lưu. Để lưu rõ ràng các kết quả ghép, hãy dùng scans match:

npx @openai/codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID

Một phát hiện có trạng thái chưa xác định khi đường dẫn của nó bị loại trừ hoặc việc đối sánh chưa chắc chắn. Nếu lượt quét sau không tìm thấy phát hiện đó trong phần mã đã quét, phát hiện có trạng thái không được ghi nhận. Chỉ phát hiện được đóng rõ ràng với lý do đã khắc phục mới có trạng thái đã giải quyết. Thêm --force vào match khi bạn cần tính toán lại kết quả đối sánh hiện có.

Để ghép khớp tất cả lần quét đã hoàn tất cho kho lưu trữ hiện tại, kể cả các lần quét từ 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 cấu hình. Việc ghép khớp và so sánh giúp theo dõi thay đổi; chúng không làm cho kết quả mang tính 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 đối với mã hiện tại.

codex-security findings

Liệt kê các phát hiện đang mở trong những lần quét của kho lưu trữ hiện tại:

npx @openai/codex-security findings list

Truyền đường dẫn kho lưu trữ để kiểm tra checkout khác:

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

Thêm --json để nhận đầu ra có cấu trúc. Danh sách xác định các phát hiện xuất hiện trong lần quét mới nhất và những phát hiện trước đó chưa được xác nhận trong lần quét đó.

Các phát hiện trước đó vẫn ở trạng thái mở cho đến khi được giải quyết hoặc bác bỏ. Việc chúng không xuất hiện trong lượt quét mới nhất không chứng minh rằng chúng đã được khắc phục.

Để 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ần 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ần quét trong tương lai. Mỗi lần 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 truy cập hiện tại. Quyết định trước đó không vô hiệu hóa một quy tắc, đường dẫn hoặc loại lỗ hổng.

codex-security export

Xuất CSV, JSON hoặc SARIF từ một lần quét đã hoàn tất và được niêm phong. Thao tác xuất xác thực các tệp kết quả quét trước khi ghi đầu ra và không tác động đến môi trường thực thi 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ần quét đã hoàn tất.

--source-root chỉ hoạt động với --export-format sarif. JSON bảo toà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ục bộ của workbench.

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. Tệp xuất có thể chứa đoạn trích 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ư bên ngoài 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 publish scan

Đăng mọi phát hiện từ một lần quét đã hoàn tất lên Linear:

usage: codex-security publish scan [SCAN_DIR] --to linear
                                   [--linear-team TEAM_ID]
                                   [--project PROJECT_ID]
                                   [--linear-api-key KEY]
                                   [--linear-assignee EMAIL_OR_USER_ID]
                                   [--dry-run] [--json]

SCAN_DIR phải chứa một lần quét đã hoàn tất và được niêm phong. Bỏ qua đối số này trong terminal tương tác để chọn một lần quét đã hoàn tất từ lịch sử quét cục bộ. Việc tạo issue cũng yêu cầu lần quét và các phát hiện của nó tồn tại trong lịch sử quét cục bộ. Chạy thử xác thực các tệp kết quả đã niêm phong mà không kiểm tra tính lưu trữ lâu dài này.

Mỗi lần gọi không phải chạy thử sẽ cố tạo một issue mới cho mọi phát hiện. Việc đăng lại cùng một lần quét sẽ không ghép khớp, cập nhật hoặc tái sử dụng issue hiện có. Nếu một số phát hiện thất bại, lệnh sẽ giữ lại các issue đã tạo thành công và trả về mã thoát 2. Với --json, hãy xem xét kết quả created và failed trước khi thử lại để tránh trùng lặp.

Xem trước payload của issue trước khi đăng:

npx @openai/codex-security publish scan /path/to/completed-scan \
  --to linear \
  --linear-team TEAM_ID \
  --dry-run \
  --json

Đăng bằng ứng dụng Linear đã kết nối

Khi không có Linear API key, lệnh sẽ khởi động Codex bằng cấu hình hiện có và ứng dụng Linear đã kết nối của bạn. Hãy đăng nhập và kết nối Linear với tài khoản Codex trước khi đăng:

npx @openai/codex-security login
npx @openai/codex-security publish scan /path/to/completed-scan \
  --to linear \
  --linear-team TEAM_ID \
  --project PROJECT_ID

Đăng bằng Linear API key

Việc cung cấp --linear-api-key hoặc CODEX_SECURITY_LINEAR_API_KEY sẽ đăng trực tiếp qua Linear API và không khởi động Codex. Khi đăng trực tiếp, issue sẽ không được gán trừ khi bạn chọn người được giao:

export CODEX_SECURITY_LINEAR_API_KEY=YOUR_LINEAR_PERSONAL_API_KEY
npx @openai/codex-security publish scan /path/to/completed-scan \
  --to linear \
  --linear-team TEAM_ID \
  --linear-assignee teammate@example.com

Giá trị dòng lệnh ghi đè biến môi trường tương ứng. Đối với API key, hãy ưu tiên CODEX_SECURITY_LINEAR_API_KEY hơn --linear-api-key vì đối số dòng lệnh có thể xuất hiện trong lịch sử shell và danh sách tiến trình.

codex-security validate và codex-security patch

Kiểm tra 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 Skill 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ố vị trí chấp nhận văn bản trực tiếp hoặc đường dẫn tệp. Các đầu vào này sử dụng thư mục hiện tại. Sử dụng validate để kiểm tra lại một phát hiện sau khi sửa hoặc khi lần quét sau không còn báo cáo phát hiện đó. Chỉ so sánh các lần quét không chứng minh được rằng bản sửa lỗi đã có hiệu quả.

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

Vá các phát hiện sau khi quét

Sử dụng scan --patch để sửa các phát hiện sau một lần quét hoàn chỉnh. Tính năng này yêu cầu @openai/codex-security 0.1.15 trở lên. Ngưỡng mức độ nghiêm trọng mặc định là low. Lệnh này chọn các phát hiện mức cao và nghiêm trọng:

npx @openai/codex-security scan . --patch --patch-severity high --json

Các phát hiện đã được xác minh và đã sửa không kích hoạt --fail-on-severity.

Vá các phát hiện đã lưu

Truyền ID phát hiện hoặc ID lần xuất hiện để vá kho lưu trữ ban đầu của phát hiện đó, hoặc chọn các phát hiện từ một lần quét đã lưu:

npx @openai/codex-security patch OCCURRENCE_ID
npx @openai/codex-security patch --scan SCAN_ID --severity high --json
npx @openai/codex-security patch --scan latest --severity medium

--scan latest chọn lần quét đã hoàn tất gần nhất cho kho lưu trữ hiện tại. Các lệnh phát hiện đã lưu hỗ trợ --json; văn bản trực tiếp và đầu vào tệp thì không.

Thêm --create-pr để chỉ commit các tệp vá đã xác minh và mở pull request bằng GitHub CLI:

npx @openai/codex-security patch --scan SCAN_ID --severity high --create-pr

Nếu thao tác push hoặc pull request thất bại, hãy chạy lệnh patch --resume-pr BRANCH được in ra từ cùng kho lưu trữ để thử lại.

Vá các issue Linear

Đặt CODEX_SECURITY_LINEAR_API_KEY hoặc LINEAR_API_KEY cho API key cá nhân, hoặc LINEAR_ACCESS_TOKEN cho token OAuth. Ưu tiên dùng biến môi trường thay vì --linear-api-key KEY để không lưu key trong lịch sử shell.

Nhập issue bằng ID hoặc URL. Lặp lại --linear-issue để chọn nhiều hơn một issue:

npx @openai/codex-security patch --linear-issue SEC-123 --linear-issue SEC-124

Sử dụng --linear-project để chọn các issue đang mở của một project. Thêm --linear-filter để thu hẹp lựa chọn:

npx @openai/codex-security patch --linear-project "Security backlog" \
  --linear-filter '{"labels":{"name":{"eq":"security"}}}'

CLI loại trừ các issue đã hoàn tất và đã hủy, trừ khi bộ lọc đặt state. CLI không thay đổi các issue Linear.

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 phiên đăng nhập hiện tại:

npx @openai/codex-security login status

Xóa phiên đă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 chỉ đọc của SDK và plugin đi kèm:

npx @openai/codex-security info --json

Khi bạn cung cấp CLI dưới dạng MCP server, info là lệnh duy nhất khả dụng. Việc quét, xuất, đăng, đă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ần quét gửi tiến trình, bản tóm tắt hoàn tất và lỗi tới stderr mà không ghi kết quả quét đầy đủ 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 tới stdout.

Terminal tương tác hiển thị bảng điều khiển trực tiếp với giai đoạn quét hiện tại, các tệp đã xem xét, hoạt động, mức sử dụng token và chi phí ước tính. CI và đầu ra được chuyển hướng sử dụng tiến trình dạng văn bản thuần. Thêm --headless để dùng tiến trình dạng văn bản thuần trong terminal tương tác:

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

Bảng điều khiển cũng hiển thị chi tiết phiên trực tiếp. Những chi tiết này không được che thông tin nhạy cảm và có thể chứa mã nguồn hoặc thông tin xác thực. Hãy xem xét trước khi chia sẻ.

Chẩn đoán chi tiết

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

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

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

Tóm tắt hoàn tất

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

  REPORT    /path/to/scan/report.md

  FINDINGS  4 (3 confirmed this scan; 1 previously found; 1 critical, 2 high, 1 informational)
  ELAPSED   1s
  TOKENS    1,250 input, 200 cached, 30 output
  RESULTS   /path/to/scan

Các phát hiện cung cấp 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 từ lần quét hiện tại, không phải các phát hiện trước đó hiển thị trong tổng số của kho lưu trữ.

Đầ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
repositoryFindings
findings
coverage
scanDir
threadId
reportPath
artifactsDir
sarifPath
cost
turn
  id
  status
  durationMs
  finalResponse
  usage

Khi vá lỗi, đầu ra JSON cũng bao gồm kết quả vá và mọi pull request đã tạo.

Tiến độ, bản tóm tắt hoàn tất, thông báo lưu trữ và lỗi vẫn được ghi ra stderr. Lượt quét hoàn tất vẫn in toàn bộ kết quả JSON khi chính sách về mức độ nghiêm trọng trả về mã thoát 1.

Tệp kết quả quét

Lượt quét hoàn tất lưu báo cáo dễ đọc cùng các tệp đầu ra có cấu trúc. Tệp kê khai đã chốt ghi lại giá trị băm của các tệp đầu ra để người đọc sau này có thể kiểm tra rằng các tệp đó chưa bị thay đổi:

<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:

Đọc scan.status trong scan-manifest.json để biết trạng thái thực thi: completed, failed, canceled hoặc interrupted. Các kết quả mới không bao gồm coverage.completeness. Xem các bề mặt hoãn rà soát, phần loại trừ được nêu rõ và câu hỏi còn bỏ ngỏ trong coverage.json để hiểu bản quét đã rà soát những gì.

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

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

Các khoảng trống trong phạm vi rà soát không làm thay đổi mã thoát của bản quét đã hoàn tất hay bỏ qua chính sách về mức độ nghiêm trọng của bản quét. Mã thoát 0 không có nghĩa là mọi tệp đã được rà soát. Khi bạn yêu cầu đầu ra có cấu trúc, các bản quét đã hoàn tất và các lần xuất bản hoàn tất một phần vẫn ghi kết quả hiện có vào stdout. CLI in ra vị trí của mọi đầu ra chưa hoàn chỉnh sau khi bị ngắt hoặc gặp lỗi thời gian chạy.

Quyền quét cục bộ

Các lần quét bằng CLI và SDK chạy với quyền hệ điều hành cục bộ của bạn. Mỗi lần quét sử dụng hồ sơ hệ thống tệp codex_security_scan và đặt approvalPolicy thành "never". Hồ sơ này cho phép đọc hệ thống tệp cục bộ và ghi vào các thư mục gốc của không gian làm việc cũng như thư mục trạng thái quét đã chọn. Quá trình quét không dừng để yêu cầu phê duyệt tương tác.

Các thiết lập được cung cấp qua --codex của CLI hoặc codexOverrides của SDK, bao gồm approval_policy, sandbox_mode và quyền hệ thống tệp, không thể thay thế hoặc hạn chế các biện pháp kiểm soát quét này. Các hạn chế của máy chủ và mạng vẫn được áp dụng.

Các tiến trình quét và workbench có thể kế thừa môi trường của bạn, bao gồm cả các token API và thông tin xác thực đám mây không liên quan. Hãy xóa các thông tin xác thực không liên quan trước khi bắt đầu quét.

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 phiên đăng nhập Codex dựa trên tệp hiện có. Với OpenRouter hoặc Fireworks, hãy đặt API key của nhà cung cấp và chọn một mô hình. Với Amazon Bedrock, hãy dùng Bedrock API key hoặc chuỗi thông tin xác thực AWS tiêu chuẩn.

Để tìm hiểu cách chọn thông tin xác thực, hãy xem Chọn phương thức xác thực khi quét.

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

CLI yêu cầu Node.js 24 hoặc 26, hoặc Node.js 22 từ phiên bản 22.13.0 trở lên. 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. Python 3.10 còn yêu cầu tomli. Sử dụng --python với scan, bulk-scan hoặc export, hoặc đặt PYTHON cho bất kỳ lệnh nào chạy dựa trên Python.

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 SDK TypeScript.

Bí danh văn bản thuần

• --output FILE|-