Codex Security: 취약점 탐지부터 검증, 패치까지 수행하는 OpenAI의 보안 스캔 CLI 및 SDK

9bow · 8월 3, 2026, 3:30오전

Codex Security 소개

코드베이스가 커질수록 보안 취약점을 찾는 일은 소수의 보안 담당자에게 몰리기 마련입니다. 정적 분석 도구를 도입해도 오탐(false positive)이 쌓이면 결과 목록을 훑는 것 자체가 일이 되고, 정작 위험한 취약점은 검토 대기열에 묻히기 쉽습니다. 발견 이후도 문제입니다. 취약점이 실제로 재현되는지 확인하고, 수정 패치를 만들고, 고친 코드가 안전한지 다시 확인하는 과정 대부분이 여전히 수작업으로 남아 있기 때문입니다.

Codex Security 는 이 흐름 전체를 다루는 OpenAI의 애플리케이션 보안 에이전트로, 코드의 보안 취약점을 찾고(find), 검증하고(validate), 수정(fix)하는 CLI와 TypeScript SDK를 오픈소스 npm 패키지 @openai/codex-security 로 제공합니다. 미리 정의된 시그니처 목록 대신 저장소별 위협 모델과 실제 코드 맥락을 바탕으로 취약점 후보를 찾고, 신호가 강한 발견은 격리된 환경에서 검증을 거친 뒤에야 결과로 보여줍니다. OpenAI는 이 접근을 "일반적인 시그니처 대신 저장소에 특화된 맥락(repo-specific context instead of generic signatures)" 이라는 문구로 요약합니다.

같은 스캐너를 Codex 데스크톱 앱의 Security 워크벤치, 터미널 CLI, TypeScript SDK, GitHub 저장소를 연동하는 Codex 클라우드(리서치 프리뷰)라는 네 가지 방식으로 쓸 수 있습니다. 스캔 결과는 SARIF·CSV·JSON으로 내보내 기존 보안 파이프라인과 연결되고, CI와 커밋 전(pre-commit) 훅에도 붙습니다. 본 게시물에서는 Codex Security의 동작 방식과 핵심 명령, SDK 사용법을 정리합니다.

기존 보안 스캐너와 Codex Security의 차이

규칙 기반 정적 분석(SAST) 도구는 빠르고 예측 가능하지만, 저장소의 구조나 인증 흐름 같은 맥락을 모른 채 패턴을 매칭하기 때문에 오탐이 많은 것으로 알려져 있습니다. Codex Security가 공식 문서에서 내세우는 차별점은 세 가지입니다. 저장소에서 만든 위협 모델과 코드 맥락으로 그 저장소에서 실제로 위험한 지점을 찾고, 신호가 강한 발견을 격리 환경에서 검증해 노이즈를 줄이며, 근거가 붙은 순위별 결과를 수정 패치 옵션까지 이어서 제공합니다.

구분	규칙 기반 SAST	Codex Security
탐지 기준	미리 정의된 규칙·시그니처	저장소별 위협 모델 + 코드 맥락
오탐 대응	결과를 사람이 선별	격리 환경 검증 후 노출, 오탐 사유 기록(`findings false-positive`)
발견 이후	별도 수작업	`validate` 로 재현 확인, `patch` 로 수정 제안
스캔 간 추적	도구별 상이	`scans compare` 가 근본 원인 기준으로 신규·지속·재발·해결을 분류

표의 Codex Security 열은 README와 공식 문서의 설명을 옮긴 것이며, 탐지 품질에 대한 공개 벤치마크 수치는 아직 저장소와 문서에서 찾을 수 없었습니다.

누구에게 유용한가

GitHub와 CI 중심으로 개발하면서 OpenAI 계정 기반의 Codex Security 접근 권한을 확보할 수 있는 팀이라면, 취약점 탐지부터 검증과 패치 제안, 스캔 이력 추적까지 한 도구로 묶을 수 있어 도입 효과가 큽니다. 반대로 모델 호출 없이 완전히 폐쇄망에서 도는 스캐너가 필요한 조직에는 맞지 않습니다. 스캔이 Codex 모델 실행을 전제로 하고, 비용도 --max-cost 옵션으로 상한을 걸어 관리하는 구조이기 때문입니다. 실행 환경도 Node.js 22.13.0 이상(22.x·24.x·26.x)과 Python 3.10 이상을 요구하므로, 도입 전에 CI 러너 사양을 먼저 확인하는 편이 좋습니다.

Codex Security의 구성 요소와 동작 방식

어떤 인터페이스로 시작하든 실제 스캔은 같은 Codex Security 플러그인과 Codex 런타임이 수행합니다. Codex 데스크톱 앱에 플러그인을 설치하면 사이드바에 Security 워크벤치가 열리고, 스캔(Scans)·발견(Findings)·저장소(Repositories) 화면에서 스캔 진행 상황과 미해결 발견을 한곳에서 관리합니다. 터미널과 CI에서는 CLI가 같은 스캐너를 실행하고, TypeScript SDK는 이를 애플리케이션 안에 내장할 수 있게 합니다. GitHub 저장소를 연동하는 Codex 클라우드는 리서치 프리뷰 단계로, 연동된 저장소를 커밋 단위로 스캔합니다.

스캔 대상은 저장소 전체뿐 아니라 특정 경로(--path), 커밋된 diff(--diff), 작업 트리 변경분(--working-tree)까지 좁힐 수 있고, 더 넓은 검토가 필요하면 deep 모드를 사용합니다. 아키텍처 문서나 보안 정책, 위협 모델 문서를 --knowledge-base 로 넘기면 스캔 맥락에 반영됩니다. 스캔 이력은 상태 디렉토리에 저장되며, scans compare 는 두 스캔의 발견을 근본 원인 기준으로 매칭해 신규·지속·재발·해결·미확인으로 분류합니다.

Codex Security의 주요 CLI 명령

README와 저장소의 sdk/typescript/README.md 에 정리된 명령 중 핵심을 추리면 다음과 같습니다.

# 저장소 스캔 (모델과 추론 강도 지정 가능)
npx @openai/codex-security scan . --model gpt-5.6-terra --effort high

# 커밋된 변경분만 스캔해 JSON으로 출력 (PR 리뷰, CI용)
npx @openai/codex-security scan /path/to/repository --diff origin/main --json

# 예상 모델 비용 상한 설정
npx @openai/codex-security scan /path/to/repository --max-cost 5

# 커밋 전마다 변경분을 스캔하는 pre-commit 훅 설치
npx @openai/codex-security install-hook

# 두 스캔 결과를 근본 원인 기준으로 비교
npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

# 오탐 피드백 기록
npx @openai/codex-security findings false-positive OCCURRENCE_ID --reason "The route already checks permissions"

# SARIF 형식으로 내보내기
npx @openai/codex-security export /path/outside/repository/results --export-format sarif --output /path/outside/repository/results.sarif

# 특정 발견의 재현 여부 검증, 수정 패치 생성
npx @openai/codex-security validate /path/outside/repository/findings.json "Possible SQL injection in src/query.ts:42"
npx @openai/codex-security patch /path/outside/repository/findings.json "Missing authorization check in src/routes.ts:18"

install-hook 은 기존 훅을 대체하지 않고 core.hooksPath 설정을 존중하며, 심각도 높음(high) 이상의 발견이나 스캔 실패 시 커밋을 차단합니다. 차단 기준은 --fail-on-severity 로 조정합니다. CSV 인벤토리를 기반으로 여러 저장소를 이어서 스캔하는 bulk-scan 명령과, 불변 Git 리비전에 고정된 저장소를 비대화형으로 스캔하는 공식 Docker 이미지·Compose 구성도 함께 제공됩니다.

TypeScript SDK로 Codex Security 스캔 내장하기

TypeScript SDK는 스캔 실행을 애플리케이션이나 개발 도구 안에 넣을 때 사용합니다. 저장소에 있는 최소 예시는 다음과 같습니다.

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

const security = new CodexSecurity();

try {
  const result = await security.run("/path/to/repository", {
    outputDir: "/path/outside/repository/results",
  });

  console.log(result.reportPath);
  console.log(result.findings.findings.length);
} finally {
  await security.close();
}

security.run() 의 옵션으로 표준/딥 모드(mode), 지식 베이스 경로(knowledgeBasePaths), 비용 상한(maxCostUsd), 결과 디렉토리(outputDir) 등을 지정하고, AbortSignal 로 진행 중인 스캔을 취소할 수 있습니다. onWorkerStatus 나 onCost 같은 콜백을 등록하면 장시간 스캔의 진행 상황과 비용을 관찰할 수 있습니다. 스캔 결과에는 소스 발췌와 취약점 상세, 재현 단계가 포함될 수 있으므로, 결과 디렉토리를 저장소 밖에 두고 접근 권한을 제한하라고 안내합니다.

Codex Security 설치 및 첫 스캔

Node.js 22.13.0 이상(22.x 라인)·24.x·26.x 중 하나와 Python 3.10 이상, 그리고 Codex Security 접근 권한이 필요합니다. OpenAI는 Trusted Access 인증을 거친 계정에서 가장 좋은 결과를 얻을 수 있다고 안내합니다.

npm install @openai/codex-security
npx @openai/codex-security login
npx @openai/codex-security scan .

로컬에서는 ChatGPT 계정으로 로그인하고, CI에서는 OPENAI_API_KEY 또는 CODEX_API_KEY 환경 변수를 설정합니다. 환경 변수로 넘긴 API 키는 현재 스캔에만 전달되고 자격증명 저장소나 시스템 키링에 저장되지 않습니다. 두 자격증명이 모두 있을 때는 --auth chatgpt / --auth api-key 플래그로 어느 쪽을 쓸지 명시할 수 있습니다.

Codex Security의 라이선스

Codex Security는 Apache License 2.0으로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다. 단, 라이선스는 이 저장소의 CLI와 SDK 코드에 적용되는 것이고, 스캔 실행에 필요한 Codex Security 서비스 접근 권한은 별도입니다.

Codex Security 공식 홈페이지

Codex Security 문서 사이트

Codex Security GitHub 저장소

더 읽어보기

이 글은 GPT 모델로 정리한 초안을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 댓글로 알려주시기를 부탁드립니다.

이 도구를 직접 설치해 사용해보셨다면, 파이토치 한국 사용자 모임 회원들을 위해 경험이나 팁을 댓글로 남겨주세요!