Codex Security

Codex Security는 본인이 소유하거나 평가할 권한이 있는 코드에서 보안 문제를 찾고, 검증하며, 검토하기 위한 오픈 소스 CLI 및 TypeScript SDK입니다.

[!NOTE]
이 패키지는 유의적 버전 (semantic versioning)을 따릅니다. 1.0.0 버전 이전의 마이너 버전 사이에서는 공개 API가 변경될 수 있습니다.

요구 사항 (Requirements)

SDK 및 CLI는 macOS, Linux, Windows를 지원하며 Node.js 22 이상이 필요합니다. 스캔 및 결과 내보내기(exporting)를 위해서는 Python 3.10 이상도 필요합니다. Python 3.10을 사용하는 경우 tomli 패키지를 설치하십시오. 패키지 설치나 --help 및 --version 실행에는 Python이 필요하지 않습니다.

스캔을 실행하기 전에 OpenAI 계정으로 로그인하거나 OpenAI API 키를 제공하십시오. 본인이 소유하거나 평가할 명시적 권한이 있는 저장소(repository)만 스캔하십시오.

설치 및 스캔 (Install and scan)

npm install @openai/codex-security
npx codex-security login
npx codex-security scan /path/to/repo

모든 명령어를 확인하려면 npx codex-security --help를 실행하고, 스캔 옵션을 확인하려면 npx codex-security scan --help를 실행하십시오.

원격 또는 헤드리스 (headless) 머신에서는 npx codex-security login --device-auth를 사용하십시오. CI 및 기타 무인 스캔(unattended scans)의 경우, 셸(shell), CI secret 또는 시크릿 매니저(secret manager)를 사용하여 OPENAI_API_KEY 또는 CODEX_API_KEY를 설정하십시오.

Windows에서는 PowerShell에서 다음과 같이 API 키를 설정하십시오:

$env:OPENAI_API_KEY = "<your-api-key>"
npx codex-security scan C:\code\repository

API 키를 저장하려면 stdin을 통해 전달하십시오:

printenv OPENAI_API_KEY | npx codex-security login --with-api-key

npx codex-security login status를 사용하여 저장된 로그인 상태를 확인하고, npx codex-security logout을 사용하여 로그아웃하십시오. Codex Security는 기존의 파일 기반 Codex 로그인을 재사용합니다. Codex가 시스템 키링(keyring)에 자격 증명을 저장하는 경우, 스캔 전에 npx codex-security login을 한 번 실행하십시오.

환경 변수(environment) API 키는 저장된 로그인 정보보다 우선순위를 갖습니다. ChatGPT 로그인을 사용하려면 OPENAI_API_KEY와 CODEX_API_KEY를 모두 해제하십시오. 로그인 상태 확인 명령은 저장된 로그인 정보가 없는 경우를 포함하여, 실제 적용된 자격 증명(credential)의 출처를 값을 출력하지 않고 보고합니다.

저장소(repository)의 일부 하위 집합을 스캔하거나 기계 판독 가능한(machine-readable) 결과를 작성하려면 다음과 같이 실행합니다:

npx codex-security scan /path/to/repo --model gpt-5.6-terra
npx codex-security scan /path/to/repo --path src --path tests
npx codex-security scan /path/to/repo --knowledge-base /path/to/threat-models --knowledge-base /path/to/architecture.pdf
...

install-hook은 각 커밋(commit) 전에 스테이징된(staged) 변경 사항과 스테이징되지 않은(unstaged) 변경 사항을 스캔합니다. 이는 core.hooksPath를 준수하며, 기존 훅(hook)을 교체하지 않고, 심각도가 높은 탐지 결과나 스캔 실패를 차단합니다. 임계값(threshold)을 변경하려면 --fail-on-severity를 설정하십시오.

CLI 버전을 확인하려면 npx codex-security --version을 사용하고, 패키지, 플러그인 및 런타임(runtime) 버전, 기본 모델 및 추론 노력(reasoning effort), 그리고 다음 스캔 명령을 확인하려면 npx codex-security info --json을 사용하십시오. Codex를 초기화하거나 네트워크에 접속하지 않고 실제 적용되는 모델과 추론 노력을 검사하려면 --dry-run을 추가하십시오.

출력 디렉터리는 스캔된 디렉터리 및 이를 포함하는 모든 Git 워크트리(worktree) 외부에 있어야 합니다. macOS 및 Linux의 경우, 기존 출력 디렉터리는 현재 사용자에게 비공개(chmod 700)여야 합니다. 스캔 아티팩트(artifacts)에는 소스 발췌본, 취약점 상세 정보 및 재현 단계가 포함될 수 있습니다. 이를 저장소, 공개 이슈 보고서 및 공유 위치에 두지 마십시오.

SARIF가 생성되면 <scan-dir>/exports/results.sarif에 기록됩니다. 모든 대상(target), 출력 및 런타임 옵션을 확인하려면 npx codex-security scan --help를 사용하십시오.

여러 파일 또는 디렉터리에 대해 --knowledge-base PATH를 반복하여 사용할 수 있습니다. 디렉터리는 Markdown, text, PDF 및 Word(.docx) 파일을 찾기 위해 재귀적으로 검색됩니다.

gh auth login으로 로그인한 다음, npx codex-security bulk-scan을 실행하여 지난 90일 동안 푸시된 GitHub 저장소(repositories)를 검색할 수 있습니다. 아카이브된 저장소와 포크(forks)는 제외됩니다. 저장소 목록을 검색하고, 스캔할 저장소를 선택한 후 스캔을 확인하십시오.

프라이빗 체크아웃(Private checkouts)은 전역 Git 설정을 변경하지 않고 GitHub CLI 로그인 정보를 재사용합니다. 자동화 또는 기존 저장소 목록을 사용하는 경우, id, repository, 그리고 전체 불변(immutable) revision 컬럼을 포함하는 CSV 파일을 전달하고 --output-dir을 지정하십시오. 모든 옵션은 npx codex-security bulk-scan --help를 통해 확인할 수 있습니다.

이 CLI는 에이전트 친화적인 검색(discovery)과 구조화된 출력을 위해 Incur를 사용합니다. 명령 매니페스트(command manifest)를 보려면 --llms를 사용하고, 명령 스키마(command schema)를 보려면 scan --schema --format json을 사용하십시오. mcp add로 MCP 서버를 등록하고, skills add로 에이전트 기술(skills)을 동기화하며, 쉘 완성(shell completions)을 위해 completions bash|zsh|fish를 사용하십시오. 스캔 결과는 --format toon|json|yaml|jsonl 및 --full-output을 지원합니다.

SDK 및 번들된 플러그인(bundled-plugin) 메타데이터를 확인하려면 info --json을 사용하십시오. MCP는 이 읽기 전용(read-only) 메타데이터 명령만 노출합니다. 스캔, 인증, 내보내기(exports), 검증(validation) 및 패칭(patching)은 MCP 전송(transport) 방식이 활성 스캔을 취소할 수 없기 때문에 CLI 전용으로 유지됩니다.

출력 디렉터리에 이미 결과가 포함되어 있는 경우 --archive-existing을 추가하십시오. CLI는 기존 결과들을 <output-dir>.previous-<timestamp>-<id>로 이동시키고, 원래 경로의 새로운 빈 디렉터리에서 스캔을 시작합니다. 파일을 이동하지 않고 목적지를 확인하려면 --dry-run을 추가하십시오.

스캔은 기본적으로 보고 전용(report-only)입니다. CI에서 완료된 스캔에 선택한 심각도(severity) 이상의 탐지 결과(finding)가 포함된 경우 종료 코드 1을 반환하려면 --fail-on-severity를 사용하십시오. 불완전한 커버리지(coverage) 및 CLI/런타임 오류는 종료 코드 2를 반환합니다. 불완전한 스캔이라도 보고 전용 모드를 포함하여 사용 가능한 인간용 또는 JSON 결과를 stdout에 작성하고, 커버리지 경고를 stderr에 작성합니다.

CI의 경우, 기계가 읽을 수 있는(machine-readable) 출력을 체크아웃된 저장소 외부로 저장하고 심각도 정책(severity policy)을 적용하십시오. 불완전한 커버리지 및 런타임 오류는 여전히 0이 아닌 종료 코드를 반환합니다:

SCAN_ROOT="$(mktemp -d)"
npx codex-security scan . \
  --diff origin/main \
...

JSON 스캔은 stderr가 터미널인 경우를 포함하여 비대화형 (noninteractive) 상태를 유지합니다. Codex를 대화형으로 실행하는 명령(validate, patch, login, logout)은 --json 옵션을 거부합니다. JSON 출력이 선택된 경우 CSV 내보내기(exports)를 파일로 작성하십시오.

스캔은 기본적으로 추가적인 고도의 추론 노력 (extra-high reasoning effort)을 사용하는 gpt-5.6-sol을 사용합니다. --model을 사용하여 모델을 전환할 수 있습니다. 다른 Codex 설정을 사용하려면 --codex를 사용하십시오:

npx codex-security scan . --model gpt-5.6-terra --codex 'model_reasoning_effort="high"'

스캔은 요청된 경로와 실제 랭킹 (ranking), 파일 검토 (file-review), 검증 (validation), 그리고 공격 경로 (attack-path) 단계를 보고합니다. 완료 시에는 발견된 심각도 (severity), 커버리지 (coverage), 경과 시간 (elapsed time), 사용 가능한 토큰 및 워커 수 (worker counts), 결과 디렉토리, 그리고 다음에 사용할 수 있는 유용한 명령어를 보여줍니다. 진행 상황은 stderr에 유지되며, JSON 결과는 stdout에 유지됩니다.

TypeScript SDK 사용하기

클라이언트를 생성하고, 저장소 외부의 프라이빗 출력 디렉토리를 선택한 다음, 스캔 후 클라이언트를 종료하십시오:

import { CodexSecurity } from "@openai/codex-security";

const security = new CodexSecurity();
...

SDK는 또한 경로 및 diff 대상, 프리플라이트 (preflight), 진행 콜백 (progress callbacks), 취소 (cancellation), 보안 지식 베이스 (security knowledge bases), 그리고 타입이 지정된 스캔 결과 (typed scan results)를 지원합니다.

Docker에서 대량 스캔 실행하기

포함된 Docker 이미지는 Linux Docker 호스트에서 제공된 CSV를 사용하여 비대화형 대량 스캔을 실행합니다. 포함된 compose.yaml은 이미지, 지속성 파일 (persistent files), 그리고 강화된 Codex 명령 샌드박스 (hardened Codex command sandbox)를 구성합니다.

저장소당 하나의 완전하고 불변하는(immutable) Git 커밋을 포함하는 repositories.csv를 생성하십시오:

id,repository,revision
payments,https://github.com/example/payments.git,0123456789abcdef0123456789abcdef01234567

프라이빗하고 지속적인 결과 및 인증 디렉토리를 생성하고, 컨테이너가 현재 사용자와 동일한 권한으로 파일을 작성할 수 있도록 설정하십시오:

mkdir -p results state
chmod 700 results state
export CODEX_SECURITY_USER="$(id -u):$(id -g)"
...

원격 또는 헤드리스 (headless) Docker 호스트에서 일회성 로그인을 수행하려면 다음을 실행하십시오:

docker compose run --rm codex-security login --device-auth

표시된 인증 URL을 브라우저에서 열고 일회성 코드를 입력하십시오. 로그인은 컨테이너가 종료된 후에도 state/ 디렉토리에 유지됩니다.

또는 호스트 환경 변수나 비밀 관리자 (secret manager)를 통해 OPENAI_API_KEY 또는 CODEX_API_KEY를 제공하십시오. 프라이빗 리포지토리 (private repositories)의 경우, 동일한 방식으로 GH_TOKEN 또는 GITHUB_TOKEN을 제공하십시오. Compose는 이름이 지정되고 구성된 자격 증명 (credentials)만을 컨테이너로 전달합니다.

기본 명령으로 재개 가능한 4개의 워커 (worker) 스캔을 시작하십시오:

docker compose run --rm codex-security

기본적인 초고성능 추론 (extra-high reasoning) 설정에서는 전체 리포지토리 스캔이 리포지토리당 수십 분이 소요될 수 있습니다. 대규모 캠페인은 비동기 배치 작업 (asynchronous batch jobs)으로 실행하고, 실행하는 동안 결과 및 인증 디렉토리를 마운트 (mount)된 상태로 유지하십시오.

완료된 보고서, 리포지토리별 탐지 결과 (findings), 그리고 스캔 매니페스트 (scan manifest)는 호스트의 results/에 나타납니다. 해당 캠페인의 워크벤치 상태 (workbench state)는 results/.codex-security-state/에 유지되며, 재사용 가능한 Codex 로그인은 state/에 별도로 유지됩니다. 이를 통해 새로운 결과 디렉토리가 이전 스캔과 충돌하지 않고 동일한 로그인 정보로 별도의 캠페인을 시작할 수 있습니다. 중단된 스캔을 재개하려면 원래의 CSV 파일과 동일한 results/ 및 state/ 디렉토리를 사용하여 동일한 명령을 다시 실행하십시오.

병렬 워커의 수를 변경하거나 실패한 리포지토리를 재시도하려면 기본 스캔 명령을 재정의하십시오:

docker compose run --rm codex-security \
  bulk-scan /input/repositories.csv \
  --output-dir /output \
...

Compose 프로젝트 외부의 기존 파일 또는 디렉터리를 사용하려면 CODEX_SECURITY_CSV, CODEX_SECURITY_RESULTS 또는 CODEX_SECURITY_STATE를 설정하세요. 승인되었고 이미 빌드된 이미지를 사용하려면 CODEX_SECURITY_IMAGE를 설정하세요. GitHub Enterprise Server에 접속할 때는 CODEX_SECURITY_GIT_HOST를 설정하세요. 자격 증명(credentials), 리포지토리(repository) 목록 및 결과물은 이미지와 Git에 포함되지 않도록 유지하십시오. 포함된 ignore 파일들이 이미지 빌드 및 커밋에서 이를 제외합니다.
모든 CSV 파일(사용자 정의 이름의 리포지토리 인벤토리 포함)은 Docker 빌드 컨텍스트(build context)에서 제외됩니다. 대신 Compose는 런타임(runtime)에 선택된 CSV를 마운트(mount)합니다.

포함된 Compose 설정은 모든 Linux 기능(capabilities)을 제거하고, 새로운 권한 부여를 방지하며, 비루트(nonroot) 사용자로 실행하고, 제공된 기본 거부(default-deny) seccomp 프로필을 적용합니다. Codex Security는 각 스캔 명령을 별도의 권한이 없는 Linux 샌드박스(sandbox)에서 실행합니다. Docker의 기본 seccomp 프로필은 해당 샌드박스에 필요한 사용자 및 마운트 네임스페이스(namespaces)를 차단하므로, 제공된 프로필은 필요한 네임스페이스 작업만 허용합니다. Linux 호스트는 권한이 없는 사용자 네임스페이스(unprivileged user namespaces)를 허용해야 합니다. 일부 Docker Desktop 가상 머신은 중첩된 마운트 네임스페이스를 추가로 제한하므로, 프로덕션(production) 스캔에는 Linux 호스트를 사용하십시오.

Docker Compose가 없는 환경의 경우, 이에 상응하는 하위 수준(lower-level) 호출 방식은 다음과 같습니다:

docker run --rm --init \
  --user "$(id -u):$(id -g)" \
  --cap-drop ALL \
...

GitHub 토큰이 제공되면 이미지는 github.com에 대한 비대화형(noninteractive) Git 자격 증명 헬퍼(credential helper)를 구성합니다. 이 토큰은 SSH 에이전트(agent)를 마운트하지 않고도 HTTPS 리포지토리 URL과 git@github.com: 리포지토리 URL 모두에서 작동합니다. 이미지는 해당 토큰을 리포지토리 URL에 배치하거나, 이미지 레이어(layers)에 쓰거나, 다른 Git 호스트로 전송하지 않습니다. 필요한 경우 CODEX_SECURITY_GIT_HOST를 GitHub Enterprise Server 인스턴스의 호스트 이름으로 설정하세요.

--workers를 사용하여 동시 리포지토리 스캔을 제어하고, --max-attempts를 사용하여 실패 시 재시도하십시오. 명령은 리포지토리 중 하나라도 실패하면 0이 아닌 상태 코드를 반환합니다.

스캔 기록 및 재실행

npx codex-security scans list는 현재 리포지토리 (repository)의 스캔 목록을 나열합니다. 다른 체크아웃 (checkout)을 검사하려면 리포지토리 경로를 전달하고, 스캔 아티팩트 (artifact) 디렉토리로 필터링하려면 --scan-root DIR을 사용하십시오. scans show SCAN_ID는 저장된 설정 (configuration), 발견 사항 (findings) 및 커버리지 (coverage)를 포함합니다.

기록은 기존 Codex Security 워크벤치 (workbench) 데이터베이스의 $CODEX_HOME/state/plugins/codex-security에 저장됩니다. 다른 위치를 선택하려면 CODEX_SECURITY_STATE_DIR을 설정하십시오.

scans rerun SCAN_ID는 현재 체크아웃에 대해 동일한 설정을 반복합니다. scans match BEFORE_SCAN_ID AFTER_SCAN_ID는 동일한 근본 원인 (root cause)을 가진 발견 사항들을 연결합니다. scans match --all은 다른 워크트리 (worktree) 및 클론 (clone)을 포함하여 현재 리포지토리의 사용 가능한 모든 완료된 스캔을 포함합니다. 저장된 매치 (matches)를 다시 계산하려면 --force를 사용하십시오.

scans compare BEFORE_SCAN_ID AFTER_SCAN_ID는 저장된 매치를 읽어 새로운 (new), 지속되는 (persisting), 다시 열린 (reopened), 해결된 (resolved) 또는 알 수 없는 (unknown) 발견 사항을 식별합니다. 커버리지가 불완전하거나 원래 위치가 검토되지 않은 경우 누락된 발견 사항은 알 수 없는 (unknown) 상태로 유지됩니다.