Run bulk security scans

For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.

Use codex-security bulk-scan to review repositories in one campaign. Discover repositories from a GitHub account or organization, or provide a CSV that pins every repository to an exact Git revision.

The Codex Security CLI is in beta and requires access. Follow the CLI quickstart to install the CLI and sign in before starting a bulk scan.

Choose a repository source

Source	When to use it
GitHub discovery	Choose repositories interactively from a GitHub account or organization.
CSV inventory	Run a repeatable, automated campaign against exact repository revisions.

Both workflows save progress, preserve per-repository results, and let you resume a campaign after an interruption.

Discover GitHub repositories

gh auth login

Start an interactive bulk scan:

npx codex-security bulk-scan

The CLI guides you through these steps:

Choose a GitHub account or organization.
Review repositories active within the last 90 days.
Search the repository list and select repositories to scan.
Choose a directory for scan results.
Review the selected repositories and confirm the campaign.

Discovery excludes archived repositories and forks. The CLI records the exact default-branch commit for each selected repository in <output-directory>/repositories.csv. No scans start until you confirm the selection.

To use GitHub Enterprise Server, first sign in to your GitHub host:

gh auth login --hostname github.example.com

Set GH_HOST when you start repository discovery:

GH_HOST=github.example.com npx codex-security bulk-scan

Interactive discovery requires a terminal. For CI, containers, or a prepared repository list, use a CSV inventory instead.

Create a repository CSV

Create a CSV with one row for each repository and pinned revision:

id,repository,revision,scope,mode
payments,https://github.com/example/payments.git,0123456789abcdef0123456789abcdef01234567,services/api,standard
identity,https://github.com/example/identity.git,fedcba9876543210fedcba9876543210fedcba98,,deep

The CSV supports these columns:

Column	Required	Description
`id`	Yes	Unique repository identifier. Use letters, numbers, periods, hyphens, or underscores.
`repository`	Yes	HTTPS URL, SSH URL, or local repository path. Relative paths resolve from the CSV directory.
`revision`	Yes	Full 40- or 64-character Git commit SHA. Branch names, tags, and shortened commit hashes aren't supported.
`scope`	No	A repository-relative directory to scan. Omit the value to scan the full repository.
`mode`	No	`standard` or `deep`. Omit the value to use the command's selected mode.

To find a local repository's full commit SHA, run:

git -C /path/to/repository rev-parse HEAD

Run a campaign from CSV

Pass the CSV and a private output directory outside the repositories:

npx codex-security bulk-scan repositories.csv \
  --output-dir /path/outside/repositories/security-scans \
  --workers 4

--workers controls the number of concurrent repository scans and defaults to 4. Use --mode deep to select deep scanning for rows without their own mode. Each CSV row can still choose its own scan mode and repository scope.

The CLI checks out each pinned revision, scans the selected target, records the result, and removes the temporary repository checkout. A repository counts as complete only when its scan has complete coverage and all required result artifacts exist.

Review campaign results

The output directory contains the pinned campaign, an append-only results ledger, and separate artifacts for each repository and attempt:

security-scans/
├── manifest.json
├── results.jsonl
├── checkouts/
└── artifacts/
    ├── payments/
    │   └── attempt-1/
    │       ├── scan-manifest.json
    │       ├── findings.json
    │       ├── coverage.json
    │       └── report.md
    └── identity/
        └── attempt-1/
            ├── scan-manifest.json
            ├── findings.json
            ├── coverage.json
            └── report.md

manifest.json records the repositories, pinned revisions, scopes, and scan modes in the campaign.
results.jsonl records each repository attempt, its status, artifact directory, and any available cost or error details.
report.md provides a readable report for one repository attempt.
findings.json and coverage.json record that attempt's findings and reviewed scope.

Export one completed repository scan when you need a portable result:

npx codex-security export \
  /path/outside/repositories/security-scans/artifacts/payments/attempt-1 \
  --export-format sarif \
  --output /path/outside/repositories/payments.sarif

Results can contain source excerpts and vulnerability details. Keep the output directory private, outside scanned repositories, and subject to an appropriate retention policy.

Resume a campaign

Run the original command with the same CSV and output directory:

npx codex-security bulk-scan repositories.csv \
  --output-dir /path/outside/repositories/security-scans \
  --workers 4

The CLI resumes repositories that still need work. It skips a completed repository only when the corresponding receipt and all required scan artifacts still exist.

Don't change the repository inventory for an existing output directory. The CLI checks the pinned manifest and rejects a different campaign. Use a new output directory when you change repositories, revisions, scopes, or scan modes.

Retry repository errors

Use --max-attempts to retry a repository after a temporary checkout or scan error:

npx codex-security bulk-scan repositories.csv \
  --output-dir /path/outside/repositories/security-scans \
  --workers 4 \
  --max-attempts 3

The default is one attempt per repository. Every attempt receives its own receipt and artifact directory.

Bulk scans use these exit codes:

Exit code	Meaning
`0`	Every repository completed successfully.
`2`	A repository couldn't complete, a scan had incomplete coverage, or the command encountered an input or runtime error.
`130`	Ctrl-C interrupted the campaign.
`143`	SIGTERM terminated the campaign.

Run bulk scans in Docker

The Codex Security repository includes a hardened Compose configuration for automated CSV campaigns on a Linux Docker host. The host must support unprivileged user namespace creation.

Keep the repository CSV, scan results, and sign-in state mounted in persistent directories. Supply OpenAI credentials through the environment or a secret manager. For private GitHub repositories, provide GH_TOKEN or GITHUB_TOKEN the same way.

Run the image with the mounted CSV and output directory:

docker compose run --rm codex-security \
  bulk-scan /input/repositories.csv \
  --output-dir /output \
  --workers 4

Use the same mounted CSV and output directory to resume the campaign. For GitHub Enterprise Server, set CODEX_SECURITY_GIT_HOST to your GitHub host.

For every available flag, see the bulk-scan command reference. For common questions about scan coverage and findings, see the CLI FAQ.

security/cli/bulk-scans.md +225 −0 created

1# Run bulk security scans

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.

5Use `codex-security bulk-scan` to review repositories in one

6campaign. Discover repositories from a GitHub account or organization, or

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

9The Codex Security CLI is in beta and requires access. Follow the [CLI

10 quickstart](https://learn.chatgpt.com/docs/security/cli) to install the CLI and sign in before

11 starting a bulk scan.

13## Choose a repository source

15| Source | When to use it |

16| ---------------- | ------------------------------------------------------------------------ |

17| GitHub discovery | Choose repositories interactively from a GitHub account or organization. |

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

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

21resume a campaign after an interruption.

23## Discover GitHub repositories

25Sign in with GitHub CLI:

27```bash

28gh auth login

29```

31Start an interactive bulk scan:

33```bash

34npx codex-security bulk-scan

35```

37The CLI guides you through these steps:

391. Choose a GitHub account or organization.

402. Review repositories active within the last 90 days.

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

424. Choose a directory for scan results.

435. Review the selected repositories and confirm the campaign.

45Discovery excludes archived repositories and forks. The CLI records the exact

46default-branch commit for each selected repository in

47`<output-directory>/repositories.csv`. No scans start until you confirm the

48selection.

50To use GitHub Enterprise Server, first sign in to your GitHub host:

52```bash

53gh auth login --hostname github.example.com

54```

56Set `GH_HOST` when you start repository discovery:

58```bash

59GH_HOST=github.example.com npx codex-security bulk-scan

60```

62Interactive discovery requires a terminal. For CI, containers, or a prepared

63repository list, use a CSV inventory instead.

65## Create a repository CSV

67Create a CSV with one row for each repository and pinned revision:

69```csv

70id,repository,revision,scope,mode

71payments,https://github.com/example/payments.git,0123456789abcdef0123456789abcdef01234567,services/api,standard

72identity,https://github.com/example/identity.git,fedcba9876543210fedcba9876543210fedcba98,,deep

73```

75The CSV supports these columns:

77| Column | Required | Description |

78| ------------ | -------- | ---------------------------------------------------------------------------------------------------------- |

79| `id` | Yes | Unique repository identifier. Use letters, numbers, periods, hyphens, or underscores. |

80| `repository` | Yes | HTTPS URL, SSH URL, or local repository path. Relative paths resolve from the CSV directory. |

81| `revision` | Yes | Full 40- or 64-character Git commit SHA. Branch names, tags, and shortened commit hashes aren't supported. |

82| `scope` | No | A repository-relative directory to scan. Omit the value to scan the full repository. |

83| `mode` | No | `standard` or `deep`. Omit the value to use the command's selected mode. |

85To find a local repository's full commit SHA, run:

87```bash

88git -C /path/to/repository rev-parse HEAD

89```

91## Run a campaign from CSV

93Pass the CSV and a private output directory outside the repositories:

95```bash

96npx codex-security bulk-scan repositories.csv \

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

98 --workers 4

99```

100

101`--workers` controls the number of concurrent repository scans and defaults to

102`4`. Use `--mode deep` to select deep scanning for rows without their own

103`mode`. Each CSV row can still choose its own scan mode and repository scope.

104

105The CLI checks out each pinned revision, scans the selected target, records the

106result, and removes the temporary repository checkout. A repository counts as

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

108artifacts exist.

109

110## Review campaign results

111

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

113ledger, and separate artifacts for each repository and attempt:

114

115```text

116security-scans/

117├── manifest.json

118├── results.jsonl

119├── checkouts/

120└── artifacts/

121 ├── payments/

122 │ └── attempt-1/

123 │ ├── scan-manifest.json

124 │ ├── findings.json

125 │ ├── coverage.json

126 │ └── report.md

127 └── identity/

128 └── attempt-1/

129 ├── scan-manifest.json

130 ├── findings.json

131 ├── coverage.json

132 └── report.md

133```

134

135- `manifest.json` records the repositories, pinned revisions, scopes, and scan

136 modes in the campaign.

137- `results.jsonl` records each repository attempt, its status, artifact

138 directory, and any available cost or error details.

139- `report.md` provides a readable report for one repository attempt.

140- `findings.json` and `coverage.json` record that attempt's findings and

141 reviewed scope.

142

143Export one completed repository scan when you need a portable result:

144

145```bash

146npx codex-security export \

147 /path/outside/repositories/security-scans/artifacts/payments/attempt-1 \

148 --export-format sarif \

149 --output /path/outside/repositories/payments.sarif

150```

151

152Results can contain source excerpts and vulnerability details. Keep the

153output directory private, outside scanned repositories, and subject to an

154appropriate retention policy.

155

156## Resume a campaign

157

158Run the original command with the same CSV and output directory:

159

160```bash

161npx codex-security bulk-scan repositories.csv \

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

163 --workers 4

164```

165

166The CLI resumes repositories that still need work. It skips a completed

167repository only when the corresponding receipt and all required scan artifacts

168still exist.

169

170Don't change the repository inventory for an existing output directory. The CLI

171checks the pinned manifest and rejects a different campaign. Use a new output

172directory when you change repositories, revisions, scopes, or scan modes.

173

174## Retry repository errors

175

176Use `--max-attempts` to retry a repository after a temporary checkout or scan

177error:

178

179```bash

180npx codex-security bulk-scan repositories.csv \

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

182 --workers 4 \

183 --max-attempts 3

184```

185

186The default is one attempt per repository. Every attempt receives its own

187receipt and artifact directory.

188

189Bulk scans use these exit codes:

190

191| Exit code | Meaning |

192| --------- | --------------------------------------------------------------------------------------------------------------------- |

193| `0` | Every repository completed successfully. |

194| `2` | A repository couldn't complete, a scan had incomplete coverage, or the command encountered an input or runtime error. |

195| `130` | Ctrl-C interrupted the campaign. |

196| `143` | SIGTERM terminated the campaign. |

197

198## Run bulk scans in Docker

199

200The [Codex Security

201repository](https://github.com/openai/codex-security) includes a hardened

202Compose configuration for automated CSV campaigns on a Linux Docker host. The

203host must support unprivileged user namespace creation.

204

205Keep the repository CSV, scan results, and sign-in state mounted in persistent

206directories. Supply OpenAI credentials through the environment or a secret

207manager. For private GitHub repositories, provide `GH_TOKEN` or `GITHUB_TOKEN`

208the same way.

209

210Run the image with the mounted CSV and output directory:

211

212```bash

213docker compose run --rm codex-security \

214 bulk-scan /input/repositories.csv \

215 --output-dir /output \

216 --workers 4

217```

218

219Use the same mounted CSV and output directory to resume the campaign. For

220GitHub Enterprise Server, set `CODEX_SECURITY_GIT_HOST` to your GitHub host.

221

222For every available flag, see the [bulk-scan command

223reference](https://learn.chatgpt.com/docs/security/cli/reference#codex-security-bulk-scan). For common

224questions about scan coverage and findings, see the [CLI

225FAQ](https://learn.chatgpt.com/docs/security/cli/faq).