Codex Security

A tutorial — run one read-only scan on a repo you own, then read the report. Codex Security is an application-security agent with three doors: desktop plugin, CLI/SDK, and Cloud. This page is the map and the first scan, not a copy of every official workflow.
Official landing: learn.chatgpt.com/codex/security. Docs: Codex Security.

Prerequisites

Need	Requirement
Permission	Scan only code you own or have authorization to assess
Account	Codex Security access. Best results: Trusted Access for Cyber
Desktop plugin	ChatGPT desktop app with Codex
CLI / SDK	Node for `npx`; optional TypeScript app
Cloud	A GitHub repo already visible in Codex Cloud

Learning objectives: tell the three doors apart; install the plugin or run the CLI help; complete one read-only first scan; know that Cloud Security is a research preview.

Non-goals: writing exploit payloads; a full SARIF/CI cookbook (see official CI docs); agent sandbox theory (CLI).

Three doors, one scanner

Codex Security
├── Plugin          desktop workbench + CLI `/plugins`
│                   Scans · Findings · Repositories
├── CLI / SDK       @openai/codex-security
│                   local, bulk, CI, TypeScript
└── Cloud           research preview
                    connected GitHub repos via Codex Cloud

The desktop Security workbench and the Codex CLI both use the Codex Security plugin. Cloud scans GitHub through Codex Cloud. Sandbox, approvals, and admin policy are still the agent security model — Security does not replace them.

Door	Use when	Start here
Plugin	Interactive triage in the desktop app	Plugin quickstart
CLI / SDK	Repeatable local scans, bulk inventory, CI	CLI quickstart · SDK
Cloud	Hosted scans of connected GitHub repos	Cloud setup

Install the plugin from ChatGPT: plugin share link.

First local scan (plugin)

Official first-scan path: Plugin quickstart. Quality default: gpt-5.6-sol with xhigh reasoning.

Desktop

Open Codex in the ChatGPT desktop app.
Plugins → search Codex Security → install and enable.
Open Security in the sidebar. If it is missing, update the app and plugin.
Scans → + Scan. Pick a repo or folder. Leave Deep scan off for the first run.
Start the scan. Review Findings, coverage, and report.md.

Workbench panes: Scans (progress and saved results), Findings (issues and evidence), Repositories (history). Details: Security workbench.

CLI session via the plugin

bash

cd ~/code/your-repo
codex

Then /plugins → install Codex Security → /new, and send:

text

Run a Codex Security scan on this repository.

Keep the task running until it finishes. Read the terminal summary, then report.md. Approve any config change only after you read the exact patch.

CLI and SDK package

Public package: @openai/codex-security.

bash

npx @openai/codex-security --help

Use the same scanner across repos and over time: discover GitHub repos, resume bulk scans, track findings, record false-positive feedback, set a cost limit, or run in CI. The TypeScript SDK embeds scanning, progress, and cancel into a tool.

Job	Official page
First terminal scan	CLI quickstart
Bulk / CSV inventory	Bulk scans
PR / MR in CI, SARIF	CLI in CI
Flags and exit codes	CLI reference
From application code	TypeScript SDK

This is not the general Codex SDK (@openai/codex-sdk). Use the Security SDK only for structured security findings.

Cloud (research preview)

Codex Security cloud scans connected GitHub repositories commit by commit. It builds a repo-specific threat model, validates high-signal issues in an isolated environment, then surfaces ranked findings with evidence and suggested patches.

If a repo is missing, confirm it is visible in your Codex Cloud workspace, or contact your OpenAI account team.

Threat-model edits: Improving the threat model. PR reviews: Security Review.

After the first scan

Next	Official page
Deep scan (slower, broader)	Deep scans
Review a PR / branch / patch	Code changes
Triage an existing backlog	Triage
Bounded fix + verify	Fix findings
Export / track	Export findings

A completed scan typically writes report.md, optional findings/<slug>/ and hardening/, plus scan-manifest.json, findings.json, and coverage.json. Keep the directory together so links from report.md still resolve.

Common pitfalls

Pitfall	What happens	Do this instead
Scanning a repo you do not own	Policy and legal problem	Stop. Assess only authorized code
Treating findings as proof	False positives still happen	Read evidence; Cloud/plugin validate, you still decide
Asking for a working exploit	Out of scope for this guide	Review official evidence; do not write exploit PoCs here
Mixing Security SDK with Codex SDK	Wrong package	`@openai/codex-security` vs `@openai/codex-sdk`
Skipping Trusted Access	Weaker scans	chatgpt.com/cyber when you qualify

Real-world use

Before a release, run a read-only plugin scan on packages/api. Accept one finding, ask for a bounded patch, and re-run the related test. Put CI on the Security CLI for pull-request diffs. Leave Cloud on for the GitHub org if your workspace has the research preview.

Next steps

Plugin first scan → Plugin quickstart
Repeatable CLI → CLI quickstart
Hosted GitHub → Cloud setup
Agent sandbox (separate layer) → Agent approvals & security

Codex Security ​

Prerequisites ​

Three doors, one scanner ​

First local scan (plugin) ​

Desktop ​

CLI session via the plugin ​

CLI and SDK package ​

Cloud (research preview) ​

After the first scan ​

Common pitfalls ​

Real-world use ​

Next steps ​

Official sources ​