openai-codex-security

OpenAI Codex Security

Skill by ara.so — Codex Skills collection.

OpenAI's Codex Security is a CLI and TypeScript SDK that uses AI to find, validate, and fix security vulnerabilities in your codebase. It supports multiple programming languages and integrates into development workflows and CI/CD pipelines.

Installation

Requirements:

• Node.js 22.13.0+ (22.x), 24.x, or 26.x
• Python 3.10 or later
• Access to Codex Security (requires OpenAI account)

npm install @openai/codex-security

For global CLI usage:

npm install -g @openai/codex-security

Authentication

Interactive Login (Local Development)

npx @openai/codex-security login

This stores credentials in Codex's credential backend, including system keyring support for managed devices.

API Key Authentication (CI/CD)

Set one of these environment variables:

export OPENAI_API_KEY=your-api-key-here
# or
export CODEX_API_KEY=your-api-key-here

Environment API keys take precedence and are never stored persistently.

Choosing Authentication Method

# Use ChatGPT login
npx @openai/codex-security scan . --auth chatgpt

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

To make ChatGPT login the default, unset API keys:

unset OPENAI_API_KEY CODEX_API_KEY

CLI Commands

Basic Scan

Scan current directory:

npx @openai/codex-security scan .

Scan specific directory:

npx @openai/codex-security scan /path/to/project

Advanced Scanning

Use specific model and effort level:

npx @openai/codex-security scan . --model gpt-5.6-terra --effort high

Scan with custom output:

npx @openai/codex-security scan . --output-format json
npx @openai/codex-security scan . --output-file security-report.json

Login Management

# Login to Codex Security
npx @openai/codex-security login

# Logout
npx @openai/codex-security logout

# Check authentication status
npx @openai/codex-security whoami

TypeScript SDK

Basic Usage

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

async function scanProject() {
  const security = new CodexSecurity();
  
  try {
    const result = await security.run(".");
    console.log("Scan complete!");
    console.log("Report path:", result.reportPath);
    console.log("Vulnerabilities found:", result.vulnerabilities.length);
  } finally {
    await security.close();
  }
}

scanProject();

Custom Configuration

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

const security = new CodexSecurity({
  model: "gpt-5.6-terra",
  effort: "high",
  apiKey: process.env.OPENAI_API_KEY,
});

const result = await security.run("/path/to/project", {
  exclude: ["node_modules", "dist", "*.test.ts"],
  include: ["src/**/*.ts", "lib/**/*.js"],
});

console.log(`Found ${result.vulnerabilities.length} vulnerabilities`);

for (const vuln of result.vulnerabilities) {
  console.log(`- ${vuln.severity}: ${vuln.title}`);
  console.log(`  File: ${vuln.file}:${vuln.line}`);
  console.log(`  Description: ${vuln.description}`);
}

await security.close();

Processing Scan Results

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

async function analyzeSecurity() {
  const security = new CodexSecurity();
  const result = await security.run(".");

  // Filter by severity
  const critical = result.vulnerabilities.filter(
    v => v.severity === "critical"
  );
  const high = result.vulnerabilities.filter(
    v => v.severity === "high"
  );

  console.log(`Critical issues: ${critical.length}`);
  console.log(`High severity issues: ${high.length}`);

  // Group by file
  const byFile = result.vulnerabilities.reduce((acc, vuln) => {
    acc[vuln.file] = acc[vuln.file] || [];
    acc[vuln.file].push(vuln);
    return acc;
  }, {} as Record<string, typeof result.vulnerabilities>);

  console.log("\nVulnerabilities by file:");
  for (const [file, vulns] of Object.entries(byFile)) {
    console.log(`${file}: ${vulns.length} issues`);
  }

  await security.close();
}

analyzeSecurity();

Validating Specific Vulnerabilities

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

async function validateVulnerability(vulnId: string) {
  const security = new CodexSecurity();
  
  const result = await security.run(".");
  const vuln = result.vulnerabilities.find(v => v.id === vulnId);
  
  if (!vuln) {
    console.log("Vulnerability not found");
    await security.close();
    return;
  }

  console.log("Vulnerability Details:");
  console.log(`ID: ${vuln.id}`);
  console.log(`Severity: ${vuln.severity}`);
  console.log(`Title: ${vuln.title}`);
  console.log(`File: ${vuln.file}:${vuln.line}`);
  console.log(`Description: ${vuln.description}`);
  
  if (vuln.recommendation) {
    console.log(`\nRecommendation: ${vuln.recommendation}`);
  }
  
  if (vuln.codeSnippet) {
    console.log(`\nCode:\n${vuln.codeSnippet}`);
  }

  await security.close();
}

CI/CD Integration

GitHub Actions

name: Security Scan

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '22'
      
      - name: Install Codex Security
        run: npm install -g @openai/codex-security
      
      - name: Run Security Scan
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: codex-security scan . --auth api-key --output-format json --output-file security-report.json
      
      - name: Upload Results
        uses: actions/upload-artifact@v3
        with:
          name: security-report
          path: security-report.json

GitLab CI

security_scan:
  image: node:22
  script:
    - npm install -g @openai/codex-security
    - codex-security scan . --auth api-key --output-format json --output-file security-report.json
  variables:
    OPENAI_API_KEY: $OPENAI_API_KEY
  artifacts:
    reports:
      security: security-report.json

Jenkins Pipeline

pipeline {
  agent any
  
  environment {
    OPENAI_API_KEY = credentials('openai-api-key')
  }
  
  stages {
    stage('Security Scan') {
      steps {
        sh 'npm install -g @openai/codex-security'
        sh 'codex-security scan . --auth api-key --output-format json --output-file security-report.json'
        archiveArtifacts artifacts: 'security-report.json'
      }
    }
  }
}

Configuration

Environment Variables

• OPENAI_API_KEY or CODEX_API_KEY: API key for authentication
• CODEX_SECURITY_STATE_DIR: Custom state directory for scan history (useful when repository directory is read-only)

Scan Configuration

Common options:

• --model <model>: AI model to use (e.g., gpt-5.6-terra)
• --effort <level>: Scan effort level (low, medium, high)
• --auth <method>: Authentication method (chatgpt, api-key)
• --output-format <format>: Output format (text, json, sarif)
• --output-file <path>: Save report to specific file
• --exclude <patterns>: Exclude files/directories from scan
• --include <patterns>: Include only specific files/directories

Common Patterns

Pre-commit Hook

#!/bin/bash
# .git/hooks/pre-commit

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

if [ $? -ne 0 ]; then
  echo "Security scan failed. Commit aborted."
  exit 1
fi

Automated Fix Application

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

async function autoFix() {
  const security = new CodexSecurity();
  const result = await security.run(".");

  for (const vuln of result.vulnerabilities) {
    if (vuln.autoFix && vuln.severity === "critical") {
      console.log(`Auto-fixing: ${vuln.title} in ${vuln.file}`);
      // Apply fix (implementation depends on vuln.autoFix structure)
    }
  }

  await security.close();
}

Progressive Scanning

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

async function progressiveScan() {
  const security = new CodexSecurity();

  // Quick scan first
  console.log("Running quick scan...");
  let result = await security.run(".", { effort: "low" });
  
  if (result.vulnerabilities.some(v => v.severity === "critical")) {
    console.log("Critical issues found, running deep scan...");
    result = await security.run(".", { effort: "high" });
  }

  await security.close();
  return result;
}

Troubleshooting

Authentication Issues

Problem: "Authentication failed" or "Invalid API key"

Solutions:

• Verify API key is set correctly: echo $OPENAI_API_KEY
• Try explicit authentication: npx @openai/codex-security login
• Check API key permissions in OpenAI dashboard
• Ensure you have access to Codex Security

Node.js Version Errors

Problem: "Unsupported Node.js version"

Solutions:

• Check version: node --version
• Install compatible version (22.13.0+, 24.x, or 26.x)
• Use nvm: nvm install 22 && nvm use 22

Scan History Not Saving

Problem: Cannot write scan history

Solution: Set custom state directory:

export CODEX_SECURITY_STATE_DIR=/tmp/codex-security-state
npx @openai/codex-security scan .

Memory Issues on Large Codebases

Problem: Out of memory errors

Solutions:

• Exclude large directories: --exclude node_modules,dist,build
• Scan incrementally by directory
• Use lower effort level: --effort low
• Increase Node.js memory: NODE_OPTIONS=--max-old-space-size=4096

False Positives

Problem: Too many false positive vulnerabilities

Solutions:

• Use higher confidence threshold in SDK options
• Review and filter results by severity
• Exclude test files and generated code
• Report false positives to improve model accuracy

CI/CD Failures

Problem: Scans fail in CI/CD pipeline

Solutions:

• Ensure Python 3.10+ is installed in CI environment
• Verify API key is properly set as secret
• Use --auth api-key explicitly in CI
• Check CI runner has sufficient memory and CPU
• Add timeout handling for long scans