Codex Security CLI는 보안팀과 엔지니어링팀이 소유하거나 평가 권한이 있는 저장소에서 취약점을 찾고, 결과를 검토하고, 변경 전후의 보안 상태를 추적하게 하는 OpenAI의 명령줄 도구다. 패키지는 공개되어 있지만 실제 scan 실행에는 Codex Security 접근 권한이 필요하다.

설치와 인증

CLI는 Node.js 22 이상이 필요하고, scan이나 export에는 Python 3.10 이상도 필요하다.

npm install @openai/codex-security
npx @openai/codex-security --version
npx @openai/codex-security --help

로컬 대화형 사용은 ChatGPT 계정으로 로그인한다.

npx @openai/codex-security login

headless 환경은 device auth를 쓸 수 있다.

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

CI나 unattended scan에서는 API key를 환경 변수로 제공한다.

export OPENAI_API_KEY="<your-api-key>"

계정과 저장소에 따라 전체 저장소 scan에는 Trusted Access for Cyber가 추가로 필요할 수 있다.

첫 scan

결과 디렉터리는 저장소 밖의 private 위치로 잡는 편이 좋다. 결과에는 source excerpt와 취약점 세부정보가 포함될 수 있기 때문이다.

REPOSITORY=/path/to/repository
SCAN_DIR=/path/outside/repository/codex-security-results

npx @openai/codex-security scan "$REPOSITORY" \
  --output-dir "$SCAN_DIR" \
  --dry-run

npx @openai/codex-security scan "$REPOSITORY" \
  --output-dir "$SCAN_DIR"

기본 scan은 진행 상황과 요약을 stderr에 출력하고, 전체 결과는 파일로 남긴다. JSON이 필요하면 명시적으로 요청한다.

npx @openai/codex-security scan "$REPOSITORY" \
  --output-dir "$SCAN_DIR" \
  --json

산출물

scan directory에는 사람이 읽는 report.md와 자동화용 구조화 파일이 함께 생성된다.

codex-security-results/
├── scan-manifest.json
├── findings.json
├── coverage.json
├── report.md
├── artifacts/
└── exports/
    └── results.sarif

findings.json은 severity, confidence, location, evidence, remediation을 담고, coverage.json은 검토한 surface, 제외 영역, deferred work, open questions, coverage completeness를 기록한다. coverage는 complete, partial, unknown 중 하나일 수 있으므로, 결과를 보안 검토 증거로 쓰기 전에 deferred 영역과 open question을 읽어야 한다.

scan 모드

모델은 기본적으로 gpt-5.6-sol과 xhigh reasoning effort를 사용한다. 필요하면 모델과 effort를 지정할 수 있다.

npx @openai/codex-security scan "$REPOSITORY" \
  --model gpt-5.6-terra \
  --effort high

CI와 대량 scan

pre-commit hook을 설치하면 커밋 전 staged·unstaged 변경을 scan하고 high severity finding이나 scan error에서 차단할 수 있다.

npx @openai/codex-security install-hook

여러 저장소를 한 번에 scan하려면 GitHub 인증 후 bulk flow를 사용할 수 있다.

gh auth login
npx @openai/codex-security bulk-scan

준비된 CSV와 worker 수를 지정해 캠페인을 재개 가능한 방식으로 돌릴 수도 있다.

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

deepsec와의 차이

deepsec도 코딩 에이전트 기반 보안 하네스지만, 저장소 내부에 .deepsec 설정을 두고 matcher·investigation·revalidation 파이프라인을 직접 구성하는 오픈소스 도구에 가깝다. Codex Security CLI는 OpenAI의 접근 권한, scan history, finding 상태 관리, coverage artifact, CI·bulk scan workflow를 포함한 제품형 도구다.

관련 문서

• deepsec — 코딩 에이전트 기반 오픈소스 보안 하네스
• ai-pentesting — 추론 모델 기반 인증·비즈니스 로직 취약점 점검
• ai-agent-security-tips-docker-sandbox — 에이전트 실행 환경 격리와 권한 제어
• cybersecurity-evals — AI 보안 능력 평가 패턴

참고 자료

• Codex Security CLI quickstart — OpenAI 공식 문서 (2026-08-04)