openai/codex-security보안 취약점을 찾고, 검증하고, 수정하기 위한 OpenAI의 Codex Security CLI 및 TypeScript SDK. npm: https://www.npmjs.com/package/@openai/codex-security
Codex Security는 코드에서 취약점을 찾고, 조사하고, 수정하는 데 도움을 줍니다.
Codex에서 보안 워크플로를 사용하거나 @openai/codex-security CLI 및 TypeScript SDK로
자동화할 수 있습니다.
SECURITY.md 정책 초안을 작성하고 나중에 검토할 수 있도록 위협 모델을 저장합니다.Codex Security 플러그인이 활성화된 Codex 세션에서 저장소를 연 다음, 다음과 같이 요청하세요:
이 저장소에서 인증 및 권한 부여에 중점을 두고 Codex Security 스캔을 실행해 줘. 저장된 보고서, 소스 증거, 커버리지 한도를 반환해 줘.
완료된 스캔은 보고서, 발견 사항, 커버리지, 그리고 가능한 경우 위협 모델을 저장합니다. 이러한 결과를 사용하여 발견 사항을 조사하거나, 패치를 요청하거나, 기존 수정 사항을 확인하세요. 플러그인 설정, 작업 선택, 필수 도구를 사용할 수 없을 때의 복구 방법은 에이전트 워크플로 가이드를 참조하세요.
22.x 내의 Node.js 22.13.0+ 또는 Node.js 24.x나 26.x, 그리고 Python 3.10+가
필요합니다. Python 3.10은 tomli도 필요합니다.
CLI를 전역으로 설치하고 로그인하세요:
npm install --global @openai/codex-security
cs login
cs는 codex-security의 짧은 별칭이며, 두 명령 모두 동일한 CLI를 실행합니다.
설치 시 npm의 전역 실행 파일 디렉터리에 두 명령이 모두 생성되며,
해당 디렉터리는 PATH에 포함되어 있어야 합니다. cs가 이미 다른 도구로
해석된다면 대신 codex-security를 사용하세요. npm이 cs에 대해 EEXIST
오류로 중단되면 전역 설치 없이 npx @openai/codex-security를 사용하세요.
저장소 디렉터리에서 스캔을 실행하세요:
cs scan .
Daybreak Blue 액세스 권한이 있는 경우 스캔 명령에 --cyber-access-program daybreak_blue를 추가하세요. 그렇지 않으면 플래그를 생략하거나 --cyber-access-program standard를 사용하세요.
Codex의 Daybreak 토글을 사용하려면 --codex daybreak=true를 전달하세요. 기본값은 꺼짐이며 호환되는 액세스 권한이 필요합니다. Deep Scan 워커를 포함한 SDK 및 플러그인 사용법은 Daybreak 구성을 참조하세요.
스캔은 기존 SECURITY.md 지침을 사용합니다. 이를 정의하거나 업데이트하려면 선택적으로 정책 초안 작성을 수행하세요:
cs policy .
초안은 저장소 외부에 저장됩니다. diff와 노트를 검토하고, 초안을 편집한 다음, SECURITY.md만 표시된 Policy target에 복사하세요. 정책을 생성하지 않고 스캔할 수 있습니다.
전역 설치 없이 실행하려면 이 예시들에서 cs를 npx @openai/codex-security로 바꾸세요. 예를 들어:
npx @openai/codex-security scan .
CI의 경우 스캔 프로세스의 환경에 OPENAI_API_KEY 또는 CODEX_API_KEY를 설정하세요.
원격 또는 헤드리스 머신에서는 워크스페이스가 허용하는 경우 login --device-auth를 사용하거나, SSH를 통한 로그인을 사용하세요.
일부 사이버보안 요청 및 보호된 발견 사항에는 Trusted Access for Cyber 승인이 필요합니다.
범위와 스캔 모드를 선택하세요:
# Scan selected paths.
cs scan . --path src --path tests
# Scan committed changes from a base revision to HEAD.
cs scan . --diff origin/main
# Run a deep scan of the repository.
cs scan . --mode deep
권고 기준 15분의 Standard 조사 허용 시간을 적용하려면 cs scan . --max-time 15를 사용하세요. 타이밍 의미론과 Deep Scan 제한은 조사 시간을 참조하세요.
명령을 둘러보려면 cs --help를, 스캔 옵션, 비용 제한, 스캔 후 패치 적용에 대해서는 cs scan --help를 사용하세요.
여러 저장소에 걸쳐 있는 애플리케이션의 경우 여러 저장소에 걸친 하나의 시스템 검토를 참조하세요. 하나의 재개 가능한 캠페인에서 독립적인 저장소 검토를 수행하려면 대량 스캔을 사용하세요.
스캔 후에는 스캔 범위와 후속 작업 검토를 통해 기록된 제외 항목을 파악하고, 발견 사항을 검토할지, 집중 스캔을 실행할지, 또는 중단된 실행을 복구할지 결정하세요.
TypeScript 프로젝트에 패키지를 로컬로 설치하세요:
npm install @openai/codex-security
그런 다음 가져옵니다:
import { CodexSecurity } from "@openai/codex-security";
const security = new CodexSecurity();
try {
const result = await security.run("/path/to/repository");
console.log(result.reportPath);
} finally {
await security.close();
}
SDK 가이드에는 심층 스캔 구성, 검증, 심각도 분류, 소유자 제안 및 결과 처리가 포함되어 있습니다.
Codex Security Cloud를 계정에서 사용할 수 있는 경우, Security 플러그인의 $cloud-findings 스킬은 Codex 데스크톱 또는 Codex CLI에서 발견 사항, 보고서, 기록된 할당 및 검증, 스캔 상태를 읽을 수 있습니다. Cloud는 선택적 연결이며, 로컬 스캔은 없이도 작동합니다.
인증 요구 사항과 읽기 전용 예시는 Cloud 연결 설정 및 CLI 읽기를 참조하세요.
policy를 사용하여 새 SECURITY.md를 작성하거나 기존 파일을 업데이트하세요. --path를 사용하여 컴포넌트를 선택하세요:
cs policy .
cs policy . --path services/api --knowledge-base architecture.md
명령은 초안을 저장소 외부에 저장하고 기존 파일은 변경하지 않습니다. diff와 노트를 검토하고 초안을 편집한 다음, 표시된 정책 대상에 SECURITY.md만 복사하세요. 저장된 아키텍처 및 위협 모델 문서는 저장소 외부에 보관하세요.
스캔은 이미 루트 및 컴포넌트 SECURITY.md 파일을 사용합니다. 변경이 필요 없다면 현재 정책을 유지하세요. 정책을 업데이트할 때는 취약점 보고 지침을 보존하세요. 명령이 정책이 이미 최신이라고 표시하면 복사할 필요가 없습니다.
.github/SECURITY.md 또는 docs/SECURITY.md에 있는 파일에는 종종 보고 지침이 포함되어 있습니다. 정책을 작성할 때 이를 보존하세요. 해당 위치는 저장소 전체 스캔 지침을 자동으로 제공하지 않습니다. 정책 위치, 미해결 질문, 저장된 아티팩트 및 SDK 사용법은 정책 가이드를 참조하세요.
스캔과 정책 생성은 결과와 함께 위협 모델을 저장합니다. 추가 분석을 시작하지 않고 저장된 모델을 내보내려면:
cs export --scan SCAN_ID --artifact threat-model --output threatmodel.md
--scan을 생략하면 현재 저장소의 최근 완료된 스캔을 사용합니다.
내보내기 가이드에서는 발견 사항, CI용 SARIF 출력, 오프라인 TypeScript API도 다룹니다.
GitHub Action을 사용하여 예약, 수동 또는 풀 리퀘스트 스캔을 실행하세요. 주간
저장소 스캔을 위해서는 OpenAI API 키를 저장소 시크릿
CODEX_SECURITY_API_KEY로 추가한 다음, 이 워크플로를
.github/workflows/codex-security.yml에 저장하세요. REPLACE_WITH_REVIEWED_COMMIT을
Action 커밋의 전체 SHA로 교체하세요.
이 워크플로는 Daybreak Blue를 요청합니다. Blue가 활성화된 프로젝트의 API 키를
사용하세요. Daybreak 액세스 권한이 없는 경우 cyber-access-program을 생략하거나
standard로 설정하세요.
name: Codex Security
on:
workflow_dispatch:
schedule:
- cron: "23 7 * * 1" # Mondays at 07:23 UTC
permissions:
contents: read
jobs:
security:
runs-on: ubuntu-24.04
steps:
# Configure Bubblewrap and AppArmor so Codex Security can run safely in its sandbox.
- name: Set up the Ubuntu sandbox
run: |
sudo apt-get update
sudo apt-get install --yes bubblewrap apparmor-profiles
sudo apparmor_parser -r /usr/share/apparmor/extra-profiles/bwrap-userns-restrict
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: openai/codex-security@REPLACE_WITH_REVIEWED_COMMIT
with:
model: gpt-5.6-sol
effort: high
cyber-access-program: daybreak_blue
env:
OPENAI_API_KEY: ${{ secrets.CODEX_SECURITY_API_KEY }}
기본적으로 발견 사항은 보고만 됩니다. 보고된 발견 사항이 해당 임계값 이상일 때 실패하도록 심각도 임계값을 설정하세요. 스캐너 및 필수 보고 오류는 작업을 실패시키지만, 의도적인 파일 제외와 조사 노트는 그렇지 않습니다. PR 스캔, 심각도 임계값, 보고서 업로드에 대해서는 Action 설정 및 입력 참조를 참조하세요.
포함된 Docker Compose 구성을 사용하여 저장소 목록을 스캔할 수 있으며, 이 구성은 실행 간에 결과와 인증을 유지합니다. 컨테이너 빠른 시작을 참조하세요. 워크플로 러너는 개별 CLI 단계를 컨테이너에서 실행하며, 별도로 배포된 발견 사항 서비스에 연결할 수 있습니다.