One of the fastest-rising repositories on GitHub this week is openai/codex-security, OpenAI’s Codex Security CLI and TypeScript SDK for finding, validating and fixing security vulnerabilities in your code. It showed 11,503 stars on GitHub’s trending page on 11 November 2026. This tutorial walks through installing the CLI, running your first scan, narrowing scans to the code you care about, drafting a SECURITY.md, and automating scans in TypeScript and GitHub Actions, using only commands documented in the project’s README.

What Codex Security does

According to the README, Codex Security can:

  • Scan whole repositories, selected paths, or Git changes. A Deep scan repeats Standard scans and returns their deduplicated findings.
  • Validate candidate findings, generate patches and verify existing fixes.
  • Draft SECURITY.md policies and save threat models for later review.
  • Browse saved scans, spot duplicates, assess severity against your own rubric and suggest owners from source and Git history.
  • Export findings as SARIF, JSON or CSV, or track them in Linear, Jira or GitHub.

You can use it inside a Codex session through the Codex Security plugin, from the terminal with the cs CLI, or in automation with the TypeScript SDK and a GitHub Action.

Requirements

  • Node.js 22.13.0 or later within 22.x, or Node.js 24.x or 26.x
  • Python 3.10 or later (Python 3.10 also needs the tomli package)
  • An OpenAI account to sign in, or an API key for CI

Scans call OpenAI models, so they cost money. Start on a small repository or a single folder until you know what a typical scan costs you.

Step 1: Install and sign in

npm install --global @openai/codex-security
cs login

cs and codex-security are the same command. If cs clashes with another tool on your machine, use codex-security. To avoid a global install (or if npm reports an EEXIST conflict), use npx for both steps:

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

Step 2: Run your first scan

From the root of your repository:

cs scan .

When the scan finishes, the terminal prints a REPORT path. Open that Markdown file to see the findings, the source evidence behind each one, and the scan’s coverage limits and exclusions. To find the latest completed scan again later:

cs scans show

Read the exclusions section carefully. A clean report only tells you about the code that was actually examined.

Step 3: Focus the scan

Scanning everything on every run is slow and expensive. The CLI lets you narrow the scope:

# Only selected paths
cs scan . --path src --path tests

# Only what changed between a base revision and HEAD (great for PRs)
cs scan . --diff origin/main

# An exhaustive deep scan, e.g. before a release
cs scan . --mode deep

# An advisory 15-minute investigation allowance for a Standard scan
cs scan . --max-time 15

A sensible routine is --diff on every feature branch and a periodic --mode deep on the main branch. Run cs scan --help to see cost limits and options for patching after a scan.

Step 4: Give the scanner your security context with SECURITY.md

Scans use the guidance in your root and component-level SECURITY.md files. If you do not have one, or yours is out of date, let the CLI draft it:

cs policy .
cs policy . --path services/api --knowledge-base architecture.md

The command writes its draft outside the repository and does not change existing files. Review the diff and notes, edit the draft, and copy only SECURITY.md to the displayed policy target. Keep your vulnerability-reporting instructions when you update an existing policy.

Note: files at .github/SECURITY.md or docs/SECURITY.md often contain reporting instructions, but those locations do not automatically provide repository-wide scan guidance.

Step 5: Export a threat model

Scans and policy runs save a threat model. Export it without starting another analysis:

cs export --scan SCAN_ID --artifact threat-model --output threatmodel.md

Leave out --scan to use the latest completed scan in the current repository. The project’s export guide also covers SARIF output for CI, which lets you show findings in code-scanning dashboards.

Step 6: Automate with the TypeScript SDK

Install the package in a Node project:

npm install @openai/codex-security

Then run a scan from code:

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

const security = new CodexSecurity();

try {
  const result = await security.run("/path/to/repository");
  console.log("Report:", result.reportPath);
} finally {
  await security.close();
}

Always call close() in a finally block so the SDK cleans up even when a scan fails. For CI or containers, set OPENAI_API_KEY or CODEX_API_KEY in the scan process’s environment instead of using an interactive login.

If you use Git worktrees, keep CODEX_SECURITY_STATE_DIR stable so linked worktrees share scan history and saved findings.

Step 7: Weekly scans with GitHub Actions

The repository ships an example workflow for a weekly scan on GitHub-hosted Ubuntu:

  1. Add an OpenAI API key as the repository secret CODEX_SECURITY_API_KEY.
  2. Copy github-action/examples/repository.yml from the repo to .github/workflows/codex-security.yml.
  3. Replace REPLACE_WITH_REVIEWED_COMMIT with the reviewed distribution commit SHA from an Action release. Pinning to a commit SHA protects you from a compromised tag.
  4. Trigger it once manually from Actions → Codex Security repository → Run workflow.

The example uses an estimated $5 limit per scan and reports findings without failing the job. Requests already in progress can go over the limit, so watch your usage for the first few weeks. The Action guide explains severity thresholds and pull request checks if you want scans to block merges.

Good habits when using AI security scanners

  • Treat findings as leads, not verdicts. Use the validation step and read the source evidence before filing or fixing.
  • Review every generated patch like a pull request from a new teammate, with tests.
  • Keep your existing tools. Dependency scanning, secret scanning and static analysis still catch things an LLM-based review may not. Codex Security can import third-party scanner findings, so you can view them together.
  • Mind the data. Scans send code to OpenAI’s service. Check your organisation’s policy before scanning private or regulated code.

Key takeaway

Codex Security gives you a quick path from “scan this repo” to validated findings, patches and a threat model. Install it with npm install --global @openai/codex-security, run cs scan ., then narrow with --diff and --path, add a reviewed SECURITY.md, and automate with the SDK or the weekly GitHub Action. Everything in this guide comes from the official repository README, which links to the full CLI, SDK and Action documentation.