@openai/codex-security 0.1.27 → 0.1.28
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +250 -55
- package/_bundled_plugin/mcp/native/win32-arm64/windows.node +0 -0
- package/_bundled_plugin/mcp/native/win32-x64/windows.node +0 -0
- package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
- package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
- package/_bundled_plugin/references/artifact-storage.md +56 -0
- package/_bundled_plugin/references/config-preflight.md +7 -1
- package/_bundled_plugin/references/final-report.md +2 -0
- package/_bundled_plugin/references/scan-artifacts.md +6 -14
- package/_bundled_plugin/references/scan-prologue.md +2 -0
- package/_bundled_plugin/references/security-guidance.md +2 -0
- package/_bundled_plugin/scripts/deep_scan_config.py +10 -8
- package/_bundled_plugin/scripts/deep_scan_defaults.json +8 -0
- package/_bundled_plugin/scripts/reserved_artifact_paths.json +6 -0
- package/_bundled_plugin/scripts/windows_scan_local_files.py +1 -3
- package/_bundled_plugin/scripts/workbench/storage.py +18 -0
- package/_bundled_plugin/scripts/workbench_cli.py +13 -0
- package/_bundled_plugin/scripts/workbench_db.py +13 -13
- package/_bundled_plugin/scripts/workbench_saved_results.py +72 -1
- package/_bundled_plugin/scripts/workbench_scan_usage.py +23 -10
- package/_bundled_plugin/skills/assess-patch-risk/SKILL.md +2 -0
- package/_bundled_plugin/skills/attack-path-analysis/SKILL.md +2 -0
- package/_bundled_plugin/skills/deep-security-scan/SKILL.md +5 -1
- package/_bundled_plugin/skills/finding-discovery/SKILL.md +2 -0
- package/_bundled_plugin/skills/fix-finding/SKILL.md +3 -1
- package/_bundled_plugin/skills/fix-finding/agents/openai.yaml +1 -1
- package/_bundled_plugin/skills/propose-security-hardening/SKILL.md +2 -0
- package/_bundled_plugin/skills/security-scan/references/desktop-scan.md +5 -1
- package/_bundled_plugin/skills/threat-model/SKILL.md +2 -0
- package/_bundled_plugin/skills/validation/SKILL.md +2 -0
- package/_bundled_plugin/skills/vulnerability-writeup/SKILL.md +2 -0
- package/dist/api.d.ts +7 -23
- package/dist/api.d.ts.map +1 -1
- package/dist/api.js +109 -113
- package/dist/api.js.map +1 -1
- package/dist/auth.d.ts.map +1 -1
- package/dist/auth.js.map +1 -1
- package/dist/bulk-scan-discovery.d.ts +1 -1
- package/dist/bulk-scan-discovery.d.ts.map +1 -1
- package/dist/bulk-scan-discovery.js +2 -2
- package/dist/bulk-scan-discovery.js.map +1 -1
- package/dist/classify-scan-severity.js.map +1 -1
- package/dist/classify-severity.d.ts.map +1 -1
- package/dist/classify-severity.js.map +1 -1
- package/dist/cli.d.ts +6 -2
- package/dist/cli.d.ts.map +1 -1
- package/dist/cli.js +646 -365
- package/dist/cli.js.map +1 -1
- package/dist/cloud-publish.js.map +1 -1
- package/dist/component-plan.js.map +1 -1
- package/dist/component-scan.d.ts +4 -2
- package/dist/component-scan.d.ts.map +1 -1
- package/dist/component-scan.js +7 -1
- package/dist/component-scan.js.map +1 -1
- package/dist/config-path.d.ts +6 -0
- package/dist/config-path.d.ts.map +1 -0
- package/dist/config-path.js +6 -0
- package/dist/config-path.js.map +1 -0
- package/dist/config.d.ts +2 -0
- package/dist/config.d.ts.map +1 -1
- package/dist/config.js +13 -3
- package/dist/config.js.map +1 -1
- package/dist/contract.js.map +1 -1
- package/dist/cost-model.d.ts +20 -6
- package/dist/cost-model.d.ts.map +1 -1
- package/dist/cost-model.js +73 -8
- package/dist/cost-model.js.map +1 -1
- package/dist/cost.d.ts.map +1 -1
- package/dist/custom-publish.js.map +1 -1
- package/dist/deduplication/checkpointed-review.d.ts.map +1 -1
- package/dist/deduplication/checkpointed-review.js.map +1 -1
- package/dist/deduplication/codex-review.d.ts.map +1 -1
- package/dist/deduplication/codex-review.js.map +1 -1
- package/dist/deduplication/deduplication-reviewer.d.ts.map +1 -1
- package/dist/deduplication/deduplication-reviewer.js.map +1 -1
- package/dist/deduplication/deduplication.js.map +1 -1
- package/dist/deduplication/scan.d.ts.map +1 -1
- package/dist/deduplication/scan.js.map +1 -1
- package/dist/deep-config.d.ts +17 -0
- package/dist/deep-config.d.ts.map +1 -0
- package/dist/deep-config.js +145 -0
- package/dist/deep-config.js.map +1 -0
- package/dist/deep-progress.d.ts.map +1 -1
- package/dist/deep-scan-defaults.d.ts +9 -0
- package/dist/deep-scan-defaults.d.ts.map +1 -0
- package/dist/deep-scan-defaults.js +10 -0
- package/dist/deep-scan-defaults.js.map +1 -0
- package/dist/errors.d.ts.map +1 -1
- package/dist/errors.js +2 -2
- package/dist/errors.js.map +1 -1
- package/dist/feedback.d.ts.map +1 -1
- package/dist/feedback.js +21 -7
- package/dist/feedback.js.map +1 -1
- package/dist/finding-catalogue.js.map +1 -1
- package/dist/finding-workflow.d.ts.map +1 -1
- package/dist/finding-workflow.js.map +1 -1
- package/dist/findings-client.d.ts.map +1 -1
- package/dist/findings-client.js.map +1 -1
- package/dist/findings-import.d.ts +6 -6
- package/dist/github.d.ts +625 -7
- package/dist/github.d.ts.map +1 -1
- package/dist/github.js.map +1 -1
- package/dist/import-scan.js.map +1 -1
- package/dist/index.d.ts +5 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -0
- package/dist/index.js.map +1 -1
- package/dist/knowledge-base.d.ts.map +1 -1
- package/dist/knowledge-base.js +17 -6
- package/dist/knowledge-base.js.map +1 -1
- package/dist/models.d.ts.map +1 -1
- package/dist/models.js.map +1 -1
- package/dist/multiscan.d.ts +6 -6
- package/dist/multiscan.d.ts.map +1 -1
- package/dist/multiscan.js +69 -4
- package/dist/multiscan.js.map +1 -1
- package/dist/patch-tui.d.ts.map +1 -1
- package/dist/patch-tui.js.map +1 -1
- package/dist/project-config-schema.d.ts +191 -0
- package/dist/project-config-schema.d.ts.map +1 -0
- package/dist/project-config-schema.js +85 -0
- package/dist/project-config-schema.js.map +1 -0
- package/dist/project-config.d.ts +50 -0
- package/dist/project-config.d.ts.map +1 -0
- package/dist/project-config.js +220 -0
- package/dist/project-config.js.map +1 -0
- package/dist/prompt-files.d.ts +13 -0
- package/dist/prompt-files.d.ts.map +1 -0
- package/dist/prompt-files.js +74 -0
- package/dist/prompt-files.js.map +1 -0
- package/dist/publication-events.d.ts.map +1 -1
- package/dist/publication-events.js.map +1 -1
- package/dist/publish.d.ts.map +1 -1
- package/dist/publish.js +1 -1
- package/dist/publish.js.map +1 -1
- package/dist/result.d.ts +2 -1
- package/dist/result.d.ts.map +1 -1
- package/dist/result.js +5 -0
- package/dist/result.js.map +1 -1
- package/dist/runtime.js +4 -4
- package/dist/runtime.js.map +1 -1
- package/dist/scan-comparison.d.ts.map +1 -1
- package/dist/scan-comparison.js.map +1 -1
- package/dist/scan-dashboard.d.ts +1 -0
- package/dist/scan-dashboard.d.ts.map +1 -1
- package/dist/scan-dashboard.js +34 -22
- package/dist/scan-dashboard.js.map +1 -1
- package/dist/scan-history-renderer.d.ts.map +1 -1
- package/dist/scan-history-renderer.js.map +1 -1
- package/dist/scan-logs.d.ts +12 -5
- package/dist/scan-logs.d.ts.map +1 -1
- package/dist/scan-logs.js +49 -18
- package/dist/scan-logs.js.map +1 -1
- package/dist/scan-modes.d.ts +3 -0
- package/dist/scan-modes.d.ts.map +1 -0
- package/dist/scan-modes.js +2 -0
- package/dist/scan-modes.js.map +1 -0
- package/dist/scan-settings.d.ts +81 -0
- package/dist/scan-settings.d.ts.map +1 -0
- package/dist/scan-settings.js +123 -0
- package/dist/scan-settings.js.map +1 -0
- package/dist/security-policy-cli.js +2 -2
- package/dist/security-policy-cli.js.map +1 -1
- package/dist/security-policy.d.ts.map +1 -1
- package/dist/security-policy.js.map +1 -1
- package/dist/server/dashboard/THIRD_PARTY_NOTICES.txt +2 -2
- package/dist/server/dashboard/app.js +2 -2
- package/dist/server/dashboard.js.map +1 -1
- package/dist/server/embeddings.d.ts.map +1 -1
- package/dist/server/embeddings.js.map +1 -1
- package/dist/server/errors.d.ts.map +1 -1
- package/dist/server/errors.js.map +1 -1
- package/dist/server/findings-service.d.ts.map +1 -1
- package/dist/server/findings-service.js.map +1 -1
- package/dist/server/serve.js.map +1 -1
- package/dist/server/sqlite-store.d.ts.map +1 -1
- package/dist/server/sqlite-store.js.map +1 -1
- package/dist/severity-store.js.map +1 -1
- package/dist/targets.d.ts +2 -1
- package/dist/targets.d.ts.map +1 -1
- package/dist/targets.js.map +1 -1
- package/dist/thread-source.d.ts.map +1 -1
- package/dist/version.js.map +1 -1
- package/dist/worker-progress.d.ts.map +1 -1
- package/dist/worker-progress.js.map +1 -1
- package/package.json +31 -28
- package/schemas/project-config.schema.json +211 -0
package/README.md
CHANGED
|
@@ -139,21 +139,25 @@ Constructor options:
|
|
|
139
139
|
Options for `security.run(repository, options)` and
|
|
140
140
|
`security.preflight(repository, options)`:
|
|
141
141
|
|
|
142
|
-
| Option
|
|
143
|
-
|
|
|
144
|
-
| `auth`
|
|
145
|
-
| `safetyIdentifier`
|
|
146
|
-
| `target`
|
|
147
|
-
| `mode`
|
|
148
|
-
| `knowledgeBasePaths`
|
|
149
|
-
| `
|
|
150
|
-
| `
|
|
151
|
-
| `
|
|
152
|
-
| `
|
|
153
|
-
| `
|
|
154
|
-
| `
|
|
155
|
-
| `
|
|
156
|
-
| `
|
|
142
|
+
| Option | Description |
|
|
143
|
+
| ------------------------------------------- | ----------------------------------------------------------------------------------- |
|
|
144
|
+
| `auth` | Credential source: `"auto"`, `"chatgpt"`, or `"api-key"`. |
|
|
145
|
+
| `safetyIdentifier` | Stable hashed end-user ID for model requests; requires API-key authentication. |
|
|
146
|
+
| `target` | Repository, repository-relative paths, committed diff, or working-tree diff. |
|
|
147
|
+
| `mode` | `"standard"` or `"deep"`; deep mode supports repositories and paths. |
|
|
148
|
+
| `knowledgeBasePaths` | Architecture documents, security policies, threat models, or directories. |
|
|
149
|
+
| `scanPrompt` / `scanPromptFile` | Additional scan instructions as text or a local file. |
|
|
150
|
+
| `validationPrompt` / `validationPromptFile` | Custom validation instructions as text or a local file; not Deep. |
|
|
151
|
+
| `postScanPrompt` / `postScanPromptFile` | Follow-up instructions as text or a local file. |
|
|
152
|
+
| `outputDir` | Artifact directory outside the enclosing Git worktree. |
|
|
153
|
+
| `archiveExisting` | Archive existing results in `outputDir` before scanning. |
|
|
154
|
+
| `maxCostUsd` | Stop when estimated model cost exceeds this positive USD amount. |
|
|
155
|
+
| `stopAfterConsecutiveErrors` | Stop deep discovery after this many consecutive errors (default: 3). |
|
|
156
|
+
| `maxTimeHours` | Deep-scan discovery limit in hours: greater than zero, up to 96. |
|
|
157
|
+
| `failureSeverity` | Severity threshold recorded in the recipe; the SDK caller decides how to handle it. |
|
|
158
|
+
| `parentScanId` | Parent scan ID for a rerun. |
|
|
159
|
+
| `expectedPluginVersion` | Required original plugin version when replaying a scan. |
|
|
160
|
+
| `signal` | `AbortSignal` to cancel a scan. |
|
|
157
161
|
|
|
158
162
|
Follow scans with `onWorkerStatus` and `onReconnect`. `onSessionEvent` receives
|
|
159
163
|
saved events with thread IDs and worker numbers. Deep scans can additionally use
|
|
@@ -164,6 +168,46 @@ and `maximum`. The maximum is a configured cap, not a percentage denominator.
|
|
|
164
168
|
`preflight` and CLI `--dry-run` check local inputs without starting Codex or
|
|
165
169
|
using the network. They don't authenticate, verify model access, resolve Python,
|
|
166
170
|
inspect the plugin, or run scan-lifecycle callbacks. Dry runs print effective settings.
|
|
171
|
+
Deep preflight includes all six resolved deep settings and their origins in
|
|
172
|
+
`deepScanSources`. Applicable legacy deep configuration is validated during
|
|
173
|
+
preflight rather than after runtime startup.
|
|
174
|
+
|
|
175
|
+
`ScanSettings` is the shared settings type. `ScanOptions` adds callbacks,
|
|
176
|
+
cancellation, workflow, and runtime controls. Load the same project file used by
|
|
177
|
+
`scan -c` through the SDK:
|
|
178
|
+
|
|
179
|
+
```ts
|
|
180
|
+
import { CodexSecurity, loadProjectConfig } from "@openai/codex-security";
|
|
181
|
+
|
|
182
|
+
const { config, options } = await loadProjectConfig("codex-security.yaml");
|
|
183
|
+
await using security = new CodexSecurity(config);
|
|
184
|
+
const result = await security.run(repository, options);
|
|
185
|
+
if (
|
|
186
|
+
options.failureSeverity !== undefined &&
|
|
187
|
+
result.hasFindingsAtOrAbove(options.failureSeverity)
|
|
188
|
+
) {
|
|
189
|
+
process.exitCode = 1;
|
|
190
|
+
}
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
`resolveProjectConfig(input, directory?)` accepts a typed `ProjectConfigInput`
|
|
194
|
+
object with the same `snake_case` keys as YAML/JSON and returns the same `{ config,
|
|
195
|
+
options }` pair and an immutable `sources` map. Resolved context, prompt, and output
|
|
196
|
+
paths have the `AbsolutePath` type. `loadProjectConfig(file, directory?)` resolves the selected file
|
|
197
|
+
from `directory`, which defaults to the current directory; paths inside the file
|
|
198
|
+
are relative to that file. Object paths are relative to the supplied directory.
|
|
199
|
+
Scope paths remain relative to the selected repository. Neither helper starts a
|
|
200
|
+
scan, reads prompt contents, or discovers another configuration file. `preflight`
|
|
201
|
+
and `run` apply the existing local checks and remaining legacy deep defaults.
|
|
202
|
+
Project-file keys follow Codex's configuration convention; SDK options keep their
|
|
203
|
+
existing `camelCase` names, and CLI flags keep `kebab-case`.
|
|
204
|
+
|
|
205
|
+
Override resolved SDK options with `{ ...options, maxCostUsd: 5 }`, or add
|
|
206
|
+
callbacks there. Direct SDK prompt-file paths use the current directory; inline
|
|
207
|
+
text takes precedence over its matching file. Files use the same regular-file
|
|
208
|
+
protections as the CLI. The SDK records `failureSeverity` without throwing or
|
|
209
|
+
changing process status. `hasFindingsAtOrAbove()` uses the CLI's severity ordering
|
|
210
|
+
and leaves the findings unchanged.
|
|
167
211
|
|
|
168
212
|
## Authentication
|
|
169
213
|
|
|
@@ -446,7 +490,73 @@ npx @openai/codex-security scan /path/to/repository --dry-run
|
|
|
446
490
|
|
|
447
491
|
Use `scan --help` for options, `--version` for the installed version, and
|
|
448
492
|
`info --json` for package, plugin, runtime, and model details. `--dry-run`
|
|
449
|
-
runs local preflight checks.
|
|
493
|
+
runs local preflight checks. `info -c FILE --json` inspects resolved configuration
|
|
494
|
+
and its sources without a repository or runtime.
|
|
495
|
+
|
|
496
|
+
### Project files
|
|
497
|
+
|
|
498
|
+
Use `scan -c FILE` / `scan --config FILE` to load reusable scan settings:
|
|
499
|
+
|
|
500
|
+
```bash
|
|
501
|
+
codex-security scan . -c codex-security.yaml --dry-run --json
|
|
502
|
+
codex-security scan . -c codex-security.json --model gpt-5.6-terra
|
|
503
|
+
codex-security init
|
|
504
|
+
codex-security info -c codex-security.yaml --json
|
|
505
|
+
```
|
|
506
|
+
|
|
507
|
+
Select one `.yaml`, `.yml`, or `.json` file. `scan`, `bulk-scan`, `scan-components`,
|
|
508
|
+
and `info` accept `-c`. They also accept an operator-set
|
|
509
|
+
`CODEX_SECURITY_PROJECT_CONFIG`; an explicit `-c` wins. Without either, no file is
|
|
510
|
+
loaded or discovered. The repository still comes from the command's target
|
|
511
|
+
selection. SDK `run()` and saved reruns do not load project files automatically.
|
|
512
|
+
|
|
513
|
+
The selected file is trusted like CLI options and SDK `codexOverrides`. Native
|
|
514
|
+
settings can start configured MCP server processes and select model-service destinations. Do not
|
|
515
|
+
select configuration controlled by an untrusted repository or pull request; keep
|
|
516
|
+
CI scanner configuration outside the checkout being assessed.
|
|
517
|
+
|
|
518
|
+
`init [file]` writes `codex-security.yaml` by default and never overwrites an
|
|
519
|
+
existing file. YAML starters show defaults as comments; JSON starters contain the
|
|
520
|
+
editor schema hint, relative to the chosen file and the invocation directory's
|
|
521
|
+
local package installation. `info` reports effective model details and native key sources
|
|
522
|
+
without dumping raw native values.
|
|
523
|
+
|
|
524
|
+
```yaml
|
|
525
|
+
# yaml-language-server: $schema=./node_modules/@openai/codex-security/schemas/project-config.schema.json
|
|
526
|
+
scan:
|
|
527
|
+
mode: standard
|
|
528
|
+
scope:
|
|
529
|
+
paths: [src]
|
|
530
|
+
codex:
|
|
531
|
+
model: gpt-5.6-sol
|
|
532
|
+
model_reasoning_effort: xhigh
|
|
533
|
+
policy:
|
|
534
|
+
fail_on_severity: high
|
|
535
|
+
```
|
|
536
|
+
|
|
537
|
+
All settings are optional; `{}` uses the existing defaults. JSON files can use a
|
|
538
|
+
root `$schema` string pointing to the same packaged schema. Schema hints are for
|
|
539
|
+
editors; the CLI uses its bundled validator without fetching URLs, coercing values,
|
|
540
|
+
or dropping unknown keys. Native `codex` settings retain their existing checks and
|
|
541
|
+
profile semantics. CLI `scan --schema --json` describes command arguments.
|
|
542
|
+
|
|
543
|
+
Settings use built-in defaults, applicable legacy deep defaults, the file, then
|
|
544
|
+
explicit CLI values. Lists and scope variants are replaced. `--head` can refine
|
|
545
|
+
a file diff and `--base` a file working-tree scope. A selected native profile can
|
|
546
|
+
still override root model/effort values. Existing native alias-conflict checks
|
|
547
|
+
and the behavior of `--provider openai` are unchanged.
|
|
548
|
+
|
|
549
|
+
File context, instruction, validation, and output paths resolve from the file's
|
|
550
|
+
directory. CLI file paths resolve from the invocation directory; scope paths
|
|
551
|
+
resolve from the repository. The file cannot select a different repository or
|
|
552
|
+
enable automatic patching/publication. The loader does not evaluate code,
|
|
553
|
+
interpolate environment values, include remote files, or merge multiple files.
|
|
554
|
+
|
|
555
|
+
Dry-run output adds `projectConfig.path` and `projectConfig.sources`, selected
|
|
556
|
+
prompt paths, and the finding policy without dumping raw native configuration.
|
|
557
|
+
Missing or invalid selected files exit `2`. Help, version, and command schema
|
|
558
|
+
output do not load project files. Existing scan and finding-policy exit codes
|
|
559
|
+
remain unchanged.
|
|
450
560
|
|
|
451
561
|
### Scan options and output
|
|
452
562
|
|
|
@@ -454,13 +564,18 @@ runs local preflight checks.
|
|
|
454
564
|
and `--working-tree` scans staged and unstaged changes. Deep scans support
|
|
455
565
|
repository and path targets.
|
|
456
566
|
|
|
567
|
+
Bulk scans use clean, shallow checkouts and support repository or path scopes.
|
|
568
|
+
They reject configured diff or working-tree scopes before starting unless each
|
|
569
|
+
affected CSV row supplies its own path scope.
|
|
570
|
+
|
|
457
571
|
Working-tree snapshots include files from untracked nested Git repositories.
|
|
458
572
|
Initialized submodules must be clean and checked out at the commit recorded by
|
|
459
573
|
the parent repository.
|
|
460
574
|
|
|
461
|
-
Repeat `--knowledge-base PATH` for
|
|
462
|
-
|
|
463
|
-
|
|
575
|
+
Repeat `--knowledge-base PATH` for UTF-8 text files with any extension (including
|
|
576
|
+
JSON and SARIF), PDF, or Word (`.docx`) files. Directories are searched recursively,
|
|
577
|
+
skipping other binary files. Explicitly supplied unsupported binary files are rejected.
|
|
578
|
+
Bulk scans share these documents with every repository.
|
|
464
579
|
|
|
465
580
|
Use an empty output directory outside the scanned directory and enclosing Git
|
|
466
581
|
worktree. On macOS/Linux, existing directories must be private to you
|
|
@@ -567,7 +682,7 @@ runtime or plugin compatibility. Older versions may omit the ID.
|
|
|
567
682
|
### Scan project components
|
|
568
683
|
|
|
569
684
|
`scan --path` runs one scan across selected paths. To scan each local project
|
|
570
|
-
component separately
|
|
685
|
+
component separately (standard mode by default), use `scan-components`:
|
|
571
686
|
|
|
572
687
|
```bash
|
|
573
688
|
npx @openai/codex-security scan-components /path/to/project \
|
|
@@ -575,6 +690,12 @@ npx @openai/codex-security scan-components /path/to/project \
|
|
|
575
690
|
--workers 4 --output-dir /path/outside/project/results
|
|
576
691
|
```
|
|
577
692
|
|
|
693
|
+
Use `-c FILE` to share settings, including `scan.mode: deep`, context and prompt
|
|
694
|
+
files, per-scan deep workers, cost limits, and severity policy. Component plans
|
|
695
|
+
override the file's scope. `output.directory` supplies the results directory when
|
|
696
|
+
`--output-dir` is omitted. A configured severity threshold returns exit `1` after
|
|
697
|
+
completed scans; failures or incomplete results return `2`.
|
|
698
|
+
|
|
578
699
|
Use `--auto` instead of `--component` for a proposed split. Save a plan to
|
|
579
700
|
review or edit, then run it with a new output directory:
|
|
580
701
|
|
|
@@ -651,6 +772,7 @@ await security.run("/path/to/repository", {
|
|
|
651
772
|
workers: 2,
|
|
652
773
|
subagents: 0,
|
|
653
774
|
stopAfterNoNew: 3,
|
|
775
|
+
stopAfterConsecutiveErrors: 2,
|
|
654
776
|
maxDiscoveryRuns: 10,
|
|
655
777
|
maxTimeHours: 1.5,
|
|
656
778
|
});
|
|
@@ -668,8 +790,10 @@ max_discovery_runs = 40
|
|
|
668
790
|
max_time_hours = 96
|
|
669
791
|
```
|
|
670
792
|
|
|
671
|
-
CLI and SDK options override these defaults.
|
|
672
|
-
|
|
793
|
+
CLI and SDK options override these defaults. Project files can use
|
|
794
|
+
`scan.deep.stop_after_consecutive_errors`, and SDK calls can use
|
|
795
|
+
`stopAfterConsecutiveErrors`; there is no new CLI flag for it. `--codex` cannot
|
|
796
|
+
configure this section. Worker and run counts must
|
|
673
797
|
be positive integers; `subagents` can be zero. Legacy `workers = "auto"` means
|
|
674
798
|
four workers. Unknown keys are rejected.
|
|
675
799
|
|
|
@@ -679,6 +803,12 @@ At the deadline, discovery stops; the scan combines and returns completed findin
|
|
|
679
803
|
`scan --workers` controls discovery workers within one deep scan;
|
|
680
804
|
`bulk-scan --workers` controls how many repositories are scanned concurrently.
|
|
681
805
|
|
|
806
|
+
The project-file deep block uses `subagents_per_worker` for the existing SDK/CLI
|
|
807
|
+
`subagents` setting. A valid deep block can remain inactive in standard mode;
|
|
808
|
+
explicit deep CLI options require deep mode. All six active values are resolved
|
|
809
|
+
before runtime preparation and saved in new recipes. Complete saved values are
|
|
810
|
+
independent of later changes to the legacy TOML file.
|
|
811
|
+
|
|
682
812
|
### Runtime configuration and worker limits
|
|
683
813
|
|
|
684
814
|
Scans use these isolated Codex defaults instead of your user or repository
|
|
@@ -761,23 +891,24 @@ restrictions.
|
|
|
761
891
|
|
|
762
892
|
### Environment variables
|
|
763
893
|
|
|
764
|
-
| Variable | Effect
|
|
765
|
-
| --------------------------------------------------------------------------- |
|
|
766
|
-
| `OPENAI_API_KEY`, `CODEX_API_KEY` | Scan credentials; `OPENAI_API_KEY` wins if both are set.
|
|
767
|
-
| `CODEX_SECURITY_EMBEDDINGS_URL` | Findings service endpoint; see [Embeddings and storage](#embeddings-and-storage).
|
|
768
|
-
| `CODEX_SECURITY_LINEAR_TEAM`, `CODEX_SECURITY_LINEAR_PROJECT` | Default team and project for completed-scan publication.
|
|
769
|
-
| `CODEX_SECURITY_LINEAR_API_KEY` | Personal API key for Linear patching and direct publication.
|
|
770
|
-
| `CODEX_SECURITY_LOG_LEVEL` | CLI-only; `debug` enables verbose diagnostics.
|
|
771
|
-
| `LOG_LEVEL` | CLI-only fallback when `CODEX_SECURITY_LOG_LEVEL` is unset.
|
|
772
|
-
| `CODEX_SECURITY_STATE_DIR` | Private scan-history, workbench, and default artifact directory.
|
|
773
|
-
| `
|
|
774
|
-
| `
|
|
775
|
-
| `
|
|
776
|
-
| `
|
|
777
|
-
| `
|
|
778
|
-
| `
|
|
779
|
-
| `
|
|
780
|
-
| `
|
|
894
|
+
| Variable | Effect |
|
|
895
|
+
| --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
|
|
896
|
+
| `OPENAI_API_KEY`, `CODEX_API_KEY` | Scan credentials; `OPENAI_API_KEY` wins if both are set. |
|
|
897
|
+
| `CODEX_SECURITY_EMBEDDINGS_URL` | Findings service endpoint; see [Embeddings and storage](#embeddings-and-storage). |
|
|
898
|
+
| `CODEX_SECURITY_LINEAR_TEAM`, `CODEX_SECURITY_LINEAR_PROJECT` | Default team and project for completed-scan publication. |
|
|
899
|
+
| `CODEX_SECURITY_LINEAR_API_KEY` | Personal API key for Linear patching and direct publication. |
|
|
900
|
+
| `CODEX_SECURITY_LOG_LEVEL` | CLI-only; `debug` enables verbose diagnostics. |
|
|
901
|
+
| `LOG_LEVEL` | CLI-only fallback when `CODEX_SECURITY_LOG_LEVEL` is unset. |
|
|
902
|
+
| `CODEX_SECURITY_STATE_DIR` | Private scan-history, workbench, and default artifact directory. |
|
|
903
|
+
| `CODEX_SECURITY_PROJECT_CONFIG` | Trusted project file for `scan`, `bulk-scan`, `scan-components`, and `info`; `-c` wins. Unset by default. |
|
|
904
|
+
| `CODEX_HOME` | Ambient Codex home for file-based sign-in and default state; defaults to `~/.codex`. |
|
|
905
|
+
| `CODEX_CLI_PATH` | Codex executable for authentication, plugin setup, scans, and workers. |
|
|
906
|
+
| `PYTHON` | Python interpreter when `--python` or SDK `pythonPath` is unset. |
|
|
907
|
+
| `GH_HOST` | GitHub Enterprise host for interactive `bulk-scan` discovery. |
|
|
908
|
+
| `CODEX_SECURITY_NO_UPDATE_NOTICE`, `NO_UPDATE_NOTIFIER` | Either variable disables interactive update notices. |
|
|
909
|
+
| `CODEX_SECURITY_NPM_REGISTRY`, `npm_config_registry`, `NPM_CONFIG_REGISTRY` | Update-check registry, in precedence order. |
|
|
910
|
+
| `CI` | Disables interactive update notices. |
|
|
911
|
+
| `NO_COLOR`, `TERM` | Disables colored scan history when `NO_COLOR` is defined or `TERM=dumb`. |
|
|
781
912
|
|
|
782
913
|
Custom Codex executables need thread source attribution for `exec` and
|
|
783
914
|
`app-server` (Codex 0.149.1+). On Windows, use a native `.exe` or `.com`;
|
|
@@ -803,20 +934,32 @@ The final summary preserves missing-data information from a matching session log
|
|
|
803
934
|
If the Codex runtime converts an omitted count to zero before recording it, the
|
|
804
935
|
CLI cannot distinguish that zero from reported usage.
|
|
805
936
|
|
|
806
|
-
|
|
807
|
-
|
|
808
|
-
|
|
809
|
-
|
|
810
|
-
|
|
811
|
-
|
|
812
|
-
|
|
937
|
+
Cost displays show a range using
|
|
938
|
+
[standard API prices](https://developers.openai.com/api/docs/pricing), because
|
|
939
|
+
runtime usage does not identify which requests received long-context pricing.
|
|
940
|
+
The minimum assumes short-context pricing; the maximum assumes long-context
|
|
941
|
+
pricing. These are token-cost estimates for the observed usage, excluding other
|
|
942
|
+
processing tiers, fees, surcharges, and account-specific pricing.
|
|
943
|
+
|
|
944
|
+
JSON results, scan history, and bulk-scan receipts preserve
|
|
945
|
+
`cost.estimatedUsdRange`: `min`, `max`, and `context: "unknown"`. A `null` maximum
|
|
946
|
+
means an upper estimate is unavailable, including models without verified
|
|
947
|
+
long-context rates. `cost.pricing` records the price source, verification date,
|
|
948
|
+
processing tier, short-context rates, and verified long-context rates when known.
|
|
949
|
+
Models without known short-context prices still have no cost estimate.
|
|
813
950
|
|
|
814
951
|
For compatibility, `cacheWriteInputTokens` remains the reported token subtotal.
|
|
815
952
|
`cacheWriteInputTokensReported: false` means at least one included usage record
|
|
816
953
|
did not report cache writes. Raw usage uses `cache_write_input_tokens_reported`.
|
|
817
|
-
In that case, the
|
|
818
|
-
it
|
|
819
|
-
and
|
|
954
|
+
In that case, the range minimum prices unclassified input as ordinary input,
|
|
955
|
+
and the maximum allows it to be cache writes. Token counts remain unchanged.
|
|
956
|
+
Older saved records remain readable and display a labeled legacy estimate;
|
|
957
|
+
they are not repriced using current rates.
|
|
958
|
+
|
|
959
|
+
For compatibility, `cost.estimatedUsd` retains the short-context baseline used
|
|
960
|
+
by existing spending limits. `cost.pricing.context: "short"` describes that
|
|
961
|
+
baseline, not observed request contexts. Use `estimatedUsdRange` for cost
|
|
962
|
+
reporting. This change does not change when spending limits stop scans.
|
|
820
963
|
|
|
821
964
|
`--max-cost USD` stops the scan and its workers when estimated cost exceeds
|
|
822
965
|
the limit, though in-flight requests can finish above it. If deep-scan
|
|
@@ -873,6 +1016,11 @@ npx @openai/codex-security bulk-scan repositories.csv \
|
|
|
873
1016
|
|
|
874
1017
|
`--scan-prompt-file PATH` adds instructions to a scan or all bulk scans. Each
|
|
875
1018
|
repository's CSV `prompt` follows the shared instructions.
|
|
1019
|
+
`-c FILE` shares config with single scans: CSV mode/scope override file defaults,
|
|
1020
|
+
and deep settings apply only to deep rows. `output.directory` can supply the
|
|
1021
|
+
results directory. `fail_on_severity` returns exit `1` without retrying completed
|
|
1022
|
+
scans, including when resuming saved results. A changed project configuration
|
|
1023
|
+
requires a new campaign output directory.
|
|
876
1024
|
`--post-scan-prompt-file PATH` runs a follow-up in the same authenticated session,
|
|
877
1025
|
even after a failed or incomplete scan, but not after cancellation or a
|
|
878
1026
|
cost-limit stop.
|
|
@@ -927,7 +1075,8 @@ file. Source review still runs; discovery workers do not receive this prompt.
|
|
|
927
1075
|
npx @openai/codex-security scan . --validation-prompt-file validation.md
|
|
928
1076
|
```
|
|
929
1077
|
|
|
930
|
-
The SDK accepts the same
|
|
1078
|
+
The SDK accepts the same file as `validationPromptFile`, or inline text as
|
|
1079
|
+
`validationPrompt`:
|
|
931
1080
|
|
|
932
1081
|
```ts
|
|
933
1082
|
const result = await security.run(repository, {
|
|
@@ -1141,7 +1290,7 @@ Omitting `--rubric` inherits each finding's existing severity without a model ca
|
|
|
1141
1290
|
|
|
1142
1291
|
`--rubric PATH` supplies the classification policy. Repeat `--knowledge-base PATH`
|
|
1143
1292
|
to provide supporting architecture, deployment, or business context. Both accept
|
|
1144
|
-
the same
|
|
1293
|
+
the same UTF-8 text, PDF, DOCX, and directory inputs as scan knowledge bases.
|
|
1145
1294
|
Rubric classification uses the full supplied report and context in a separate
|
|
1146
1295
|
read-only Codex turn per finding, without source inspection, tools, or new
|
|
1147
1296
|
validation. `--model` and `--effort` select the classification model and reasoning
|
|
@@ -1275,11 +1424,35 @@ and worker activity. These can contain source code, prompts, findings, tool
|
|
|
1275
1424
|
output, and other sensitive data. Only include logs you can share with OpenAI.
|
|
1276
1425
|
The command uses Codex's feedback service and respects `feedback.enabled = false`.
|
|
1277
1426
|
|
|
1427
|
+
For scans started through the Desktop plugin, run the command on the machine
|
|
1428
|
+
where the scan ran, using the same Codex home and Codex Security state directory.
|
|
1429
|
+
It searches active and archived sessions in both that Codex home and the CLI's
|
|
1430
|
+
managed home, and attaches available worker logs even if the parent log is missing.
|
|
1431
|
+
Earlier retries that started separate sessions may be missing when their session
|
|
1432
|
+
IDs are no longer recorded.
|
|
1433
|
+
|
|
1434
|
+
Standard scans run inside an existing Codex conversation attach only the owner's
|
|
1435
|
+
saved session; they do not record which subagents belong to the scan. Deep Scans
|
|
1436
|
+
and scans launched by `codex-security` also attach their recorded execution
|
|
1437
|
+
threads and descendants, without following unrelated children of the owner.
|
|
1438
|
+
|
|
1278
1439
|
### Scan history and reruns
|
|
1279
1440
|
|
|
1280
1441
|
Commands default to the current repository. Select scans by full ID or a
|
|
1281
1442
|
unique prefix of at least eight characters.
|
|
1282
1443
|
|
|
1444
|
+
New recipes retain resolved settings and the authentication choice, not
|
|
1445
|
+
credentials. Reruns do not reload project files; complete saved deep settings do
|
|
1446
|
+
not use current legacy defaults. Older partial recipes retain their previous
|
|
1447
|
+
fallback behavior. Context paths and the current checkout are not immutable input
|
|
1448
|
+
snapshots.
|
|
1449
|
+
|
|
1450
|
+
Reruns require replacement scan instructions when the original scan used them.
|
|
1451
|
+
New recipes mark this requirement, and `scans rerun` refuses to omit them silently; use
|
|
1452
|
+
`scans rerun [SCAN_ID] --scan-prompt-file FILE` to supply a nonempty replacement.
|
|
1453
|
+
Replacement files resolve from the invocation directory. Custom validation keeps its existing
|
|
1454
|
+
`scans rerun --validation-prompt-file` requirement.
|
|
1455
|
+
|
|
1283
1456
|
| Command | Purpose |
|
|
1284
1457
|
| ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
|
|
1285
1458
|
| `scans list [REPOSITORY]` | List scans. Filter by artifact root with `--scan-root DIR`. |
|
|
@@ -1308,8 +1481,10 @@ The checkout's identity, revision, and contents must match the saved target.
|
|
|
1308
1481
|
Completed, failed, and canceled scans cannot resume; `scans rerun` starts a new scan.
|
|
1309
1482
|
|
|
1310
1483
|
Resume uses the saved configuration and instructions with the installed plugin.
|
|
1311
|
-
New scans save the explicit safety identifier and
|
|
1312
|
-
|
|
1484
|
+
New scans save the selected authentication mode, explicit safety identifier, and
|
|
1485
|
+
post-scan prompt contents. Resume restores the authentication choice without
|
|
1486
|
+
saving credentials. Single-scan resume restores the prompt even if its original
|
|
1487
|
+
file changes or disappears.
|
|
1313
1488
|
Older records that did not save these values cannot reconstruct them. Bulk
|
|
1314
1489
|
recovery still requires matching campaign inputs and options; it uses the supplied
|
|
1315
1490
|
post-scan prompt when the scan has no saved prompt.
|
|
@@ -1465,11 +1640,31 @@ npx @openai/codex-security patch --scan SCAN_ID --assess-patch-risk --create-pr
|
|
|
1465
1640
|
npx @openai/codex-security patch --linear-issue SEC-123 --assess-patch-risk --create-pr
|
|
1466
1641
|
```
|
|
1467
1642
|
|
|
1468
|
-
`--scan latest` selects the current repository's latest scan.
|
|
1469
|
-
|
|
1643
|
+
`--scan latest` selects the current repository's latest scan. Patch commands
|
|
1644
|
+
support `--json`, including literal-text and file inputs. Change
|
|
1470
1645
|
the model with `--codex 'model="gpt-5.6-sol"'` or effort with `--effort high`.
|
|
1471
1646
|
Each finding gets its own saved Codex desktop task.
|
|
1472
1647
|
|
|
1648
|
+
Before patching, the CLI runs a command with the task's sandbox policy. If the
|
|
1649
|
+
sandbox cannot start, the command exits with a nonzero status and reports
|
|
1650
|
+
`SANDBOX_UNAVAILABLE`. JSON errors include `ok: false`. A completed model response
|
|
1651
|
+
with no repository changes fails with `NO_PATCH_APPLIED`. Results report `applied`,
|
|
1652
|
+
`filesChanged`, and `files`; existing local changes do not count as patch changes.
|
|
1653
|
+
These fields report file changes, not proof that the security issue is fixed.
|
|
1654
|
+
Saved findings still require a verified result from the patch task.
|
|
1655
|
+
|
|
1656
|
+
For a controlled container that provides its own isolation, explicitly opt in:
|
|
1657
|
+
|
|
1658
|
+
```bash
|
|
1659
|
+
npx @openai/codex-security patch "Security issue" --external-sandbox --json
|
|
1660
|
+
```
|
|
1661
|
+
|
|
1662
|
+
`--external-sandbox` defaults to false. It uses Codex's external-sandbox policy
|
|
1663
|
+
and prints a warning: Codex does not enforce filesystem or network isolation for
|
|
1664
|
+
the patch task. The container must enforce those boundaries. The CLI never
|
|
1665
|
+
falls back to this mode automatically. Optional patch-risk assessment still uses
|
|
1666
|
+
its read-only Codex sandbox.
|
|
1667
|
+
|
|
1473
1668
|
`scan --patch` patches after a complete scan. `--patch-severity` defaults to
|
|
1474
1669
|
`low`; `high` selects high and critical findings. Use the interactive browser
|
|
1475
1670
|
to select findings and add patch instructions. Results include a `patches`
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
# Artifact Storage
|
|
2
|
+
|
|
3
|
+
Apply this policy to plugin-managed scans and standalone artifact-producing skills. An explicitly SDK-owned workflow keeps its SDK-provided directories and existing artifact-writing and completion behavior; follow its existing instructions instead of this policy. Bound Deep workers keep their existing narrow artifact tools and read-only execution profile.
|
|
4
|
+
|
|
5
|
+
## Scan ownership
|
|
6
|
+
|
|
7
|
+
For a full scan, obtain the authoritative `scanId` before creating artifacts. Standard uses `start_codex_security_standard_scan`; a headless Diff without a scan uses `start_codex_security_prompt_only_scan` with its exact target, `mode: "diff"`, `scope: "."` and `diffTarget`. Deep uses its existing coordinator. Preserve an existing scan and handoff token. If the required MCP is unavailable or the selected baseline is unsupported, report the blocker; do not fall back to shell-authored canonical files. These rules take precedence over older terminal file-authoring fallbacks.
|
|
8
|
+
|
|
9
|
+
Keep structured outputs on their existing tools: inventories, candidate discovery, validation, attack paths, semantic drafts, checkpoints and completion. Canonical results and recovery checkpoints are persistent even while a scan is running. Never use the supplemental file tool to replace them or generate `report.md`.
|
|
10
|
+
|
|
11
|
+
## Supplemental files
|
|
12
|
+
|
|
13
|
+
Use the existing plugin MCP's `save_codex_security_artifact` and `read_codex_security_artifact` for Markdown, optional finding write-ups, hardening documents/diagrams, validation evidence and retained helper output. Do not write these retained files with shell redirection, `apply_patch`, Python or other ordinary file-writing tools.
|
|
14
|
+
|
|
15
|
+
Identify the owner with exactly one of:
|
|
16
|
+
|
|
17
|
+
- `scanId` and the current `handoffClaimToken` when required, for a running scan;
|
|
18
|
+
- `targetPath`, for a standalone phase or a derived document requested after a scan completes. Use the authorized repository or input-document directory. This creates a target-bound artifact collection without starting a scan. Never invent a scan ID.
|
|
19
|
+
|
|
20
|
+
Select `storage` explicitly:
|
|
21
|
+
|
|
22
|
+
- `persistent`: retained documents/evidence under the authoritative scan directory or standalone collection. The default root is `$CODEX_SECURITY_STATE_DIR/scans`, or `$CODEX_HOME/state/plugins/codex-security/scans` when no state override is set; `CODEX_HOME` defaults to `~/.codex`. The existing `CODEX_SECURITY_SCAN_ROOT` override still takes precedence for plugin-created output. If the default workbench state is unwritable, retained artifacts follow its temporary fallback state's `scans` directory and can be removed by OS temporary-directory cleanup. Preserve an existing scan's saved path, including older temporary paths.
|
|
23
|
+
- `temporary`: disposable staging and execution output in a context-specific OS temporary directory. Standalone temporary saves and reads do not create or require the persistent collection. It is not part of the completed result and must not be referenced from canonical findings or coverage. It can disappear independently of retained files.
|
|
24
|
+
|
|
25
|
+
Relative storage overrides resolve from the plugin directory, matching the workbench, regardless of the MCP launch directory.
|
|
26
|
+
|
|
27
|
+
Omit `path`, `content` and `sourcePath` to prepare the selected directory. Use the returned `directory`; never construct or guess the physical path. A save with a file requires `path` plus exactly one of `content` or `sourcePath`.
|
|
28
|
+
|
|
29
|
+
Example for a running scan:
|
|
30
|
+
|
|
31
|
+
```text
|
|
32
|
+
save_codex_security_artifact({ scanId, handoffClaimToken?, storage: "persistent", path: "artifacts/01_context/threat_model.md", content: "<exact Markdown>" })
|
|
33
|
+
save_codex_security_artifact({ scanId, handoffClaimToken?, storage: "temporary" })
|
|
34
|
+
save_codex_security_artifact({ scanId, handoffClaimToken?, storage: "persistent", path: "artifacts/02_discovery/validation_artifacts/<candidate_id>/poc.bin", sourcePath: "<returned temporary directory>/poc.bin" })
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
`path` is a portable relative filename under `artifacts/`, `findings/` or `hardening/`; `report_validation.md` is also supported. Standalone collections additionally support `threat_model.md`. Use the existing relative artifact layouts for each phase. The tool returns the physical `path`, canonical `relativePath` and content digest. Use the persistent relative path in scan evidence references. Read with the same identity, `storage` and relative `path`; request `encoding: "base64"` only for binary content.
|
|
38
|
+
|
|
39
|
+
Source/configuration edits and external-publication request bodies are separate from scan artifacts and retain their existing tools and authorization. Explicit user instructions still take precedence. If a required output destination cannot be represented by managed storage, explain that limitation instead of silently substituting a different destination or claiming it was written.
|
|
40
|
+
|
|
41
|
+
## Generated evidence and legacy helpers
|
|
42
|
+
|
|
43
|
+
PoC execution and builds can create files. Prepare `temporary` storage first and run authorized build/test/generation commands only in that workspace or its disposable repository copy. Author PoC source/input files with the save tool using `storage: "temporary"`. Tools that generate inventories, normalization output or other files must receive temporary output paths. Import each file needed in the final record with `storage: "persistent"` and `sourcePath` inside the same returned temporary directory. Import the actual bytes, not a model transcription of binary output or logs. Do not retain entire dependency/build trees without a reason.
|
|
44
|
+
|
|
45
|
+
For standalone/legacy mutable ledgers, use the save tool to replace their complete contents, or import a helper-produced temporary file. Do not append directly into the retained scan directory. Current Standard and Deep scans do not introduce legacy inventories or ledgers.
|
|
46
|
+
|
|
47
|
+
## Threat-model cache and completed results
|
|
48
|
+
|
|
49
|
+
For the shared repository threat model, use `targetPath: <repo_root>`, `storage: "persistent"`, `path: "threat_model.md"`. Read that collection's cached file only when the threat-model workflow allows cache reuse and its exact repository/version footer matches. Save the exact selected text into `artifacts/01_context/threat_model.md` with the running scan's `scanId`. Preserve the workflow's conditions that forbid reading or replacing the shared cache; the storage tool does not authorize a cache update.
|
|
50
|
+
|
|
51
|
+
End each shared threat model with these two lines:
|
|
52
|
+
|
|
53
|
+
- `Repository: <stable target identity from scan-contract.md>`
|
|
54
|
+
- `Version: <revision for an immutable Git tree; snapshot digest otherwise>`
|
|
55
|
+
|
|
56
|
+
Completed/sealed scan files cannot be edited through the save tool. For later write-ups or hardening requests, use the standalone target collection and link those returned files separately. Preserve the original result and its references. Temporary cleanup must not remove retained files or recovery checkpoints. The save tool publishes running-scan files under the same completion lock as finalization; surface a stopped/sealed-scan rejection and preserve existing output.
|
|
@@ -2,6 +2,8 @@
|
|
|
2
2
|
|
|
3
3
|
Codex Security Standard and diff scan skills should run the read-only helper before substantive scan work. Deep scans have no parent capability requirements and do not run this helper.
|
|
4
4
|
|
|
5
|
+
The top-level parent reads `artifact-storage.md` once before preflight and follows its scan-ownership rules, including for terminal Diff scans.
|
|
6
|
+
|
|
5
7
|
Load `desktop-config-preflight.md` only after the host explicitly identifies itself as the Codex desktop app.
|
|
6
8
|
|
|
7
9
|
Resolve `<python_command>` to the configured Python interpreter (`"$PYTHON"` in POSIX shells or `& "$env:PYTHON"` in PowerShell), otherwise use `python` on Windows and `python3` on Unix-like hosts. Before constructing the first helper command, inspect the current tool surface once and use that discovery result for both the runtime checks and `<verified-multi-agent-runtime-arguments>`. Do not omit active runtime facts from the first invocation and wait for an `incomplete` result before supplying them. The command is written on one line so it works in PowerShell, Command Prompt, and POSIX shells:
|
|
@@ -88,4 +90,8 @@ Codex CLI and other hosts use the same prompt-based preflight before substantive
|
|
|
88
90
|
|
|
89
91
|
## Daybreak Access Advisory
|
|
90
92
|
|
|
91
|
-
After capability preflight is `ready` and immediately before the workflow's first substantive scan action, call the plugin's `get_codex_security_daybreak_access` tool
|
|
93
|
+
After capability preflight is `ready` and immediately before the workflow's first substantive scan action, call the plugin's `get_codex_security_daybreak_access` tool once only if it is available in the current session. If the tool is unavailable, skip the advisory silently: do not attempt a call, probe for it, or use a replacement access tool or connector. ChatGPT-authenticated desktop and CLI sessions support this advisory; skip it silently in known API-key-only sessions, which cannot verify account access. For Deep Security Scan, make the call immediately before `start_codex_security_deep_scan`. Reuse an existing result when continuing the same scan.
|
|
94
|
+
|
|
95
|
+
If the call fails, returns `status: "unknown"`, or returns `stale: true`, continue silently. Do not expose the unavailable check, unknown status, empty program list, or a speculative protected-output warning in progress messages or the final response. For a fresh `granted` result, report the exact status and available Daybreak programs. For a fresh `not_granted` result, before any other scan-start progress, present a separate, prominent warning that Daybreak access is not granted for this account and protected scan outputs may not be displayable. Include the returned `enrollmentUrl` as a clickable application link, falling back to `https://chatgpt.com/cyber` when absent.
|
|
96
|
+
|
|
97
|
+
Continue regardless: this advisory never authorizes or gates the scan. Do not retry, poll, or repeat it between phases. If the user explicitly asks about Daybreak access, report the result or explain that it could not be verified; an unavailable or unknown result does not establish that access is denied. Recheck only when the user explicitly requests a fresh result after an account or Daybreak access change, and only when the tool is available.
|
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
# Final Report and Codex Review Directives
|
|
2
2
|
|
|
3
|
+
Follow `artifact-storage.md` for storing canonical results, supplementary documents and `report_validation.md`.
|
|
4
|
+
|
|
3
5
|
Use this guidance when authoring canonical report semantics and returning the generated Codex Security report and review directives.
|
|
4
6
|
|
|
5
7
|
## Final Outputs
|
|
@@ -2,15 +2,15 @@
|
|
|
2
2
|
|
|
3
3
|
Use these shared path conventions for Codex Security scan workflows unless the user explicitly provides different input or output paths.
|
|
4
4
|
|
|
5
|
+
Follow `artifact-storage.md` for storage selection, file authoring and shared threat-model cache rules.
|
|
6
|
+
|
|
5
7
|
## Base Paths
|
|
6
8
|
|
|
7
9
|
- `plugin_dir=<codex-security plugin root>`
|
|
8
|
-
- `repo_name=<basename of repo_root>`
|
|
9
10
|
- `target_id=<stable scan target identity from references/scan-contract.md>`
|
|
10
|
-
- `
|
|
11
|
-
- `
|
|
12
|
-
- `
|
|
13
|
-
- `scan_dir=<security_scans_dir>/<scan_id>`
|
|
11
|
+
- `scan_id=<scanId returned by the MCP scan context, or CODEX_SECURITY_SCAN_ID when provided>`
|
|
12
|
+
- `scan_dir=<scanDir returned by the MCP scan context>`; when `CODEX_SECURITY_SCAN_DIR` is provided, use that existing SDK-owned directory. Never derive a scan directory from a repository name, revision, timestamp or temporary-directory formula.
|
|
13
|
+
- For a standalone phase, use the `directory` returned by `save_codex_security_artifact` for the selected `targetPath` and `storage`, as described in `artifact-storage.md`.
|
|
14
14
|
- `target_paths_file=<CODEX_SECURITY_TARGET_PATHS_FILE>` for SDK scoped-path scans; reference it as `"$CODEX_SECURITY_TARGET_PATHS_FILE"` in POSIX shells or `"$env:CODEX_SECURITY_TARGET_PATHS_FILE"` in PowerShell. This read-only scope input lives in the isolated Codex home outside the model-writable scan directory. Pass it directly to `make-repo-scope-input --scopes-file` and `bind-repo-scopes --scopes-file` before finalization, and do not print, evaluate, modify, or treat its contents as shell syntax.
|
|
15
15
|
- `artifacts_dir=<scan_dir>/artifacts`
|
|
16
16
|
- `context_dir=<artifacts_dir>/01_context`
|
|
@@ -19,22 +19,14 @@ Use these shared path conventions for Codex Security scan workflows unless the u
|
|
|
19
19
|
- `reconciliation_dir=<artifacts_dir>/04_reconciliation`
|
|
20
20
|
- `findings_dir=<artifacts_dir>/05_findings`
|
|
21
21
|
|
|
22
|
-
The plugin resolves the platform temporary directory automatically. For a manual workflow, use the active process temporary directory (for example, `%TEMP%` on Windows or `$TMPDIR` when configured on Unix-like hosts) instead of hardcoding `/tmp`.
|
|
23
|
-
|
|
24
22
|
Resolve `<python_command>` to the configured Python interpreter (`"$PYTHON"` in POSIX shells or `& "$env:PYTHON"` in PowerShell), otherwise use `python` on Windows and `python3` on Unix-like hosts.
|
|
25
23
|
|
|
26
24
|
## Threat Model (Phase 1) Paths
|
|
27
25
|
|
|
28
26
|
- Resolved SECURITY.md guidance: `<context_dir>/security_guidance.md`
|
|
29
|
-
- Repository-scoped threat model:
|
|
27
|
+
- Repository-scoped threat model: use the shared cache policy in `artifact-storage.md`.
|
|
30
28
|
- Per-scan threat model copy: `<context_dir>/threat_model.md`
|
|
31
29
|
- Later scan phases should treat `<context_dir>/threat_model.md` as the source of truth.
|
|
32
|
-
- When a repository-scoped threat model already exists, copy it to `<context_dir>/threat_model.md` without alteration for auditability.
|
|
33
|
-
|
|
34
|
-
End each repository-scoped threat model with these two lines:
|
|
35
|
-
|
|
36
|
-
- `Repository: <target_id>`
|
|
37
|
-
- `Version: <revision for an immutable Git tree; snapshot digest otherwise>`
|
|
38
30
|
|
|
39
31
|
## Finding Discovery (Phase 2) Paths
|
|
40
32
|
|
|
@@ -4,6 +4,8 @@ Apply this guidance once when a Standard or Deep Security Scan owns the top-leve
|
|
|
4
4
|
|
|
5
5
|
## Setup and Scan Ownership
|
|
6
6
|
|
|
7
|
+
Read `artifact-storage.md` before choosing artifact paths and follow its scan-ownership and storage rules.
|
|
8
|
+
|
|
7
9
|
Follow the active scan mode's existing direct-start, native-continuation, SDK-owned, or headless-launch path. Codex CLI, evaluation harnesses, automation, and other headless hosts never open or wait for a desktop workspace. An explicitly identified desktop host retains its documented app continuation and authoritative scan context.
|
|
8
10
|
|
|
9
11
|
When an existing native continuation provides a `scanId`, load `get_codex_security_scan_context` once with its `handoffClaimToken` when present; preserve the returned scan identity, directory, target, scope, mode, exact `userContext`, and handoff token. If required context is missing, malformed, or belongs to another mode, follow the active entrypoint's existing error or routing behavior instead of inventing an identifier, creating a replacement scan, or widening the target. An SDK-owned scan preserves its SDK-provided scan identity and directory without creating or finalizing another scan.
|
|
@@ -4,6 +4,8 @@
|
|
|
4
4
|
|
|
5
5
|
## Resolve
|
|
6
6
|
|
|
7
|
+
Read `artifact-storage.md` for the applicable storage rules. When using its artifact MCP, request `--out -`, consume the result directly, and save the exact output as `security_guidance.md` through `save_codex_security_artifact` if required; do not pass the persistent artifact path to the helper.
|
|
8
|
+
|
|
7
9
|
Compile the full `SECURITY.md` policy for a file or directory with:
|
|
8
10
|
|
|
9
11
|
```
|