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ạo tác đượ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 máy chủ MCP:

npx @openai/codex-security mcp add

Đồng bộ kỹ năng 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

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 vùng chứa hoặc chuỗi thông tin xác thực AWS mặc định. Các lần quét Bedrock dùng thông tin xác thực AWS thay cho --auth, phiên đă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ầ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 stage:

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, quá trình quét sẽ 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. Nếu không worker nào hoàn tất việc xem xét mã nguồn, lần quét sẽ ghi nhận phạm vi bao phủ một phần và trả về mã thoát 2.

Đặ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 hướng dẫn quét, hãy cung cấp tệp văn bản hoặc Markdown bằng --scan-prompt-file. Sử dụng --post-scan-prompt-file để chạy các hướng dẫn tiếp theo 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 có 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ạ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í nhỉnh hơn 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ẽ niêm phong kết quả hiện có, đánh dấu phạm vi bao phủ là partial và trả về mã thoát 2. Nếu không, CLI trả về 2 và để lại mọi đầu ra một phần 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 runtime

Sử dụng các tùy chọn runtime 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 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 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 stage 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

Khám phá và quét các kho lưu trữ GitHub hoặc chạy một lần quét có thể tiếp tục từ 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 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:

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

Sử dụng --knowledge-base PATH để chia sẻ tài liệu bảo mật cho mọi kho lưu trữ. Sử dụng --scan-prompt-file FILE để thêm hướng dẫn quét dùng chung; cột CSV prompt sẽ thêm hướng dẫn riêng cho từng kho lưu trữ sau lời nhắc dùng chung đó. --post-scan-prompt-file FILE chạy hướng dẫn tiếp theo sau mỗi lần quét, kể cả các lần quét có phạm vi bao phủ không đầy đủ hoặc có lỗi. Tùy chọn này không chạy sau khi hủy hoặc khi lần quét đạt giới hạn chi phí.

--workers giới hạn số lần 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 lỗi kho lưu trữ hoặc lỗi quét. Các lần quét đã hoàn tất nhưng có phạm vi 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 trả về mã thoát 2.

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ần quét đã hoàn tất, kể cả những lần có phạm vi bao phủ không đầy đủ.

Đố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 kết quả có định dạng máy chứa đầy đủ thông tin.

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

So sánh hai lần quét để tìm các phát hiện mới, còn tồn tại, xuất hiện lại, đã giải quyết và 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 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 coi là không xác định khi lần 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 lại một kết quả ghép 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 đó.

Lưu ý rằng 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 loại bỏ (việc không xuất hiện trong lần quét mới nhất không được xem là bằng chứng rằng vấn đề đã đượ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ạo tác quét trước khi ghi đầu ra và không tác động đến runtime 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ạo tác đã 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 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ố 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 máy chủ MCP, 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

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

  REPORT    /path/to/scan/report.md

  FINDINGS  4 (3 confirmed this scan; 1 previously found; 1 critical, 2 high, 1 informational)
  COVERAGE  complete
  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 trình, bản tóm tắt hoàn tất, thông báo lưu trữ và lỗi vẫn ở stderr. Một lần 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ần quét đã hoàn tất giữ 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ần quét ghi nhận phạm vi bao phủ hoàn chỉnh cho phạm vi đã chọn.
• partial: Lần quét ghi nhận công việc trì hoãn hoặc các giới hạn phạm vi bao phủ khác.
• unknown: Lần 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ị trì hoãn, nội dung loại trừ rõ ràng và câu hỏi mở trước khi 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ần 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ần quét đã hoàn tất và các lượt đăng một phần 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ị gián đoạn hoặc gặp lỗi runtime.

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 workspace 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.

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ả API token và thông tin xác thực đám mây không liên quan. Chỉ quét các kho lưu trữ mà bạn tin cậy và được phép đánh giá, đồng thời chỉ cung cấp thông tin xác thực mà lần quét yêu cầu.

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 22 (22.13.0 trở lên), 24 hoặc 26. Các tác vụ quét, quét hàng loạt, xuất, lịch sử quét và phát hiện đã lưu 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 với scan, bulk-scan hoặc export, hoặc đặt PYTHON cho mọi lệnh 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|-