Codex Security CLI 참조

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

프로젝트에 게시된 패키지를 설치합니다.

npm install @openai/codex-security

설치된 패키지를 npx @openai/codex-security로 호출합니다. 실행 파일이 PATH에서 제공되는 경우 codex-security을 직접 사용할 수 있습니다.

명령 개요

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 skills를 에이전트에 동기화합니다.

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

스캔 인증 선택

기본값인 --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을 실행합니다.

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 프로필, 웹 ID, 컨테이너 자격 증명 또는 기본 AWS 자격 증명 체인으로 인증합니다. Bedrock 스캔은 --auth, ChatGPT 로그인 또는 OpenAI API key 대신 AWS 자격 증명을 사용합니다. scan과 bulk-scan은 모두 --provider을 지원합니다.

스캔 대상 선택

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

--path, --diff, --working-tree은 상호 배타적입니다. --head에는 --diff이 필요하고, --base에는 --working-tree이 필요합니다. 심층 모드는 리포지토리 및 경로 대상을 지원합니다.

Diff 및 작업 트리 스캔에서는 리포지토리 인수가 Git worktree 루트여야 합니다. 선택한 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

보안 컨텍스트 추가

--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는 디렉터리를 재귀적으로 검색하고, 링크된 입력 경로를 거부하고, 링크된 디렉터리 항목을 건너뛰며, 추출한 문서 콘텐츠를 저장된 스캔 결과 외부에 보관합니다.

출력 및 정책 옵션 설정

다음 옵션을 사용하여 아티팩트를 보관하거나, 이전 결과를 보존하거나, 머신 판독 가능한 결과를 생성합니다.

비용 한도는 추정치이며 엄격한 지출 상한이 아닙니다. 이미 진행 중인 요청은 한도를 초과해 완료될 수 있으며 부분 스캔 결과는 계속 사용할 수 있습니다.

--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 worktree 외부에 있어야 합니다. 스캔은 --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

TOML 파서가 문자열을 받도록 --codex을 통해 전달하는 문자열 값을 따옴표로 감쌉니다.

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-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 열은 개별 리포지토리를 구성합니다.

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

--workers은 동시 스캔 수를 제한하며 기본값은 4입니다. --mode의 기본값은 standard이고, --max-attempts의 기본값은 1입니다. 오류가 발생한 후 리포지토리를 재시도하려면 --max-attempts을 설정합니다. 기존 출력 디렉터리에서 일괄 스캔을 재개하려면 같은 명령을 다시 실행합니다. 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

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

npx @openai/codex-security scans rerun SCAN_ID

발견 항목 매칭 및 비교

두 스캔에서 근본 원인이 같은 발견 항목을 매칭합니다.

npx @openai/codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID

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

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

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

다른 체크아웃의 스캔을 포함하여 현재 리포지토리에서 완료된 모든 스캔을 매칭하려면 다음을 실행합니다.

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

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

codex-security findings

검토한 발견 항목을 오탐으로 기록합니다.

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 validate 및 codex-security patch

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

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

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

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

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을 요청합니다.

상세 진단

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

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

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

이러한 로깅 제어는 CLI에만 적용됩니다. 자격 증명과 공급자 식별자는 계속 수정된 상태로 유지되며 구조화된 스캔 결과는 stdout에 유지됩니다.

완료 요약

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

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

정보성 발견 항목은 요약의 총계에 포함됩니다. 심각도 정책은 critical, high, medium, low 발견 항목만 평가합니다.

JSON 출력

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

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

진행 상황, 완료 요약, 아카이브 알림, 오류는 계속 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는 중단 또는 런타임 오류 후 부분 출력이 있는 경우 그 위치를 출력합니다.

인증 및 사전 요구 사항

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

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

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

CLI를 사용하려면 Node.js 22 이상이 필요합니다. 스캔을 실행하거나 발견 항목을 내보내려면 Python 3.10 이상도 필요합니다. Python 3.10에는 tomli도 필요합니다. 자동 검색이 적합하지 않을 때는 --python 또는 PYTHON을 사용하여 인터프리터를 선택합니다.

CLI 빠른 시작, 일괄 스캔 가이드, CLI FAQ, CI 가이드 또는 TypeScript SDK 가이드로 계속 진행하세요.

일반 텍스트 별칭

• --output FILE|-