How to Run a Comprehensive Security Audit with OpenAI Codex Security

How to Run a Comprehensive Security Audit with OpenAI Codex Security

Last week, I pushed a two-year-old internal tools project to GitHub. Less than half a day later, a stranger opened an issue pointing out a hardcoded AWS test key. It had minimal permissions, but it sure didn't look professional. Honestly, I was a bit embarrassed—not because I didn't know the risk, but because daily development moves so fast that security scans always get pushed down the backlog.

If you've faced similar situations: your project is growing, dependencies are multiplying, and manually reviewing security vulnerabilities is overwhelming, this guide is for you. I'll walk you through using OpenAI's official Codex Security tool, from zero-to-hero configuration, running a full code security scan, integrating the SDK into a TypeScript project for automated checks, and generating a professional security report. The whole process takes about 15-20 minutes. Once you're done, you'll have a clear picture of your project's security posture.

Prerequisites

Before we begin, ensure your environment meets these requirements:

• Node.js: 22.13.0+ (22.x branch), 24.x, or 26.x
• Python: 3.10+ (if using 3.10, install tomli as well)
• OpenAI API Key: You'll need an OpenAI account and an API key. If you have Daybreak Blue access, tutorial parameters will cover it; otherwise, the default standard mode works fine.
• A project directory to scan (your own repo or a cloned open-source project for practice)

## Check environment versions
node -v
python3 --version

Step 1: Installation and Authentication

Codex Security provides both a CLI and a TypeScript SDK. Let's start with the CLI to quickly run a scan.

## Install in current project (or globally with -g)
npm install @openai/codex-security

## Login to obtain access credentials
npx @openai/codex-security login

The login command will open a browser to guide you through OAuth authorization. If you're working on a remote server or a headless environment, use device authentication:

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

It will output a verification code in the terminal and prompt you to open a specified URL on another device with a browser to complete authorization. This is a thoughtful design that avoids wrestling with server-side browsers.

Why log in first? The scanning capabilities rely on AI models to analyze code context. Logging in fetches the necessary API credentials. In CI environments, you don't need the interactive login; just set OPENAI_API_KEY or CODEX_API_KEY as environment variables.

Step 2: Running Your First Scan

Once authenticated, it's time to scan your project. Navigate to your target directory (. represents the current directory):

## Scan current project using standard mode
npx @openai/codex-security scan . \
  --cyber-access-program standard

After scanning, the terminal lists discovered security issues. You can filter the scan scope using --path:

## Scan only src and tests directories
npx @openai/codex-security scan . --path src --path tests

## Scan changes from main branch to current HEAD (ideal for pre-commit checks)
npx @openai/codex-security scan . --diff origin/main

## Deep scan mode: more thorough but time-consuming
npx @openai/codex-security scan . --mode deep

Why so many modes? In daily development, you don't want a full scan on every commit. The --diff mode checks only changes, saving time and costs. --mode deep is best reserved for pre-release checks or auditing legacy codebases. Choose based on your scenario; don't blindly use the strongest mode to save tokens and time.

Step 3: Generating a SECURITY.md

Many open-source projects include a SECURITY.md in the root to guide external reporters on how to disclose vulnerabilities. Codex Security can auto-draft this for you:

## Generate a security policy draft for the entire project
npx @openai/codex-security policy .

## Generate for a specific service component, referencing architecture docs
npx @openai/codex-security policy . --path services/api --knowledge-base architecture.md

The draft is saved outside your project directory for you to review before committing. Do not use it as a final file directly; AI-generated content requires adjustments based on your project's actual setup. Its real value lies in providing a solid framework, saving you from hunting for templates from scratch.

Hands-On: Securing an Express API Project

Commands are great, but let's ground this in a real-world scenario.

Suppose you have a REST API built with Express, structured like this:

my-api/
├── src/
│   ├── routes/
│   ├── middleware/
│   └── db.js
├── tests/
├── package.json
└── .env

You want to automatically run a security scan before every PR merge. Here's how:

1. Install the dependency in your project

cd my-api
npm install @openai/codex-security

2. Add a scan script to package.json

{
  "scripts": {
    "security-scan": "npx @openai/codex-security scan . --path src"
  }
}

Now team members can just run npm run security-scan without memorizing long CLI flags.

3. Integrate the SDK in a TypeScript Project

If you want to embed security scans into build pipelines or custom scripts, the SDK is your best bet:

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

const security = new CodexSecurity();

try {
  // Scan the specified repository path
  const result = await security.run("./src");
  console.log("Scan complete. Report path:", result.reportPath);
  
  // You can process the result object further,
  // e.g., check for critical vulnerabilities and decide whether to block the build
} finally {
  // Releases resources occupied during the scan. Don't forget this!
  await security.close();
}

This code works perfectly in CI pipelines or as part of a local pre-commit hook. The close() in the finally block is crucial for resource cleanup.

4. Export Reports

After scanning, you can export results to SARIF (supported by GitHub Code Scanning), JSON, or CSV:

## Export threat model
npx @openai/codex-security export --artifact threat-model --output threatmodel.md

## Export using a specific scan ID
npx @openai/codex-security export --scan SCAN_ID --artifact threat-model --output threatmodel.md

If --scan is omitted, it defaults to the most recent completed scan in the repo. The exported files can be attached directly to PR descriptions or shared internally.

Troubleshooting & FAQs

Q1: I get a prompt requiring Daybreak Blue permissions, but I don't have them. What should I do?
Remove the --cyber-access-program daybreak_blue flag, or explicitly set --cyber-access-program standard. The standard mode is sufficient for most projects.

Q2: How do I configure authentication in CI environments?
Set OPENAI_API_KEY or CODEX_API_KEY in your CI job's environment variables to skip the login step. In GitHub Actions, reference it securely as ${{ secrets.CODEX_SECURITY_API_KEY }}.

Q3: The scan is stuck or running extremely slow?
Deep mode (--mode deep) spawns multiple parallel worker threads, which can take longer on large repos. Use --diff for incremental CI scans and schedule full scans periodically (e.g., weekly). Also, verify your Node.js version meets the requirements, as mismatched versions can cause the scan engine to crash unexpectedly.

Q4: Does it support other AI providers?
Yes. Besides OpenAI, you can use Amazon Bedrock, OpenRouter, and Fireworks AI. Bedrock utilizes AWS credentials directly, bypassing the need for OpenAI login. Refer to the project's provider documentation for configuration details.

Summary

Let's recap what we covered today:

1. Installed @openai/codex-security and authenticated via login
2. Scanned the project using the scan command, leveraging --path, --diff, or --mode deep as needed
3. Generated a SECURITY.md draft with policy, and exported scan reports with export
4. Integrated the SDK into a TypeScript project to automate security checks

Security scanning isn't a one-time chore. My recommendation: run a full baseline scan locally first to understand your current posture. Then, configure --diff incremental scans in CI to catch new issues early. Finally, schedule deep scans monthly or quarterly, combining them with exported threat models during code reviews.

If you're interested in exploring further, check out the GitHub repository: openai/codex-security. The documentation covers GitHub Actions setup, batch scanning for container deployments, and detailed guides for the Findings Service. In security, early action beats late remediation every time. Spend 15 minutes running a scan today, and it might just save you from a production incident tomorrow.