@openai/codex-security 0.1.27 → 0.1.29
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 +328 -59
- package/_bundled_plugin/examples/completed-scan/report.md +0 -1
- 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/finalize_scan_contract.py +2 -0
- package/_bundled_plugin/scripts/generate_in_scope_files.py +12 -2
- package/_bundled_plugin/scripts/generate_rank_input.py +1 -6
- package/_bundled_plugin/scripts/rank_preview.py +8 -7
- package/_bundled_plugin/scripts/report_projection.py +0 -1
- 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_dashboard.py +24 -3
- package/_bundled_plugin/scripts/workbench_db.py +13 -13
- package/_bundled_plugin/scripts/workbench_saved_results.py +77 -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-scan-logs-json.d.ts +3 -0
- package/dist/cli-scan-logs-json.d.ts.map +1 -0
- package/dist/cli-scan-logs-json.js +22 -0
- package/dist/cli-scan-logs-json.js.map +1 -0
- package/dist/cli.d.ts +6 -2
- package/dist/cli.d.ts.map +1 -1
- package/dist/cli.js +802 -394
- 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 +26 -4
- 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.d.ts +12 -1
- package/dist/deduplication/deduplication.d.ts.map +1 -1
- package/dist/deduplication/deduplication.js +41 -7
- package/dist/deduplication/deduplication.js.map +1 -1
- package/dist/deduplication/refusal.d.ts +3 -0
- package/dist/deduplication/refusal.d.ts.map +1 -0
- package/dist/deduplication/refusal.js +16 -0
- package/dist/deduplication/refusal.js.map +1 -0
- 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 +1 -1
- 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 +6 -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 +76 -19
- 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 +3 -3
- package/dist/server/dashboard/app.css +1 -1
- package/dist/server/dashboard/app.js +7 -7
- package/dist/server/dashboard-types.d.ts +4 -1
- package/dist/server/dashboard-types.d.ts.map +1 -1
- package/dist/server/dashboard-types.js.map +1 -1
- package/dist/server/dashboard.d.ts.map +1 -1
- package/dist/server/dashboard.js +18 -4
- 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 +4 -4
- 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
|
|
@@ -472,6 +587,23 @@ Scans are report-only by default. Set `--fail-on-severity high` to exit with
|
|
|
472
587
|
`1` if a completed scan finds high or critical issues. Incomplete scans exit
|
|
473
588
|
with `2`, writing available results to stdout and a coverage warning to stderr.
|
|
474
589
|
|
|
590
|
+
For machine-readable scan output (`--format json` or `--format jsonl`), a scan
|
|
591
|
+
execution failure writes one structured object to stdout:
|
|
592
|
+
|
|
593
|
+
```json
|
|
594
|
+
{
|
|
595
|
+
"status": "failed",
|
|
596
|
+
"code": "SCAN_FAILED",
|
|
597
|
+
"message": "..."
|
|
598
|
+
}
|
|
599
|
+
```
|
|
600
|
+
|
|
601
|
+
The command still exits with `2` for runtime, export, invalid-input, or
|
|
602
|
+
incomplete-scan failures, and human-readable diagnostics remain on stderr.
|
|
603
|
+
Use `scan --schema --format json` to discover this failure variant alongside
|
|
604
|
+
the successful scan output. Cancellation and termination retain their `130`
|
|
605
|
+
and `143` exit codes.
|
|
606
|
+
|
|
475
607
|
### Import findings as a saved scan
|
|
476
608
|
|
|
477
609
|
Import an existing findings CSV or JSON file into local scan history and SQLite:
|
|
@@ -567,7 +699,7 @@ runtime or plugin compatibility. Older versions may omit the ID.
|
|
|
567
699
|
### Scan project components
|
|
568
700
|
|
|
569
701
|
`scan --path` runs one scan across selected paths. To scan each local project
|
|
570
|
-
component separately
|
|
702
|
+
component separately (standard mode by default), use `scan-components`:
|
|
571
703
|
|
|
572
704
|
```bash
|
|
573
705
|
npx @openai/codex-security scan-components /path/to/project \
|
|
@@ -575,6 +707,12 @@ npx @openai/codex-security scan-components /path/to/project \
|
|
|
575
707
|
--workers 4 --output-dir /path/outside/project/results
|
|
576
708
|
```
|
|
577
709
|
|
|
710
|
+
Use `-c FILE` to share settings, including `scan.mode: deep`, context and prompt
|
|
711
|
+
files, per-scan deep workers, cost limits, and severity policy. Component plans
|
|
712
|
+
override the file's scope. `output.directory` supplies the results directory when
|
|
713
|
+
`--output-dir` is omitted. A configured severity threshold returns exit `1` after
|
|
714
|
+
completed scans; failures or incomplete results return `2`.
|
|
715
|
+
|
|
578
716
|
Use `--auto` instead of `--component` for a proposed split. Save a plan to
|
|
579
717
|
review or edit, then run it with a new output directory:
|
|
580
718
|
|
|
@@ -651,6 +789,7 @@ await security.run("/path/to/repository", {
|
|
|
651
789
|
workers: 2,
|
|
652
790
|
subagents: 0,
|
|
653
791
|
stopAfterNoNew: 3,
|
|
792
|
+
stopAfterConsecutiveErrors: 2,
|
|
654
793
|
maxDiscoveryRuns: 10,
|
|
655
794
|
maxTimeHours: 1.5,
|
|
656
795
|
});
|
|
@@ -668,8 +807,10 @@ max_discovery_runs = 40
|
|
|
668
807
|
max_time_hours = 96
|
|
669
808
|
```
|
|
670
809
|
|
|
671
|
-
CLI and SDK options override these defaults.
|
|
672
|
-
|
|
810
|
+
CLI and SDK options override these defaults. Project files can use
|
|
811
|
+
`scan.deep.stop_after_consecutive_errors`, and SDK calls can use
|
|
812
|
+
`stopAfterConsecutiveErrors`; there is no new CLI flag for it. `--codex` cannot
|
|
813
|
+
configure this section. Worker and run counts must
|
|
673
814
|
be positive integers; `subagents` can be zero. Legacy `workers = "auto"` means
|
|
674
815
|
four workers. Unknown keys are rejected.
|
|
675
816
|
|
|
@@ -679,6 +820,12 @@ At the deadline, discovery stops; the scan combines and returns completed findin
|
|
|
679
820
|
`scan --workers` controls discovery workers within one deep scan;
|
|
680
821
|
`bulk-scan --workers` controls how many repositories are scanned concurrently.
|
|
681
822
|
|
|
823
|
+
The project-file deep block uses `subagents_per_worker` for the existing SDK/CLI
|
|
824
|
+
`subagents` setting. A valid deep block can remain inactive in standard mode;
|
|
825
|
+
explicit deep CLI options require deep mode. All six active values are resolved
|
|
826
|
+
before runtime preparation and saved in new recipes. Complete saved values are
|
|
827
|
+
independent of later changes to the legacy TOML file.
|
|
828
|
+
|
|
682
829
|
### Runtime configuration and worker limits
|
|
683
830
|
|
|
684
831
|
Scans use these isolated Codex defaults instead of your user or repository
|
|
@@ -761,23 +908,24 @@ restrictions.
|
|
|
761
908
|
|
|
762
909
|
### Environment variables
|
|
763
910
|
|
|
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
|
-
| `
|
|
911
|
+
| Variable | Effect |
|
|
912
|
+
| --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
|
|
913
|
+
| `OPENAI_API_KEY`, `CODEX_API_KEY` | Scan credentials; `OPENAI_API_KEY` wins if both are set. |
|
|
914
|
+
| `CODEX_SECURITY_EMBEDDINGS_URL` | Findings service endpoint; see [Embeddings and storage](#embeddings-and-storage). |
|
|
915
|
+
| `CODEX_SECURITY_LINEAR_TEAM`, `CODEX_SECURITY_LINEAR_PROJECT` | Default team and project for completed-scan publication. |
|
|
916
|
+
| `CODEX_SECURITY_LINEAR_API_KEY` | Personal API key for Linear patching and direct publication. |
|
|
917
|
+
| `CODEX_SECURITY_LOG_LEVEL` | CLI-only; `debug` enables verbose diagnostics. |
|
|
918
|
+
| `LOG_LEVEL` | CLI-only fallback when `CODEX_SECURITY_LOG_LEVEL` is unset. |
|
|
919
|
+
| `CODEX_SECURITY_STATE_DIR` | Private scan-history, workbench, and default artifact directory. |
|
|
920
|
+
| `CODEX_SECURITY_PROJECT_CONFIG` | Trusted project file for `scan`, `bulk-scan`, `scan-components`, and `info`; `-c` wins. Unset by default. |
|
|
921
|
+
| `CODEX_HOME` | Ambient Codex home for file-based sign-in and default state; defaults to `~/.codex`. |
|
|
922
|
+
| `CODEX_CLI_PATH` | Codex executable for authentication, plugin setup, scans, and workers. |
|
|
923
|
+
| `PYTHON` | Python interpreter when `--python` or SDK `pythonPath` is unset. |
|
|
924
|
+
| `GH_HOST` | GitHub Enterprise host for interactive `bulk-scan` discovery. |
|
|
925
|
+
| `CODEX_SECURITY_NO_UPDATE_NOTICE`, `NO_UPDATE_NOTIFIER` | Either variable disables interactive update notices. |
|
|
926
|
+
| `CODEX_SECURITY_NPM_REGISTRY`, `npm_config_registry`, `NPM_CONFIG_REGISTRY` | Update-check registry, in precedence order. |
|
|
927
|
+
| `CI` | Disables interactive update notices. |
|
|
928
|
+
| `NO_COLOR`, `TERM` | Disables colored scan history when `NO_COLOR` is defined or `TERM=dumb`. |
|
|
781
929
|
|
|
782
930
|
Custom Codex executables need thread source attribution for `exec` and
|
|
783
931
|
`app-server` (Codex 0.149.1+). On Windows, use a native `.exe` or `.com`;
|
|
@@ -803,20 +951,32 @@ The final summary preserves missing-data information from a matching session log
|
|
|
803
951
|
If the Codex runtime converts an omitted count to zero before recording it, the
|
|
804
952
|
CLI cannot distinguish that zero from reported usage.
|
|
805
953
|
|
|
806
|
-
|
|
807
|
-
|
|
808
|
-
|
|
809
|
-
|
|
810
|
-
|
|
811
|
-
|
|
812
|
-
|
|
954
|
+
Cost displays show a range using
|
|
955
|
+
[standard API prices](https://developers.openai.com/api/docs/pricing), because
|
|
956
|
+
runtime usage does not identify which requests received long-context pricing.
|
|
957
|
+
The minimum assumes short-context pricing; the maximum assumes long-context
|
|
958
|
+
pricing. These are token-cost estimates for the observed usage, excluding other
|
|
959
|
+
processing tiers, fees, surcharges, and account-specific pricing.
|
|
960
|
+
|
|
961
|
+
JSON results, scan history, and bulk-scan receipts preserve
|
|
962
|
+
`cost.estimatedUsdRange`: `min`, `max`, and `context: "unknown"`. A `null` maximum
|
|
963
|
+
means an upper estimate is unavailable, including models without verified
|
|
964
|
+
long-context rates. `cost.pricing` records the price source, verification date,
|
|
965
|
+
processing tier, short-context rates, and verified long-context rates when known.
|
|
966
|
+
Models without known short-context prices still have no cost estimate.
|
|
813
967
|
|
|
814
968
|
For compatibility, `cacheWriteInputTokens` remains the reported token subtotal.
|
|
815
969
|
`cacheWriteInputTokensReported: false` means at least one included usage record
|
|
816
970
|
did not report cache writes. Raw usage uses `cache_write_input_tokens_reported`.
|
|
817
|
-
In that case, the
|
|
818
|
-
it
|
|
819
|
-
and
|
|
971
|
+
In that case, the range minimum prices unclassified input as ordinary input,
|
|
972
|
+
and the maximum allows it to be cache writes. Token counts remain unchanged.
|
|
973
|
+
Older saved records remain readable and display a labeled legacy estimate;
|
|
974
|
+
they are not repriced using current rates.
|
|
975
|
+
|
|
976
|
+
For compatibility, `cost.estimatedUsd` retains the short-context baseline used
|
|
977
|
+
by existing spending limits. `cost.pricing.context: "short"` describes that
|
|
978
|
+
baseline, not observed request contexts. Use `estimatedUsdRange` for cost
|
|
979
|
+
reporting. This change does not change when spending limits stop scans.
|
|
820
980
|
|
|
821
981
|
`--max-cost USD` stops the scan and its workers when estimated cost exceeds
|
|
822
982
|
the limit, though in-flight requests can finish above it. If deep-scan
|
|
@@ -873,6 +1033,11 @@ npx @openai/codex-security bulk-scan repositories.csv \
|
|
|
873
1033
|
|
|
874
1034
|
`--scan-prompt-file PATH` adds instructions to a scan or all bulk scans. Each
|
|
875
1035
|
repository's CSV `prompt` follows the shared instructions.
|
|
1036
|
+
`-c FILE` shares config with single scans: CSV mode/scope override file defaults,
|
|
1037
|
+
and deep settings apply only to deep rows. `output.directory` can supply the
|
|
1038
|
+
results directory. `fail_on_severity` returns exit `1` without retrying completed
|
|
1039
|
+
scans, including when resuming saved results. A changed project configuration
|
|
1040
|
+
requires a new campaign output directory.
|
|
876
1041
|
`--post-scan-prompt-file PATH` runs a follow-up in the same authenticated session,
|
|
877
1042
|
even after a failed or incomplete scan, but not after cancellation or a
|
|
878
1043
|
cost-limit stop.
|
|
@@ -927,7 +1092,8 @@ file. Source review still runs; discovery workers do not receive this prompt.
|
|
|
927
1092
|
npx @openai/codex-security scan . --validation-prompt-file validation.md
|
|
928
1093
|
```
|
|
929
1094
|
|
|
930
|
-
The SDK accepts the same
|
|
1095
|
+
The SDK accepts the same file as `validationPromptFile`, or inline text as
|
|
1096
|
+
`validationPrompt`:
|
|
931
1097
|
|
|
932
1098
|
```ts
|
|
933
1099
|
const result = await security.run(repository, {
|
|
@@ -1141,7 +1307,7 @@ Omitting `--rubric` inherits each finding's existing severity without a model ca
|
|
|
1141
1307
|
|
|
1142
1308
|
`--rubric PATH` supplies the classification policy. Repeat `--knowledge-base PATH`
|
|
1143
1309
|
to provide supporting architecture, deployment, or business context. Both accept
|
|
1144
|
-
the same
|
|
1310
|
+
the same UTF-8 text, PDF, DOCX, and directory inputs as scan knowledge bases.
|
|
1145
1311
|
Rubric classification uses the full supplied report and context in a separate
|
|
1146
1312
|
read-only Codex turn per finding, without source inspection, tools, or new
|
|
1147
1313
|
validation. `--model` and `--effort` select the classification model and reasoning
|
|
@@ -1275,11 +1441,35 @@ and worker activity. These can contain source code, prompts, findings, tool
|
|
|
1275
1441
|
output, and other sensitive data. Only include logs you can share with OpenAI.
|
|
1276
1442
|
The command uses Codex's feedback service and respects `feedback.enabled = false`.
|
|
1277
1443
|
|
|
1444
|
+
For scans started through the Desktop plugin, run the command on the machine
|
|
1445
|
+
where the scan ran, using the same Codex home and Codex Security state directory.
|
|
1446
|
+
It searches active and archived sessions in both that Codex home and the CLI's
|
|
1447
|
+
managed home, and attaches available worker logs even if the parent log is missing.
|
|
1448
|
+
Earlier retries that started separate sessions may be missing when their session
|
|
1449
|
+
IDs are no longer recorded.
|
|
1450
|
+
|
|
1451
|
+
Standard scans run inside an existing Codex conversation attach only the owner's
|
|
1452
|
+
saved session; they do not record which subagents belong to the scan. Deep Scans
|
|
1453
|
+
and scans launched by `codex-security` also attach their recorded execution
|
|
1454
|
+
threads and descendants, without following unrelated children of the owner.
|
|
1455
|
+
|
|
1278
1456
|
### Scan history and reruns
|
|
1279
1457
|
|
|
1280
1458
|
Commands default to the current repository. Select scans by full ID or a
|
|
1281
1459
|
unique prefix of at least eight characters.
|
|
1282
1460
|
|
|
1461
|
+
New recipes retain resolved settings and the authentication choice, not
|
|
1462
|
+
credentials. Reruns do not reload project files; complete saved deep settings do
|
|
1463
|
+
not use current legacy defaults. Older partial recipes retain their previous
|
|
1464
|
+
fallback behavior. Context paths and the current checkout are not immutable input
|
|
1465
|
+
snapshots.
|
|
1466
|
+
|
|
1467
|
+
Reruns require replacement scan instructions when the original scan used them.
|
|
1468
|
+
New recipes mark this requirement, and `scans rerun` refuses to omit them silently; use
|
|
1469
|
+
`scans rerun [SCAN_ID] --scan-prompt-file FILE` to supply a nonempty replacement.
|
|
1470
|
+
Replacement files resolve from the invocation directory. Custom validation keeps its existing
|
|
1471
|
+
`scans rerun --validation-prompt-file` requirement.
|
|
1472
|
+
|
|
1283
1473
|
| Command | Purpose |
|
|
1284
1474
|
| ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
|
|
1285
1475
|
| `scans list [REPOSITORY]` | List scans. Filter by artifact root with `--scan-root DIR`. |
|
|
@@ -1308,8 +1498,10 @@ The checkout's identity, revision, and contents must match the saved target.
|
|
|
1308
1498
|
Completed, failed, and canceled scans cannot resume; `scans rerun` starts a new scan.
|
|
1309
1499
|
|
|
1310
1500
|
Resume uses the saved configuration and instructions with the installed plugin.
|
|
1311
|
-
New scans save the explicit safety identifier and
|
|
1312
|
-
|
|
1501
|
+
New scans save the selected authentication mode, explicit safety identifier, and
|
|
1502
|
+
post-scan prompt contents. Resume restores the authentication choice without
|
|
1503
|
+
saving credentials. Single-scan resume restores the prompt even if its original
|
|
1504
|
+
file changes or disappears.
|
|
1313
1505
|
Older records that did not save these values cannot reconstruct them. Bulk
|
|
1314
1506
|
recovery still requires matching campaign inputs and options; it uses the supplied
|
|
1315
1507
|
post-scan prompt when the scan has no saved prompt.
|
|
@@ -1448,6 +1640,26 @@ Use the SDK loop for a disposition per alert.
|
|
|
1448
1640
|
files or literal text and work in the current directory. Pass a saved finding
|
|
1449
1641
|
or occurrence ID to `patch` to use its original repository.
|
|
1450
1642
|
|
|
1643
|
+
Add `--validation-prompt-file PATH` to supply custom dynamic validation
|
|
1644
|
+
instructions, using the same UTF-8 prompt file format as `scan`. The patch task
|
|
1645
|
+
uses these instructions to set up the environment, build or start the application,
|
|
1646
|
+
exercise the fix, check legitimate behavior, and clean up. Include the commands,
|
|
1647
|
+
authorized targets, expected results, and cleanup steps for your environment.
|
|
1648
|
+
The task must report validation evidence or explain which checks failed or could
|
|
1649
|
+
not run before claiming the patch is fixed or verified.
|
|
1650
|
+
|
|
1651
|
+
```bash
|
|
1652
|
+
npx @openai/codex-security patch OCCURRENCE_ID --validation-prompt-file validation.md
|
|
1653
|
+
npx @openai/codex-security patch issues.md --validation-prompt-file validation.md
|
|
1654
|
+
```
|
|
1655
|
+
|
|
1656
|
+
The flag works with saved findings, issue text/files, and Linear inputs. Relative
|
|
1657
|
+
prompt paths resolve from the directory where you invoke the CLI, including when
|
|
1658
|
+
the saved finding belongs to another repository. The file is read once before
|
|
1659
|
+
patching; missing, empty, or non-regular files fail before the patch task starts.
|
|
1660
|
+
Without the flag, the usual fix-finding verification applies. The flag does not
|
|
1661
|
+
change sandbox permissions and cannot be combined with `--resume-pr`.
|
|
1662
|
+
|
|
1451
1663
|
Add `--assess-patch-risk` to a `patch` command to run the bundled patch-risk
|
|
1452
1664
|
assessment skill once on the completed patch. The assessment is advisory and
|
|
1453
1665
|
does not change the patch or its merge state. Human-readable commands print the
|
|
@@ -1465,16 +1677,38 @@ npx @openai/codex-security patch --scan SCAN_ID --assess-patch-risk --create-pr
|
|
|
1465
1677
|
npx @openai/codex-security patch --linear-issue SEC-123 --assess-patch-risk --create-pr
|
|
1466
1678
|
```
|
|
1467
1679
|
|
|
1468
|
-
`--scan latest` selects the current repository's latest scan.
|
|
1469
|
-
|
|
1680
|
+
`--scan latest` selects the current repository's latest scan. Patch commands
|
|
1681
|
+
support `--json`, including literal-text and file inputs. Change
|
|
1470
1682
|
the model with `--codex 'model="gpt-5.6-sol"'` or effort with `--effort high`.
|
|
1471
1683
|
Each finding gets its own saved Codex desktop task.
|
|
1472
1684
|
|
|
1685
|
+
Before patching, the CLI runs a command with the task's sandbox policy. If the
|
|
1686
|
+
sandbox cannot start, the command exits with a nonzero status and reports
|
|
1687
|
+
`SANDBOX_UNAVAILABLE`. JSON errors include `ok: false`. A completed model response
|
|
1688
|
+
with no repository changes fails with `NO_PATCH_APPLIED`. Results report `applied`,
|
|
1689
|
+
`filesChanged`, and `files`; existing local changes do not count as patch changes.
|
|
1690
|
+
These fields report file changes, not proof that the security issue is fixed.
|
|
1691
|
+
Saved findings still require a verified result from the patch task.
|
|
1692
|
+
|
|
1693
|
+
For a controlled container that provides its own isolation, explicitly opt in:
|
|
1694
|
+
|
|
1695
|
+
```bash
|
|
1696
|
+
npx @openai/codex-security patch "Security issue" --external-sandbox --json
|
|
1697
|
+
```
|
|
1698
|
+
|
|
1699
|
+
`--external-sandbox` defaults to false. It uses Codex's external-sandbox policy
|
|
1700
|
+
and prints a warning: Codex does not enforce filesystem or network isolation for
|
|
1701
|
+
the patch task. The container must enforce those boundaries. The CLI never
|
|
1702
|
+
falls back to this mode automatically. Optional patch-risk assessment still uses
|
|
1703
|
+
its read-only Codex sandbox.
|
|
1704
|
+
|
|
1473
1705
|
`scan --patch` patches after a complete scan. `--patch-severity` defaults to
|
|
1474
1706
|
`low`; `high` selects high and critical findings. Use the interactive browser
|
|
1475
1707
|
to select findings and add patch instructions. Results include a `patches`
|
|
1476
1708
|
entry per finding with status `verified`, `no_change`, `blocked`, or `failed`.
|
|
1477
1709
|
Verified and already-fixed findings no longer fail `--fail-on-severity`.
|
|
1710
|
+
Patching shows each finding's position, elapsed time, and live Codex activity.
|
|
1711
|
+
Progress goes to stderr; completed results stay in the terminal history.
|
|
1478
1712
|
|
|
1479
1713
|
`--create-pr` commits generated patch files and opens a draft GitHub pull request
|
|
1480
1714
|
with `gh` or a draft GitLab merge request with `glab`. Install and authenticate
|
|
@@ -1578,6 +1812,12 @@ cancels, resumes, publishes, edits, or deduplicates anything.
|
|
|
1578
1812
|
|
|
1579
1813
|
The dashboard opens on Findings, followed by Duplicate groups. Both views
|
|
1580
1814
|
support search, repository filtering, sorting, pagination, and record details.
|
|
1815
|
+
Click any column header to sort all matching records; click it again to reverse
|
|
1816
|
+
the order. The arrow marks the active column and direction. Changing the sort
|
|
1817
|
+
returns to the first page, and automatic refreshes keep the selected order.
|
|
1818
|
+
By default, findings sort by last update descending, then severity descending,
|
|
1819
|
+
then ID ascending to break ties. Groups sort by last update descending and ID
|
|
1820
|
+
ascending.
|
|
1581
1821
|
Findings show stored content and links to their duplicate groups. Groups link
|
|
1582
1822
|
back to their member findings, preserving separate overlapping groups and the
|
|
1583
1823
|
original finding records.
|
|
@@ -1594,7 +1834,10 @@ repository choices, a page of records, and optional selected-record details:
|
|
|
1594
1834
|
|
|
1595
1835
|
- `view`: `findings` (default) or `groups`.
|
|
1596
1836
|
- `query`, `repository`: optional search text and exact repository ID.
|
|
1597
|
-
- `sort`: `activity` (default;
|
|
1837
|
+
- `sort`: `activity` (default; last update), `newest` (created), `title`,
|
|
1838
|
+
`repository`, `severity` (findings only), or `members` (groups only).
|
|
1839
|
+
- `direction`: `asc` or `desc` (default). Text sorts alphabetically without
|
|
1840
|
+
case sensitivity, severity by level, and member counts numerically.
|
|
1598
1841
|
- `limit`, `offset`: existing pagination conventions, defaulting to 50 and 0.
|
|
1599
1842
|
- `id`: optional exact record ID to include in `detail`; unknown IDs return
|
|
1600
1843
|
`detail: null` without hiding the list.
|
|
@@ -1721,7 +1964,7 @@ console.log(receipt.repositoryId, receipt.findingIds);
|
|
|
1721
1964
|
Publish the scan with `--to custom` (or import it through the bulk API with its
|
|
1722
1965
|
`repositoryId`) before deduplicating. The
|
|
1723
1966
|
workflow reads a completed saved scan, queries candidates by finding ID, and
|
|
1724
|
-
runs Luna and Sol in the calling SDK/CLI process. Once all reviews
|
|
1967
|
+
runs Luna and Sol in the calling SDK/CLI process. Once all reviews finish,
|
|
1725
1968
|
it posts accepted groups to the service. It does not re-upload findings or
|
|
1726
1969
|
change scan artifacts.
|
|
1727
1970
|
|
|
@@ -1742,7 +1985,14 @@ has finished and none voted `DISTINCT`. It can run while unrelated Luna
|
|
|
1742
1985
|
screenings continue. Results are combined in input order so completion timing
|
|
1743
1986
|
does not change the groups.
|
|
1744
1987
|
|
|
1745
|
-
|
|
1988
|
+
An explicit model refusal keeps the affected pairs separate and allows unrelated
|
|
1989
|
+
reviews to continue. It is recorded as `NO_DECISION`, not a reviewed `DISTINCT`
|
|
1990
|
+
verdict. A screening refusal applies to every anchor/candidate pair in that
|
|
1991
|
+
screening; a pair-review refusal applies only to its assigned pair. Neither pair
|
|
1992
|
+
can be merged indirectly through other findings. Recognized policy errors and
|
|
1993
|
+
explicit refusal responses are not retried or sent to another model.
|
|
1994
|
+
|
|
1995
|
+
If another kind of job fails after its retries, queued jobs stop and already running jobs
|
|
1746
1996
|
finish before the command reports the failure. No groups are posted from an
|
|
1747
1997
|
incomplete review. To retain completed reviews across runs, use a
|
|
1748
1998
|
`--workflow-id` as described below.
|
|
@@ -1806,6 +2056,19 @@ has the highest reported severity; ties use finding ID. Results do not delete,
|
|
|
1806
2056
|
merge, or change stored finding documents. Accepted groups are saved as durable
|
|
1807
2057
|
associations in the service before `deduplicationStatus` becomes `completed`.
|
|
1808
2058
|
|
|
2059
|
+
When any review is refused, the result instead has
|
|
2060
|
+
`deduplicationStatus: "completed_with_refusals"` and a `refusals` array. Each
|
|
2061
|
+
entry contains `decision: "NO_DECISION"`, `stage`, `model`, `findingIds`, and
|
|
2062
|
+
`reason`. For screening, the first finding ID is the anchor and the remaining
|
|
2063
|
+
IDs are its candidates. The CLI logs each refusal to stderr and exits
|
|
2064
|
+
successfully after saving the accepted groups. SDK callers can inspect and log
|
|
2065
|
+
the same structured entries. Findings retained because of a refusal are not
|
|
2066
|
+
confirmed unique. Successful runs without refusals keep their existing output
|
|
2067
|
+
shape. No command, flag, or default changes are required.
|
|
2068
|
+
|
|
2069
|
+
This behavior applies to post-scan Luna/Sol deduplication. Deep Scan's internal
|
|
2070
|
+
reducer uses a separate workflow.
|
|
2071
|
+
|
|
1809
2072
|
### Stored duplicate groups
|
|
1810
2073
|
|
|
1811
2074
|
`POST /v1/dedupe-groups` accepts a batch of explicitly reviewed member sets:
|
|
@@ -1907,10 +2170,16 @@ exponential backoff with jitter; HTTP retries honor `Retry-After`. Waiting to re
|
|
|
1907
2170
|
occupies the job's concurrency slot.
|
|
1908
2171
|
|
|
1909
2172
|
Cancellation, authentication or configuration errors, permanent HTTP errors, and
|
|
1910
|
-
required-source-access blockers are not retried.
|
|
2173
|
+
required-source-access blockers are not retried. Model refusals continue with
|
|
2174
|
+
`NO_DECISION` as described above. Other exhausted retries fail deduplication;
|
|
1911
2175
|
invalid or unfinished reviews are not cached. Completed checkpoints remain
|
|
1912
2176
|
available when the workflow resumes.
|
|
1913
2177
|
|
|
2178
|
+
Refusals are not saved as validated review checkpoints. A completed workflow
|
|
2179
|
+
retains its final `completed_with_refusals` result, including all refusal entries,
|
|
2180
|
+
and returns it on subsequent calls. To attempt those reviews again after
|
|
2181
|
+
resolving the refusal, run dedupe without that workflow ID or with a new one.
|
|
2182
|
+
|
|
1914
2183
|
Checkpoints bind to the exact original records and ordering, approved source path,
|
|
1915
2184
|
Git revision and current file contents (including ignored files), repository scope,
|
|
1916
2185
|
model and reasoning settings, Codex configuration and version, and prompt/contract version. Changed
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|