security/setup.md +140 −0 added
1# Codex Security setup
2
3This page walks you from initial access to reviewed findings and remediation pull requests in Codex Security.
4
5Confirm you've set up Codex Cloud first. If not, see [Codex
6 Cloud](https://developers.openai.com/codex/cloud) to get started.
7
8## 1. Access and environment
9
10Codex Security scans GitHub repositories connected through [Codex Cloud](https://developers.openai.com/codex/cloud).
11
12- Confirm your workspace has access to Codex Security.
13- Confirm the repository you want to scan is available in Codex Cloud.
14
15Go to [Codex environments](https://chatgpt.com/codex/settings/environments) and check whether the repository already has an environment. If it doesn't, create one there before continuing.
16
17<CtaPillLink
18 href="https://chatgpt.com/codex/settings/environments"
19 label="Open environments"
20 icon="external"
21 class="my-8"
22/>
23
24<div class="not-prose my-8 max-w-6xl overflow-hidden rounded-xl border border-subtle bg-surface">
25 <img
26 src={createEnvironment.src}
27 alt="Codex environments"
28 class="block h-auto w-full"
29 />
30</div>
31
32## 2. New security scan
33
34After the environment exists, go to [Create a security scan](https://chatgpt.com/codex/security/scans/new) and choose the repository you just connected.
35
36<CtaPillLink
37 href="https://chatgpt.com/codex/security/scans/new"
38 label="Create a security scan"
39 icon="external"
40 class="my-8"
41/>
42
43Codex Security scans repositories from newest commits backward first. It uses this to build and refresh scan context as new commits come in.
44
45To configure a repository:
46
471. Select the GitHub organization.
482. Select the repository.
493. Select the branch you want to scan.
504. Select the environment.
515. Choose a **history window**. Longer windows provide more context, but backfill takes longer.
526. Click **Create**.
53
54<div class="not-prose my-8 max-w-6xl overflow-hidden rounded-xl border border-subtle bg-surface">
55 <img
56 src={createScan.src}
57 alt="Create a security scan"
58 class="block h-auto w-full"
59 />
60</div>
61
62## 3. Initial scans can take a while
63
64When you create the scan, Codex Security first runs a commit-level security pass across the selected history window.
65The initial backfill can take a few hours, especially for larger repositories or longer windows.
66If findings aren't visible right away, this is expected. Wait for the initial scan to finish before opening a ticket or troubleshooting.
67
68Initial scan setup is automatic and thorough. This can take a few hours. Don’t
69 be alarmed if the first set of findings is delayed.
70
71## 4. Review scans and improve the threat model
72
73<CtaPillLink
74 href="https://chatgpt.com/codex/security/scans"
75 label="Review scans"
76 icon="external"
77 class="my-8"
78/>
79
80<div class="not-prose my-8 max-w-6xl overflow-hidden rounded-xl border border-subtle bg-surface">
81 <img
82 src={reviewThreatModel.src}
83 alt="Threat model editor in Codex Security"
84 class="block h-auto w-full"
85 />
86</div>
87
88When the initial scan finishes, open the scan and review the threat model that was generated.
89After initial findings appear, update the threat model so it matches your architecture, trust boundaries, and business context.
90This helps Codex Security rank issues for your team.
91
92If you want scan results to change, you can edit the threat model with your
93 updated scope, priorities, and assumptions.
94
95After initial findings appear, revisit the model so scan guidance stays aligned with current priorities.
96Keeping it current helps Codex Security produce better suggestions.
97
98For a deeper explanation of threat models and how they affect criticality and triage, see [Improving the threat model](https://developers.openai.com/codex/security/threat-model).
99
100## 5. Review findings and patch
101
102After the initial backfill completes, review findings from the **Findings** view.
103
104<CtaPillLink
105 href="https://chatgpt.com/codex/security/findings"
106 label="Open findings"
107 icon="external"
108 class="my-8"
109/>
110
111You can use two views:
112
113- **Recommended Findings**: an evolving top 10 list of the most critical issues in the repo
114- **All Findings**: a sortable, filterable table of findings across the repository
115
116
117
118Click a finding to open its detail page, which includes:
119
120- a concise description of the issue
121- key metadata such as commit details and file paths
122- contextual reasoning about impact
123- relevant code excerpts
124- call-path or data-flow context when available
125- validation steps and validation output
126
127You can review each finding and create a PR directly from the finding detail page.
128
129<CtaPillLink
130 href="https://chatgpt.com/codex/security/findings"
131 label="Review findings and create a PR"
132 icon="external"
133 class="my-8"
134/>
135
136## Related docs
137
138- [Codex Security](https://developers.openai.com/codex/security) gives the product overview.
139- [FAQ](https://developers.openai.com/codex/security/faq) covers common questions.
140- [Improving the threat model](https://developers.openai.com/codex/security/threat-model) explains how to improve scan context and finding prioritization.