Documentation 2026-07-29 22:01 UTC to 2026-07-30 23:58 UTC

65credential chain. The local client can use these standard AWS SDK credential65credential chain. The local client can use these standard AWS SDK credential

66sources:66sources:

67 67 

681. Shared AWS `config` and `credentials` files.68#### Shared AWS configuration files

69 

70Configure the shared AWS `config` and `credentials` files:

69 71 

70```shell72```shell

71 aws configure73aws configure

72```74```

73 75 

742. Environment variables.76#### Environment variables

77 

78Set the standard AWS SDK credential environment variables:

75 79 

76```shell80```shell

77 export AWS_ACCESS_KEY_ID=<your-access-key-id>81export AWS_ACCESS_KEY_ID=<your-access-key-id>

78 export AWS_SECRET_ACCESS_KEY=<your-secret-access-key>82export AWS_SECRET_ACCESS_KEY=<your-secret-access-key>

79 export AWS_SESSION_TOKEN=<your-session-token>83export AWS_SESSION_TOKEN=<your-session-token>

80```84```

81 85 

823. AWS Management Console credentials.86#### AWS Management Console credentials

87 

88Log in with AWS Management Console credentials:

83 89 

84```shell90```shell

85 aws login91aws login

86```92```

87 93 

884. AWS SSO or a named profile.94#### AWS SSO or a named profile

95 

96Log in with AWS SSO and select the named profile:

89 97 

90```shell98```shell

91 aws sso login --profile codex-bedrock99aws sso login --profile codex-bedrock

92 export AWS_PROFILE=codex-bedrock100export AWS_PROFILE=codex-bedrock

93```101```

94 102 

955. Federated identity configured with `credential_process`. For corporate SSO or103#### Federated identity

96 OIDC federation, configure the AWS profile outside the local client and let104 

97 the AWS SDK resolve credentials. Put browser login, token exchange, caching,105For corporate SSO or OIDC federation, configure a federated identity with

98 and refresh in your AWS profile's `credential_process` helper.106`credential_process` outside the local client and let the AWS SDK resolve

107credentials. Put browser login, token exchange, caching, and refresh in your

108AWS profile's `credential_process` helper.

99 109 

100## Desktop app and IDE extension110## Desktop app and IDE extension

101 111 

4 4 

5Codex Micro is a limited-run collaboration between Codex and Work Louder. It5Codex Micro is a limited-run collaboration between Codex and Work Louder. It

6works with the ChatGPT desktop app, giving you a quick way to check on chats,6works with the ChatGPT desktop app, giving you a quick way to check on chats,

7jump between them, use push-to-talk, and trigger common actions or skills7jump between them, use voice input, and trigger common actions or skills without

8without leaving the keyboard.8leaving the keyboard.

9 9 

10 10

11 11 

24## Set up Codex Micro24## Set up Codex Micro

25 25 

261. Open the ChatGPT desktop app.261. Open the ChatGPT desktop app.

272. Connect Codex Micro to your computer with a USB-C cable or Bluetooth, then272. Press the rear button once to turn on Codex Micro.

28 follow the setup that appears when ChatGPT detects it.283. Connect it with a USB-C cable or [pair it with Bluetooth](#pair-with-bluetooth),

293. On macOS, allow **Input Monitoring** when prompted so ChatGPT can respond to29 then follow the setup that appears when ChatGPT detects it.

304. On macOS, allow **Input Monitoring** when prompted so ChatGPT can respond to

30 key presses.31 key presses.

314. Open **Settings > Codex Micro** to choose which chats the Agent Keys follow,325. Open **Settings > Codex Micro** to choose what the Agent Keys follow or

32 assign actions to the Command Keys and analog directions, and adjust the33 trigger, customize the Command Keys, analog stick, and dial, and adjust

33 lighting.34 lighting and voice controls.

34 35 

35To open these settings again, press and hold the dial for 500 milliseconds or36By default, press and hold the dial for a short while to open these settings. You

36select the Codex Micro icon beside your account name at the bottom of ChatGPT.37can also select the Micro icon beside your account name at the bottom of ChatGPT.

38A custom dial assignment can replace the press-and-hold shortcut.

37 39 

38You'll see **Codex Micro** in Settings after ChatGPT detects the device for the40The device settings remain available after ChatGPT detects a supported Micro for

39first time. If you want to use the device outside ChatGPT, customize those41the first time. Work Louder Input isn't required for the ChatGPT integration.

40controls with [Work Louder Input](https://worklouder.cc/micro-setup).42Use it to customize controls for other apps or configure more layers.

43 

44## Pair with Bluetooth

45 

46Codex Micro provides three Bluetooth channels.

47 

481. Press the rear button once to turn on the Micro.

492. Press and hold the touch control on the bottom-left edge for three seconds.

50 The lighting under the Micro turns blue when Bluetooth mode is active.

513. Tap the touch control to choose Bluetooth channel 1, 2, or 3. A fast-flashing

52 channel light means the Micro is ready to pair.

534. Open your computer's Bluetooth settings and connect to the Micro when it

54 appears.

555. Wait for the channel light to turn solid, which means pairing is complete.

56 

57The connection selector closes after five seconds without input. To switch to

58another paired channel, open the selector again, choose the channel, and wait

59for it to close. To pair that channel again, press and hold the touch control

60for three seconds until its light begins flashing.

61 

62To use USB-C instead, open the connection selector and tap the touch control

63until the lighting under the Micro turns white. Connecting a USB-C cable while

64the Micro is still in Bluetooth mode charges it but doesn't switch it to the

65wired connection.

66 

67For hardware diagrams, see the [Work Louder Codex Micro setup

68guide](https://worklouder.cc/openai-micro-setup).

41 69 

42<a id="read-and-switch-tasks-with-agent-keys"></a>70<a id="read-and-switch-tasks-with-agent-keys"></a>

43 71 

46Each of the six frosted Agent Keys can follow a chat and light up to show its74Each of the six frosted Agent Keys can follow a chat and light up to show its

47current status. Press an Agent Key once to switch to that chat without bringing75current status. Press an Agent Key once to switch to that chat without bringing

48ChatGPT forward. Press it twice within 350 milliseconds to switch chats and76ChatGPT forward. Press it twice within 350 milliseconds to switch chats and

49bring the ChatGPT window forward.77bring the ChatGPT window forward. To focus ChatGPT with the first press, turn on

78**Focus ChatGPT with a single tap** in the device settings.

50 79 

51| Light | Status | Meaning |80| Light | Status | Meaning |

52| ----- | ---------------- | ----------------------------------------- |81| ----- | ---------------- | ----------------------------------------- |

60The selected chat's key pulses with its status light.89The selected chat's key pulses with its status light.

61 90 

62Out of the box, the keys follow your six most recently updated chats, whether91Out of the box, the keys follow your six most recently updated chats, whether

63or not they're pinned. You can change **Agent source** in **Settings > Codex92or not they're pinned. Change **Agent keys** in the device settings to use a

64Micro** to use a different arrangement:93different arrangement:

65 94 

66- **Most recent chats**: Follow the six most recently updated chats, pinned or95- **Most recent chats**: Follow the six most recently updated chats, pinned or

67 unpinned.96 unpinned.

68- **Pinned chats**: Follow the first six chats in **Pinned**.97- **Pinned chats**: Follow the first six chats in **Pinned**.

69- **Priority chats**: Put chats waiting for input, unread chats, and active98- **Priority chats**: Put chats waiting for input, unread chats, and active

70 chats first.99 chats first.

71- **Custom assignments**: Choose the chat assigned to each Agent Key. Press an100- **Custom assignments**: Assign a chat, shortcut, physical key action, or enabled

72 unassigned Agent Key to open a new chat. When you start the chat, ChatGPT101 skill to each Agent Key. Press an unassigned Agent Key to open a new chat.

73 assigns it to that key.102 When you start the chat, ChatGPT assigns it to that key.

74 103 

75The status colors stay the same. You can decide which chats the Agent Keys104The status colors stay the same for keys that follow chats. With **Custom

76follow, but you can't turn them into extra Command Keys.105assignments**, an Agent Key can trigger an action instead.

77 106 

78## Use and customize Command Keys107## Use and customize Command Keys

79 108 

99 128 

100 129 

101The Mic key uses your computer's microphone. Codex Micro doesn't have a130The Mic key uses your computer's microphone. Codex Micro doesn't have a

102microphone of its own. Hold the key while you speak, then release it to stop.131microphone of its own. By default, it uses **Push to talk**: hold the key while

103For hands-free recording, press it twice within 350 milliseconds to keep132you speak, then release it to stop. For hands-free recording, press it twice

104recording. Press it again to stop.133within 350 milliseconds to keep recording. Press it again to stop.

105 134 

106A sea-green light moves around the keyboard while you record. It changes to a135A sea-green light moves around the keyboard while you record. It changes to a

107moving white light while ChatGPT processes your speech, then turns solid white136moving white light while ChatGPT processes your speech, then turns solid white

108when the prompt is ready. Press the Codex key to send it.137when the prompt is ready. Press the Codex key to send it.

109 138 

110In **Settings > Codex Micro**, select a Command Key, then choose its keycap and139If **Voice Chat** is available under **Microphone key**, choose it to use the

111action. You can open the browser or terminal, review changes, commit with Git,140Mic key to start a Voice Chat or toggle your microphone; press and hold it to

112create a pull request, attach files or photos, manage scheduled tasks, change141end the chat. Turn on **Use separate microphone keys** to map the two switches

113reasoning effort, or open **Skills**. If you choose a keycap that's already used142under the wide Mic key independently.

143 

144In the device settings, select a Command Key in the **Layout** preview, then

145choose its keycap and action. You can open the browser or terminal, manage

146chats, review changes, run Git and pull request actions, attach files or photos,

147open plugins or scheduled tasks, change reasoning effort, run an enabled skill,

148or assign another shortcut. If you choose a keycap that's already used

114somewhere else, ChatGPT swaps the two instead of using one keycap twice.149somewhere else, ChatGPT swaps the two instead of using one keycap twice.

115 150 

116After you remap a key, swap the physical keycap to match its new action.151After you remap a key, swap the physical keycap to match its new action.

152Select **Reset layout** to restore the default Command Key and analog stick

153assignments without changing the Agent Key mode or custom chat assignments.

117 154 

118 155

119 156 

132actions. Codex Micro starts with the mappings shown here.169actions. Codex Micro starts with the mappings shown here.

133 170 

134Choose any available ChatGPT desktop command or enabled skill for each171Choose any available ChatGPT desktop command or enabled skill for each

135direction in **Settings > Codex Micro**.172direction in the device settings.

136 173 

137 174

138 175 

151 188 

152 189 

153 190 

154The dial moves through the composer controls and options, with **Reasoning**191The dial uses **Composer navigation** by default. Turn it to move through

155selected by default. Turn the dial to change the selection, then press it to192composer controls and options, then press it to open or select the focused

156open or select the focused control. When a composer control or menu is open,193control. When a composer control or menu is open, the Agent Key immediately to

157the Agent Key immediately to the right of the dial lights red. Press that key194the right of the dial lights red. Press that key to cancel.

158to cancel.195 

196Choose one of four dial modes in the device settings:

197 

198| Mode | Behavior |

199| -------------------------- | ------------------------------------------------------------------------------ |

200| **Composer navigation** | Move through composer controls and select the focused control. |

201| **Reasoning only** | Adjust reasoning effort and open its slider or advanced options. |

202| **Conversation scrolling** | Scroll the active chat; press the dial to jump to the latest message. |

203| **Custom assignments** | Assign an action or skill to the left turn, right turn, press, and long press. |

159 204 

160In **Settings > Codex Micro**, choose whether the dial uses **Composer205Pressing and holding the dial opens the device settings in every mode except

161navigation** or **Reasoning only**. In **Reasoning only** mode, turning the dial206**Custom assignments**, where it runs the action assigned to the long press.

162opens and adjusts reasoning effort. Press the dial to open the slider or its

163advanced options.

164 207 

165## Adjust lighting208## Adjust lighting

166 209 

167In **Settings > Codex Micro**, adjust the brightness and choose how long the210{/* vale Microsoft.Auto = NO */}

168lights stay on when you're not using Codex Micro. They come back on when you

169use the keyboard or an Agent Key changes status. By default, the lights turn

170off after three minutes.

171 211 

172When the keyboard reports its battery status, you can see it in **Settings >212In the device settings, adjust **Brightness** and choose an **Auto-dim**

173Codex Micro** and in the Codex Micro icon's sidebar tooltip.213interval from 30 seconds to one hour, or turn automatic dimming off. The lights

214come back on when you use the Micro or an Agent Key changes status. By default,

215the lights turn off after three minutes.

216 

217{/* vale Microsoft.Auto = YES */}

218 

219When the Micro reports its battery status, you can see it in the device settings

220and beside the Micro icon in the sidebar.

174 221 

175## Add more layers222## Add more layers

176 223 

177Codex uses layer 1. Use [Work Louder224ChatGPT uses layer 1. Use [Work Louder

178Input](https://worklouder.cc/micro-setup) to configure up to five more layers225Input](https://worklouder.cc/micro-setup) to configure up to five more layers

179with shortcuts and actions for other apps.226with shortcuts and actions for other apps.

180 227 

181## Troubleshoot Codex Micro228## Troubleshoot Codex Micro

182 229 

183### Pair the keyboard again

184 

185Use the bottom-left touch control to start pairing again. The rear button

186controls power and doesn't start pairing.

187 

1881. Hold the bottom-left touch control for three seconds to enter communication

189 mode.

1902. Tap the control to choose Bluetooth channel 1, 2, or 3.

1913. Hold the control for three seconds on that channel. The channel light flashes

192 while pairing and turns solid when paired.

193 

194### Fix Input Monitoring on macOS230### Fix Input Monitoring on macOS

195 231 

196If **Settings > Codex Micro** shows that Input Monitoring isn't set up, select232If the device settings show that Input Monitoring isn't set up, select **Open

197**Open System Settings**, then follow these steps:233System Settings**, then follow these steps:

198 234 

1991. Open **System Settings > Privacy & Security > Input Monitoring**.2351. Open **System Settings > Privacy & Security > Input Monitoring**.

2002. Turn on access for ChatGPT if it's already listed. If it's missing, drag2362. Turn on access for ChatGPT if it's already listed. If it's missing, drag

201 **ChatGPT** from Applications into the list, or select **Add (+)** and choose237 **ChatGPT** from Applications into the list, or select **Add (+)** and choose

202 **ChatGPT**.238 **ChatGPT**.

2033. Quit and reopen ChatGPT, then confirm ChatGPT detects Codex Micro on layer 1.2393. Quit and reopen ChatGPT, then confirm it detects the Micro on layer 1.

204 240 

205For more about this macOS permission, see [Apple's Input Monitoring241For more about this macOS permission, see [Apple's Input Monitoring

206guide](https://support.apple.com/guide/mac-help/mchl4cedafb6/mac).242guide](https://support.apple.com/guide/mac-help/mchl4cedafb6/mac).

207 243 

208### Get more Work Louder help244### Fix connection interference

245 

246ChatGPT retries automatically when it detects a Micro but can't connect or loses

247communication. If the problem continues, reconnect the Micro and check whether

248a keyboard utility or security tool blocks access to it.

209 249 

210For help with Bluetooth, cables, power, or resetting the keyboard, see250{/* vale Vale.Spelling = NO */}

211the [Creator Micro 2 setup guide from Work Louder](https://worklouder.cc/micro-setup).

212For direct support, email [hello@worklouder.cc](mailto:hello@worklouder.cc).

213 251 

214## Get Codex Micro252On macOS, Work Louder notes that Karabiner and Logitech Options+ can interfere

253with Micro communication when those apps have Input Monitoring permission. To

254test for interference, quit the keyboard utility or temporarily turn off its

255Input Monitoring access, then reconnect the Micro. If your organization manages

256your computer, ask your IT administrator to check the device rules.

215 257 

216You can buy Codex Micro through [OpenAI Supply258{/* vale Vale.Spelling = YES */}

217Co](https://openai.com/supply/co-lab/work-louder/) while supplies last.259 

260### Get more Work Louder help

218 261 

219{/* vale Microsoft.We = NO */}262For help with Bluetooth, cables, power, or resetting the keyboard, see the [Work

220{/* vale write-good.TooWordy = NO */}263Louder Codex Micro setup guide](https://worklouder.cc/openai-micro-setup). For

264direct support, email

265[hello@worklouder.cc](mailto:hello@worklouder.cc).

221 266 

222We expect orders to begin shipping shortly after purchase.267## Get a compatible Micro

223 268 

224{/* vale Microsoft.We = YES */}269Check Codex Micro availability through [OpenAI Supply

225{/* vale write-good.TooWordy = YES */}270Co](https://openai.com/supply/co-lab/work-louder/). The ChatGPT desktop app also

271supports [Creator Micro 2](https://worklouder.cc/creator-micro-2), available

272directly from Work Louder.

17For a prescriptive first local scan, start with the [Codex Security plugin17For a prescriptive first local scan, start with the [Codex Security plugin

18quickstart](https://learn.chatgpt.com/docs/security/plugin).18quickstart](https://learn.chatgpt.com/docs/security/plugin).

19 19 

20## Use Codex Security in the desktop app

21 

22Install and enable the Codex Security plugin to open **Security** in the

23desktop-app sidebar. The Security workbench keeps your scans, findings, and

24repositories in one place while Codex runs each scan in a task.

25 

26- Use **Scans** to start scans, follow their progress, and review saved results.

27- Use **Findings** to inspect issues and evidence across completed scans.

28- Use **Repositories** to review repository history and open findings.

29 

30See [Use the Security workbench](https://learn.chatgpt.com/docs/security/plugin/workbench) for the

31complete desktop-app workflow.

32 

20### Explore plugin use cases33### Explore plugin use cases

21 34 

22- [Run a security scan](https://learn.chatgpt.com/docs/security/plugin/scans) for a repository or one scoped folder.35- [Run a security scan](https://learn.chatgpt.com/docs/security/plugin/scans) for a repository or one scoped folder.

29- [Propose security hardening](https://learn.chatgpt.com/docs/security/plugin/security-hardening) from scan results or other security evidence.42- [Propose security hardening](https://learn.chatgpt.com/docs/security/plugin/security-hardening) from scan results or other security evidence.

30- [See what's new](https://learn.chatgpt.com/docs/security/plugin/changelog) in the Codex Security plugin.43- [See what's new](https://learn.chatgpt.com/docs/security/plugin/changelog) in the Codex Security plugin.

31 44 

32The plugin runs in your Codex chat. Codex Security cloud scans connected45The desktop Security workbench and Codex CLI use the Codex Security plugin.

33 GitHub repositories through Codex cloud. For Codex sandboxing, approvals,46 Codex Security cloud scans connected GitHub repositories through Codex cloud.

34 network controls, and admin settings, see [Agent approvals &47 For Codex sandboxing, approvals, network controls, and admin settings, see

35 security](https://learn.chatgpt.com/docs/agent-approvals-security).48 [Agent approvals & security](https://learn.chatgpt.com/docs/agent-approvals-security).

36 49 

37## Codex Security CLI and SDK50## Codex Security CLI and SDK

38 51 

39The Codex Security CLI and SDK are in limited beta and available only to52The CLI and TypeScript SDK are available as the public

40approved customers and partners. Contact your account team for access.53[`@openai/codex-security`](https://github.com/openai/codex-security) package.

54Install the package:

55 

56```bash

57npm install @openai/codex-security

58```

59 

60Running scans requires Codex Security access. For best results, use an account

61verified for [Trusted Access for Cyber](https://chatgpt.com/cyber).

41 62 

42Use the same scanner as the plugin across repositories and over time. The CLI63Use the same scanner as the plugin across repositories and over time. The CLI

43discovers GitHub repositories, resumes bulk scans, tracks findings across64discovers GitHub repositories, resumes bulk scans, tracks findings across

90## Related docs111## Related docs

91 112 

92- [Codex Security plugin quickstart](https://learn.chatgpt.com/docs/security/plugin) walks through installation and a first local scan.113- [Codex Security plugin quickstart](https://learn.chatgpt.com/docs/security/plugin) walks through installation and a first local scan.

114- [Security workbench](https://learn.chatgpt.com/docs/security/plugin/workbench) explains saved scans, findings, repositories, and scan activity in the desktop app.

93- [Codex Security CLI quickstart](https://learn.chatgpt.com/docs/security/cli) walks through setup, preflight, and a first terminal scan.115- [Codex Security CLI quickstart](https://learn.chatgpt.com/docs/security/cli) walks through setup, preflight, and a first terminal scan.

94- [Run bulk security scans](https://learn.chatgpt.com/docs/security/cli/bulk-scans) explains GitHub discovery, CSV inventories, campaign results, and resume behavior.116- [Run bulk security scans](https://learn.chatgpt.com/docs/security/cli/bulk-scans) explains GitHub discovery, CSV inventories, campaign results, and resume behavior.

95- [Codex Security CLI FAQ](https://learn.chatgpt.com/docs/security/cli/faq) answers common questions about scans, findings, coverage, and costs.117- [Codex Security CLI FAQ](https://learn.chatgpt.com/docs/security/cli/faq) answers common questions about scans, findings, coverage, and costs.

7repositories you own or have permission to assess, review findings over time,7repositories you own or have permission to assess, review findings over time,

8and check changes before they land.8and check changes before they land.

9 9 

10The Codex Security CLI and SDK are in beta and require access. Follow the10The `@openai/codex-security` package is public. Running scans requires Codex

11 installation instructions provided with your access. For an interactive scan11 Security access. For an interactive scan in Codex, start with the [Codex

12 in Codex, start with the [Codex Security plugin12 Security plugin quickstart](https://learn.chatgpt.com/docs/security/plugin). For connected GitHub

13 quickstart](https://learn.chatgpt.com/docs/security/plugin). For connected GitHub repositories, see13 repositories, see [Codex Security cloud setup](https://learn.chatgpt.com/docs/security/setup).

14 [Codex Security cloud setup](https://learn.chatgpt.com/docs/security/setup).

15 14 

16## Check the prerequisites15## Check the prerequisites

17 16 

21 20 

22## Set up and verify the CLI21## Set up and verify the CLI

23 22 

24Follow the installation instructions provided for your Codex Security access.23Install the published package:

24 

25```bash

26npm install @openai/codex-security

27```

28 

25Check the installed version:29Check the installed version:

26 30 

27```bash31```bash

34npx @openai/codex-security --help38npx @openai/codex-security --help

35```39```

36 40 

37Use `npx @openai/codex-security scan --help` or `npx @openai/codex-security export --help` for the41Use `npx @openai/codex-security scan --help` or

38complete command help. The [CLI reference](https://learn.chatgpt.com/docs/security/cli/reference)42`npx @openai/codex-security export --help` for complete command help. The

39covers each argument, output format, and exit code.43[CLI reference](https://learn.chatgpt.com/docs/security/cli/reference) covers each argument, output

44format, and exit code.

40 45 

41## Sign in46## Sign in

42 47 

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

53```58```

54 59 

55For CI and other automated workflows, use an OpenAI API key instead:60For CI and other automated workflows, set an OpenAI API key:

56 61 

57```bash62```bash

58export OPENAI_API_KEY="<your-api-key>"63export OPENAI_API_KEY="<your-api-key>"

59```64```

60 65 

61Keep API keys in your shell or secret manager. Codex Security can also reuse an66Keep API keys in your shell or secret manager. Codex Security can also reuse an

62existing file-backed Codex sign-in.67existing file-backed Codex sign-in. When both a stored ChatGPT sign-in and an

68environment API key are available, interactive scans with text output ask

69which to use. CI, JSON and JSONL scans, and other unattended scans use the

70API key by default.

63 71 

64If a ChatGPT sign-in and `OPENAI_API_KEY` or `CODEX_API_KEY` are both72To use your ChatGPT sign-in when an API key is also set, select it explicitly:

65available, interactive scans with text output ask which credential to use. CI,

66JSON and JSONL scans, and other scans without an interactive terminal use the

67environment API key by default. Dry runs don't prompt or load credentials.

68 

69To use your stored sign-in for a scan, pass `--auth chatgpt`:

70 73 

71```bash74```bash

72npx @openai/codex-security scan . --auth chatgpt75npx @openai/codex-security scan . --auth chatgpt

73```76```

74 77 

75To use an environment API key, pass `--auth api-key`:78To require the environment API key, select API-key authentication:

76 79 

77```bash80```bash

78npx @openai/codex-security scan . --auth api-key81npx @openai/codex-security scan . --auth api-key

102state directory. Results can include source excerpts and vulnerability details,105state directory. Results can include source excerpts and vulnerability details,

103so choose a private location and an appropriate retention policy.106so choose a private location and an appropriate retention policy.

104 107 

108If the default state directory isn't writable, select a writable directory

109outside the scanned repository:

110 

111```bash

112export CODEX_SECURITY_STATE_DIR=/path/outside/repository/codex-security-state

113```

114 

105Check the repository, target, and output directory before starting a scan:115Check the repository, target, and output directory before starting a scan:

106 116 

107```bash117```bash

119npx @openai/codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR"129npx @openai/codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR"

120```130```

121 131 

122The CLI writes the scan result to stdout and sends progress and its completion132By default, the CLI writes scan progress and its completion summary to stderr.

123summary to stderr. A completed scan prints a summary like this:133It doesn't print the full scan result to stdout. A completed scan prints a

134summary like this:

124 135 

125```text136```text

126codex-security: Findings: 2 (1 high, 1 medium). Coverage: complete.137codex-security: Findings: 2 (1 high, 1 medium). Coverage: complete.

127codex-security: Elapsed: 42s. Workers: 3/6.138codex-security: Elapsed: 42s.

139codex-security: Report: /path/outside/repository/codex-security-results/report.md

128codex-security: Results: /path/outside/repository/codex-security-results140codex-security: Results: /path/outside/repository/codex-security-results

129codex-security: Next: codex-security export /path/outside/repository/codex-security-results --export-format sarif

130```141```

131 142 

132For a local package installation, run the suggested export command with143Token usage and estimated cost appear when available. To print the complete

133`npx @openai/codex-security`.144result as machine-readable JSON, request structured output explicitly:

145 

146```bash

147npx @openai/codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR" --json

148```

134 149 

135Scans are report-only by default, so findings remain available for local150Scans are report-only by default, so findings remain available for local

136review. You may want to add a severity threshold when you are ready to [run scans in151review. You may want to add a severity threshold when you are ready to [run scans in

137CI](https://learn.chatgpt.com/docs/security/cli/ci).152CI](https://learn.chatgpt.com/docs/security/cli/ci).

138 153 

154## Choose a model and reasoning effort

155 

156Scans use `gpt-5.6-sol` with `xhigh` reasoning effort by default. Select a

157different model and effort when the task requires them:

158 

159```bash

160npx @openai/codex-security scan "$REPOSITORY" \

161 --model gpt-5.6-terra \

162 --effort high

163```

164 

165Supported effort levels are `minimal`, `low`, `medium`, `high`, and `xhigh`.

166 

139## Review the results167## Review the results

140 168 

141Open `report.md` for the readable result. The scan directory also contains the169Open `report.md` for the readable result. The scan directory also contains the

169Use a path scan when a repository contains separate services or packages:197Use a path scan when a repository contains separate services or packages:

170 198 

171```bash199```bash

172npx @openai/codex-security scan "$REPOSITORY" --path services/billing --path packages/auth200npx @openai/codex-security scan "$REPOSITORY" \

201 --path services/billing \

202 --path packages/auth

173```203```

174 204 

175Review committed changes between the base revision and `HEAD`:205Review committed changes between the base revision and `HEAD`:

193npx @openai/codex-security scan "$REPOSITORY" --mode deep223npx @openai/codex-security scan "$REPOSITORY" --mode deep

194```224```

195 225 

226Deep mode supports repository and path targets, not diff or working-tree scans.

227 

196## Add architecture and security context228## Add architecture and security context

197 229 

198Provide architecture documents, threat models, or security policies as scan230Provide architecture documents, threat models, or security policies as scan

296npx @openai/codex-security scans show SCAN_ID328npx @openai/codex-security scans show SCAN_ID

297```329```

298 330 

331To mark a reviewed finding as a false positive, explain why the finding doesn't

332apply:

333 

334```bash

335npx @openai/codex-security findings false-positive FINDING_OCCURRENCE_ID \

336 --reason "The route already checks permissions"

337```

338 

339Later scans consider that explanation but still recheck the current code.

340 

299Run the same scan against the current checkout using its original configuration:341Run the same scan against the current checkout using its original configuration:

300 342 

301```bash343```bash

2 2 

3> For the complete documentation index, see [llms.txt](https://learn.chatgpt.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.3> For the complete documentation index, see [llms.txt](https://learn.chatgpt.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.

4 4 

5Use `codex-security bulk-scan` to review repositories in one5Use `npx @openai/codex-security bulk-scan` to review repositories in one

6campaign. Discover repositories from a GitHub account or organization, or6campaign. Discover repositories from your personal GitHub account or an

7provide a CSV that pins every repository to an exact Git revision.7organization, or provide a CSV that pins every repository to an exact Git

8revision.

8 9 

9The Codex Security CLI is in beta and requires access. Follow the [CLI10The `@openai/codex-security` package is public. Running scans requires Codex

10 quickstart](https://learn.chatgpt.com/docs/security/cli) to install the CLI and sign in before11 Security access. Follow the [CLI quickstart](https://learn.chatgpt.com/docs/security/cli) to install

11 starting a bulk scan.12 the CLI and sign in.

12 13 

13## Choose a repository source14## Choose a repository source

14 15 

15| Source | When to use it |16| Source | When to use it |

16| ---------------- | ------------------------------------------------------------------------ |17| ---------------- | --------------------------------------------------------------------------------------- |

17| GitHub discovery | Choose repositories interactively from a GitHub account or organization. |18| GitHub discovery | Choose repositories interactively from your personal GitHub account or an organization. |

18| CSV inventory | Run a repeatable, automated campaign against exact repository revisions. |19| CSV inventory | Run a repeatable, automated campaign against exact repository revisions. |

19 20 

20Both workflows save progress, preserve per-repository results, and let you21Both workflows save progress, preserve per-repository results, and let you

36 37 

37The CLI guides you through these steps:38The CLI guides you through these steps:

38 39 

391. Choose a GitHub account or organization.401. Choose your personal GitHub account or an organization.

402. Review repositories active within the last 90 days.412. Review repositories active within the last 90 days.

413. Search the repository list and select repositories to scan.423. Search the repository list and select repositories to scan.

424. Choose a directory for scan results.434. Choose a directory for scan results.

107complete only when its scan has complete coverage and all required result108complete only when its scan has complete coverage and all required result

108artifacts exist.109artifacts exist.

109 110 

111## Choose a model and reasoning effort

112 

113Bulk scans use `gpt-5.6-sol` with `xhigh` reasoning effort by default. To

114choose another model and effort for a CSV campaign:

115 

116```bash

117npx @openai/codex-security bulk-scan repositories.csv \

118 --output-dir /path/outside/repositories/security-scans \

119 --workers 4 \

120 --model gpt-5.6-terra \

121 --effort high

122```

123 

124The same options work during interactive repository discovery:

125 

126```bash

127npx @openai/codex-security bulk-scan --model gpt-5.6-terra --effort high

128```

129 

130Supported effort levels are `minimal`, `low`, `medium`, `high`, and `xhigh`.

131 

110## Review campaign results132## Review campaign results

111 133 

112The output directory contains the pinned campaign, an append-only results134The output directory contains the pinned campaign, an append-only results

7severity. Start with advisory results, review scan quality and runtime, then7severity. Start with advisory results, review scan quality and runtime, then

8add a severity policy that fits your repository.8add a severity policy that fits your repository.

9 9 

10The Codex Security CLI is in beta and requires access. Follow the installation10Install the public `@openai/codex-security` package. Running scans still

11 instructions provided with your access.11 requires Codex Security access.

12 12 

13This guide uses GitHub Actions. The same scan and export commands work in other13This guide uses GitHub Actions. The same scan and export commands work in other

14CI systems.14CI systems.

18Store an OpenAI API key as a repository or organization secret named18Store an OpenAI API key as a repository or organization secret named

19`CODEX_SECURITY_API_KEY`.19`CODEX_SECURITY_API_KEY`.

20 20 

21Map this secret directly to the scan step's `CODEX_API_KEY` environment21Map this secret directly to the scan step's `OPENAI_API_KEY` environment

22variable. Keep the credential scoped to that variable within the scan process.22variable. Keep the credential scoped to the scan process and use

23 23`--auth api-key` to select it explicitly.

24Set the `CODEX_SECURITY_PACKAGE` repository or organization variable to an

25approved package source provided with your access, such as a trusted archive

26location or registry package specification. The source must be available to

27the runner before it checks out the repository.

28 24 

29The runner needs:25The runner needs:

30 26 

31- Node.js 22 or later.27- Node.js 22 or later.

32- Python 3.10 or later.28- Python 3.10 or later.

33- The Codex Security CLI, installed outside the repository checkout using the29- The published `@openai/codex-security` package, installed outside the

34 instructions provided with your access.30 repository checkout.

35- The pull-request head and base history so Git can calculate the merge base.31- The pull-request head and base history so Git can calculate the merge base.

36- [GitHub Code Security](https://docs.github.com/en/code-security/code-scanning/integrating-with-code-scanning/uploading-a-sarif-file-to-github)32- [GitHub Code Security](https://docs.github.com/en/code-security/code-scanning/integrating-with-code-scanning/uploading-a-sarif-file-to-github)

37 enabled for private or internal repositories when you upload SARIF.33 enabled for private or internal repositories when you upload SARIF.

38 34 

39The example skips pull requests from forks and Dependabot. These workflows

40 don't receive normal Actions secrets, and Dependabot receives a read-only

41 `GITHUB_TOKEN` by default. Keep scan credentials available only to trusted

42 workflows.

43 

44## Add the GitHub Actions workflow35## Add the GitHub Actions workflow

45 36 

46Create `.github/workflows/codex-security.yml`. Before checking out the pull37Create `.github/workflows/codex-security.yml`. Before checking out the pull

47request, install the approved package under `$RUNNER_TEMP/codex-security` so38request, install `@openai/codex-security@0.1.3` under

48the trusted executable is available at39`$RUNNER_TEMP/codex-security` so the trusted executable is available at

49`$RUNNER_TEMP/codex-security/node_modules/.bin/codex-security`:40`$RUNNER_TEMP/codex-security/node_modules/.bin/codex-security`:

50 41 

51```yaml42```yaml

74 python-version: "3.14"65 python-version: "3.14"

75 66 

76 - name: Install Codex Security67 - name: Install Codex Security

77 env:

78 CODEX_SECURITY_PACKAGE: ${{ vars.CODEX_SECURITY_PACKAGE }}

79 run: |68 run: |

80 set -euo pipefail69 set -euo pipefail

81 if test -z "$CODEX_SECURITY_PACKAGE"; then

82 echo "Set the CODEX_SECURITY_PACKAGE repository or organization variable." >&2

83 exit 1

84 fi

85 npm install \70 npm install \

86 --prefix "$RUNNER_TEMP/codex-security" \71 --prefix "$RUNNER_TEMP/codex-security" \

87 --ignore-scripts \72 --ignore-scripts \

88 --no-audit \73 --no-audit \

89 --no-fund \74 --no-fund \

90 "$CODEX_SECURITY_PACKAGE"75 @openai/codex-security@0.1.3

91 76 

92 - name: Verify Codex Security77 - name: Verify Codex Security

93 env:78 env:

106 91 

107 - name: Scan the pull request92 - name: Scan the pull request

108 env:93 env:

109 CODEX_API_KEY: ${{ secrets.CODEX_SECURITY_API_KEY }}94 OPENAI_API_KEY: ${{ secrets.CODEX_SECURITY_API_KEY }}

110 CODEX_SECURITY_BIN: ${{ runner.temp }}/codex-security/node_modules/.bin/codex-security95 CODEX_SECURITY_BIN: ${{ runner.temp }}/codex-security/node_modules/.bin/codex-security

96 CODEX_SECURITY_STATE_DIR: ${{ runner.temp }}/codex-security-state

111 BASE_SHA: ${{ github.event.pull_request.base.sha }}97 BASE_SHA: ${{ github.event.pull_request.base.sha }}

112 HEAD_SHA: ${{ github.event.pull_request.head.sha }}98 HEAD_SHA: ${{ github.event.pull_request.head.sha }}

113 SCAN_DIR: ${{ runner.temp }}/codex-security-results99 SCAN_DIR: ${{ runner.temp }}/codex-security-results

117 "$CODEX_SECURITY_BIN" scan . \103 "$CODEX_SECURITY_BIN" scan . \

118 --diff "$BASE_REVISION" \104 --diff "$BASE_REVISION" \

119 --head "$HEAD_SHA" \105 --head "$HEAD_SHA" \

106 --auth api-key \

120 --output-dir "$SCAN_DIR" \107 --output-dir "$SCAN_DIR" \

121 --json > "$RUNNER_TEMP/codex-security.json"108 --json > "$RUNNER_TEMP/codex-security.json"

122 109 

163target exact. `persist-credentials: false` keeps the repository token out of150target exact. `persist-credentials: false` keeps the repository token out of

164the checked-out Git configuration. Installing the CLI before checkout and151the checked-out Git configuration. Installing the CLI before checkout and

165running its absolute path keeps repository-controlled executables away from152running its absolute path keeps repository-controlled executables away from

166the scan credential. Pinning each action to a verified commit prevents an153the scan credential. `--auth api-key` explicitly selects the scoped API key.

167upstream tag change from changing the workflow.154The scan saves its history in a writable state directory outside the

155repository.

168 156 

169`--json` writes one complete JSON document to stdout, so the workflow can save157`--json` writes one complete JSON document to stdout, so the workflow can save

170it directly. Progress, completion summaries, and errors remain on stderr. This158it directly. Progress, completion summaries, and errors remain on stderr. This

228 directory already contains results.216 directory already contains results.

229- **Missing credentials:** Confirm the `CODEX_SECURITY_API_KEY` repository217- **Missing credentials:** Confirm the `CODEX_SECURITY_API_KEY` repository

230 secret is available to the trusted workflow and mapped directly to the scan218 secret is available to the trusted workflow and mapped directly to the scan

231 step's `CODEX_API_KEY` environment variable.219 step's `OPENAI_API_KEY` environment variable.

220- **Scan history error:** Set `CODEX_SECURITY_STATE_DIR` to a writable

221 directory outside the repository.

232- **Python setup error:** Confirm that the runner uses Python 3.10 or later.222- **Python setup error:** Confirm that the runner uses Python 3.10 or later.

233- **Incomplete coverage:** Review `coverage.json`, including deferred surfaces223- **Incomplete coverage:** Review `coverage.json`, including deferred surfaces

234 and open questions, then rerun with an appropriate target or environment.224 and open questions, then rerun with an appropriate target or environment.

10 10 

11### Who can use the CLI11### Who can use the CLI

12 12 

13The Codex Security CLI and SDK are in limited beta. Approved customers and13The `@openai/codex-security` package is public. Install the CLI and SDK:

14partners receive installation instructions with their access. Contact your14 

15account team if you need access.15```bash

16npm install @openai/codex-security

17```

18 

19Running scans requires Codex Security access. For best results, use an account

20verified for [Trusted Access for Cyber](https://chatgpt.com/cyber).

16 21 

17### Why does a scan use an API key after sign-in22### Why does a scan use an API key after sign-in

18 23 

28npx @openai/codex-security scan . --auth chatgpt33npx @openai/codex-security scan . --auth chatgpt

29```34```

30 35 

36To require an API key from `OPENAI_API_KEY` or `CODEX_API_KEY`:

37 

38```bash

39npx @openai/codex-security scan . --auth api-key

40```

41 

31To make your stored credentials the automatic default, run42To make your stored credentials the automatic default, run

32`unset OPENAI_API_KEY CODEX_API_KEY`. For all supported authentication modes,43`unset OPENAI_API_KEY CODEX_API_KEY`. For all supported authentication modes,

33see the [CLI reference](https://learn.chatgpt.com/docs/security/cli/reference#select-scan-authentication).44see the [CLI reference](https://learn.chatgpt.com/docs/security/cli/reference#select-scan-authentication).

107artifacts together. See [Scan118artifacts together. See [Scan

108artifacts](https://learn.chatgpt.com/docs/security/cli/reference#scan-artifacts) for the full layout.119artifacts](https://learn.chatgpt.com/docs/security/cli/reference#scan-artifacts) for the full layout.

109 120 

121### What if the CLI can't save scan history

122 

123Codex Security keeps scan history in a workbench database. If the default

124state directory isn't writable, choose a private directory outside the

125repository:

126 

127```bash

128export CODEX_SECURITY_STATE_DIR=/path/outside/repository/codex-security-state

129```

130 

110### How do scans distinguish new and known findings131### How do scans distinguish new and known findings

111 132 

112Match findings that share a root cause across the two scans:133Match findings that share a root cause across the two scans:

136Record why that finding doesn't apply:157Record why that finding doesn't apply:

137 158 

138```bash159```bash

139npx @openai/codex-security findings mark-false-positive FINDING_OCCURRENCE_ID \160npx @openai/codex-security findings false-positive FINDING_OCCURRENCE_ID \

140 --reason "The framework escapes this input before it reaches the query"161 --reason "The framework escapes this input before it reaches the query"

141```162```

142 163 

6output formats, and exit behavior. For a guided first scan, start with the6output formats, and exit behavior. For a guided first scan, start with the

7[CLI quickstart](https://learn.chatgpt.com/docs/security/cli).7[CLI quickstart](https://learn.chatgpt.com/docs/security/cli).

8 8 

9The Codex Security CLI is in beta and requires access. Follow the installation9The `@openai/codex-security` package is public. Running scans requires Codex

10 instructions provided with your access.10 Security access.

11 11 

12When you install the package in a local project, invoke the executable as12Install the published package in your project:

13`npx @openai/codex-security`. Use `codex-security` directly when the executable is13 

14available on your `PATH`.14```bash

15npm install @openai/codex-security

16```

17 

18Invoke the installed package as `npx @openai/codex-security`. You can use

19`codex-security` directly when the executable is available on your `PATH`.

15 20 

16## Command overview21## Command overview

17 22 

107working tree.112working tree.

108 113 

109```text114```text

110usage: codex-security scan [-h] [--path PATH | --diff BASE | --working-tree]115usage: codex-security scan [-h] [--auth {auto,chatgpt,api-key}]

116 [--path PATH | --diff BASE | --working-tree]

111 [--head HEAD] [--base BASE]117 [--head HEAD] [--base BASE]

112 [--auth {auto,chatgpt,api-key}]

113 [--knowledge-base PATH]118 [--knowledge-base PATH]

114 [--mode {standard,deep}] [--model MODEL]119 [--mode {standard,deep}] [--model MODEL]

120 [--effort {minimal,low,medium,high,xhigh}]

115 [--output-dir DIR]121 [--output-dir DIR]

116 [--archive-existing]122 [--archive-existing]

117 [--plugin-path PATH] [--python PATH]123 [--plugin-path PATH] [--python PATH]

118 [--codex KEY=VALUE] [--fail-on-severity LEVEL]124 [--codex KEY=VALUE] [--fail-on-severity LEVEL]

119 [--max-cost USD] [--dry-run] [--json] [repository]125 [--max-cost USD] [--dry-run]

126 [--json] [--format {toon,json,yaml,jsonl}]

127 [--full-output] [repository]

120```128```

121 129 

122`repository` defaults to the current directory.130`repository` defaults to the current directory.

223| `--max-cost USD` | Stop a scan when its estimated model cost exceeds the specified USD amount. |231| `--max-cost USD` | Stop a scan when its estimated model cost exceeds the specified USD amount. |

224| `--dry-run` | Check the repository, target, output directory, and Codex configuration without starting a scan. |232| `--dry-run` | Check the repository, target, output directory, and Codex configuration without starting a scan. |

225| `--json` | Print manifest, findings, coverage, paths, and turn metadata as one JSON document. |233| `--json` | Print manifest, findings, coverage, paths, and turn metadata as one JSON document. |

234| `--format FORMAT` | Print the complete scan result as `toon`, `json`, `yaml`, or `jsonl`. |

235| `--full-output` | Print the complete result using the default structured output format. |

226 236 

227The cost limit is an estimate, not a hard spending cap. Requests already in237The cost limit is an estimate, not a hard spending cap. Requests already in

228progress can finish above the limit, and partial scan results remain available.238progress can finish above the limit, and partial scan results remain available.

234contain source excerpts and vulnerability details, so manage their permissions244contain source excerpts and vulnerability details, so manage their permissions

235and retention accordingly.245and retention accordingly.

236 246 

237The output directory can be new or empty. On macOS and Linux, an existing247The workbench keeps scan history in

238directory must be private to the current user. A scan can replace an existing248`$CODEX_HOME/state/plugins/codex-security/workbench.sqlite3`. Setting

239result directory with `--archive-existing`.249`CODEX_SECURITY_STATE_DIR` also moves the workbench database.

250 

251The output directory must be outside the scanned directory and any enclosing

252Git worktree. A scan can replace an existing result directory with

253`--archive-existing`.

254 

255To preserve earlier results before reusing an output directory:

240 256 

241```bash257```bash

242npx @openai/codex-security scan . \258npx @openai/codex-security scan . \

260probing the plugin's Python interpreter:276probing the plugin's Python interpreter:

261 277 

262```bash278```bash

263npx @openai/codex-security scan . --output-dir /path/outside/repository/results --dry-run279npx @openai/codex-security scan . \

280 --output-dir /path/outside/repository/results \

281 --dry-run

264```282```

265 283 

266### Configure the runtime284### Configure the runtime

269Codex configuration value.287Codex configuration value.

270 288 

271| Argument | Description |289| Argument | Description |

272| -------------------- | -------------------------------------------------------------------------------------------------------- |290| ------------------------------------------ | -------------------------------------------------------------------------------------------------------- |

273| `--model MODEL` | Select the model for the scan. |291| `--auth {auto,chatgpt,api-key}` | Select the scan credentials. The default is `auto`. |

292| `--model MODEL` | Select the OpenAI model. The default is `gpt-5.6-sol`. |

293| `--effort {minimal,low,medium,high,xhigh}` | Select the model's reasoning effort. The default is `xhigh`. |

274| `--plugin-path PATH` | Use a Codex Security plugin directory or ZIP to override the bundled plugin. |294| `--plugin-path PATH` | Use a Codex Security plugin directory or ZIP to override the bundled plugin. |

275| `--python PATH` | Select the Python interpreter for the plugin runtime. |295| `--python PATH` | Select the Python interpreter for the plugin runtime. |

276| `--codex KEY=VALUE` | Override an isolated Codex configuration value. Values use TOML syntax. Repeat the flag for more values. |296| `--codex KEY=VALUE` | Override an isolated Codex configuration value. Values use TOML syntax. Repeat the flag for more values. |

277 297 

298To select a different model and reasoning effort without writing TOML:

299 

300```bash

301npx @openai/codex-security scan . --model gpt-5.6-terra --effort high

302```

303 

278Quote string values passed through `--codex` so the TOML parser receives a304Quote string values passed through `--codex` so the TOML parser receives a

279string:305string:

280 306 

281```bash307```bash

282npx @openai/codex-security scan . --codex 'model="<model>"'308npx @openai/codex-security scan . --codex 'model="gpt-5.6-terra"'

283```309```

284 310 

285Codex Security owns plugin-loading configuration and rejects conflicting

286overrides. Use `--plugin-path` to select a plugin.

287 

288## `codex-security install-hook`311## `codex-security install-hook`

289 312 

290Install a Git pre-commit security check for the current repository:313Install a Git pre-commit security check for the current repository:

314```text337```text

315usage: codex-security bulk-scan [input] [--output-dir DIR]338usage: codex-security bulk-scan [input] [--output-dir DIR]

316 [--workers N] [--mode {standard,deep}]339 [--workers N] [--mode {standard,deep}]

340 [--model MODEL]

341 [--effort {minimal,low,medium,high,xhigh}]

317 [--max-attempts N] [--plugin-path PATH]342 [--max-attempts N] [--plugin-path PATH]

318 [--python PATH] [--codex KEY=VALUE]343 [--python PATH] [--codex KEY=VALUE]

319```344```

320 345 

321Run `codex-security bulk-scan` without arguments or options to select346Run `npx @openai/codex-security bulk-scan` without arguments to select

322repositories interactively. This flow requires a GitHub CLI sign-in.347repositories interactively. This flow requires a GitHub CLI sign-in.

323 348 

349To choose a model and reasoning effort during interactive discovery:

350 

351```bash

352npx @openai/codex-security bulk-scan --model gpt-5.6-terra --effort high

353```

354 

324For a prepared repository list, provide a CSV and `--output-dir`:355For a prepared repository list, provide a CSV and `--output-dir`:

325 356 

326```bash357```bash

419Record a reviewed finding as a false positive:450Record a reviewed finding as a false positive:

420 451 

421```text452```text

422usage: codex-security findings mark-false-positive OCCURRENCE_ID453usage: codex-security findings false-positive OCCURRENCE_ID

423 --reason REASON454 --reason REASON

424```455```

425 456 

432Record a specific explanation for the false positive:463Record a specific explanation for the false positive:

433 464 

434```bash465```bash

435npx @openai/codex-security findings mark-false-positive FINDING_OCCURRENCE_ID \466npx @openai/codex-security findings false-positive FINDING_OCCURRENCE_ID \

436 --reason "The framework escapes this input before it reaches the query"467 --reason "The framework escapes this input before it reaches the query"

437```468```

438 469 

484Write SARIF to stdout:515Write SARIF to stdout:

485 516 

486```bash517```bash

487npx @openai/codex-security export /path/to/scan --export-format sarif --source-root . --output -518npx @openai/codex-security export /path/to/scan \

519 --export-format sarif \

520 --source-root . \

521 --output -

488```522```

489 523 

490Export findings as JSON:524Export findings as JSON:

508Check whether a candidate finding is valid:542Check whether a candidate finding is valid:

509 543 

510```bash544```bash

511npx @openai/codex-security validate findings.json "Possible SQL injection in src/query.ts:42"545npx @openai/codex-security validate findings.json \

546 "Possible SQL injection in src/query.ts:42"

512```547```

513 548 

514Generate a fix with the bundled remediation skill:549Generate a fix with the bundled remediation skill:

515 550 

516```bash551```bash

517npx @openai/codex-security patch findings.json "Missing authorization check in src/routes.ts:18"552npx @openai/codex-security patch findings.json \

553 "Missing authorization check in src/routes.ts:18"

518```554```

519 555 

520Each argument can contain literal text or point to a file. Both commands work556Each argument can contain literal text or point to a file. Both commands work

523comparison alone doesn't prove that a fix worked. External tools can use these559comparison alone doesn't prove that a fix worked. External tools can use these

524commands without rebuilding the scanner.560commands without rebuilding the scanner.

525 561 

562Use `--effort` to select reasoning effort for either command:

563 

564```bash

565npx @openai/codex-security validate "Possible SQL injection" --effort high

566```

567 

526## `codex-security login`, `logout`, and `info`568## `codex-security login`, `logout`, and `info`

527 569 

528Sign in interactively:570Sign in interactively:

572 614 

573## Read scan output615## Read scan output

574 616 

575The CLI writes structured command results to stdout and sends progress,617By default, scans send progress, completion summaries, and errors to stderr

576completion summaries, and errors to stderr. This lets terminal users read a618without writing the complete scan result to stdout. Request `--json`,

577summary while automation captures a clean JSON or SARIF document.619`--format`, or `--full-output` to send structured scan results to stdout.

578 620 

579### Completion summary621### Completion summary

580 622 

581A completed scan writes its finding count, severity breakdown, coverage,623A completed scan writes its finding count, severity breakdown, coverage,

582elapsed time, result directory, and next step to stderr. It includes worker624elapsed time, report path, and result directory to stderr. It includes token

583counts and token usage when available:625usage and estimated cost when available:

584 626 

585```text627```text

586codex-security: Findings: 4 (1 critical, 2 high, 1 informational). Coverage: complete.628codex-security: Findings: 4 (1 critical, 2 high, 1 informational). Coverage: complete.

587codex-security: Elapsed: 1s. Workers: 3/6.629codex-security: Elapsed: 1s.

588codex-security: Tokens: 1,250 input, 200 cached, 30 output.630codex-security: Tokens: 1,250 input, 200 cached, 30 output.

631codex-security: Report: /path/to/scan/report.md

589codex-security: Results: /path/to/scan632codex-security: Results: /path/to/scan

590codex-security: Next: codex-security export /path/to/scan --export-format sarif

591```633```

592 634 

593Informational findings count toward the summary total. Severity policies635Informational findings count toward the summary total. Severity policies

671| `143` | SIGTERM terminated a scan. |713| `143` | SIGTERM terminated a scan. |

672 714 

673Any scan with `partial` or `unknown` coverage returns `2`, even without a715Any scan with `partial` or `unknown` coverage returns `2`, even without a

674severity policy. Completed scans still write the available results to stdout.716severity policy. When you request structured output, completed scans still

675The CLI prints the location of any partial output after an interruption or717write the available results to stdout. The CLI prints the location of any

676runtime error.718partial output after an interruption or runtime error.

677 719 

678## Authentication and prerequisites720## Authentication and prerequisites

679 721 

680Set `OPENAI_API_KEY` or `CODEX_API_KEY`, sign in with `codex-security login`, or722Set `OPENAI_API_KEY` or `CODEX_API_KEY`, sign in with

681use an existing file-backed Codex sign-in. When a ChatGPT sign-in and an723`npx @openai/codex-security login`, or use an existing file-backed Codex

682environment API key are both available, interactive scans with text output ask724sign-in.

683which credential to use. CI, JSON and JSONL scans, and other scans without an725 

684interactive terminal use the environment API key by default. Dry runs don't726For credential selection, see [Select scan

685prompt or load credentials. Use `--auth` to select the credential explicitly.727authentication](#select-scan-authentication).

728 

686For CI, keep the API key scoped to the scan step and use a trusted workflow.729For CI, keep the API key scoped to the scan step and use a trusted workflow.

687 730 

688The CLI requires Node.js 22 or later. Running a scan or exporting findings also731The CLI requires Node.js 22 or later. Running a scan or exporting findings also

10Follow this quickstart to install the plugin and run a read-only scan of a local10Follow this quickstart to install the plugin and run a read-only scan of a local

11repository in Codex.11repository in Codex.

12 12 

13This page covers the plugin that runs in a local Codex chat. To scan a13This page covers the Codex Security plugin in the desktop app or Codex CLI. To

14 connected GitHub repository in Codex cloud, see [Codex Security cloud14 scan a connected GitHub repository in Codex cloud, see [Codex Security cloud

15 setup](https://learn.chatgpt.com/docs/security/setup).15 setup](https://learn.chatgpt.com/docs/security/setup).

16 16 

17## Install the plugin17## Install the plugin

18 18 

19<ContentModeSwitch group="codex-surface" id="app">19<ContentModeSwitch group="codex-surface" id="app">

20 20 

211. Open the repository you want to assess in Codex in the [ChatGPT desktop211. Open [Codex in the ChatGPT desktop app](https://learn.chatgpt.com/docs/app).

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

232. Open **Plugins**, search for **Codex Security**, or use the button below:222. Open **Plugins**, search for **Codex Security**, or use the button below:

24 23 

25 24

36 35

37 36 

38 37 

393. Start a new Codex chat for that repository. Don't continue an existing chat.383. Confirm the plugin is enabled, then open **Security** in the sidebar.

40 39 

41</ContentModeSwitch>40</ContentModeSwitch>

42 41 

56 55 

57 56 

58 57 

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

59 different plugin versions. Check the [plugin

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

61 start a long-running scan. If **Security** doesn't appear in the desktop-app

62 sidebar, update the app and plugin and confirm that the plugin is enabled.

63 

59## Run your first scan64## Run your first scan

60 65 

61For the best scan quality, use `gpt-5.6-sol`66For the best scan quality, use `gpt-5.6-sol`

63 68 

64<ContentModeSwitch group="codex-surface" id="app">69<ContentModeSwitch group="codex-surface" id="app">

65 70 

66<VideoPlayer71<figure className="not-prose my-8">

67 src="/videos/codex/security/scan-setup-to-findings.mp4"72 <CodexScreenshot

68 poster="/videos/codex/security/scan-setup-to-findings-poster.webp"73 alt="Native Codex Security workbench showing the new scan setup before a repository scan starts"

69/>74 lightSrc={scanOverview.src}

75 darkSrc={scanOverviewDark.src}

76 maxHeight="520px"

77 />

78 <figcaption className="mt-3 text-sm text-secondary">

79 Choose a repository and configure a new security scan before you start it.

80 </figcaption>

81</figure>

70 82 

71<WorkflowSteps variant="headings">83<WorkflowSteps variant="headings">

72 84 

731. Ask for an ordinary scan851. Open the scan setup

74 86 

75 Send this prompt in the new chat:87 Select **Security** in the sidebar, open **Scans**, and select **+ Scan**.

76 88 

77```text892. Choose the codebase and scan area

78 Run a Codex Security scan on this repository.

79```

80 90 

812. Confirm the setup91 Select an existing repository or use another folder. Choose **Codebase**,

92 leave **Deep scan** off, and select the entire repository or one folder.

93 Confirm that the branch and revision identify the code you intended to scan.

82 94 

83 Codex opens a setup workspace before it starts. For your first run, use these953. Add relevant context

84 settings:

85 - **Scan type:** `Codebase`

86 - **Deep scan:** Off

87 - **Scan area:** `Entire codebase`

88 - **Threat model scoping guidance:** Leave blank unless you already know a

89 specific attack vector or application area that deserves priority.

90 96 

91 Confirm that **Codebase**, **Current branch**, and **Last commit** identify97 Choose the model and reasoning effort. Open **Additional context** only when

92 the repository you intended to scan. Then select **Start scan**.98 you need to describe a specific attack vector, security-sensitive area, or

99 repository detail that should guide the review.

93 100 

94 <figure className="not-prose my-6">101 <figure className="not-prose my-6">

95 102 <CodexScreenshot

96 103 alt="Native Codex Security scan setup with additional context enabled and example attack vectors, focus areas, and security guidance"

97 <img104 lightSrc={scanSetup.src}

98 src={scanSetup.src}105 darkSrc={scanSetupDark.src}

99 alt="Codex Security setup workspace configured to scan an entire codebase"106 maxHeight="460px"

100 className="block h-auto w-full"

101 />107 />

102

103 

104 <figcaption className="mt-3 text-sm text-secondary">108 <figcaption className="mt-3 text-sm text-secondary">

105 Configure the scan target, scan area, branch, and optional threat model109 Turn on additional context to describe attack vectors, focus areas, and

106 guidance before starting the scan.110 relevant security guidance.

107 </figcaption>111 </figcaption>

108 </figure>112 </figure>

109 113 

1103. Let the scan finish1144. Start the scan

111 115 

112 Keep the scan running until the workspace reports that it is complete. If116 Select **Start scan** and follow the scan phases in the Security workbench.

113 Codex identifies a configuration limitation, review the limitation and the117 Select **View activity** to inspect the Codex task that performs the scan.

114 exact proposed change before you approve a configuration update.

115 118 

1164. Review the result1195. Review the result

117 120 

118 Use the UI to browse findings, or open `report.md` as the entry point to the121 Open the completed scan to inspect findings, coverage, and available report

119 complete scan directory.122 artifacts. Use **Findings** to review issues across scans or **Repositories**

123 to inspect a repository's scan history.

120 124 

121 <figure className="not-prose my-6">125 <figure className="not-prose my-6">

122 126 <CodexScreenshot

123 127 alt="Completed Codex Security scan showing findings in the native workbench"

124 <img128 lightSrc={findingsWorkspace.src}

125 src={findingsWorkspace.src}129 darkSrc={findingsWorkspaceDark.src}

126 alt="Completed Codex Security findings workspace for OWASP Juice Shop"130 maxHeight="520px"

127 className="block h-auto w-full"

128 />131 />

129

130 

131 <figcaption className="mt-3 text-sm text-secondary">132 <figcaption className="mt-3 text-sm text-secondary">

132 Browse findings by severity, category, directory, patch status, and133 Review scan results, findings, and coverage in the Security workbench.

133 review status.

134 </figcaption>134 </figcaption>

135 </figure>135 </figure>

136 136 

172 172 

173<ContentModeSwitch group="codex-surface" id="app">173<ContentModeSwitch group="codex-surface" id="app">

174 174 

175Every completed scan opens a findings workspace. Use it to review findings and175Completed scans remain available in **Scans**. Review their findings and

176coverage without inspecting raw artifacts. The scan also creates the files176coverage in the Security workbench, or inspect related findings and repository

177history in **Findings** and **Repositories**. The scan also creates the files

177below.178below.

178 179 

179</ContentModeSwitch>180</ContentModeSwitch>

188 189 

189 190 

190- `report.md`, the primary readable entry point to the scan results.191- `report.md`, the primary readable entry point to the scan results.

191- `findings/<slug>/`, with one detailed vulnerability report per reportable192- `findings/<slug>/`, when detailed vulnerability reports and supporting

192 finding and supporting proof-of-concept files when available.193 proof-of-concept files are available.

193- `hardening/`, with a structural hardening portfolio and supporting proposals194- `hardening/`, when structural hardening guidance and supporting proposals or

194 or diagrams when the scan has reportable findings.195 diagrams are available.

195- Structured scan data in `scan-manifest.json`, `findings.json`, and196- Structured scan data in `scan-manifest.json`, `findings.json`, and

196 `coverage.json` for automation and integrations. You normally don't need to197 `coverage.json` for automation and integrations. You normally don't need to

197 open these files yourself.198 open these files yourself.

201 202 

202## Choose your next workflow203## Choose your next workflow

203 204 

205- [Use the Security workbench](https://learn.chatgpt.com/docs/security/plugin/workbench) to manage

206 saved scans, findings, repositories, and scan activity in the desktop app.

204- [Run a scan from the CLI](https://learn.chatgpt.com/docs/security/cli) if you have beta access and207- [Run a scan from the CLI](https://learn.chatgpt.com/docs/security/cli) if you have beta access and

205 need a repeatable terminal workflow with structured results.208 need a repeatable terminal workflow with structured results.

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

11 11 

12## Run a manual review12## Run a manual review

13 13 

14For uncommitted changes, ask Codex:14In the desktop app, open **Security**, select **Scans**, and select **+ Scan**.

15Choose the repository, then select **Changes**. Review uncommitted changes, a

16single commit, or a base and head revision. **Deep scan** isn't available for a

17changes scan.

18 

19You can also ask Codex to review uncommitted changes in a conversation:

15 20 

16```text21```text

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

30 35 

31<WorkflowSteps>36<WorkflowSteps>

32 37 

331. Confirm **Scan type** is `Changes`.381. Select **Changes**.

342. Confirm the checked-out **Codebase**, **Current branch**, and **Last commit**.392. Confirm the checked-out repository, current branch, and latest commit.

353. Under **Changes to review**, choose:403. Under **Changes to review**, choose:

36 - `Uncommitted changes` for the current working tree.41 - `Uncommitted changes` for the current working tree.

37 - The latest commit for a single-commit review.42 - The latest commit for a single-commit review.

93`$TMPDIR/codex-security-scans/<repository>/<scan-id>/`:98`$TMPDIR/codex-security-scans/<repository>/<scan-id>/`:

94 99 

95| File | Contents |100| File | Contents |

96| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |101| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |

97| `report.md` | Primary readable entry point to the complete scan directory. |102| `report.md` | Primary readable entry point to the complete scan directory. |

98| `findings/<slug>/` | One detailed vulnerability report per reportable finding, with supporting proof-of-concept files when available. |103| `findings/<slug>/` | One detailed vulnerability report per reportable finding, with supporting proof-of-concept files when available. |

99| `hardening/` | Structural hardening portfolio and supporting proposals or diagrams when the scan has reportable findings. |104| `hardening/` | Structural hardening portfolio and supporting proposals or diagrams when the scan has reportable findings. |