1# Codex Security plugin1# Codex Security plugin quickstart
2 2
3The Codex Security plugin adds security-review workflows to Codex for code that3Codex Security is a security-review plugin for Codex that scans your code for
4you have authorization to assess. Use it from an open repository to investigate4vulnerabilities, validates plausible findings, and presents evidence and
5a codebase, review a change set for security regressions, confirm plausible5remediation guidance in a reviewable workspace. Use it to find security issues
6findings, and prepare minimal fixes for review.6in code you own or have authorization to assess before they reach production.
7 7
8This page covers the installable plugin that runs in your Codex thread. For8This quickstart takes you through one recommended first run: an ordinary,
9 the research-preview product that scans connected GitHub repositories through9read-only scan of a local repository in the Codex app.
10 Codex Web, see [Codex Security](https://developers.openai.com/codex/security).10
11This page covers the plugin that runs in a local Codex thread. To scan a
12 connected GitHub repository in Codex web, see [Codex Security cloud
13 setup](https://developers.openai.com/codex/security/setup).
11 14
12## Install the plugin15## Install the plugin
13 16
14<Tabs17Open the repository you want to assess in the Codex app, then install Codex
15 param="install"18Security:
16 tabs={[19
17 {20<div className="not-prose my-6">
18 id: "app",
19 label: "Codex app",
20 },
21 {
22 id: "cli",
23 label: "Codex CLI",
24 },
25 ]}
26>
27 <div slot="app">
28 <ButtonLink21 <ButtonLink
29 href="codex://plugins/install/codex-security?marketplace=openai-curated"22 href="codex://plugins/install/codex-security?marketplace=openai-curated"
30 color="primary"23 color="primary"
31 variant="solid"24 variant="solid"
32 size="lg"25 size="lg"
33 pill26 pill
34 className="mt-2"
35 >27 >
36 Install the Codex Security plugin28 Install the Codex Security plugin
37 </ButtonLink>29 </ButtonLink>
30</div>
38 31
39 <br />32After installation, start a new thread in that repository. Codex loads plugins
40 33when the thread starts, so don't continue in a thread that was already open.
41 After installation, start a new thread in the repository you want to
42 assess.
43 34
44 </div>35## Run your first scan
45 36
46 <div slot="cli">37For the best scan quality, use `gpt-5.5`
47 <WorkflowSteps variant="headings">38with `high` or `xhigh` reasoning effort.
48 1. Open Codex
49 39
50 Start Codex from your repository:40<VideoPlayer
41 src="/videos/codex/security/scan-setup-to-findings.mp4"
42 poster="/videos/codex/security/scan-setup-to-findings-poster.webp"
43/>
51 44
52 ```bash45<WorkflowSteps variant="headings">
53 codex
54 ```
55 46
56 2. Open the plugin browser471. Ask for an ordinary scan
57 48
58 Enter:49 Send this prompt in the new thread:
59 50
60 ```text51 ```text
61 /plugins52 Run a Codex Security scan on this repository.
62 ```53 ```
63 54
64 3. Install Codex Security552. Confirm the setup
65 56
66 Search for **Codex Security**, open it, and select `Install plugin`.57 Codex opens a setup workspace before it starts. For your first run, use these
67 58 settings:
68 4. Start a new thread59 - **Scan type:** `Codebase`
69 60 - **Deep scan:** Off
70 Start a new thread in the repository you are authorized to review.61 - **Scan area:** `Entire codebase`
71 </WorkflowSteps>62 - **Threat model scoping guidance:** Leave blank unless you already know a
72 63 specific attack vector or application area that deserves priority.
64
65 Confirm that **Codebase**, **Current branch**, and **Last commit** identify
66 the repository you intended to scan. Then select **Start scan**.
67
68 <figure className="not-prose my-6">
69 <div className="overflow-hidden rounded-xl border border-subtle bg-surface">
70 <img
71 src={scanSetup.src}
72 alt="Codex Security setup workspace configured to scan an entire codebase"
73 className="block h-auto w-full"
74 />
73 </div>75 </div>
74</Tabs>76 <figcaption className="mt-3 text-sm text-secondary">
75 77 Configure the scan target, scan area, branch, and optional threat model
76## Choose a security workflow78 guidance before starting the scan.
77 79 </figcaption>
78Choose the narrowest workflow that answers your question. A diff-focused scan80 </figure>
79is faster to review than a repository-wide scan; a deep scan intentionally uses81
80more time and tokens to search for more candidate findings.823. Let the scan finish
81 83
82| Goal | Skill | Scope and output |84 The scan can take time. Keep the thread running until the workspace reports
83| -------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |85 completion. If Codex identifies a configuration limitation, review the exact
84| Review a repository or one scoped path | `$codex-security:security-scan` | Runs threat modeling, finding discovery, validation, attack-path analysis, and produces Markdown and HTML reports. |86 limitation and proposed change before allowing it to update your
85| Run a higher-recall audit | `$codex-security:deep-security-scan` | Repeats repository-wide discovery with delegated workers before validation and reporting. Use it only for an entire repository. |87 configuration.
86| Review a change before merge | `$codex-security:security-diff-scan` | Reviews a pull request, commit, branch diff, or working-tree patch and produces a Markdown report grounded in changed code. |88
87| Fix one finding | `$codex-security:fix-finding` | Reproduces or validates one plausible finding, makes a minimal fix when needed, and checks that the vulnerable behavior no longer reproduces. |894. Review the result
90
91 Use the UI to browse findings or open the generated report for a complete,
92 portable review.
93
94 <figure className="not-prose my-6">
95 <div className="overflow-hidden rounded-xl border border-subtle bg-surface">
96 <img
97 src={findingsWorkspace.src}
98 alt="Completed Codex Security findings workspace for OWASP Juice Shop"
99 className="block h-auto w-full"
100 />
101 </div>
102 <figcaption className="mt-3 text-sm text-secondary">
103 Browse findings by severity, category, directory, patch status, and
104 review status.
105 </figcaption>
106 </figure>
88 107
89For example, to scan a repository:108</WorkflowSteps>
90 109
91```text110## What the scan creates
92Use $codex-security:security-scan to scan this repository for security
93vulnerabilities. Keep the scan grounded in code evidence, validate plausible
94findings where feasible, and return the final report paths. Do not modify code.
95```
96 111
97To review the current change instead:112Every completed scan opens a findings workspace. Use it to review findings and
113coverage without inspecting raw artifacts. The scan also creates:
98 114
99```text115- `report.md`, a complete portable report for sharing or archiving.
100Use $codex-security:security-diff-scan to review the current branch diff for116- Structured scan data in `scan-manifest.json`, `findings.json`, and
101security regressions. Keep the review scoped to changed code and directly117 `coverage.json` for automation and integrations. You normally don't need to
102supporting files. Do not modify code.118 open these files yourself.
103```
104 119
105## Review the result and fix findings120## Choose your next workflow
106 121
107Repository scans use a staged workflow:122- [Run a standard or scoped scan](https://developers.openai.com/codex/security/plugin/scans) when you want
123 to scan a repository or one folder with the default workflow.
124- [Run a deep scan](https://developers.openai.com/codex/security/plugin/deep-scans) when you need a more
125 comprehensive scan and can wait longer for it to finish.
126- [Review code changes](https://developers.openai.com/codex/security/plugin/code-changes) when the target is
127 a pull request, commit, branch range, or working-tree patch.
128- [Triage a backlog](https://developers.openai.com/codex/security/plugin/triage-backlog) when you have
129 existing security findings to review.
130- [Fix and verify a finding](https://developers.openai.com/codex/security/plugin/fix-findings) after you
131 accept one finding for remediation.
132- [Export or track findings](https://developers.openai.com/codex/security/plugin/export-findings) when you
133 need JSON, CSV, SARIF, an approval-gated Linear, GitHub, or Jira issue, or a
134 private draft GitHub Security Advisory.
108 135
1091. **Threat modeling** identifies entry points, trust boundaries, sensitive136## Install from Codex CLI
110 actions, and risky components.
1112. **Finding discovery** looks for concrete source-to-sink paths or broken
112 controls in the requested scope.
1133. **Validation** tests or otherwise verifies plausible findings and records
114 evidence or proof gaps.
1154. **Attack-path analysis** traces exploitable paths and rates severity for
116 findings that survive validation.
1175. **Reporting** writes findings, affected locations, validation evidence,
118 remediation guidance, and review directives to artifacts.
119 137
120An ordinary repository scan or a deep scan writes `report.md` and a readable138To install the same plugin from the CLI, start Codex in the repository and open
121`report.html` within its scan directory. A diff scan writes a focused Markdown139the plugin browser:
122report. Review affected files, evidence, assumptions, and severity before
123starting remediation.
124
125When a finding is actionable, ask for a bounded fix:
126 140
127```text141```text
128Use $codex-security:fix-finding to fix finding [finding ID or report142codex
129reference]. Add focused regression coverage, verify legitimate behavior still143/plugins
130works, and show that the original issue no longer reproduces. Do not broaden
131the change beyond this finding.
132```144```
133 145
134## Keep security work authorized and reviewable146Search for **Codex Security**, select `Install plugin`, and start a new thread.
135 147Then use the same first-scan prompt.
136Run scans only against repositories, diffs, and systems that you own or that
137your organization authorizes you to assess. A finding is an input to review,
138not an instruction to merge code or test unrelated targets.
139
140- Keep the first scan read-only unless you explicitly ask Codex to prepare a
141 fix.
142- Review commands that build, run, or reproduce behavior before approving
143 them, especially in unfamiliar repositories.
144- Review every proposed patch and validation result before merging it.
145- Keep repository instructions and approval policies in place while using the
146 plugin. For details, see [Agent approvals and security](https://developers.openai.com/codex/agent-approvals-security).
147
148## Explore security use cases
149
150- [Run a deep security scan](https://developers.openai.com/codex/use-cases/deep-security-scan)
151- [Scan code changes for security](https://developers.openai.com/codex/use-cases/scan-code-changes-for-security)
152- [Remediate a vulnerability backlog](https://developers.openai.com/codex/use-cases/remediate-vulnerability-backlog)
