Codex Security CLI 레퍼런스

codex-security 명령어, 플래그, 출력 형식 및 종료 동작을 확인하세요. 처음 스캔한다면 CLI 빠른 시작을 따라 하세요.

CLI를 실행하려면 npx @openai/codex-security를 사용하세요. 설치한 패키지는 cs 별칭도 제공합니다.

명령어 개요

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이 필요하지 않습니다. 설치된 CLI를 업데이트하려면 codex-security --update를 사용하세요.

명령어 확인 및 에이전트 연결

에이전트가 읽을 수 있는 명령어 매니페스트를 출력하세요.

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을 지원합니다. --export-format은 완료된 스캔에서 내보낼 아티팩트의 형식을 선택합니다. 전체 명령어 도움말에는 md도 표시되지만 스캔 결과는 Markdown 출력을 지원하지 않습니다.

CLI를 MCP 서버로 등록하세요.

npx @openai/codex-security mcp add

Codex Security 스킬을 에이전트에 동기화하세요.

npx @openai/codex-security skills add

CLI의 MCP 서버에서는 읽기 전용 메타데이터 명령어인 info만 사용할 수 있습니다. 스캔, 내보내기, 게시, 인증, 검증 및 패치는 CLI에서만 실행할 수 있습니다.

codex-security scan

리포지터리, 선택한 경로, 커밋된 변경 사항 또는 작업 트리를 스캔합니다.

usage: codex-security scan [-h] [--auth {auto,chatgpt,api-key}]
                           [--config FILE]
                           [--cyber-access-program PROGRAM]
                           [--provider {openai,openrouter,fireworks,amazon-bedrock}]
                           [--path PATH | --diff BASE | --working-tree]
                           [--head HEAD] [--base BASE]
                           [--knowledge-base PATH] [--scan-prompt-file FILE]
                           [--validation-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 MINUTES]
                           [--model MODEL]
                           [--effort EFFORT]
                           [--output-dir DIR]
                           [--archive-existing]
                           [--plugin-path PATH] [--python PATH]
                           [--codex KEY=VALUE] [--fail-on-severity LEVEL]
                           [--validate] [--patch] [--patch-severity {critical,high,medium,low}]
                           [--create-pr]
                           [--max-cost USD] [--show-cost] [--dry-run] [--mock]
                           [--workflow-id ID] [--safety-identifier ID]
                           [--headless] [--verbose]
                           [--json] [--format {toon,json,yaml,jsonl}]
                           [--full-output] [repository]

repository의 기본값은 현재 디렉터리입니다.

프로젝트 설정 불러오기

초기 설정 파일을 만들고 스캔에 사용할 파일을 명시적으로 선택하세요.

npx @openai/codex-security init codex-security.yaml
npx @openai/codex-security scan . --config codex-security.yaml

init은 기존 파일을 덮어쓰지 않습니다. -c FILE은 --config FILE의 축약형입니다. 또는 CODEX_SECURITY_PROJECT_CONFIG를 설정하세요. 명시적으로 지정한 플래그가 환경 변수보다 우선합니다. CLI는 프로젝트 파일을 자동으로 찾지 않습니다.

직접 관리하는 설정만 선택하세요. 설정에는 CLI 옵션과 같은 권한이 있습니다. Codex 자체 설정으로 MCP 서버 프로세스를 시작하고 모델 요청을 보낼 서비스를 선택할 수 있습니다. 신뢰할 수 없는 리포지터리나 pull request에서 관리하는 파일을 선택하지 마세요. CI에서는 스캐너 설정을 평가 대상 체크아웃 외부에 보관하세요. 설정 항목과 우선순위는 프로젝트 설정 가이드를 참고하세요.

스캔 인증 방식 선택

기본값인 --auth auto를 사용하면 자격 증명이 자동으로 선택됩니다. ChatGPT 로그인 정보가 있고 OPENAI_API_KEY 또는 CODEX_API_KEY도 설정되어 있으면 텍스트를 출력하는 대화형 스캔에서는 사용할 자격 증명을 묻습니다. CI에서 실행하는 스캔, JSON 및 JSONL 스캔, 그 밖에 대화형 터미널 없이 실행하는 스캔은 환경 변수의 API 키를 사용합니다. 모의 실행에서는 자격 증명을 묻거나 불러오지 않습니다.

저장된 자격 증명을 사용하려면 --auth chatgpt를 전달하세요.

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

환경 변수의 API 키를 사용하려면 --auth api-key를 전달하세요.

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

Daybreak Blue로 스캔하려면 Blue가 활성화된 프로젝트의 API 키를 사용하고 명령어에 --model gpt-6-sol --cyber-access-program daybreak_blue를 추가하세요. 다른 모델은 모델 및 액세스 프로그램 표를 참고하세요.

자동 선택 시 저장된 자격 증명을 기본으로 사용하려면 unset OPENAI_API_KEY CODEX_API_KEY를 실행하세요.

스캔에 최종 사용자 식별자 지정

사용자를 대신해 스캔할 때 API 키로 인증하면 --safety-identifier ID에 사용자별로 일정하게 유지되는 해시 식별자를 전달할 수 있습니다. 1~64자로 지정하고 NUL 문자나 이메일 주소 등의 개인정보는 포함하지 마세요.

식별자를 전달하려면 CODEX_CLI_PATH로 이 옵션을 지원하는 Codex 빌드를 선택하고 식별자를 워커에 전달하는 플러그인을 사용하세요. 번들 Codex 런타임은 이 옵션을 지원하지 않습니다.

OpenRouter 또는 Fireworks 사용

OpenRouter를 선택하려면 API 키를 설정하고 모델을 명시하세요.

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

Fireworks를 선택하려면 API 키를 설정하고 모델을 명시하세요.

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과 Bedrock 모델 ID를 scan 또는 bulk-scan에 지정하세요. Bedrock 스캔은 AWS 자격 증명을 사용합니다. --auth, OpenAI 로그인 또는 OpenAI API 키는 필요하지 않습니다.

Daybreak Blue 및 Daybreak Red

OpenAI 계정 담당 팀에 문의하거나 엔터프라이즈 액세스 신청서를 제출해 Daybreak 액세스를 요청하세요. Daybreak Red 승인에는 GPT-5.6 Cyber 액세스가 포함됩니다. OpenAI가 요청을 승인하면 AWS 계정 담당 팀에 스캔에 사용할 계정에 모델을 프로비저닝해 달라고 요청하세요.

이용 가능 여부는 Daybreak Blue와 Daybreak Red의 AWS 모델 카드에서 확인하세요.

사용할 모델에 액세스할 수 있는 AWS 프로필을 선택하세요. 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

Daybreak Red로 스캔하려면 다음 명령어를 실행하세요.

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

AWS_BEARER_TOKEN_BEDROCK 또는 표준 AWS 자격 증명 체인으로도 인증할 수 있습니다. 임시 액세스 키에는 AWS_SESSION_TOKEN이 필요합니다. 스캔을 실행하는 셸 또는 CI 작업에서 자격 증명과 AWS_REGION을 설정하세요.

로컬 결과 및 액세스 확인

저장된 로컬 보고서 열람, scans show 및 export에는 클라우드 자격 증명이 필요하지 않습니다.

info와 scan --dry-run은 AWS 자격 증명이나 모델 액세스를 검사하지 않습니다. 액세스를 확인하려면 스캔을 실행하세요. AWS 인증 오류나 액세스 거부 오류가 발생하면 자격 증명, 리전 및 모델 권한을 확인하세요.

Bedrock 예상 비용

CLI는 위 Daybreak Blue 및 Daybreak Red 모델 ID에 대해 비용 추정과 --max-cost를 지원합니다. 예상 비용은 AWS 수수료를 포함한 AWS Standard의 상용 리전 내 요금을 기준으로 계산합니다. 비용 한도에는 짧은 컨텍스트 기준 추정치인 estimatedUsd를 사용합니다. 이미 진행 중인 요청으로 인해 추정치가 한도를 넘을 수 있습니다. 긴 컨텍스트 요금이 적용되면 보고되는 estimatedUsdRange도 한도를 초과할 수 있습니다. 이 한도는 실제 청구 금액을 제한하지 않습니다.

스캔 대상 선택

스캔마다 대상 유형을 하나 선택하세요.

--path, --diff, --working-tree 중 하나만 사용할 수 있습니다. --head에는 --diff가 필요하고 --base에는 --working-tree가 필요합니다. 심층 모드는 리포지터리와 경로 대상을 지원합니다.

커밋 간 차이나 작업 트리를 스캔하려면 리포지터리 인수로 Git 작업 트리의 루트를 지정해야 합니다. 선택한 참조는 해당 체크아웃에 존재해야 합니다.

전체 리포지터리를 스캔하세요.

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

심층 스캔 설정

--mode deep에서 다음 옵션으로 보안 이슈 탐색 방식을 조정하세요.

예를 들어 다음 명령어는 워커 두 개를 사용해 최대 열 번 스캔하고 탐색 시간을 90분으로 제한합니다.

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

제한 시간이 지나면 스캔은 아직 실행 중인 워커를 중단하고 완료된 워커가 찾은 보안 이슈를 보고서에 모읍니다. 표준 스캔에서 --max-time은 권장 조사 시간을 설정합니다. 보고서 작성은 그 이후에 끝날 수 있습니다. 사용자 지정 검증과 스캔 후 지침을 실행하는 시간은 여기에 포함되지 않습니다.

이 제한을 재사용하려면 프로젝트 설정 파일에 저장하세요.

scan:
  mode: deep
  max_time_minutes: 90
  deep:
    workers: 2
    subagents_per_worker: 0
    stop_after_no_new: 3
    max_discovery_runs: 10

명령줄 옵션이 프로젝트 설정보다 우선합니다. scan.deep.stop_after_consecutive_errors로 워커 오류가 몇 번 연속 발생하면 탐색을 중단할지 설정하세요. 기본값은 3입니다. bulk-scan에서는 --workers가 동시에 스캔할 리포지터리 수를 제어합니다.

보안 컨텍스트 추가

--knowledge-base PATH로 아키텍처 문서, 위협 모델 또는 보안 정책을 제공하세요. 파일이나 디렉터리를 여러 개 지정하려면 옵션을 반복하세요.

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

UTF-8 텍스트 파일(JSON 및 SARIF 포함), PDF 및 DOCX 파일을 지원합니다. CLI는 디렉터리를 재귀적으로 검색하고 링크가 포함된 입력 경로는 거부하며 디렉터리 안의 링크 항목은 건너뜁니다. 스캔을 재개할 수 있도록 추출한 문서를 스캔 아티팩트 옆에 있는 비공개 재개용 파일 .scan-knowledge.json에 저장합니다. 이 파일을 스캔 디렉터리와 함께 보관하세요. 정식 보고서에는 문서 본문이 포함되지 않습니다.

스캔 지침 추가

스캔 지침을 추가하려면 --scan-prompt-file로 텍스트 또는 Markdown 파일을 제공하세요. --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는 경고를 표시하고 완료된 스캔을 보존합니다. 스캔이 취소되거나 비용 한도에 도달하면 후속 작업을 실행하지 않습니다. 후속 작업이 실행되더라도 스캔 비용 추적과 --max-cost의 적용 대상에서는 제외됩니다.

자체 환경에서 보안 이슈 검증

--validation-prompt-file FILE로 최종 검증 단계를 자체 테스트 절차로 대체하세요. Codex는 먼저 소스를 검토하고 보안 이슈 후보가 없으면 검증을 건너뜁니다. 프롬프트와 테스트 스크립트는 체크아웃 외부에서 직접 관리하는 디렉터리에 보관하세요.

npx @openai/codex-security scan . \
  --validation-prompt-file /path/to/security-tests/validation.md

예를 들어 로컬 테스트 서버가 실행 중이라면 validation.md에 다음 지침을 작성하세요.

/path/to/security-tests/validate.sh 스크립트를 http://localhost:3000 서버를 대상으로 실행하세요.
어떤 보안 이슈가 재현되는지 보고하고 관련 테스트 출력을 포함하세요.

이 플래그는 리포지터리, 경로, 커밋 간 차이 또는 작업 트리를 대상으로 하는 표준 스캔에 사용하세요. 표준 컴포넌트 스캔에서는 scan.validation_file을 프로젝트 설정에 지정하세요. 심층 스캔은 사용자 지정 검증을 허용하지 않습니다.

새 스캔 명령어에 --validate를 추가하면 보고된 각 보안 이슈를 소스만으로 별도 평가합니다. 스캔에서 보안 이슈가 보고되면 CLI는 평가 내용을 스캔 디렉터리의 보고서에 기록합니다. 이 평가는 보안 이슈나 심각도 정책 판정을 변경하지 않습니다. --validate는 --dry-run, --mock 또는 명령줄이나 프로젝트 설정에서 지정한 스캔 비용 한도와 함께 사용할 수 없습니다.

출력 및 정책 옵션 설정

다음 옵션으로 아티팩트와 이전 결과를 보존하거나 기계가 읽을 수 있는 결과를 생성하세요.

모의 데이터 모드는 리포지터리, 경로 및 커밋 간 차이에 대한 표준 스캔을 지원합니다. --dry-run, --patch, 심층 모드, 사용자 지정 검증 또는 스캔 후 프롬프트와 함께 사용할 수 없습니다. 스캔 프롬프트와 지식 베이스는 합성 보안 이슈에 영향을 주지 않습니다. 모의 데이터가 스캔 기록에 섞이지 않도록 별도의 CODEX_SECURITY_STATE_DIR를 사용하세요.

비용 한도에는 짧은 컨텍스트 기준 추정치인 estimatedUsd를 사용합니다. 이미 진행 중인 요청으로 인해 추정치가 한도를 넘을 수 있습니다. 긴 컨텍스트 요금이 적용되면 estimatedUsdRange도 한도를 초과할 수 있습니다. 이 한도는 실제 청구 금액을 제한하지 않습니다.

Codex Security가 완료된 워커 결과를 집계한 후 심층 스캔이 한도에 도달하면 CLI는 완료 결과를 봉인하고 예산 경고를 표시할 수 있습니다. 이때 0을 반환하며, 설정한 심각도 기준에 해당하는 보안 이슈가 있으면 1을 반환합니다. 유효한 완료 결과를 생성할 수 없으면 2를 반환하고 확보한 출력은 디스크에 남깁니다.

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

워크벤치는 스캔 기록을 $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 설정값을 선택하세요.

Codex Security는 모델 ID와 추론 수준을 문자열로 받습니다. 지원하는 조합은 모델, 제공업체, Codex 버전 및 자격 증명에 따라 다릅니다.

스캔의 격리된 Codex 설정에서 프로필을 선택한 경우 해당 프로필의 model과 model_reasoning_effort 값이 --model과 --effort보다 우선합니다. 평소 사용하는 Codex 설정은 불러오지 않습니다. 실제로 적용될 모델과 추론 수준을 확인하려면 --dry-run --verbose를 스캔 명령어에 추가해 스캔 전에 실행하세요.

모델과 추론 수준을 지정하려면 계정에서 사용할 수 있는 Codex 모델을 선택하세요.

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

--codex로 문자열 값을 전달할 때는 TOML 파서가 문자열로 인식하도록 따옴표로 감싸세요.

npx @openai/codex-security scan . --codex 'model="gpt-6.1-sol"'

모델과 추론 수준 값은 Codex에 그대로 전달됩니다. 지원되지 않는 조합을 지정하면 다른 모델이나 추론 수준으로 대체하지 않고 Codex 또는 제공업체의 오류를 반환합니다.

codex-security scan import

보안 분석이나 모델 호출 없이 기존 보안 이슈를 완료된 스캔으로 로컬 기록에 저장합니다. 가져오기에는 모델 인증이 필요하지 않습니다.

usage: codex-security scan import (--csv FILE | --json FILE)
                                  [--output-dir DIR] [--archive-existing]
                                  [--dry-run] [--format json]

입력을 정확히 하나 지정하세요. CSV는 Codex Security 내보내기 형식의 열을 사용합니다. JSON 입력으로는 완전한 codex-security.findings 문서 또는 보안 이슈 스키마에 맞는 findings 배열을 포함한 객체를 사용할 수 있습니다. 임의의 스캐너 JSON이나 GitHub 알림 원본 배열은 보안 이슈로 저장할 수 없습니다.

다음 합성 예제를 findings.csv로 저장하세요.

occurrence_id,finding_id,title,summary,severity,confidence,status,close_reason,note,remediation,path,start_line,end_line
occ_000000000000000000000001,csf_000000000000000000000001,Missing authorization check,The route reads a record without checking ownership,high,high,open,,,Check record ownership before returning data,src/routes.ts,18,18

파일을 검증한 다음 가져오세요.

npx @openai/codex-security scan import --csv findings.csv --dry-run --format json
npx @openai/codex-security scan import --csv findings.csv --format json

모의 실행은 스캔을 저장하지 않고 dryRun: true와 findingCount: 1을 보고합니다. 가져오기를 실행하면 저장된 스캔 ID와 결과 경로가 반환됩니다. JSON을 가져오려면 다음과 같이 실행하세요.

npx @openai/codex-security scan import --json findings.json --format json

이 명령어에서 --json FILE은 입력 파일을 선택합니다. JSON 출력에는 --format json을 사용하세요.

경로에 심볼릭 링크나 디렉터리 정션이 없는 일반 파일을 입력으로 사용하세요. 가져올 때마다 중복을 포함한 보안 이슈의 개별 발생 기록을 보존하고 입력을 artifacts/import/ 아래에 보관합니다. 원본 식별자는 extensions.import에 저장됩니다. 완료 상태는 가져오기가 끝났다는 뜻이며 소스를 검토했다는 의미는 아닙니다. scans rerun SCAN_ID는 보관된 입력을 다시 가져옵니다.

이름이 import인 리포지터리를 스캔하려면 scan ./import를 사용하세요.

codex-security import github

GitHub를 변경하거나 코드를 체크아웃하지 않고 GitHub 코드 스캔 알림을 읽습니다.

npx @openai/codex-security import github example/repository --format json > /path/outside/repository/alerts.json
npx @openai/codex-security import github example/repository \
  --github-alert 12 --github-alert 18 --format json

example/repository를 사용 중인 리포지터리로 바꾸세요. 코드 스캔 읽기 권한이 있는 GitHub CLI 자격 증명으로 인증하세요. 기본적으로 가져오기는 서드 파티 SARIF 업로드를 포함해 기본 브랜치의 열린 알림을 읽습니다.

알림 번호를 지정할 때는 open 이외의 상태를 함께 지정하지 마세요. 명령어는 스캔을 저장하지 않고 원본 알림 배열을 반환합니다. 해당 로컬 리포지터리에서 codex-security validate /path/outside/repository/alerts.json을 실행해 알림을 평가하세요. 검증 입력을 저장할 때는 출력 필터나 토큰 제한을 적용하지 말고 전체 JSON을 보존하세요. 이미 Codex Security 스키마에 맞는 보안 이슈에는 scan import를 사용하세요. Dependabot 알림을 가져오려면 publish findings를 사용하세요.

codex-security install-hook

CLI를 리포지터리 외부에 설치하고 리포지터리의 기존 pre-commit 훅을 확인한 다음 체크아웃 외부에서 설치된 CLI를 실행하세요.

git -C /path/to/repository rev-parse --git-path hooks/pre-commit
codex-security install-hook /path/to/repository

훅은 커밋할 때마다 스테이징된 변경 사항과 스테이징되지 않은 변경 사항을 스캔합니다. 심각도가 높음 또는 치명적 수준인 보안 이슈가 있거나 스캔 오류가 발생하면 커밋을 차단합니다. 로컬 훅은 선택 사항이므로 검사를 강제하려면 필수 CI 검사를 사용하세요. 사용자 지정 훅, 링크된 훅, 공유 훅 및 해당 훅 디렉터리는 소유자가 관리하도록 두세요. 설치 프로그램은 관련 없는 pre-commit 스크립트를 교체하지 않습니다. 필요하면 다른 심각도 기준을 설정하세요.

codex-security install-hook /path/to/repository --fail-on-severity medium

codex-security policy

프로젝트 보안 경계와 보안 이슈로 판단할 기준을 설명하는 SECURITY.md 정책 초안을 작성합니다.

npx @openai/codex-security policy .
npx @openai/codex-security policy . --headless --json

이 명령어는 리포지터리 외부에 초안을 저장하며 기존 파일은 변경하지 않습니다. 초안, 변경 내역 및 검토 메모를 확인한 다음 검토를 마친 SECURITY.md만 표시된 정책 경로에 복사하세요. 헤드리스 모드에서는 답하지 않은 질문이 검토 메모에 남습니다. 정책 생성은 선택 사항입니다. 스캔은 기존 정책을 사용하거나 정책 없이 실행할 수 있습니다. 경로 범위와 옵션은 정책 가이드를 참고하세요.

codex-security scan-components

scan-components를 사용하면 한 리포지터리의 서비스나 패키지를 각각 스캔할 수 있습니다. 계획만 생성하는 경우를 포함해 매번 Git 작업 트리 외부에 새 디렉터리나 빈 디렉터리를 출력 위치로 지정해야 합니다. --output-dir 또는 프로젝트 설정의 output.directory로 지정하세요.

예를 들어 다음과 같이 두 서비스를 병렬로 스캔하세요.

npx @openai/codex-security scan-components . \
  --component apps/api --component apps/web \
  --output-dir /path/outside/repository/manual-components

scan --path와 달리 이 명령어는 컴포넌트마다 스캔을 생성한 다음 보안 이슈를 모아 서로 일치하는 항목을 찾습니다. 기본적으로 컴포넌트 스캔 네 개를 동시에 실행할 수 있습니다. 이 제한을 변경하려면 --workers N을 설정하세요. --max-cost USD는 개별 컴포넌트 스캔의 비용을 제한합니다. 자동 계획과 컴포넌트 간 이슈 매칭 비용은 제외됩니다.

Codex가 컴포넌트 분할 방식을 제안하도록 하려면 스캔 전에 검토할 계획을 저장하세요.

npx @openai/codex-security scan-components . --auto --plan-only \
  --output-dir /path/outside/repository/component-plan

components.json에서 컴포넌트 이름과 경로를 검토한 다음 새 출력 디렉터리를 지정해 저장된 계획을 실행하세요.

npx @openai/codex-security scan-components . \
  --components-file /path/outside/repository/component-plan/components.json \
  --output-dir /path/outside/repository/components

출력 디렉터리에서 report.md를 열어 통합된 보안 이슈를 검토하세요. 컴포넌트 스캔이 실패하면 저장된 재시도 계획으로 실패한 컴포넌트만 다시 스캔하세요.

npx @openai/codex-security scan-components . \
  --components-file /path/outside/repository/components/retry-components.json \
  --output-dir /path/outside/repository/retry-results

재시도 보고서에는 다시 스캔한 컴포넌트만 포함됩니다. 첫 실행에서 스캔을 마친 컴포넌트의 보안 이슈를 검토할 수 있도록 원본 보고서도 보관하세요.

스캔 또는 매칭에 실패하면 2를 반환합니다. 심각도 정책을 위반하면 1을 반환합니다. 계획 구문과 재시도 방법은 컴포넌트 스캔 가이드를 참고하세요.

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 EFFORT]
                                [--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 로그인이 필요합니다.

대화형 탐색에는 계정에서 사용할 수 있는 Codex 모델을 선택하세요.

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

미리 준비한 리포지터리 목록을 사용하려면 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,권한 부여 경계를 검토하세요.

--knowledge-base PATH로 모든 리포지터리에 공통으로 적용할 보안 문서를 지정하세요. --scan-prompt-file FILE로 공통 스캔 지침을 추가할 수 있습니다. CSV의 prompt 열은 공통 프롬프트 뒤에 리포지터리별 지침을 추가합니다. --post-scan-prompt-file FILE은 오류를 반환한 스캔을 포함해 각 스캔 후에 후속 지침을 실행합니다. 스캔이 취소되거나 비용 한도에 도달하면 실행하지 않습니다.

--workers는 동시에 스캔할 리포지터리 수를 제한하며 기본값은 4입니다. --mode의 기본값은 standard이고 --max-attempts의 기본값은 1입니다. 리포지터리 오류나 스캔 오류가 발생했을 때 재시도하려면 --max-attempts를 설정하세요. 제외 항목이나 후속 메모가 있어도 완료된 스캔은 재시도하지 않습니다. 실행 실패가 남아 있으면 2를 반환하고 완료된 스캔에서 심각도 정책 위반이 있으면 1을 반환합니다.

기존 출력 디렉터리에서 재개하려면 같은 명령어를 다시 실행하세요. CLI는 완료된 스캔을 건너뜁니다. 일치하는 캠페인에서 실패하거나 중단된 시도를 다시 실행하려면 --recover를 사용하세요.

컨테이너에서 캠페인을 실행하려면 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

재실행하면 저장된 설정과 인증 방식, 현재 체크아웃 및 현재 컨텍스트 파일을 사용해 새 스캔을 만듭니다. 프로젝트 설정 파일을 다시 불러오거나 저장된 자격 증명을 재사용하지 않습니다. 원래 스캔에서 스캔 프롬프트나 사용자 지정 검증 프롬프트를 사용했다면 --scan-prompt-file과 --validation-prompt-file로 해당 파일을 다시 제공하세요.

재실행에는 원래 스캔에 기록된 플러그인 버전이 필요합니다. 설치된 버전이 다르면 실행을 중단합니다.

저장된 스캔 로그 확인

스캔과 워커에 대해 저장된 전체 세션 이벤트를 읽으세요. 이 로그에는 마스킹을 적용하지 않으므로 소스 코드나 자격 증명이 포함될 수 있습니다. 공유하기 전에 검토하세요.

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

경로가 제외되었거나 매칭이 불확실한 보안 이슈는 확인 불가 상태입니다. 이후 스캔에서 검사한 코드에 해당 이슈가 발견되지 않으면 미관찰 상태입니다. 이미 수정되었다는 이유로 명시적으로 닫은 보안 이슈만 해결 상태입니다. 기존 매칭을 다시 계산하려면 --force를 match에 추가하세요.

다른 체크아웃에서 실행한 스캔을 포함해 현재 리포지터리에서 완료된 모든 스캔의 보안 이슈를 매칭하세요.

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

Codex를 시작하거나 자격 증명을 불러오지 않고 저장된 보안 이슈 또는 위협 모델을 내보냅니다. 보안 이슈를 CSV, JSON, SARIF 또는 ServiceNow AVIT CSV로 내보내려면 스캔이 완료되고 결과가 봉인되어 있어야 합니다. 위협 모델에는 Markdown을 사용합니다.

usage: codex-security export [scan_dir | --scan SCAN_ID]
                             [--artifact {findings,threat-model}]
                             [--export-format {csv,json,sarif,md,servicenow-avit}]
                             [--avit-template FILE]
                             [--output FILE|-] [--source-root PATH]
                             [--python PATH]

scan_dir와 --scan을 생략하면 현재 리포지터리에서 가장 최근에 완료된 스캔을 사용합니다. 특정 스캔을 사용하려면 저장된 결과 디렉터리를 지정하거나 --scan에 스캔 ID 또는 8자 이상의 고유 접두사를 지정하세요. 두 방식을 함께 사용할 수는 없습니다.

--source-root는 보안 이슈를 SARIF로 내보낼 때만 작동합니다. JSON은 봉인된 보안 이슈 문서를 그대로 보존합니다. CSV에는 이식 가능한 보안 이슈 열이 포함되며 로컬 워크벤치의 이슈 분류 상태는 포함되지 않습니다.

--output을 생략하면 CLI는 현재 작업 디렉터리에 SARIF는 results.sarif, JSON은 findings.json, CSV는 findings.csv, ServiceNow AVIT CSV는 servicenow-avit.csv, Markdown은 threatmodel.md로 저장합니다. 내보낸 파일에는 소스 코드 일부와 취약점 세부 정보가 포함될 수 있습니다. --output에 체크아웃 외부의 비공개 경로를 전달하세요. 리포지터리 외부에서 실행할 때는 결과 디렉터리 또는 --scan도 지정하세요.

보안 이슈 내보내기

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

ServiceNow용 보안 이슈 내보내기

ServiceNow에서는 Ethical Hacker 역할(sn_vul.app_pen_tester)이 필요합니다. All > Manual AVIT Ingestion > Upload File UI 메뉴를 열고 CSV 템플릿을 다운로드하세요. 원본 헤더를 유지하고 데이터 행은 정확히 하나만 남기세요. ServiceNow 애플리케이션의 정확한 이름을 사용하세요. 용도, 민감한 데이터 유형, 규정 준수 프로그램, 기술 스택, 애플리케이션 담당 팀 및 테스트할 URL을 입력하세요. Requested by, Assigned to, Assignment group 필드를 설정하세요. 보안 이슈 필드는 비워 두세요. 스캔한 리포지터리 외부의 비공개 디렉터리에 템플릿을 app.csv로 저장하세요. 같은 애플리케이션을 스캔할 때 재사용할 수 있습니다.

스캔한 리포지터리에서 해당 템플릿으로 최신 보안 이슈를 내보내세요. 출력도 비공개 디렉터리에 보관하세요.

npx @openai/codex-security export --scan latest \
  --export-format servicenow-avit \
  --avit-template /path/outside/repository/exports/app.csv \
  --output /path/outside/repository/exports/findings-avit.csv

CLI는 보안 이슈마다 행 하나를 작성하고 기록된 공격 경로가 있으면 이를 바탕으로 Steps to reproduce 필드를 채웁니다. 재현 단계를 검토하고 내보낸 CSV의 빈칸을 채우세요. Upload File UI 화면으로 돌아가 Import File을 선택하고 CSV를 업로드한 다음 Submit을 선택하세요. 업로드할 때마다 해당 애플리케이션에 대한 새 침투 테스트 양식이 생성됩니다. ServiceNow 업로드 지침을 참고하세요.

저장된 위협 모델 내보내기

모델을 다시 호출하지 않고 가장 최근에 완료된 스캔에 저장된 위협 모델을 stdout으로 내보내세요.

npx @openai/codex-security export --artifact threat-model --output -

또는 스캔을 선택해 해당 위협 모델을 파일에 저장하세요.

npx @openai/codex-security export --scan SCAN_ID \
  --artifact threat-model \
  --output /path/outside/repository/exports/threatmodel.md

ID나 디렉터리로 스캔을 선택하면 미완료 또는 실패한 스캔에 저장된 위협 모델도 내보낼 수 있습니다. 저장된 모델이 없으면 명령어가 오류를 반환합니다. 문서에서 임시 또는 복구된 내용으로 표시한 부분은 재사용하기 전에 검토하세요.

내보낸 모델을 다른 스캔의 컨텍스트로 제공하려면 해당 경로를 --knowledge-base에 전달하세요.

codex-security publish scan

완료된 스캔에서 선택한 보안 이슈를 Linear 또는 사용자 지정 보안 이슈 서비스에 게시합니다. 다음은 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에는 완료되고 봉인된 스캔이 있어야 합니다. 대화형 터미널에서 이 인수를 생략하면 로컬 스캔 기록에서 완료된 스캔을 선택할 수 있습니다. 이슈를 생성하려면 해당 스캔과 보안 이슈가 로컬 스캔 기록에도 있어야 합니다. 모의 실행은 로컬 기록에 저장되었는지 확인하지 않고 봉인된 아티팩트를 검증합니다.

디렉터리 대신 --scan SCAN_ID 또는 --scan latest로 저장된 스캔을 선택할 수 있습니다. Linear에 일부 보안 이슈만 게시하려면 --finding-id ID를 반복하세요. publish check SCAN_DIR에 Linear 대상 옵션을 지정하면 아티팩트와 게시 기록을 확인합니다. API 키를 사용하면 인증과 대상 액세스도 확인합니다. 연결된 앱의 액세스 상태는 not-checked로 표시됩니다.

모의 실행이 아니면 호출할 때마다 선택한 보안 이슈별로 새 이슈 생성을 시도합니다. 단, --skip-existing이 해당 발생 기록, 팀 및 프로젝트의 게시 성공 기록을 찾으면 건너뜁니다. 이 옵션은 원격 이슈를 확인하지 않으며 기록되지 않은 게시나 동시에 진행되는 게시에는 적용되지 않습니다. 일부 보안 이슈 게시에 실패하면 성공적으로 생성된 이슈를 보존하고 종료 코드 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 키가 없으면 명령어는 기존 설정과 연결된 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 키로 게시

--linear-api-key 또는 CODEX_SECURITY_LINEAR_API_KEY를 지정하면 Codex를 시작하지 않고 Linear API를 통해 직접 게시합니다. 직접 게시할 때 담당자를 선택하지 않으면 이슈에 담당자가 지정되지 않습니다.

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 키에는 CODEX_SECURITY_LINEAR_API_KEY 사용을 권장합니다. --linear-api-key로 전달하면 명령줄 인수가 셸 기록과 프로세스 목록에 나타날 수 있습니다.

사용자 지정 보안 이슈 서비스에 게시

기존 보안 이슈 서비스를 사용하려면 URL을 명시적으로 지정하세요.

npx @openai/codex-security publish scan --scan latest \
  --to custom --findings-url http://localhost:3000

게시 시 봉인된 전체 보안 이슈와 리포지터리 대상 ID를 전송합니다. 보안 이슈에는 소스 코드 일부, 근거 및 취약점 세부 정보가 포함될 수 있습니다. 로컬 머신 외부의 서비스에는 HTTPS를 사용하고 전송 전에 --dry-run --json을 추가해 페이로드를 확인하세요.

CLI는 사용자 지정 서비스에 모델 자격 증명을 전송하지 않습니다. 필요한 인증은 CLI 외부에서 처리하세요. 배포 및 프로토콜 세부 사항은 보안 이슈 서비스 가이드를 참고하세요.

codex-security publish findings

가져온 보안 이슈를 로컬 머신에 저장하려면 --to local을 사용하세요. --to cloud를 사용하면 미리보기만 실행해도 서비스에 접속합니다. 이 경우 파일에 저장된 ChatGPT 로그인 정보가 필요하며, 기존 클라우드 환경이 있고 액세스 권한이 있는 리포지터리의 ID나 URL을 지정해야 합니다. 클라우드로 가져올 때 서비스에서 개별 레코드를 거부하면 일부 결과만 반환될 수 있습니다. 두 워크플로우는 GitHub 가져오기 가이드를 참고하세요.

로컬 체크아웃에 Dependabot 알림을 가져오려면 같은 GitHub 리포지터리에서 내보낸 파일이 필요합니다. Dependabot 내보내기 가이드에 따라 Dependabot 알림 읽기 권한이 있는 토큰으로 모든 페이지를 체크아웃 외부에 저장하세요.

내보내기 스크립트를 실행하기 전에 맨 끝에 echo "$out/dependabot.jsonl"을 추가하세요. 새 셸에서 스크립트가 출력한 경로를 사용해 파일을 미리 확인하세요. ./project와 OWNER/REPO를 각각 체크아웃 경로와 리포지터리 이름으로 바꾸세요. 체크아웃에 네트워크 원격 리포지터리가 설정되어 있으면 그중 하나가 알림을 내보낸 리포지터리와 일치해야 합니다. 네트워크 원격 리포지터리가 없으면 내보낸 파일이 해당 체크아웃의 것인지 직접 확인하세요.

export CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1
npx @openai/codex-security publish findings /path/to/dependabot.jsonl \
  --to local --repository ./project --provider github \
  --source-key github.com/OWNER/REPO/dependabot --dry-run --format json

미리보기에서 저장 대상과 제외 항목을 확인하세요. 제외된 알림이 표시되더라도 모의 실행은 종료 코드 0을 반환합니다. 수락된 알림을 저장하려면 --dry-run을 빼고 다시 실행한 뒤 확인 메시지에 응답하거나, --dry-run을 --yes로 바꿔 실행하세요. 가져올 때 제외된 알림이 하나라도 있으면 수락된 알림을 저장하고 종료 코드 1을 반환합니다. 같은 셸에서 저장된 알림을 확인하세요.

npx @openai/codex-security findings imported ./project --format json

가져온 알림의 초기 평가 상태는 not_assessed입니다. 같은 소스 키로 다시 가져오면 파일에 있는 알림의 저장된 레코드가 업데이트됩니다. 파일에서 빠진 알림은 마지막으로 가져왔을 때의 상태를 유지합니다. 같은 보안 권고에 해당하는 알림도 각각 별도 레코드로 유지됩니다.

보안 이슈 검토 명령어

다음 명령어는 기존 보안 이슈를 대상으로 합니다.

verify-fix는 검사 결과가 하나라도 불확실하거나 검사에 실패하면 2를 반환합니다. 그렇지 않은 경우 취약한 상태로 남은 보안 이슈가 있으면 1을, 모두 수정되었으면 0을 반환합니다. 선택자, 모델 설정 및 출력 옵션은 각 명령어의 --help로 확인하세요.

codex-security feedback

OpenAI에 문제 설명을 보내고 지원팀에 공유할 ID를 받으세요.

npx @openai/codex-security feedback SCAN_ID \
  --reason "The scan stopped before it finished" --json

스캔 ID를 생략하면 현재 리포지터리에서 가장 최근에 시작한 스캔을 선택합니다. 실행 중이거나 실패한 스캔도 포함됩니다. 스캔이 없으면 일반 보고서를 전송합니다. 보고서에는 설명, 버전 및 선택된 스캔/세션 ID가 포함됩니다. 로그는 기본적으로 제외됩니다. 로그에 포함된 소스, 프롬프트, 보안 이슈 및 도구 출력을 OpenAI와 공유할 수 있을 때만 --include-logs를 추가하세요.

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는 읽기 전용 샌드박스에서 소스 코드상의 근거를 평가합니다. 대상을 빌드하거나 애플리케이션 코드를 실행하지 않으며 테스트나 개념 증명 코드를 실행하거나 서비스에 접속하지도 않습니다. 표준 스캔, 심층 스캔 및 커밋 간 차이 스캔은 각각 자체 검증 워크플로우를 유지합니다. patch는 보안 이슈를 수정하고 검증합니다.

수정 후 또는 이후 스캔에서 해당 보안 이슈가 더 이상 보고되지 않을 때 validate로 다시 평가하세요. 스캔 비교만으로는 수정이 효과가 있었음을 입증할 수 없습니다. 런타임 근거가 필요하면 별도로 재현 절차를 실행하세요.

명령어는 보고서를 저장하지 않고 평가 내용을 stdout으로 출력합니다. 보관하려면 stdout을 리디렉션하세요.

npx @openai/codex-security validate findings.json > /path/outside/repository/assessment.md

보안 컨텍스트를 제공하려면 --context TEXT, --context-file FILE 또는 반복 가능한 --knowledge-base PATH 옵션을 추가하세요. 구조화된 출력에는 --output-schema FILE로 모델과 제공업체가 지원하는 독립형 JSON Schema를 지정하세요. CLI는 stdout에 기록하기 전에 생성된 JSON이 스키마에 맞는지 확인합니다. 출력이 유효하지 않으면 CLI는 2로 종료하며 평가 내용을 출력하지 않습니다. validate는 --json을 지원하지 않습니다.

두 명령어 모두 --effort로 추론 수준을 선택할 수 있습니다.

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

스캔 후 보안 이슈 패치

스캔이 완료된 후 보안 이슈를 수정하려면 scan --patch를 사용하세요. 기본 심각도 기준은 low입니다. 다음 명령어는 심각도가 높음 또는 치명적 수준인 보안 이슈를 선택합니다.

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

수정이 검증되었거나 이미 수정된 보안 이슈는 --fail-on-severity의 실패 조건에 해당하지 않습니다.

저장된 보안 이슈 패치

보안 이슈 ID 또는 발생 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는 현재 리포지터리에서 가장 최근에 완료된 스캔을 선택합니다. patch는 저장된 보안 이슈, 텍스트 자체 및 파일 입력에 대해 --json을 지원합니다.

--create-pr를 추가하면 검증된 패치 파일만 커밋하고 해당 CLI를 사용해 GitHub 초안 pull request 또는 GitLab 초안 병합 요청을 엽니다.

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

푸시 또는 pull request 생성에 실패하면 같은 리포지터리에서 출력된 patch --resume-pr BRANCH 명령어를 실행해 재시도하세요.

Linear 이슈 패치

개인 API 키에는 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

API 키를 stdin으로 전달해 저장하세요.

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

스캔 출력 읽기

기본적으로 스캔은 진행 상황, 완료 요약 및 오류를 stderr로 보내고 전체 스캔 결과는 stdout에 기록하지 않습니다. 구조화된 스캔 결과를 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를 설정하세요. LOG_LEVEL=debug도 CODEX_SECURITY_LOG_LEVEL이 설정되지 않았거나 비어 있으면 진단 출력을 활성화합니다.

Codex Security는 진단 텍스트를 그대로 보존합니다. 진단 정보에 소스 코드나 자격 증명이 포함될 수 있으므로 공유하기 전에 검토하세요.

완료 요약

스캔이 완료되면 리포지터리의 열린 보안 이슈 수, 심각도별 집계, 경과 시간, 보고서 경로 및 결과 디렉터리를 stderr로 출력합니다. 토큰 사용량을 확인할 수 있으면 함께 표시하고, --show-cost 또는 --max-cost를 설정하면 예상 비용도 표시합니다. 출력 예시는 다음과 같습니다.

  REPORT    /path/to/scan/report.md

  FINDINGS  4 (3 confirmed this scan; 1 previously found; 1 critical, 2 high, 1 informational)
  SCOPE     repository: .
  ELAPSED   1s
  RESULTS   /path/to/scan

정보 수준의 보안 이슈도 요약의 총수에 포함됩니다. 심각도 정책은 현재 스캔에서 발견된 critical, high, medium, low 보안 이슈만 평가합니다. 리포지터리 총수에 포함된 이전 보안 이슈는 평가하지 않습니다.

JSON 출력

scan --json은 하나의 JSON 문서를 stdout으로 출력합니다. manifest.scan에서 상태와 범위를, findings에서 현재 스캔의 보안 이슈를 확인하세요. repositoryFindings가 있으면 현재 보안 이슈와 이전에 발견된 열린 보안 이슈가 함께 포함됩니다. review.excludedPaths에는 스캔에서 검토 제외 대상으로 기록한 경로 패턴이 나열됩니다. scanDir, reportPath, artifactsDir는 저장된 결과의 위치를 가리킵니다.

threatModel에는 저장된 모델이 구조화된 데이터 또는 Markdown으로 들어 있습니다. threatModelPath는 저장된 문서의 경로입니다. 어느 값이든 null일 수 있습니다. 문서 기록에 실패했더라도 모델을 내보낼 수 있습니다.

패치를 실행하면 JSON 출력에는 패치 결과와 생성된 pull request도 포함됩니다.

진행 상황, 완료 요약, 아카이브 알림 및 진단 정보는 계속 stderr로 출력됩니다. 완료된 스캔은 심각도 정책에 따라 종료 코드 1을 반환하더라도 JSON 결과를 출력합니다.

JSON이 정상적으로 파싱되더라도 프로세스 종료 코드를 항상 확인하세요. 실행이 실패해 스캔 결과가 반환되지 않은 경우 status, code, message를 포함한 구조화된 오류가 --json, --format json 또는 --format jsonl 출력에 표시됩니다. 대상이 변경된 경우처럼 유효한 스캔 결과가 보존되어 있으면 일반 스캔 결과와 warnings가 대신 출력될 수 있습니다. --json, --format json 또는 --format jsonl에 --full-output을 추가하면 ok: false인 응답 객체를 받습니다. 이 객체의 error에는 오류가, data에는 보존된 유효한 봉인 결과가 들어 있습니다. 다른 형식에서는 --full-output을 사용하더라도 실패를 stderr로만 보고합니다. 이 규칙은 scans rerun과 scans resume에도 적용됩니다.

스캔 아티팩트

완료된 스캔은 사람이 읽을 수 있는 보고서와 구조화된 아티팩트를 함께 보관합니다. 봉인된 매니페스트에 아티팩트 해시를 기록하므로 나중에 파일이 변경되지 않았는지 확인할 수 있습니다.

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

각 파일의 내용은 다음과 같습니다.

완료 여부 및 검토 범위

scan.status를 scan-manifest.json에서 확인해 스캔 완료 여부를 파악하세요. scan.scope에서 설정된 범위를, scan.review.excludedPaths에서 검토 중 기록된 제외 항목을 확인하세요. 스캔을 비교할 때도 이 제외 항목을 사용합니다. 스캔이 완료되었더라도 범위에 포함된 일부 파일은 검토되지 않았을 수 있습니다.

미해결 작업이 있으면 scans show SCAN_ID와 scans logs SCAN_ID로 확보된 근거를 살펴보세요. 중단된 심층 스캔이 재개 요건을 충족하면 scans resume SCAN_ID로 이어서 실행할 수 있습니다. 저장된 설정으로 새 검토를 시작하려면 실행에 필요한 정보가 기록되어 있는 경우 scans rerun SCAN_ID를 사용하세요. 플러그인 스캔에는 재실행에 필요한 정보가 없을 수 있습니다. 이 경우 원하는 경로와 컨텍스트를 지정해 새 스캔을 시작하세요.

종료 코드 및 시그널

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

검토되지 않은 부분이 있어도 완료된 스캔의 종료 코드가 바뀌거나 심각도 정책 적용이 생략되지는 않습니다. 종료 코드 0은 모든 파일을 검토했다는 뜻이 아닙니다. 구조화된 출력을 요청하면 완료된 스캔이나 일부만 성공한 게시도 확보된 결과를 stdout으로 출력합니다. 실행이 중단되거나 런타임 오류가 발생하면 CLI는 부분 출력이 저장된 위치를 표시합니다.

로컬 스캔 권한

CLI 및 SDK 스캔은 사용자의 로컬 운영체제 권한으로 실행됩니다. 스캔 프로필은 로컬 파일시스템 읽기와 워크스페이스 루트에 대한 쓰기를 허용합니다. 실행 승인 요청은 자동으로 검토되며 특정 작업에 추가 권한이 부여될 수 있습니다. 권한 요청을 거부하려면 --codex 'approval_policy="never"'를 사용하거나 SDK에서 codexOverrides.approval_policy: "never"를 설정하세요. 호스트 및 네트워크 제한은 계속 적용됩니다.

스캔 및 워크벤치 프로세스는 관련 없는 API 토큰과 클라우드 자격 증명을 포함해 사용자의 환경 변수를 상속할 수 있습니다. 스캔을 시작하기 전에 관련 없는 자격 증명을 제거하세요.

인증 및 사전 요구 사항

OPENAI_API_KEY 또는 CODEX_API_KEY를 설정하거나, npx @openai/codex-security login으로 로그인하거나, 파일에 저장된 기존 Codex 로그인 정보를 사용하세요. OpenRouter 또는 Fireworks의 경우 해당 제공업체의 API 키를 설정하고 모델을 선택하세요. Amazon Bedrock의 경우 Bedrock API 키 또는 표준 AWS 자격 증명 체인을 사용하세요.

자격 증명 선택 방법은 스캔 인증 방식 선택을 참고하세요.

CI에서는 API 키를 스캔 단계에서만 사용할 수 있도록 하고 신뢰할 수 있는 워크플로우를 사용하세요.

CLI에는 Node.js 24 또는 26이 필요합니다. Node.js 22에서는 22.13.0부터 지원합니다. 스캔, 일괄 스캔, 내보내기, 스캔 기록 및 저장된 보안 이슈 기능에는 Python 3.10 이상도 필요합니다. Python 3.10에는 tomli도 필요합니다. --python을 scan, bulk-scan 또는 export와 함께 사용하거나 Python 기반 명령어에 사용할 PYTHON을 설정하세요.

압축된 Codex 세션(.jsonl.zst)을 읽거나 재개하려면 Node.js 22.x 중 22.15.0 이상 버전 또는 Node.js 24나 26을 사용하세요. 압축되지 않은 .jsonl 세션은 지원되는 모든 Node.js 버전에서 작동합니다.

이어서 CLI 빠른 시작, 일괄 스캔 가이드, CLI FAQ, CI 가이드 또는 TypeScript SDK 가이드를 참고하세요.