Documentation 2026-07-24 15:00 UTC to 2026-07-27 18:59 UTC

1# Codex Security plugin quickstart1# Codex Security plugin quickstart

2 2 

3Codex Security is a security-review plugin for Codex that scans your code for3Codex Security scans your code for vulnerabilities and validates plausible

4vulnerabilities, validates plausible findings, and presents evidence and4findings. For each reportable issue, it gives you the evidence and remediation

5remediation guidance in a reviewable workspace. Use it to find security issues5guidance you need to review the result. Scan only code you own or have

6in code you own or have authorization to assess before they reach production.6permission to assess.

7 7 

8This quickstart takes you through one recommended first run: an ordinary,8Follow this quickstart to install the plugin and run a read-only scan of a local

9read-only scan of a local repository in Codex.9repository in Codex.

10 10 

11This page covers the plugin that runs in a local Codex chat. To scan a11This page covers the plugin that runs in a local Codex chat. To scan a

12 connected GitHub repository in Codex cloud, see [Codex Security cloud12 connected GitHub repository in Codex cloud, see [Codex Security cloud

18 18 

191. Open the repository you want to assess in Codex in the [ChatGPT desktop191. Open the repository you want to assess in Codex in the [ChatGPT desktop

20 app](https://chatgpt.com/download/).20 app](https://chatgpt.com/download/).

212. Go to **Plugins** and search for **Codex Security**, or select the button212. Open **Plugins**, search for **Codex Security**, or use the button below:

22 below:

23 22 

24 <div className="not-prose my-6">23 <div className="not-prose my-6">

25 <ButtonLink24 <ButtonLink

33 </ButtonLink>32 </ButtonLink>

34 </div>33 </div>

35 34 

363. Start a new chat in Codex for that repository (don't continue in a chat that353. Start a new Codex chat for that repository. Don't continue an existing chat.

37 was already open).

38 36 

39 37 

40 38 

42 40 

43 41 

44 42 

43The hosted desktop-app catalog and public Codex CLI marketplace can offer

44 different plugin versions. Check the [plugin

45 changelog](https://learn.chatgpt.com/docs/security/plugin/changelog) before you rely on a feature or

46 start a long-running scan.

47 

45## Run your first scan48## Run your first scan

46 49 

47For the best scan quality, use `gpt-5.6-sol`50For the best scan quality, use `gpt-5.6-sol`

93 96 

943. Let the scan finish973. Let the scan finish

95 98 

96 The scan can take time. Keep the scan running until the workspace reports99 Keep the scan running until the workspace reports that it is complete. If

97 completion. If Codex identifies a configuration limitation, review the exact100 Codex identifies a configuration limitation, review the limitation and the

98 limitation and proposed change before allowing it to update your101 exact proposed change before you approve a configuration update.

99 configuration.

100 102 

1014. Review the result1034. Review the result

102 104 

153 155 

154## Choose your next workflow156## Choose your next workflow

155 157 

156- [Run a standard or scoped scan](https://learn.chatgpt.com/docs/security/plugin/scans) when you want158- [Run a standard or scoped scan](https://learn.chatgpt.com/docs/security/plugin/scans) to review a

157 to scan a repository or one folder with the default workflow.159 repository or one folder with the default workflow.

158- [Run a deep scan](https://learn.chatgpt.com/docs/security/plugin/deep-scans) when you need a more160- [Run a deep scan](https://learn.chatgpt.com/docs/security/plugin/deep-scans) for a more thorough scan

159 comprehensive scan and can wait longer for it to finish.161 when you can allow for a longer runtime.

160- [Review code changes](https://learn.chatgpt.com/docs/security/plugin/code-changes) when the target is162- [Review code changes](https://learn.chatgpt.com/docs/security/plugin/code-changes) to assess a pull

161 a pull request, commit, branch range, or working-tree patch.163 request, commit, branch range, or working-tree patch.

162- [Triage a backlog](https://learn.chatgpt.com/docs/security/plugin/triage-backlog) when you have164- [Triage a backlog](https://learn.chatgpt.com/docs/security/plugin/triage-backlog) to review existing

163 existing security findings to review.165 security findings.

164- [Fix and verify a finding](https://learn.chatgpt.com/docs/security/plugin/fix-findings) after you166- [Fix and verify a finding](https://learn.chatgpt.com/docs/security/plugin/fix-findings) after you

165 accept one finding for remediation.167 accept one finding for remediation.

166- [Export or track findings](https://learn.chatgpt.com/docs/security/plugin/export-findings) when you168- [Export or track findings](https://learn.chatgpt.com/docs/security/plugin/export-findings) to create

167 need JSON, CSV, SARIF, an approval-gated Linear, GitHub, or Jira issue, or a169 JSON, CSV, SARIF, an approval-gated Linear, GitHub, or Jira issue, or a private

168 private draft GitHub Security Advisory.170 draft GitHub Security Advisory.

169- [Write vulnerability reports](https://learn.chatgpt.com/docs/security/plugin/vulnerability-reports)171- [Write vulnerability reports](https://learn.chatgpt.com/docs/security/plugin/vulnerability-reports)

170 when you want to turn supplied findings, disclosure notes, source, and PoCs172 to turn supplied findings, disclosure notes, source, and PoCs into

171 into polished, self-contained reports.173 self-contained reports.

172- [Propose security hardening](https://learn.chatgpt.com/docs/security/plugin/security-hardening) when174- [Propose security hardening](https://learn.chatgpt.com/docs/security/plugin/security-hardening) to

173 you want structural or architectural options based on scan results or other175 consider structural or architectural options based on scan results or other

174 security evidence.176 security evidence.

1# Codex Security plugin changelog1# Codex Security plugin changelog

2 2 

3This changelog highlights changes that affect how you run scans, review3Use this changelog to see what changed in Codex Security and which plugin

4results, and move findings toward remediation.4versions are available from each installation source.

5 5 

6## 0.1.11 (July 2026)6**Latest release in the hosted Codex Security catalog:** `0.1.12`.

7 

8**Latest release in the public Codex CLI plugin marketplace:** `0.1.11`.

9 

10Check the plugin version in your current Codex environment before you use a

11feature from a newer release. Reopening or rerunning a saved scan doesn't pin

12the installed plugin version.

13 

14These versions apply to the Codex Security plugin. The Codex app, Codex CLI,

15TypeScript SDK, and plugin app have separate version numbers.

16 

17## 0.1.12 (July 23, 2026)

18 

19### Run deeper scans with clearer progress

20 

21- Run deep scans that coordinate workers across an entire repository

22 or a selected directory.

23- Carry your model and reasoning settings into delegated scan work.

24- See preflight results, scan progress, available worker capacity, and fallback

25 behavior before and during a scan.

26 

27### Review and rerun previous scans

28 

29- Open current and previous scans from the security scan list.

30- Reopen a saved scan in the findings workspace, or rerun it to refresh the

31 results.

32- See clearer completion states and more consistent finding details and scan

33 history.

34 

35### Configure scans with fewer interruptions

36 

37- Start scans from the native setup flow without leaving your current task.

38- Keep scan setup in the side panel, even when Codex is in full-screen mode.

39- Dismiss setup when you don't need it and keep that preference for later

40 scans.

41 

42### Review and remediate validated findings

43 

44- Keep validated low-severity findings in completed results.

45- Review more consistent finding details across scans, reports, and exports.

46- Retry remediation and carry relevant scan context into follow-up fixes.

47 

48### Export results for existing security workflows

49 

50- Export completed findings as JSON, CSV, or SARIF.

51- Generate SARIF results locally for code-scanning and security-tool

52 integrations.

53- Preserve consistent finding details across exported formats.

54 

55## 0.1.11 (July 10, 2026)

7 56 

8### Produce detailed finding and hardening reports57### Produce detailed finding and hardening reports

9 58 

29- Define threat-model context, security invariants, reportable finding78- Define threat-model context, security invariants, reportable finding

30 criteria, exclusions, and severity context in root or nested `SECURITY.md`79 criteria, exclusions, and severity context in root or nested `SECURITY.md`

31 files. The closest applicable file takes precedence.80 files. The closest applicable file takes precedence.

81- Improve repository review coverage before validation while preserving

82 explicitly deferred surfaces and proof gaps.

32- Review deleted source files in change scans and expand the default repository83- Review deleted source files in change scans and expand the default repository

33 review coverage before validation.84 review coverage before validation.

34- Check deep-scan phase skills, delegated workers, and worker capacity before a85- Check deep-scan phase skills, delegated workers, and worker capacity before a

35 deep scan starts.86 deep scan starts.

36 87 

37## 0.1.9 (June 2026)88## 0.1.10 (June 23, 2026)

89 

90### Improve Jira and Linear ticket intake

91 

92- Ask before importing Linear sub-issues and preserve parent-child

93 relationships in the results.

94- Distinguish missing connections, insufficient permissions, inaccessible

95 tickets, and temporary connector failures.

96- Stop instead of creating a verdict when the requested ticket content isn't

97 available.

98- Assign unique positive integer ranks starting at `1` within each confirmed

99 or needs-review queue.

100 

101### Review code changes more reliably

102 

103- Compare an inspected commit with its actual parent and preserve the diff

104 target in the findings workspace.

105- Report unavailable patch state instead of reviewing a different change.

106- Review more consistent triage results and finding context.

107 

108## 0.1.9 (June 18, 2026)

38 109 

39### Review scans in the findings workspace110### Review scans in the findings workspace

40 111 

60 coverage data, and a Markdown report derived from the same canonical result.131 coverage data, and a Markdown report derived from the same canonical result.

61- Export findings as JSON, CSV, or SARIF for analysis, archiving, and integration132- Export findings as JSON, CSV, or SARIF for analysis, archiving, and integration

62 with other security tools.133 with other security tools.

63- Improved scan completion and filesystem handling, including fixes for Windows134- Complete scans more reliably, including when Windows paths or scan locking

64 paths and scan locking.135 affect filesystem access.

65 136 

66### Triage and track existing findings137### Triage and track existing findings

67 138 

75- Review duplicate checks, source context, destination visibility, and the146- Review duplicate checks, source context, destination visibility, and the

76 exact proposed content before approving a write. Codex reads the result back147 exact proposed content before approving a write. Codex reads the result back

77 after creation or update to verify it.148 after creation or update to verify it.

149 

150## 0.1.7 (June 4, 2026)

151 

152### Run evidence-backed security reviews

153 

154- Scan an authorized repository or selected folder for security

155 vulnerabilities.

156- Run repeated discovery across an entire repository when you need more

157 thorough coverage.

158- Review pull requests, commits, branch differences, and local patches for

159 security regressions.

160- Move each candidate through threat modeling, finding discovery, validation,

161 and impact analysis before generating scan reports.

162- Fix one accepted finding with a focused patch, regression coverage, and

163 verification of the original issue.

1# Review code changes for security1# Review code changes for security

2 2 

3Use a security change review when you need evidence about regressions introduced3Run a security change review to find regressions in one Git-backed change set.

4by one Git-backed change set. The workflow reviews every changed source-like4Codex reviews each changed source-like file and its directly supporting code.

5file and directly supporting code without turning the task into a general5It doesn't expand the review into a full repository audit.

6repository audit.

7 6 

8If you want to scan a full repository instead of a specific change, see [Run a7To scan an entire repository instead of a specific change, see [Run a security

9security scan](https://learn.chatgpt.com/docs/security/plugin/scans).8scan](https://learn.chatgpt.com/docs/security/plugin/scans).

10 9 

11## Run a manual review10## Run a manual review

12 11 

13For uncommitted changes, send:12For uncommitted changes, ask Codex:

14 13 

15```text14```text

16Use $codex-security:security-diff-scan to review my current uncommitted changes for security regressions.15Use $codex-security:security-diff-scan to review my current uncommitted changes for security regressions.

17```16```

18 17 

19For a commit or branch range, identify both ends when needed:18For a commit or branch range, specify both revisions when needed:

20 19 

21```text20```text

22Use $codex-security:security-diff-scan to review the changes from origin/main to HEAD for security regressions. Focus on authentication, authorization, input handling, filesystem access, network requests, and secrets.21Use $codex-security:security-diff-scan to review the changes from origin/main to HEAD for security regressions. Focus on authentication, authorization, input handling, filesystem access, network requests, and secrets.

40 39 

41</WorkflowSteps>40</WorkflowSteps>

42 41 

43The workflow doesn't check out another branch or change the selected working42Codex doesn't check out another branch or switch the selected working tree. If

44tree. If a requested revision isn't available locally, fetch it before the43a requested revision isn't available locally, fetch it before the review or

45review or provide a locally available base and head.44provide a locally available base and head.

46 45 

47## Act on findings46## Act on findings

48 47 

52 51 

53## Automate reviews in CI/CD52## Automate reviews in CI/CD

54 53 

55Run the same `$codex-security:security-diff-scan` skill from CI when the runner54Run `$codex-security:security-diff-scan` in CI when the runner can invoke the

56can invoke the Codex CLI without interaction. First install the CLI and plugin55Codex CLI without interaction. First, install the CLI and plugin without

57without exposing the scan credential:56exposing the scan credential:

58 57 

59```bash58```bash

60npm install --global @openai/codex59npm install --global @openai/codex

61codex plugin add codex-security@openai-curated60codex plugin add codex-security@openai-curated

62```61```

63 62 

64Then expose an OpenAI API key from your CI secret store as63The install command uses the public Codex CLI plugin marketplace, which can

65`CODEX_SECURITY_API_KEY` only for the scan:64offer a different version from the hosted desktop-app catalog. Check the

65[plugin changelog](https://learn.chatgpt.com/docs/security/plugin/changelog) before you depend on a

66specific plugin version or feature in CI.

67 

68Next, provide an OpenAI API key from your CI secret store as

69`CODEX_SECURITY_API_KEY`. Expose the credential only for the scan:

66 70 

67```bash71```bash

68CODEX_API_KEY="$CODEX_SECURITY_API_KEY" codex exec \72CODEX_API_KEY="$CODEX_SECURITY_API_KEY" codex exec \

70 "Use \$codex-security:security-diff-scan to review changes from $BASE_REVISION to $HEAD_REVISION for security regressions. Do not modify the checkout."74 "Use \$codex-security:security-diff-scan to review changes from $BASE_REVISION to $HEAD_REVISION for security regressions. Do not modify the checkout."

71```75```

72 76 

77The writable sandbox lets the scan create temporary artifacts. The prompt

78still requires Codex to leave the source checkout unchanged.

79 

73The scan writes its output to80The scan writes its output to

74`$TMPDIR/codex-security-scans/<repository>/<scan-id>/`:81`$TMPDIR/codex-security-scans/<repository>/<scan-id>/`:

75 82 

83| `coverage.json` | Reviewed and deferred surfaces, exclusions, and coverage completeness. |90| `coverage.json` | Reviewed and deferred surfaces, exclusions, and coverage completeness. |

84 91 

85The [`findings.json` schema](https://github.com/openai/plugins/blob/main/plugins/codex-security/schemas/findings.schema.json)92The [`findings.json` schema](https://github.com/openai/plugins/blob/main/plugins/codex-security/schemas/findings.schema.json)

86defines the complete structure. Some key fields are:93defines the complete structure. The schema includes these fields:

87 94 

88| Field | Type | Description |95| Field | Type | Description |

89| ------------------------- | ------ | ---------------------------------------------------------------------- |96| ------------------------- | ------ | ---------------------------------------------------------------------- |

1193, `jq`, and the provider's command-line tools. The `npm` global package prefix1263, `jq`, and the provider's command-line tools. The `npm` global package prefix

120must be writable.127must be writable.

121 128 

122Here are examples of how to use Codex Security in common pipelines:129Choose the example for your CI provider:

123 130 

124<Tabs131<Tabs

125 id="codex-security-ci-examples"132 id="codex-security-ci-examples"

1# Run a deep security scan1# Run a deep security scan

2 2 

3A deep scan is slower but more thorough than a standard scan. Use it when you3Run a deep scan when you need a more thorough review and can allow for a longer

4want to reduce variability and search more comprehensively.4runtime. Deep scans search a repository more extensively and can reduce

5variability between runs.

5 6 

6Start with a [standard scan](https://learn.chatgpt.com/docs/security/plugin/scans). Once you're7Start with a [standard scan](https://learn.chatgpt.com/docs/security/plugin/scans) to check your scope

7satisfied with the results, run a deep scan for a more thorough assessment.8and results. Then use a deep scan when you need a more thorough assessment.

8 9 

9## Choose between standard and deep scans10## Choose between standard and deep scans

10 11 

30Use $codex-security:deep-security-scan to run a deep security scan of /absolute/path/to/repository/services/payments.31Use $codex-security:deep-security-scan to run a deep security scan of /absolute/path/to/repository/services/payments.

31```32```

32 33 

33In the ChatGPT desktop app, a scoped deep scan resolves the selected folder as the34For a scoped deep scan in the ChatGPT desktop app, the selected folder becomes

34**Codebase** and shows its scan area as the entire selected target.35the **Codebase**. The scan area covers the entire selected folder.

35 36 

36## Confirm setup and preflight37## Confirm setup and preflight

37 38 

53the current runtime doesn't meet those requirements, use a standard scan or54the current runtime doesn't meet those requirements, use a standard scan or

54move the task to a runtime that passes the capability preflight.55move the task to a runtime that passes the capability preflight.

55 56 

57On supported desktop-app versions, discovery workers inherit your selected

58model and reasoning settings. Keep the scan active until Codex reports that it

59is complete. Reopening or rerunning a saved scan doesn't pin the plugin version

60or guarantee that work interrupted by an update will resume. Check the [plugin

61changelog](https://learn.chatgpt.com/docs/security/plugin/changelog) before you update the plugin or

62start another deep scan.

63 

56<VideoPlayer64<VideoPlayer

57 src="/videos/codex/security/deep-scan-progress.mp4"65 src="/videos/codex/security/deep-scan-progress.mp4"

58 poster="/videos/codex/security/deep-scan-progress-poster.webp"66 poster="/videos/codex/security/deep-scan-progress-poster.webp"

66remain. Keep the linked `findings/` and `hardening/` directories with the74remain. Keep the linked `findings/` and `hardening/` directories with the

67report when sharing or archiving the result.75report when sharing or archiving the result.

68 76 

69Review the coverage summary before the findings. A deep scan searches the code77Review the coverage summary before the findings. Even a deep scan has limits,

70more extensively, but any deferred surface or proof gap still limits the78so check deferred surfaces and remaining proof gaps before drawing a

71conclusion. For a finding you accept, continue with [Fix and verify a79conclusion. For a finding you accept, continue with [Fix and verify a

72finding](https://learn.chatgpt.com/docs/security/plugin/fix-findings).80finding](https://learn.chatgpt.com/docs/security/plugin/fix-findings).

73 81 

1# Export and track security findings1# Export and track security findings

2 2 

3Use a completed Codex Security scan as the source for two different handoffs:3Use a completed Codex Security scan for either of these handoffs:

4 4 

5- **Export** creates a portable JSON, CSV, or SARIF file.5- **Export** creates a portable JSON, CSV, or SARIF file.

6- **Track findings** prepares selected findings as Linear, GitHub, or Jira issues6- **Track findings** prepares selected findings as Linear, GitHub, or Jira

7 or one private draft GitHub Security Advisory, checks for duplicates, and7 issues, or as one private draft GitHub Security Advisory. Codex checks for

8 waits for your approval before writing.8 duplicates and waits for your approval before writing.

9 9 

10These workflows don't change the sealed scan bundle.10Neither workflow changes the sealed scan bundle.

11 

12Available export formats and workspace controls depend on your Codex surface

13 and installed plugin version. Check the [plugin

14 changelog](https://learn.chatgpt.com/docs/security/plugin/changelog) before you use a format in

15 automation.

11 16 

12## Export a portable artifact17## Export a portable artifact

13 18 

19| CSV | Review findings and current local triage state in a spreadsheet. |24| CSV | Review findings and current local triage state in a spreadsheet. |

20| SARIF | Send findings to tools that support the SARIF interchange format. |25| SARIF | Send findings to tools that support the SARIF interchange format. |

21 26 

22Select **Export findings** and use the returned artifact path. Keep the27Select **Export findings**, then use the returned artifact path. If another

23original `scan-manifest.json`, `findings.json`, and `coverage.json` together28tool needs the complete scan context, keep the original `scan-manifest.json`,

24when another tool needs the complete scan context rather than a findings-only29`findings.json`, and `coverage.json` together. The plugin generates SARIF

25projection.30locally. Exporting doesn't upload findings to a code-scanning service.

26 31 

27<figure className="not-prose my-8">32<figure className="not-prose my-8">

28 <div className="overflow-hidden rounded-xl border border-subtle bg-surface">33 <div className="overflow-hidden rounded-xl border border-subtle bg-surface">

40 45 

41## Track selected findings46## Track selected findings

42 47 

43The `$codex-security:track-findings` workflow accepts one validated finding or48Run `$codex-security:track-findings` with one validated finding or an

44an explicitly selected batch of up to 25 findings from one sealed scan for49explicitly selected batch of up to 25 findings from the same sealed scan. Each

45issue tracking. Draft GitHub Security Advisories accept one finding only. One50run uses one provider and one destination. A private draft GitHub Security

46run uses one provider and one destination.51Advisory accepts only one finding.

47 52 

48For Linear, send a prompt like:53To prepare a Linear issue, send:

49 54 

50```text55```text

51Use $codex-security:track-findings to prepare finding [finding ID] from56Use $codex-security:track-findings to prepare finding [finding ID] from

54and destination. Do not create or update anything until I approve that payload.59and destination. Do not create or update anything until I approve that payload.

55```60```

56 61 

57For GitHub issues, send:62To prepare a GitHub issue, send:

58 63 

59```text64```text

60Use $codex-security:track-findings to prepare finding [finding ID] from65Use $codex-security:track-findings to prepare finding [finding ID] from

64update anything until I approve that payload.69update anything until I approve that payload.

65```70```

66 71 

67For Jira, send:72To prepare a Jira issue, send:

68 73 

69```text74```text

70Use $codex-security:track-findings to prepare finding [finding ID] from75Use $codex-security:track-findings to prepare finding [finding ID] from

77Jira tracking requires the Atlassian Rovo plugin in Codex. Reusing an issue82Jira tracking requires the Atlassian Rovo plugin in Codex. Reusing an issue

78requires read access; creating or updating one requires read and write access.83requires read access; creating or updating one requires read and write access.

79 84 

80For a private draft GitHub Security Advisory, send:85To prepare a private draft GitHub Security Advisory, send:

81 86 

82```text87```text

83Use $codex-security:track-findings to prepare finding [finding ID] from88Use $codex-security:track-findings to prepare finding [finding ID] from

122 127 

123## Verify the tracked item128## Verify the tracked item

124 129 

125After approval, Codex revalidates the sealed source, destination, access, and130After you approve the proposed write, Codex rechecks the sealed source,

126duplicate state. It processes a batch serially and stops on the first uncertain131destination, access, and duplicate state. For a batch, it processes findings

127result. A create, update, or reuse is complete only after Codex reads the exact132one at a time and stops at the first uncertain result. Creation, update, or

128issue back and verifies its binding identifiers and content.133reuse is complete only after Codex reads the exact issue back and verifies its

134binding identifiers and content.

129 135 

130Keep the returned canonical issue or advisory URL with your triage record.136Keep the returned canonical issue or advisory URL with your triage record.

131Continue with [Fix and verify a finding](https://learn.chatgpt.com/docs/security/plugin/fix-findings)137Continue with [Fix and verify a finding](https://learn.chatgpt.com/docs/security/plugin/fix-findings)

1# Fix and verify security findings1# Fix and verify security findings

2 2 

3Codex Security helps you turn a backlog of accepted findings into tested code3Use Codex Security to turn an accepted security finding into a focused,

4changes. You can fix findings in the findings workspace UI or invoke the4verified patch. You can work in the findings workspace or run the remediation

5remediation workflow from a prompt, the command line, or CI/CD. In each case,5workflow from a prompt, the command line, or CI/CD. Codex validates the issue

6Codex validates the issue, proposes a focused patch, adds regression coverage,6and, when testing is safe and practical, adds a focused regression test that

7and verifies that legitimate behavior still works.7fails before the fix and passes after it. It also checks that legitimate

8 8behavior still works. If a regression test is unsafe or infeasible, Codex

9Start by fixing one accepted finding so you can evaluate the patch and9records the proof gap and provides the strongest repeatable validation

10verification quality. Once the workflow meets your standards, scale it across10artifact instead.

11more accepted findings by processing each finding in a separate task or CI/CD11 

12job. Keeping each fix scoped makes the code changes and evidence easier to12Start with one accepted finding and review the proposed patch and verification

13review.13evidence. If the workflow meets your standards, process other accepted

14findings one at a time in separate Codex tasks or CI/CD jobs. Keeping each task

15scoped makes its code changes and evidence easier to review.

14 16 

15## Fix a finding in the UI17## Fix a finding in the UI

16 18 

27 29 

282. Review the proposed diff302. Review the proposed diff

29 31 

30 Read every changed source and regression-test file. Use **Open diff in32 Read every changed source, regression test, and validation artifact. Select

31 editor** when you want the full patch in the editor. Reject broad refactors,33 **Open diff in editor** to review the full patch in your editor. Reject

32 unrelated cleanup, or changes that weaken another security control.34 broad refactors, unrelated cleanup, or changes that weaken another security

35 control.

33 36 

343. Apply the patch locally373. Apply the patch locally

35 38 

39 42 

404. Verify the fix434. Verify the fix

41 44 

42 Select **Verify fix**. Codex reruns the original reproducer or strongest45 Select **Verify fix**. Codex reruns the original reproducer or the strongest

43 available exploit check, focused regression coverage, legitimate-behavior46 available exploit check. If a regression test is safe and practical, Codex

44 checks, nearby bypass checks, and relevant repository tests.47 checks that it fails before the fix and passes after it. If the test is

48 unsafe or infeasible, Codex records the proof gap and provides the

49 strongest repeatable validation artifact instead. It also checks

50 legitimate behavior, nearby bypasses, and relevant repository tests.

45 51 

465. Close the finding deliberately525. Close the finding deliberately

47 53 

67 73 

68## Fix a finding from the CLI74## Fix a finding from the CLI

69 75 

70Use the Codex CLI when you already have a finding from a scan, ticket, advisory,76Use the Codex CLI for an accepted finding from a scan, ticket, advisory,

71disclosure, security assessment, or internal review:77disclosure, security assessment, or internal review.

72 78 

73The commands below assume Codex Security is already installed in the79Install Codex Security in the `CODEX_HOME` that `codex exec` uses before you

74`CODEX_HOME` used by `codex exec`. A fresh CI runner doesn't have marketplace80run these commands. A fresh CI runner doesn't include marketplace plugins by

75plugins installed by default.81default.

76 82 

77```text83```text

78Use $codex-security:fix-finding to fix finding <finding-id> from <report-path>. Validate the issue, make the smallest safe change, add focused regression coverage, and verify that the issue no longer reproduces.84Use $codex-security:fix-finding to fix finding <finding-id> from <report-path>. Validate the issue, make the smallest safe change, and add a focused regression test that fails before the fix and passes after it. If that test is unsafe or infeasible, record the proof gap and provide the strongest repeatable validation artifact instead. Verify that the issue no longer reproduces.

79```85```

80 86 

81Include the known source, sink, attacker input, impact, expected invariant,87Include the known source, sink, attacker input, impact, expected invariant,

82reproducer, affected files, and validation command. Codex can inspect the88reproducer, affected files, and validation command. Codex can inspect the

83repository for missing technical details, but it should ask before guessing a89repository for missing technical details. It should ask before assuming a

84product policy or intended security invariant.90product policy or intended security invariant.

85 91 

86For an automated run, pass the prompt to `codex exec` after checking out the92For an automated run, check out the code, make the finding report available,

87code, making the finding report available, and provisioning the plugin in that93and install the plugin in the runner's `CODEX_HOME`. Then enable workspace

88`CODEX_HOME`:94writes and pass the prompt to `codex exec`:

89 95 

90```bash96```bash

91codex exec 'Use $codex-security:fix-finding to fix finding <finding-id> from <report-path>. Validate the issue, make the smallest safe change, add focused regression coverage, and verify that the issue no longer reproduces.'97codex exec --sandbox workspace-write 'Use $codex-security:fix-finding to fix finding <finding-id> from <report-path>. Validate the issue, make the smallest safe change, and add a focused regression test that fails before the fix and passes after it. If that test is unsafe or infeasible, record the proof gap and provide the strongest repeatable validation artifact instead. Verify that the issue no longer reproduces.'

92```98```

93 99 

94## Scan and fix findings in CI/CD100## Scan and fix findings in CI/CD

95 101 

96Provision Codex Security in the runner's `CODEX_HOME` before invoking these102Install Codex Security in the runner's `CODEX_HOME` before you invoke either

97skills. The command below uses the installed plugin; it doesn't install the103skill. The commands below use the installed plugin; they don't install it.

98plugin itself.

99 104 

100In CI/CD, use one Codex run to scan the diff and generate fixes for every105In CI/CD, separate the change scan from remediation and require the scan to

101finding it discovers. The job doesn't need finding IDs or report paths as106leave the checkout unchanged. Preserve the completed scan directory as a job

102inputs. Codex carries the findings from the scan into remediation within the107artifact, review the findings, and start a separate Codex task or job for each

103same run.108finding accepted for remediation.

104 109 

105The all-in-one run should:110By default, `codex exec` uses a read-only sandbox. Run both the change scan and

111remediation with `--sandbox workspace-write`. The scan needs that permission

112to save temporary artifacts, but its prompt must still require `Do not modify

113the checkout`. Remediation needs the same permission to write the focused

114patch and verification evidence. See [Permissions and

115safety](https://learn.chatgpt.com/docs/non-interactive-mode#permissions-and-safety).

116 

117For each scan and accepted finding:

106 118 

1071. Resolve the base and head revisions for the change.1191. Resolve the base and head revisions for the change.

1082. Run `$codex-security:security-diff-scan` against that diff.1202. Run `$codex-security:security-diff-scan` against that diff without modifying

1093. Invoke `$codex-security:fix-finding` for every finding returned by the scan.121 the checkout.

1104. Generate focused patches and regression coverage, then verify each fix.1223. Preserve the complete scan directory and select the findings to fix.

1115. Return the scan results, patches, tests, verification commands, and any1234. Invoke `$codex-security:fix-finding` once for each accepted finding, passing

112 finding it couldn't fix.124 its finding ID and completed scan directory.

1255. Generate one focused patch and add a regression test that fails before the

126 fix and passes after it. If that test is unsafe or infeasible, record the

127 proof gap and use the strongest repeatable validation artifact instead.

1286. Verify the original issue and legitimate behavior. Return each patch, test

129 or fallback validation artifact, verification command, and any proof gap

130 independently.

113 131 

114For example:132For example:

115 133 

116```bash134```bash

117codex exec 'Use $codex-security:security-diff-scan to review changes from <base-revision> to HEAD. For every finding returned by the scan, use $codex-security:fix-finding to generate and verify a minimal fix. Continue until every finding has either a verified fix or an explicit explanation of why it could not be fixed. Return the scan results, patches, tests, verification commands, and remaining failures.'135codex exec --sandbox workspace-write 'Use $codex-security:security-diff-scan to review changes from <base-revision> to <head-revision> for security regressions. Do not modify the checkout.'

136 

137codex exec --sandbox workspace-write 'Use $codex-security:fix-finding to fix finding <finding-id> from <completed-scan-directory>. Validate the finding, generate one minimal patch, and add a focused regression test that fails before the fix and passes after it. If that test is unsafe or infeasible, record the proof gap and provide the strongest repeatable validation artifact instead. Verify that the issue no longer reproduces.'

118```138```

119 139 

120After verification, merge the patch through your normal code-review and release140Repeat the second command in an independent task or job for each remaining

121process. To hand findings to another team before remediation, see [Export or141accepted finding. After verification, merge each patch through your normal

122track findings](https://learn.chatgpt.com/docs/security/plugin/export-findings).142code-review and release process. To hand findings to another team before

143remediation, see [Export or track

144findings](https://learn.chatgpt.com/docs/security/plugin/export-findings).

1# Run a Codex Security scan1# Run a Codex Security scan

2 2 

3Use a Codex Security scan for your first review and for most routine repository3Start with a standard Codex Security scan for an initial review or a routine

4or component assessments. It runs the complete scan workflow once.4repository or component assessment. It runs the full scan workflow once.

5 5 

6Once you're satisfied with the results, run a [deep scan](https://learn.chatgpt.com/docs/security/plugin/deep-scans)6For a more thorough assessment, review the results and then run a [deep

7for a more comprehensive assessment. Deep scans take longer, but they're more7scan](https://learn.chatgpt.com/docs/security/plugin/deep-scans). Deep scans take longer and search

8thorough.8more extensively.

9 9 

10## Choose the scan area10## Choose the scan area

11 11 

40 40 

41</WorkflowSteps>41</WorkflowSteps>

42 42 

43For persistent repository security guidance, add a `SECURITY.md` at the43Add `SECURITY.md` to the repository root for persistent security guidance.

44repository root. Use it to describe the threat model, security invariants,44Describe the threat model, security invariants, reportable finding criteria,

45reportable finding criteria, exclusions, and severity context. For45exclusions, and severity context. Add nested `SECURITY.md` files for

46directory-specific guidance, add nested `SECURITY.md` files. When policies46directory-specific guidance. When policies conflict, the file closest to the

47conflict, the file closest to the code takes precedence. Codex Security treats47code takes precedence. Codex Security treats these files as policy context,

48this content as policy context, not executable instructions.48not executable instructions.

49 49 

50Use `AGENTS.md` for supported build and validation commands and other50Use `AGENTS.md` for supported build and validation commands and other

51repository-specific instructions.51repository-specific instructions.

60 controls and source-to-sink paths.60 controls and source-to-sink paths.

613. **Validation** tests or otherwise checks each candidate and records evidence613. **Validation** tests or otherwise checks each candidate and records evidence

62 or proof gaps.62 or proof gaps.

634. **Attack-path analysis** evaluates realistic reachability, impact, and634. **Impact and path analysis** evaluates each candidate's realistic paths,

64 severity.64 impact, and severity.

655. **Detailed reporting** creates one source-backed vulnerability report per655. **Detailed reporting** creates one source-backed vulnerability report per

66 reportable finding, with supporting proof-of-concept files when available.66 reportable finding, with supporting proof-of-concept files when available.

676. **Structural hardening** analyzes the complete finding set and creates a676. **Structural hardening** analyzes the complete finding set and creates a

697. **Finalization** validates the structured scan contract and generates697. **Finalization** validates the structured scan contract and generates

70 `report.md`, which links the detailed reports and hardening portfolio.70 `report.md`, which links the detailed reports and hardening portfolio.

71 71 

72Codex reports phase and coverage progress as the scan runs. Don't judge the72Codex reports phase and coverage progress as the scan runs. Wait for the

73result from early candidates or stop the scan because one phase takes longer73complete result instead of judging early candidates or stopping because one

74than another.74phase takes longer than another.

75 75 

76## Review the completed scan76## Review the completed scan

77 77 

115 </figure>115 </figure>

116</div>116</div>

117 117 

118## Reopen or rerun a previous scan

119 

120In the ChatGPT desktop app, open a completed scan from the security scan list

121to review its saved findings workspace. To update the results, rerun the saved

122configuration against the current code. The rerun creates a new scan and leaves

123the earlier scan and its artifacts unchanged.

124 

125Scan history, rerun controls, and other workspace features depend on your Codex

126surface and installed plugin version. A rerun doesn't pin that version or

127guarantee that interrupted work will resume after a plugin update. Check the

128[plugin changelog](https://learn.chatgpt.com/docs/security/plugin/changelog) before you start or rerun

129a long-running scan.

130 

118## Use the results131## Use the results

119 132 

120Use the findings workspace for normal review. It presents findings, coverage,133Use the findings workspace to review findings, coverage, and follow-up areas

121and follow-up areas without requiring you to inspect raw JSON. Open `report.md`134without inspecting raw JSON. Open `report.md` for the readable entry point to

122as the primary readable entry point to the complete scan directory. Keep the135the complete scan directory. Keep the directory together when you share or

123directory together when sharing or archiving it because the report links to136archive it: the report links to detailed reports in `findings/` and, when

124detailed reports under `findings/` and, when reportable findings exist,137reportable findings exist, structural hardening guidance in `hardening/`.

125structural hardening guidance under `hardening/`.

126 138 

127Behind the workspace, each scan preserves `scan-manifest.json`, `findings.json`,139Behind the workspace, each scan preserves `scan-manifest.json`, `findings.json`,

128and `coverage.json` for automation and integrations. You normally don't need to140and `coverage.json` for automation and integrations. You normally don't need to

133 145 

134## Next step146## Next step

135 147 

136After a person accepts a finding, use [Fix and verify a finding](https://learn.chatgpt.com/docs/security/plugin/fix-findings)148After you accept a finding, use [Fix and verify a

137to generate and review one bounded patch. Don't ask Codex to fix every finding149finding](https://learn.chatgpt.com/docs/security/plugin/fix-findings) to generate and review one

138from a scan in one chat.150bounded patch. Don't ask Codex to fix every finding from a scan in one chat.