Codex Security CLI 참조

이 참조 문서에서 지원되는 codex-security 명령, 플래그, 출력 형식 및 종료 동작을 확인하세요. 안내에 따라 첫 스캔을 실행하려면 CLI 빠른 시작부터 살펴보세요.

npx @openai/codex-security로 CLI를 실행합니다.

명령 개요

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

CLI는 다음 명령을 제공합니다.

CLI는 다음 통합 명령도 제공합니다.

사용 가능한 모든 명령을 나열합니다.

npx @openai/codex-security --help

명령에 --help를 추가하여 인수와 옵션을 확인합니다.

npx @openai/codex-security scan --help

codex-security --version는 설치된 버전을 출력하고 종료합니다. codex-security info --json는 SDK 및 번들 플러그인 버전을 보고합니다. 어느 명령에도 Python은 필요하지 않습니다.

명령 검색 및 에이전트 연결

에이전트가 읽을 수 있는 명령 매니페스트를 출력합니다.

npx @openai/codex-security --llms

스캔 인수 스키마를 JSON으로 검사합니다.

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

Bash용 셸 자동 완성을 생성합니다.

npx @openai/codex-security completions bash

해당 셸을 사용하려면 bash를 zsh 또는 fish로 바꾸세요.

스캔 결과는 --format toon|json|yaml|jsonl 및 --full-output을 지원합니다. 이 프레임워크 수준의 --format는 완료된 스캔에서 내보내는 아티팩트의 형식을 선택하는 --export-format와 별개입니다. 전역 명령 도움말에는 md도 나열되지만 스캔 결과는 Markdown 출력을 지원하지 않습니다.

CLI를 MCP 서버로 등록합니다.

npx @openai/codex-security mcp add

Codex Security 스킬을 에이전트에 동기화합니다.

npx @openai/codex-security skills add

MCP는 읽기 전용 info 메타데이터 명령만 노출합니다. 스캔, 내보내기, 인증, 검증 및 패치는 계속 CLI에서만 사용할 수 있습니다.

codex-security scan

저장소, 선택한 경로, 커밋된 변경 사항 또는 작업 트리를 대상으로 스캔을 실행합니다.

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의 기본값은 현재 디렉터리입니다.

스캔 인증 선택

기본값인 --auth auto를 사용하면 자격 증명이 자동으로 선택됩니다. ChatGPT 로그인과 OPENAI_API_KEY 또는 CODEX_API_KEY를 모두 사용할 수 있으면, 텍스트를 출력하는 대화형 스캔에서 사용할 자격 증명을 묻습니다. CI, JSON 및 JSONL 스캔과 대화형 터미널이 없는 기타 스캔은 환경 API key를 사용합니다. 드라이런은 자격 증명을 묻거나 불러오지 않습니다.

저장된 자격 증명을 사용하려면 --auth chatgpt을 전달합니다.

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

환경 API key를 사용하려면 --auth api-key를 전달합니다.

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

저장된 자격 증명을 자동 선택의 기본값으로 지정하려면 unset OPENAI_API_KEY CODEX_API_KEY을 실행합니다.

OpenRouter 또는 Fireworks 사용

API key와 명시적인 모델을 사용하여 OpenRouter를 선택합니다.

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

API key와 명시적인 모델을 사용하여 Fireworks를 선택합니다.

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

두 공급자 모두 bulk-scan도 지원합니다.

Amazon Bedrock 사용

--provider amazon-bedrock로 Amazon Bedrock을 선택하고 --model으로 명시적인 Bedrock 모델을 지정합니다.

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

AWS_REGION을 설정하고 AWS_BEARER_TOKEN_BEDROCK, 표준 AWS 액세스 키, AWS 프로필, 웹 자격 증명, 컨테이너 자격 증명 또는 기본 AWS 자격 증명 체인으로 인증합니다. Bedrock 스캔은 --auth, ChatGPT 로그인 또는 OpenAI API key 대신 AWS 자격 증명을 사용합니다. scan 및 bulk-scan 모두 --provider를 지원합니다.

스캔 대상 선택

각 스캔에서 하나의 대상 유형을 선택합니다.

--path, --diff 및 --working-tree는 함께 사용할 수 없습니다. --head에는 --diff이 필요하며 --base에는 --working-tree이 필요합니다. Deep 모드는 저장소 및 경로 대상을 지원합니다.

Diff 및 작업 트리 스캔을 실행하려면 저장소 인수가 Git 작업 트리 루트여야 합니다. 선택한 ref는 해당 체크아웃에 존재해야 합니다.

전체 저장소를 스캔합니다.

npx @openai/codex-security scan .

선택한 경로를 스캔합니다.

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

커밋된 변경 사항을 스캔합니다.

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

스테이징된 변경 사항과 스테이징되지 않은 변경 사항을 스캔합니다.

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

저장소를 더 심층적으로 검토합니다.

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

Deep 스캔 구성

--mode deep에 다음 옵션을 사용하여 작업자 동시 실행 수와 런타임을 제어합니다.

--subagents은 0 또는 양의 정수를 허용합니다. --max-time-hours은 96 이하의 양수를 허용합니다. 나머지 옵션에는 양의 정수가 필요합니다. 표준 스캔에서는 이러한 옵션을 사용할 수 없습니다.

예를 들어 작업자 두 개를 사용하고 최대 10회 실행을 허용하며 1.5시간 후 작업자 실행을 중지하려면 다음과 같이 합니다.

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

시간 제한이 만료되면 스캔은 완료되지 않은 작업자를 중지하고 완료된 스캔 결과를 유지한 후 최종 보고서로 집계합니다. 소스 검토를 완료한 작업자가 없으면 스캔은 부분적 검사 범위를 기록하고 종료 코드 2를 반환합니다.

~/.codex/codex-security/config.toml 또는 CODEX_HOME를 설정한 경우 $CODEX_HOME/codex-security/config.toml에 영구 기본값을 설정합니다.

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

명령줄 옵션은 이러한 기본값보다 우선합니다. scan --workers은 하나의 Deep 스캔에서 독립 표준 스캔 작업자 수를 제어하고, bulk-scan --workers는 동시에 실행되는 저장소 스캔 수를 제어합니다. stop_after_consecutive_errors는 TOML 파일에서만 설정하세요. 기본값은 3입니다.

보안 컨텍스트 추가

--knowledge-base PATH을 사용하여 아키텍처 문서, 위협 모델 또는 보안 정책을 제공합니다. 더 많은 파일이나 디렉터리를 추가하려면 옵션을 반복합니다.

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

지원되는 문서에는 .md, .markdown, .txt, .pdf 및 .docx 파일이 포함됩니다. CLI는 디렉터리를 재귀적으로 검색하고 연결된 입력 경로를 거부하며, 연결된 디렉터리 항목을 건너뛰고 추출한 문서 콘텐츠를 저장된 스캔 결과 외부에 보관합니다.

스캔 지침 추가

스캔 지침을 추가하려면 텍스트 또는 Markdown 파일을 --scan-prompt-file으로 제공합니다. --post-scan-prompt-file를 사용하면 성공한 스캔과 검사 범위가 불완전하거나 오류가 있는 스캔 후 동일한 인증 세션에서 후속 지침을 실행할 수 있습니다.

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

예를 들어 스캔 프롬프트로 권한 부여 경계에 집중하고 후속 작업에 스캔 디렉터리의 새 post-scan-summary.md을 작성하도록 요청할 수 있습니다. 후속 작업이 실패하면 CLI는 경고를 보고하고 완료된 스캔을 유지합니다. 취소된 후 또는 스캔이 비용 한도에 도달한 경우에는 후속 작업이 실행되지 않습니다.

출력 및 정책 옵션 설정

다음 옵션을 사용하여 아티팩트를 유지하고 이전 결과를 보존하거나 기계 판독 가능한 결과를 생성합니다.

비용 한도는 추정치일 뿐 엄격한 지출 상한이 아닙니다. 이미 진행 중인 요청은 한도를 약간 초과하여 완료될 수 있습니다. Codex Security가 완료된 작업자 결과를 집계한 후 Deep 스캔이 한도에 도달하면 CLI는 사용 가능한 결과를 봉인하고, 검사 범위를 partial로 표시한 후 종료 코드 2을 반환합니다. 그렇지 않으면 2을 반환하고 사용 가능한 부분 출력을 디스크에 남깁니다.

--output-dir를 생략하면 결과는 $CODEX_HOME/state/plugins/codex-security/scans/<repository> 아래에 영구 보관됩니다. CODEX_HOME의 기본값은 ~/.codex입니다. 결과를 대신 $CODEX_SECURITY_STATE_DIR/scans/<repository> 아래에 보관하려면 CODEX_SECURITY_STATE_DIR을 설정합니다. 이러한 디렉터리에는 소스 발췌문과 취약점 세부 정보가 포함될 수 있으므로 권한과 보존 기간을 적절히 관리하세요.

워크벤치는 스캔 기록을 $CODEX_HOME/state/plugins/codex-security/workbench.sqlite3에 보관합니다. CODEX_SECURITY_STATE_DIR을 설정하면 워크벤치 데이터베이스도 이동합니다.

출력 디렉터리는 스캔한 디렉터리와 이를 포함하는 모든 Git 작업 트리의 외부에 있어야 합니다. 스캔은 --archive-existing을 사용하여 기존 결과 디렉터리를 교체할 수 있습니다.

출력 디렉터리를 재사용하기 전에 이전 결과를 보존하려면 다음과 같이 합니다.

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

스캔은 기본적으로 보고만 수행합니다. CI에서 심각도 정책을 평가하려면 --fail-on-severity을 추가합니다.

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

드라이런은 자격 증명을 불러오거나 Codex를 시작하거나 플러그인의 Python 인터프리터를 조사하지 않고 지식 베이스 문서를 포함한 로컬 입력을 검사합니다.

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

런타임 구성

명시적인 모델, 인터프리터, 플러그인 또는 Codex 구성 값이 필요할 때 런타임 옵션을 사용합니다.

TOML을 작성하지 않고 다른 모델과 추론 수준을 선택하려면 다음과 같이 합니다.

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

--codex을 통해 전달되는 문자열 값에 따옴표를 추가하여 TOML 파서가 문자열을 받도록 합니다.

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

codex-security install-hook

현재 저장소에 Git pre-commit 보안 검사를 설치합니다.

npx @openai/codex-security install-hook

검사는 각 커밋 전에 스테이징된 변경 사항과 스테이징되지 않은 변경 사항을 스캔하고 심각도가 높은 발견 항목이나 스캔 오류가 있으면 차단합니다. core.hooksPath를 준수하며 기존 pre-commit 스크립트를 교체하지 않습니다. 필요한 경우 다른 심각도 임계값을 설정합니다.

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

codex-security bulk-scan

GitHub 저장소를 검색하여 스캔하거나 저장소 CSV에서 재개 가능한 스캔을 실행합니다.

GitHub 검색, CSV 인벤토리, 캠페인 결과 및 컨테이너화된 스캔에 대한 전체 안내는 일괄 보안 스캔 실행을 참조하세요.

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]

인수 없이 npx @openai/codex-security bulk-scan를 실행하여 저장소를 대화형으로 선택합니다. 이 흐름에는 GitHub CLI 로그인이 필요합니다.

대화형 검색 중 모델과 추론 수준을 선택하려면 다음과 같이 합니다.

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

준비된 저장소 목록의 경우 CSV와 --output-dir를 제공합니다.

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

CSV에는 id, repository 및 revision 열이 필요합니다. 리비전은 전체 커밋 해시여야 합니다. 선택적 scope, mode 및 prompt 열로 개별 저장소를 구성합니다.

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

--knowledge-base PATH를 사용하여 모든 저장소에서 보안 문서를 공유합니다. --scan-prompt-file FILE을 사용하여 공유 스캔 지침을 추가합니다. CSV의 prompt 열은 이 공유 프롬프트 뒤에 저장소별 지침을 추가합니다. --post-scan-prompt-file FILE는 검사 범위가 불완전하거나 오류가 있는 스캔을 포함하여 각 스캔 후 후속 지침을 실행합니다. 취소된 후 또는 스캔이 비용 한도에 도달한 경우에는 실행되지 않습니다.

--workers은 동시에 실행되는 저장소 스캔 수를 제한하며 기본값은 4입니다. --mode의 기본값은 standard이며 --max-attempts의 기본값은 1입니다. 저장소 또는 스캔 오류를 재시도하려면 --max-attempts를 설정합니다. 검사 범위가 불완전한 완료된 스캔은 재시도되지 않습니다. 결과는 계속 사용할 수 있으며 명령은 종료 코드 2을 반환합니다.

기존 출력 디렉터리에서 재개하려면 같은 명령을 다시 실행합니다. CLI는 검사 범위가 불완전한 스캔을 포함하여 완료된 스캔을 건너뜁니다.

컨테이너화된 캠페인은 Docker에서 일괄 스캔 실행을 참조하세요.

codex-security scans

저장된 스캔 찾기

현재 디렉터리에 저장된 스캔을 나열합니다.

npx @openai/codex-security scans

다른 저장소의 스캔을 나열합니다.

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

특정 출력 디렉터리 아래에 저장된 스캔을 찾습니다.

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

스캔 검사 또는 반복

저장된 스캔의 결과와 구성을 표시합니다.

npx @openai/codex-security scans show SCAN_ID

이전 스캔의 발견 항목 링크를 포함하려면 --show-linked-findings를 추가합니다.

원래 구성을 사용하여 현재 체크아웃을 대상으로 스캔을 다시 실행합니다.

npx @openai/codex-security scans rerun SCAN_ID

재실행에는 원래 스캔이 기록한 플러그인 버전이 필요합니다. 설치된 버전이 다르면 명령은 다른 플러그인으로 실행하는 대신 중지됩니다.

저장된 스캔 로그 검사

스캔과 해당 작업자의 저장된 전체 세션 이벤트를 읽습니다. 이러한 로그는 수정되지 않으며 소스 코드나 자격 증명을 포함할 수 있으므로 공유하기 전에 검토하세요.

npx @openai/codex-security scans logs SCAN_ID

전체 정보를 포함하는 기계 형식의 결과를 얻으려면 --json을 추가합니다.

발견 항목 매칭 및 비교

두 스캔을 비교하여 새로 발생하거나 지속되거나 다시 발생하거나 해결되거나 알 수 없는 발견 항목을 찾습니다.

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

비교 시 동일한 근본 원인을 공유하는 발견 항목을 자동으로 매칭하고 저장된 매칭을 재사용합니다. 매칭을 명시적으로 저장하려면 scans match을 사용합니다.

npx @openai/codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID

이후 스캔의 검사 범위가 불완전하거나 발견 항목의 원래 위치를 검사하지 않으면 해당 발견 항목은 알 수 없음으로 분류됩니다. 기존 매칭을 다시 계산해야 하는 경우 match에 --force을 추가합니다.

다른 체크아웃의 스캔을 포함하여 현재 저장소의 완료된 모든 스캔을 매칭하려면 다음과 같이 합니다.

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

동일한 구성을 다시 실행하더라도 스캔 결과는 달라질 수 있습니다. 매칭과 비교는 변경 사항을 추적할 뿐 결과를 결정적으로 만들거나 취약점이 더 이상 존재하지 않음을 증명하지 않습니다. 보안에 중요한 발견 항목을 현재 코드에서 다시 검사하려면 validate을 사용합니다.

codex-security findings

현재 저장소의 여러 스캔에서 열린 발견 항목을 나열합니다.

npx @openai/codex-security findings list

다른 체크아웃을 검사하려면 저장소 경로를 전달합니다.

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

구조화된 출력을 사용하려면 --json를 추가합니다. 목록에서는 최신 스캔에서 확인된 발견 항목과 해당 스캔에서 확인되지 않은 이전 발견 항목을 식별합니다.

이전 발견 항목은 해결되거나 기각될 때까지 열린 상태로 유지됩니다(최신 스캔에 없다는 사실을 수정되었다는 증거로 해석하지 않습니다).

검토한 발견 항목을 오탐으로 기록하려면 다음과 같이 합니다.

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

저장된 스캔을 검사하여 발견 항목 발생 건을 식별합니다.

npx @openai/codex-security scans show SCAN_ID

오탐에 대한 구체적인 설명을 기록합니다.

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

이유는 비워 둘 수 없습니다. Codex Security는 저장소에 결정을 저장하고 향후 스캔에 컨텍스트로 제공합니다. 각 스캔은 현재 소스, 제어 및 도달 가능성을 독립적으로 다시 검사합니다. 이전 결정은 규칙, 경로 또는 취약점 클래스를 억제하지 않습니다.

codex-security export

완료되고 봉인된 스캔에서 CSV, JSON 또는 SARIF를 내보냅니다. 내보내기는 출력을 기록하기 전에 스캔 아티팩트를 검증하며 Codex 런타임과 자격 증명을 건드리지 않습니다.

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

scan_dir는 완료된 스캔 디렉터리입니다.

--source-root은 --export-format sarif에서만 작동합니다. JSON은 봉인된 발견 항목 문서를 보존합니다. CSV에는 이식 가능한 발견 항목 열이 포함되며 로컬 워크벤치 분류 상태는 포함되지 않습니다.

--output가 없으면 CLI는 현재 작업 디렉터리에서 SARIF를 results.sarif에, JSON을 findings.json에, CSV를 findings.csv에 기록합니다. 내보내기에는 소스 발췌문과 취약점 세부 정보가 포함될 수 있습니다. 저장소 외부에서 명령을 실행하거나 스캔한 체크아웃 외부의 비공개 경로를 --output으로 전달하세요.

SARIF를 파일에 기록합니다.

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

SARIF를 stdout에 기록합니다.

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

발견 항목을 JSON으로 내보냅니다.

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

발견 항목을 CSV로 내보냅니다.

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

codex-security publish scan

완료된 스캔의 모든 발견 항목을 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에는 완료되고 봉인된 스캔이 있어야 합니다. 로컬 스캔 기록에서 완료된 스캔을 선택하려면 대화형 터미널에서 이를 생략합니다. 이슈를 생성하려면 스캔과 해당 발견 항목이 로컬 스캔 기록에도 있어야 합니다. 드라이런은 이 영속성 검사 없이 봉인된 아티팩트를 검증합니다.

드라이런이 아닌 각 호출은 모든 발견 항목에 대해 새 이슈 생성을 시도합니다. 동일한 스캔을 다시 게시해도 기존 이슈를 매칭하거나 업데이트하거나 재사용하지 않습니다. 일부 발견 항목이 실패하면 명령은 성공적으로 생성된 이슈를 보존하고 종료 코드 2을 반환합니다. --json를 사용하는 경우 중복을 방지할 수 있도록 재시도 전에 created 및 failed 결과를 검토하세요.

게시하기 전에 이슈 페이로드를 미리 봅니다.

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

연결된 Linear 앱으로 게시

Linear API key가 없으면 명령은 기존 구성과 연결된 Linear 앱을 사용하여 Codex를 시작합니다. 게시하기 전에 로그인하고 Linear를 Codex 계정에 연결하세요.

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

Linear API key로 게시

--linear-api-key 또는 CODEX_SECURITY_LINEAR_API_KEY을 제공하면 Linear API를 통해 직접 게시하고 Codex를 시작하지 않습니다. 직접 게시에서는 담당자를 선택하지 않으면 이슈가 할당되지 않은 상태로 유지됩니다.

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

명령줄 값은 이에 대응하는 환경 변수보다 우선합니다. API key의 경우 명령줄 인수가 셸 기록과 프로세스 목록에 나타날 수 있으므로 --linear-api-key보다 CODEX_SECURITY_LINEAR_API_KEY을 사용하는 것이 좋습니다.

codex-security validate 및 codex-security patch

발견 항목 후보가 유효한지 검사합니다.

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

번들 수정 스킬로 수정 사항을 생성합니다.

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

각 위치 인수에는 리터럴 텍스트 또는 파일 경로를 사용할 수 있습니다. 이러한 입력은 현재 디렉터리를 사용합니다. 수정 후 또는 이후 스캔에서 더 이상 발견 항목을 보고하지 않을 때 발견 항목을 다시 검사하려면 validate을 사용합니다. 스캔 비교만으로는 수정이 적용되었음을 증명할 수 없습니다.

두 명령 중 하나에서 추론 수준을 선택하려면 --effort를 사용합니다.

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

스캔 후 발견 항목 패치

완료된 스캔 후 발견 항목을 수정하려면 scan --patch을 사용합니다. 이 기능에는 @openai/codex-security 0.1.15 이상이 필요합니다. 기본 심각도 임계값은 low입니다. 이 명령은 심각도가 높음 및 치명적인 발견 항목을 선택합니다.

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

검증되었거나 이미 수정된 발견 항목은 --fail-on-severity을 트리거하지 않습니다.

저장된 발견 항목 패치

발견 항목 또는 발생 건 ID를 전달하여 원래 저장소를 패치하거나 저장된 스캔에서 발견 항목을 선택합니다.

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은 현재 저장소에서 완료된 최신 스캔을 선택합니다. 저장된 발견 항목 명령은 --json을 지원하지만 리터럴 텍스트 및 파일 입력은 지원하지 않습니다.

검증된 패치 파일만 커밋하고 GitHub CLI로 pull request를 열려면 --create-pr를 추가합니다.

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

푸시 또는 pull request가 실패하면 동일한 저장소에서 출력된 patch --resume-pr BRANCH 명령을 실행하여 다시 시도하세요.

Linear 이슈 패치

개인 API key에는 CODEX_SECURITY_LINEAR_API_KEY 또는 LINEAR_API_KEY를 설정하고, OAuth 토큰에는 LINEAR_ACCESS_TOKEN을 설정합니다. 키가 셸 기록에 남지 않도록 --linear-api-key KEY보다 환경 변수를 사용하는 것이 좋습니다.

ID 또는 URL로 이슈를 가져옵니다. 둘 이상의 이슈를 선택하려면 --linear-issue을 반복합니다.

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

프로젝트의 열린 이슈를 선택하려면 --linear-project을 사용합니다. 선택 범위를 좁히려면 --linear-filter을 추가합니다.

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

필터에서 state을 설정하지 않으면 CLI는 완료되거나 취소된 이슈를 제외합니다. Linear 이슈는 변경하지 않습니다.

codex-security login, logout 및 info

대화형으로 로그인합니다.

npx @openai/codex-security login

원격 또는 헤드리스 머신에서 기기 인증을 사용합니다.

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

현재 로그인 상태를 확인합니다.

npx @openai/codex-security login status

저장된 로그인 정보를 제거합니다.

npx @openai/codex-security logout

stdin으로 API key를 전달하여 저장합니다.

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

엔터프라이즈 액세스 토큰을 저장합니다.

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

읽기 전용 SDK 및 번들 플러그인 메타데이터를 검사합니다.

npx @openai/codex-security info --json

CLI를 MCP 서버로 노출하면 info만 사용할 수 있습니다. 스캔, 내보내기, 게시, 로그인, 검증 및 패치는 계속 CLI에서만 사용할 수 있습니다.

스캔 출력 읽기

기본적으로 스캔은 전체 스캔 결과를 stdout에 기록하지 않고 진행 상황, 완료 요약 및 오류를 stderr로 보냅니다. 구조화된 스캔 결과를 stdout으로 보내려면 --json, --format 또는 --full-output를 요청합니다.

대화형 터미널에는 현재 스캔 단계, 검토한 파일, 활동, 토큰 사용량 및 예상 비용을 보여주는 실시간 대시보드가 표시됩니다. CI 및 리디렉션된 출력은 일반 텍스트 진행 상황을 사용합니다. 대화형 터미널에서 일반 텍스트 진행 상황을 사용하려면 --headless을 추가합니다.

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

대시보드에는 실시간 세션 세부 정보도 표시됩니다. 이 정보는 수정되지 않으며 소스 코드나 자격 증명을 포함할 수 있습니다. 공유하기 전에 검토하세요.

상세 진단

--verbose을 추가하여 수정된 수명 주기, 인증, 진행 상황 및 비용 진단 정보를 stderr에 출력합니다.

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

플래그 없이 동일한 진단을 활성화하려면 CODEX_SECURITY_LOG_LEVEL=debug을 설정합니다. CODEX_SECURITY_LOG_LEVEL이 설정되지 않은 경우 LOG_LEVEL=debug도 진단을 활성화합니다.

완료 요약

완료된 스캔은 저장소에서 열린 발견 항목 수, 심각도 분석, 검사 범위, 경과 시간, 보고서 경로 및 결과 디렉터리를 stderr에 기록합니다. 사용 가능한 경우 토큰 사용량과 예상 비용도 포함합니다.

  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

정보성 발견 항목도 요약 합계에 포함됩니다. 심각도 정책은 저장소 합계에 표시된 이전 발견 항목이 아니라 현재 스캔의 critical, high, medium 및 low 발견 항목만 평가합니다.

JSON 출력

scan --json는 하나의 완전한 JSON 문서를 stdout에 기록합니다. 최상위 구조는 다음과 같습니다.

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

패치하는 경우 JSON 출력에는 패치 결과와 생성된 pull request도 포함됩니다.

진행 상황, 완료 요약, 보관 알림 및 오류는 계속 stderr에 표시됩니다. 심각도 정책이 종료 코드 1을 반환하거나 불완전한 검사 범위가 종료 코드 2을 반환하더라도 완료된 스캔은 전체 JSON 결과를 출력합니다.

스캔 아티팩트

완료된 스캔은 읽을 수 있는 보고서와 구조화된 아티팩트를 함께 보관합니다.

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

구조화된 파일은 각각 다른 용도로 사용됩니다.

검사 범위 완전성에는 세 가지 값이 있습니다.

• complete: 스캔이 선택한 범위의 완전한 검사 내역을 기록합니다.
• partial: 스캔이 보류된 작업 또는 기타 검사 범위 제한을 기록합니다.
• unknown: 스캔이 검사 범위 완전성을 알 수 없음으로 보고합니다.

검사 범위를 보안 결정의 근거로 사용하기 전에 보류된 영역, 명시적 제외 사항 및 미해결 질문을 검토하세요.

종료 코드 및 신호

CLI는 다음 종료 코드를 사용합니다.

검사 범위가 partial 또는 unknown인 모든 스캔은 심각도 정책이 없어도 2을 반환합니다. 구조화된 출력을 요청하면 완료된 스캔과 부분적으로 완료된 게시도 사용 가능한 결과를 stdout에 기록합니다. CLI는 중단 또는 런타임 오류 후 부분 출력이 있으면 해당 위치를 출력합니다.

로컬 스캔 권한

CLI 및 SDK 스캔은 사용자의 로컬 운영 체제 권한으로 실행됩니다. 모든 스캔은 codex_security_scan 파일 시스템 프로필을 사용하고 approvalPolicy을 "never"으로 설정합니다. 이 프로필은 로컬 파일 시스템 읽기와 워크스페이스 루트 및 선택한 스캔 상태 디렉터리 쓰기를 허용합니다. 스캔은 대화형 승인을 요청하기 위해 중지되지 않습니다.

CLI --codex 또는 SDK codexOverrides를 통해 제공된 설정은 approval_policy, sandbox_mode 및 파일 시스템 권한을 포함하여 이러한 스캔 제어를 교체하거나 제한할 수 없습니다. 호스트 및 네트워크 제한은 계속 적용됩니다.

스캔 및 워크벤치 프로세스는 관련 없는 API 토큰과 클라우드 자격 증명을 포함한 사용자의 환경을 상속할 수 있습니다. 신뢰하며 평가 권한이 있는 저장소만 스캔하고 스캔에 필요한 자격 증명만 제공하세요.

인증 및 사전 요구 사항

OPENAI_API_KEY 또는 CODEX_API_KEY을 설정하거나, npx @openai/codex-security login로 로그인하거나, 기존 파일 기반 Codex 로그인을 사용합니다. OpenRouter 또는 Fireworks의 경우 공급자의 API key를 설정하고 모델을 선택합니다. Amazon Bedrock의 경우 Bedrock API key 또는 표준 AWS 자격 증명 체인을 대신 사용합니다.

자격 증명 선택에 대해서는 스캔 인증 선택을 참조하세요.

CI에서는 API key의 범위를 스캔 단계로 제한하고 신뢰할 수 있는 워크플로를 사용하세요.

CLI에는 Node.js 22(22.13.0 이상), 24 또는 26이 필요합니다. 스캔, 일괄 스캔, 내보내기, 스캔 기록 및 저장된 발견 항목에는 Python 3.10 이상도 필요합니다. Python 3.10에는 tomli도 필요합니다. scan, bulk-scan 또는 export와 함께 --python를 사용하거나 Python 기반 명령에 PYTHON을 설정합니다.

CLI 빠른 시작, 일괄 스캔 가이드, CLI FAQ, CI 가이드 또는 TypeScript SDK 가이드를 계속 살펴보세요.

일반 텍스트 별칭

• --output FILE|-