@openai/codex-security 0.4.0 → 0.5.0
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 +45 -9
- package/_bundled_plugin/.mcp.json +1 -0
- package/_bundled_plugin/mcp/helpers.mjs.br.part-000 +0 -0
- 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/core-scan.md +2 -0
- package/_bundled_plugin/references/final-report.md +5 -1
- package/_bundled_plugin/references/investigation-time-budget.md +11 -0
- package/_bundled_plugin/references/sarif-adapter.md +1 -0
- package/_bundled_plugin/references/scan-prologue.md +2 -6
- package/_bundled_plugin/references/scan-runtime.md +15 -0
- package/_bundled_plugin/references/threat-model.md +2 -0
- package/_bundled_plugin/schemas/definitions/artifact-common.schema.json +5 -1
- package/_bundled_plugin/scripts/deep_scan_workbench.py +7 -0
- package/_bundled_plugin/scripts/finalize_scan_contract.py +80 -43
- package/_bundled_plugin/scripts/finding_preview.py +5 -3
- package/_bundled_plugin/scripts/generate_rank_input.py +1 -0
- package/_bundled_plugin/scripts/launch_codex_security_mcp +39 -4
- package/_bundled_plugin/scripts/snapshot_sqlite.py +7 -0
- package/_bundled_plugin/scripts/windows_scan_local_files.py +43 -1
- package/_bundled_plugin/scripts/workbench_cli.py +0 -3
- package/_bundled_plugin/scripts/workbench_constants.py +4 -0
- package/_bundled_plugin/scripts/workbench_db.py +56 -33
- package/_bundled_plugin/scripts/workbench_progress.py +0 -50
- package/_bundled_plugin/scripts/workbench_scan_history.py +3 -2
- package/_bundled_plugin/scripts/workbench_scan_start.py +12 -4
- package/_bundled_plugin/scripts/workbench_scan_usage.py +190 -30
- package/_bundled_plugin/scripts/workbench_schema.py +1 -1
- package/_bundled_plugin/scripts/workbench_source_excerpt.py +74 -51
- package/_bundled_plugin/scripts/workbench_source_scopes.py +388 -0
- package/_bundled_plugin/scripts/workbench_target.py +7 -5
- package/_bundled_plugin/scripts/workbench_validation.py +37 -1
- package/_bundled_plugin/shared/workbench-history-repairs.json +19 -0
- package/_bundled_plugin/shared/workbench-migrations.json +5 -0
- package/_bundled_plugin/skills/deep-security-scan/SKILL.md +1 -1
- package/_bundled_plugin/skills/security-diff-scan/SKILL.md +4 -2
- package/_bundled_plugin/skills/security-scan/SKILL.md +3 -1
- package/_bundled_plugin/skills/security-scan/references/desktop-scan.md +2 -2
- package/dist/api.d.ts +3 -2
- package/dist/api.d.ts.map +1 -1
- package/dist/api.js +54 -36
- package/dist/api.js.map +1 -1
- package/dist/artifact-export.d.ts +2 -1
- package/dist/artifact-export.d.ts.map +1 -1
- package/dist/artifact-export.js +38 -23
- package/dist/artifact-export.js.map +1 -1
- package/dist/classify-severity-records.d.ts +76 -0
- package/dist/classify-severity-records.d.ts.map +1 -0
- package/dist/classify-severity-records.js +141 -0
- package/dist/classify-severity-records.js.map +1 -0
- package/dist/classify-severity.d.ts +1 -23
- package/dist/classify-severity.d.ts.map +1 -1
- package/dist/classify-severity.js +3 -24
- package/dist/classify-severity.js.map +1 -1
- package/dist/cli-help.d.ts.map +1 -1
- package/dist/cli-help.js +2 -0
- package/dist/cli-help.js.map +1 -1
- package/dist/cli.d.ts +4 -2
- package/dist/cli.d.ts.map +1 -1
- package/dist/cli.js +136 -147
- package/dist/cli.js.map +1 -1
- package/dist/cloud-publish.js +1 -1
- package/dist/cloud-publish.js.map +1 -1
- package/dist/codex-sdk-environment.js +1 -1
- package/dist/codex-sdk-environment.js.map +1 -1
- package/dist/config.d.ts +12 -0
- package/dist/config.d.ts.map +1 -1
- package/dist/config.js +10 -4
- package/dist/config.js.map +1 -1
- package/dist/contract.d.ts +5 -0
- package/dist/contract.d.ts.map +1 -1
- package/dist/contract.js +65 -17
- package/dist/contract.js.map +1 -1
- package/dist/cost-model.d.ts.map +1 -1
- package/dist/cost-model.js +7 -2
- package/dist/cost-model.js.map +1 -1
- package/dist/custom-validation-prompt.js +3 -3
- package/dist/custom-validation-prompt.js.map +1 -1
- package/dist/deduplication/deduplication-prompts.d.ts +1 -1
- package/dist/deduplication/deduplication-prompts.d.ts.map +1 -1
- package/dist/deduplication/deduplication-prompts.js +2 -2
- package/dist/deduplication/deduplication-prompts.js.map +1 -1
- package/dist/deduplication/records.js +1 -1
- package/dist/deduplication/records.js.map +1 -1
- package/dist/deduplication/scan.d.ts.map +1 -1
- package/dist/deduplication/scan.js +10 -9
- package/dist/deduplication/scan.js.map +1 -1
- package/dist/deep-config.d.ts +4 -1
- package/dist/deep-config.d.ts.map +1 -1
- package/dist/deep-config.js +21 -1
- package/dist/deep-config.js.map +1 -1
- package/dist/findings-import.d.ts +1 -1
- package/dist/findings-import.d.ts.map +1 -1
- package/dist/findings-import.js +3 -3
- package/dist/findings-import.js.map +1 -1
- package/dist/git-remote.d.ts +10 -0
- package/dist/git-remote.d.ts.map +1 -0
- package/dist/git-remote.js +24 -0
- package/dist/git-remote.js.map +1 -0
- package/dist/github.d.ts.map +1 -1
- package/dist/github.js +5 -7
- package/dist/github.js.map +1 -1
- package/dist/host-protocol.js +1 -1
- package/dist/host-protocol.js.map +1 -1
- package/dist/host-records-protocol.d.ts +15 -0
- package/dist/host-records-protocol.d.ts.map +1 -0
- package/dist/host-records-protocol.js +15 -0
- package/dist/host-records-protocol.js.map +1 -0
- package/dist/hosted-scan.d.ts +1 -6
- package/dist/hosted-scan.d.ts.map +1 -1
- package/dist/hosted-scan.js +2 -2
- package/dist/hosted-scan.js.map +1 -1
- package/dist/index.d.ts +4 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +2 -0
- package/dist/index.js.map +1 -1
- package/dist/knowledge-base.d.ts.map +1 -1
- package/dist/knowledge-base.js +87 -7
- package/dist/knowledge-base.js.map +1 -1
- package/dist/multiscan.d.ts.map +1 -1
- package/dist/multiscan.js +62 -28
- package/dist/multiscan.js.map +1 -1
- package/dist/patch-publication.d.ts +26 -0
- package/dist/patch-publication.d.ts.map +1 -0
- package/dist/patch-publication.js +105 -0
- package/dist/patch-publication.js.map +1 -0
- package/dist/patch-tui.d.ts.map +1 -1
- package/dist/patch-tui.js +4 -1
- package/dist/patch-tui.js.map +1 -1
- package/dist/project-config-schema.d.ts +2 -0
- package/dist/project-config-schema.d.ts.map +1 -1
- package/dist/project-config-schema.js +1 -0
- package/dist/project-config-schema.js.map +1 -1
- package/dist/project-config.d.ts +1 -0
- package/dist/project-config.d.ts.map +1 -1
- package/dist/project-config.js +16 -6
- package/dist/project-config.js.map +1 -1
- package/dist/publication.d.ts.map +1 -1
- package/dist/publication.js +135 -19
- package/dist/publication.js.map +1 -1
- package/dist/publish.d.ts.map +1 -1
- package/dist/publish.js +39 -25
- package/dist/publish.js.map +1 -1
- package/dist/runtime.d.ts.map +1 -1
- package/dist/runtime.js +83 -22
- package/dist/runtime.js.map +1 -1
- package/dist/scan-settings.d.ts +1 -0
- package/dist/scan-settings.d.ts.map +1 -1
- package/dist/scan-settings.js +7 -1
- package/dist/scan-settings.js.map +1 -1
- package/dist/scan-time-budget.d.ts +9 -0
- package/dist/scan-time-budget.d.ts.map +1 -0
- package/dist/scan-time-budget.js +16 -0
- package/dist/scan-time-budget.js.map +1 -0
- package/dist/severity-review.d.ts +29 -0
- package/dist/severity-review.d.ts.map +1 -0
- package/dist/severity-review.js +47 -0
- package/dist/severity-review.js.map +1 -0
- package/dist/validation-records.d.ts +38 -0
- package/dist/validation-records.d.ts.map +1 -0
- package/dist/validation-records.js +76 -0
- package/dist/validation-records.js.map +1 -0
- package/dist/version.d.ts.map +1 -1
- package/dist/version.js +4 -2
- package/dist/version.js.map +1 -1
- package/dist/worker-progress.d.ts +2 -6
- package/dist/worker-progress.d.ts.map +1 -1
- package/dist/worker-progress.js +1 -43
- package/dist/worker-progress.js.map +1 -1
- package/docs/classify-severity-records.md +89 -0
- package/docs/cli.md +269 -33
- package/docs/validate-records.md +69 -0
- package/package.json +12 -10
- package/schemas/project-config.schema.json +7 -1
- package/_bundled_plugin/preflight/capability-profiles.toml +0 -76
- package/_bundled_plugin/references/config-preflight.md +0 -93
- package/_bundled_plugin/references/desktop-config-preflight.md +0 -11
- package/_bundled_plugin/scripts/config_preflight.py +0 -911
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
# Classify canonical records with host-provided execution
|
|
2
|
+
|
|
3
|
+
`codex-security classify-severity --records` accepts canonical reports without a
|
|
4
|
+
repository, saved scan, synthetic provenance, local Codex login, or filesystem
|
|
5
|
+
state. It uses the same bidirectional JSON-RPC transport as [record deduplication](dedupe-records.md).
|
|
6
|
+
Use `--records` alone; saved-scan classification remains unchanged.
|
|
7
|
+
|
|
8
|
+
The SDK exports `classifySeverityRecords`, `classifySeverityRecordsInputSchema`,
|
|
9
|
+
and their input, result, and review-request types. The protocol and input have
|
|
10
|
+
version `1`. This is an additive capability: pin an artifact containing this
|
|
11
|
+
implementation until it is included in a published release. A prior CLI that does
|
|
12
|
+
not advertise `--records` in `classify-severity --help` cannot run this protocol.
|
|
13
|
+
|
|
14
|
+
## Immutable inputs
|
|
15
|
+
|
|
16
|
+
Send one newline-delimited JSON-RPC request with `method: "run"` and these params:
|
|
17
|
+
|
|
18
|
+
```ts
|
|
19
|
+
{
|
|
20
|
+
version: 1,
|
|
21
|
+
rubric: { revision: 4, markdown: rubricMarkdown, sha256: rubricSha256 },
|
|
22
|
+
model: "your-authorized-model",
|
|
23
|
+
effort: "high",
|
|
24
|
+
records: [{ id: "canonical-one", revision: 7, findingJson, inputSha256 }]
|
|
25
|
+
}
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
`findingJson` is the exact JSON text of an object with nonblank `findingId`,
|
|
29
|
+
`title`, and `summary`. `findingId` must equal the canonical `id`. Optional
|
|
30
|
+
`severity.level` uses `critical`, `high`, `medium`, `low`, or `informational`.
|
|
31
|
+
Other report fields are preserved as evidence. Missing legacy titles or summaries
|
|
32
|
+
must be resolved by the caller; do not invent evidence or scan metadata.
|
|
33
|
+
|
|
34
|
+
Both hashes are lowercase SHA-256 hex of the exact UTF-8 string bytes, without
|
|
35
|
+
normalizing newlines, whitespace, Unicode, object key order, or JSON numbers.
|
|
36
|
+
Compute `inputSha256` from `findingJson`, not from its parsed/reserialized object.
|
|
37
|
+
For example, Node uses `createHash("sha256").update(text, "utf8").digest("hex")`;
|
|
38
|
+
Python uses `hashlib.sha256(text.encode("utf-8")).hexdigest()`.
|
|
39
|
+
The CLI recomputes both hashes before requesting any review. Rubric revisions are
|
|
40
|
+
positive safe integers; record revisions are nonnegative safe integers. Duplicate
|
|
41
|
+
canonical IDs and invalid records reject the entire input before host work.
|
|
42
|
+
The implementation snapshots caller input before awaiting model execution and
|
|
43
|
+
preserves the validated report JSON text verbatim in the model prompt, including
|
|
44
|
+
numeric evidence that JavaScript cannot represent exactly.
|
|
45
|
+
|
|
46
|
+
## Host execution contract
|
|
47
|
+
|
|
48
|
+
For each record the CLI emits `method: "review.run"`, with a unique request ID
|
|
49
|
+
and params containing `requestId`, `stage: "severity-classification"`, explicit
|
|
50
|
+
`model` and `effort`, `trustedInstructions`, untrusted report/rubric `prompt`, and
|
|
51
|
+
an output JSON `schema`. The host must authorize the requested model and effort,
|
|
52
|
+
create a fresh independent review context, preserve the instruction/data boundary,
|
|
53
|
+
and disable tools, repository access, browsing, and source inspection.
|
|
54
|
+
A managed-agent host can execute this request directly in its existing session
|
|
55
|
+
infrastructure; it does not need a repository checkout. The CLI does not provide
|
|
56
|
+
credentials, create sessions, or select an authentication fallback.
|
|
57
|
+
|
|
58
|
+
Reply with the same JSON-RPC ID and `result` set to the schema-conforming assessment
|
|
59
|
+
object. Do not wrap the assessment in a string or an array. An assessment contains
|
|
60
|
+
`findingId`, `decision` (`assessed` or `excluded`), normalized `level`, original
|
|
61
|
+
`rubricLabel`, `rationale`, separate `confidence`, and nullable `reviewTrigger`.
|
|
62
|
+
Excluded assessments require null level and label; assessed ones require both.
|
|
63
|
+
|
|
64
|
+
The host owns model budgets, transport limits, timeouts, and session cancellation.
|
|
65
|
+
Use the transport's `cancel` notification with the active run ID and also stop
|
|
66
|
+
any remote execution. EOF or a broken pipe means disconnection, not successful
|
|
67
|
+
completion. No review is retried automatically, including after an ambiguous
|
|
68
|
+
host execution error.
|
|
69
|
+
|
|
70
|
+
## Results and persistence
|
|
71
|
+
|
|
72
|
+
A completed result contains `version: 1`, `status: "completed"`, the rubric's
|
|
73
|
+
`revision` and `sha256`, and `assessments`. Each assessment replaces model-provided
|
|
74
|
+
`findingId` with the verified canonical `id`, `revision`, and `inputSha256`.
|
|
75
|
+
The original report and severity are never rewritten.
|
|
76
|
+
|
|
77
|
+
Invalid or mismatched model output and host failures return `status: "unresolved"`,
|
|
78
|
+
an empty `assessments` array, and an error with `recordId` and stable code
|
|
79
|
+
`invalid_assessment` or `review_failed`. Earlier assessments in that invocation
|
|
80
|
+
are discarded. Invalid input, protocol errors, and cancellation use JSON-RPC error
|
|
81
|
+
responses. Exit codes are 0 for completion, 1 for unresolved review, and 2 for
|
|
82
|
+
input/protocol failure (130/143 for SIGINT/SIGTERM).
|
|
83
|
+
|
|
84
|
+
Prefer one canonical record per workflow invocation when the host needs independent
|
|
85
|
+
retries and partial success. The host should retain immutable rubric/report
|
|
86
|
+
snapshots, compare every echoed binding, and conditionally persist only computed
|
|
87
|
+
prioritization fields if the expected canonical version and rubric still apply.
|
|
88
|
+
Keep manual edits and original severity intact. Repeating the same inputs binds
|
|
89
|
+
results to the same hashes; it does not promise deterministic model answers.
|
package/docs/cli.md
CHANGED
|
@@ -16,6 +16,13 @@ codex-security info --json
|
|
|
16
16
|
`info --json` reports package, plugin, runtime, and model details.
|
|
17
17
|
`scans` and `findings` default to their `list` subcommands.
|
|
18
18
|
|
|
19
|
+
To retrieve GitHub code scanning alerts without an MCP server, use
|
|
20
|
+
[`import github`](#import-alerts-from-the-cli). To save an existing CSV or JSON
|
|
21
|
+
findings file in local scan history, use
|
|
22
|
+
[`scan import`](#import-findings-as-a-saved-scan). These are separate workflows:
|
|
23
|
+
GitHub import returns upstream alerts for validation; file import saves findings
|
|
24
|
+
without running security analysis.
|
|
25
|
+
|
|
19
26
|
## Authentication
|
|
20
27
|
|
|
21
28
|
Sign in with ChatGPT, or supply an API key for CI:
|
|
@@ -169,6 +176,9 @@ codex-security scan . --provider openrouter --model anthropic/claude-sonnet-4.5
|
|
|
169
176
|
|
|
170
177
|
export FIREWORKS_API_KEY="<your-fireworks-api-key>"
|
|
171
178
|
codex-security scan . --provider fireworks --model accounts/fireworks/models/qwen3-235b-a22b
|
|
179
|
+
|
|
180
|
+
export CHEAPER_INFERENCE_API_KEY="<your-cheaper-inference-api-key>"
|
|
181
|
+
codex-security scan . --provider cheaperinference --model gpt-5.4
|
|
172
182
|
```
|
|
173
183
|
|
|
174
184
|
### Amazon Bedrock
|
|
@@ -354,11 +364,15 @@ SARIF), PDF, DOCX, or directories. Directory traversal skips other binary files;
|
|
|
354
364
|
explicit unsupported binary files are rejected. Bulk scans share this context
|
|
355
365
|
with every repository.
|
|
356
366
|
|
|
357
|
-
|
|
358
|
-
|
|
367
|
+
Use `--output-dir DIR` to choose where a scan saves its results. The directory
|
|
368
|
+
must be empty and outside the scanned directory and enclosing Git worktree. On
|
|
369
|
+
macOS/Linux, existing directories must be private (`chmod 700`).
|
|
359
370
|
`--archive-existing` moves earlier output to
|
|
360
371
|
`<output-dir>.previous-<timestamp>-<id>`; `--dry-run` previews the move.
|
|
361
|
-
|
|
372
|
+
|
|
373
|
+
Scans also attempt to write SARIF to `<scan-dir>/exports/results.sarif`. If that
|
|
374
|
+
optional export fails, the scan can still complete. Use the
|
|
375
|
+
[export command](#export-findings) to write or retry SARIF from the saved results.
|
|
362
376
|
|
|
363
377
|
Completed scans exit with `0` by default. Configure `--fail-on-severity high`
|
|
364
378
|
to return `1` for high or critical findings. Scope exclusions, skipped files, and follow-up notes
|
|
@@ -371,6 +385,13 @@ Legacy completeness values affect neither.
|
|
|
371
385
|
Bulk and component summaries report completed and failed scans without an
|
|
372
386
|
`incomplete` count. Component matching errors have status `failed`.
|
|
373
387
|
|
|
388
|
+
Usage coverage is separate from execution status. A recorded interruption or a
|
|
389
|
+
closed turn without a numeric usage receipt makes usage coverage `partial`, even
|
|
390
|
+
if a later turn succeeds. Recorded numeric zero is distinct from a missing
|
|
391
|
+
receipt. These checks describe available local records; they cannot reconstruct
|
|
392
|
+
requests whose usage was never persisted locally or prove an exhaustive billing
|
|
393
|
+
total.
|
|
394
|
+
|
|
374
395
|
New drafts use the current finding schema: `codeEvidence`, `rootCause`,
|
|
375
396
|
`attackPath.dataflow`, and `evidenceRefs`. Source snippets belong in
|
|
376
397
|
`codeEvidence`; `rootCause.evidenceRefs` links to them. Legacy aliases and
|
|
@@ -406,6 +427,82 @@ Diagnostics stay on stderr. Each command's `--schema --format json` describes
|
|
|
406
427
|
its successful output and failure codes.
|
|
407
428
|
See [Exports and CI](#exports-and-ci) for exit codes and CI examples.
|
|
408
429
|
|
|
430
|
+
### Understand scan scope and follow-up work
|
|
431
|
+
|
|
432
|
+
A completed scan means the requested workflow finished. It does not mean every
|
|
433
|
+
file or possible vulnerability was examined. A scan can finish with intentional
|
|
434
|
+
exclusions, deferred review work, or unanswered questions.
|
|
435
|
+
|
|
436
|
+
To investigate a particular run, use its scan ID explicitly:
|
|
437
|
+
|
|
438
|
+
```bash
|
|
439
|
+
codex-security scans show SCAN_ID --json
|
|
440
|
+
codex-security scans logs SCAN_ID
|
|
441
|
+
```
|
|
442
|
+
|
|
443
|
+
Replace `SCAN_ID` with the ID from the completion or failure summary. A scan can
|
|
444
|
+
fail after registration but before writing its artifacts; investigate those
|
|
445
|
+
failures through its history record and any available logs. When artifacts were
|
|
446
|
+
retained, use the saved results directory returned by `scans show` to inspect
|
|
447
|
+
whichever of these files are present:
|
|
448
|
+
|
|
449
|
+
| File | What to check |
|
|
450
|
+
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
451
|
+
| `scan-manifest.json` | `scan.status`, the target snapshot, and any recorded `scan.scope` limitations. |
|
|
452
|
+
| `report.md` | Scope, reviewed surfaces, and open questions or follow-up work. |
|
|
453
|
+
| `coverage.json` | `includePaths` and `excludePaths` for scope boundaries; `explicitExclusions` for recorded exclusion reasons; `surfaces` for reviewed areas; `deferred` for unfinished review work; and optional `openQuestions`. |
|
|
454
|
+
|
|
455
|
+
Deferred items can identify affected `paths` or `surfaceIds`. Surface
|
|
456
|
+
`receiptRefs` link to retained evidence under `artifacts/` when available.
|
|
457
|
+
Deep Scan summaries retain coverage from accepted worker reviews, including
|
|
458
|
+
worker-specific deferred work. Check those details as well as the final findings.
|
|
459
|
+
|
|
460
|
+
These records describe what the scan recorded, not an exhaustive file-by-file
|
|
461
|
+
audit. A retained source inventory, when present, lists inputs rather than
|
|
462
|
+
proving that each file was reviewed. An absent path in a surface summary does not
|
|
463
|
+
establish whether it was read, and the scan ID cannot reconstruct evidence that
|
|
464
|
+
was never saved.
|
|
465
|
+
Session logs can help explain failures and tool activity, but do not prove
|
|
466
|
+
complete review either.
|
|
467
|
+
|
|
468
|
+
For a local plugin scan, ask Codex to open the saved scan and explain its scope,
|
|
469
|
+
exclusions, deferred work, and follow-up questions. CLI history can also locate
|
|
470
|
+
that scan when it uses the same Codex home and state directory on the machine
|
|
471
|
+
where the scan ran. A scan ID alone does not download another machine's or
|
|
472
|
+
Cloud's artifacts. Preserve the saved results directory with the ID.
|
|
473
|
+
|
|
474
|
+
Choose the next step from the recorded reason:
|
|
475
|
+
|
|
476
|
+
- **The run completed and its scope matches your intent:** analyze the findings.
|
|
477
|
+
Record any remaining limitations; an exclusion or follow-up note alone is not
|
|
478
|
+
an execution failure.
|
|
479
|
+
- **An important path or security question remains unreviewed:** run a focused
|
|
480
|
+
scan with `--path`, adding relevant context with `--knowledge-base` or specific
|
|
481
|
+
instructions with `--scan-prompt-file`. Address missing access or context first.
|
|
482
|
+
Repeating the same scan does not guarantee that an omission will be resolved.
|
|
483
|
+
- **The run failed or was canceled:** inspect its logs and address the cause.
|
|
484
|
+
Use `scans rerun SCAN_ID` when the scan has a saved launch recipe; otherwise,
|
|
485
|
+
start a new scan with the intended scope, including for plugin scans without
|
|
486
|
+
a recipe. Retained findings can still be reviewed, but absence of findings
|
|
487
|
+
from a stopped run is inconclusive.
|
|
488
|
+
- **A Deep Scan was interrupted and is still recorded as `running`:** it may
|
|
489
|
+
support [resume](#resuming-an-interrupted-deep-scan) with the original checkout,
|
|
490
|
+
artifacts, and session. Completed, failed, and canceled scans cannot resume.
|
|
491
|
+
|
|
492
|
+
For example, after identifying an omitted API directory:
|
|
493
|
+
|
|
494
|
+
```bash
|
|
495
|
+
codex-security scan . --path services/api --knowledge-base architecture.md
|
|
496
|
+
```
|
|
497
|
+
|
|
498
|
+
Replace the path and context file with those for your repository. A new scan
|
|
499
|
+
reviews the current checkout; it does not amend the original saved report.
|
|
500
|
+
|
|
501
|
+
Older reports may still contain `coverage.completeness: "partial"` or
|
|
502
|
+
`"unknown"`. Read their scope and follow-up details to understand the limitation.
|
|
503
|
+
Current reports omit that field, and current commands do not use legacy
|
|
504
|
+
completeness values to determine scan status or exit codes.
|
|
505
|
+
|
|
409
506
|
### Project files
|
|
410
507
|
|
|
411
508
|
```bash
|
|
@@ -551,6 +648,29 @@ From TypeScript, use `runComponentScans({ repository, outputDir, components })`.
|
|
|
551
648
|
Use `auto: true`, `planOnly: true`, and `scanOptions.auth` for the corresponding
|
|
552
649
|
planning and authentication choices.
|
|
553
650
|
|
|
651
|
+
### Set investigation time
|
|
652
|
+
|
|
653
|
+
```bash
|
|
654
|
+
codex-security scan . --max-time 15
|
|
655
|
+
codex-security scan . --diff origin/main --max-time 15
|
|
656
|
+
codex-security scan . --mode deep --max-time 90
|
|
657
|
+
```
|
|
658
|
+
|
|
659
|
+
`--max-time` accepts positive fractional **minutes**. Standard scans have no
|
|
660
|
+
time allowance by default. When selected, it is advisory: spend the available
|
|
661
|
+
time on useful investigation and validation, finish early if no worthwhile work
|
|
662
|
+
remains, and stop starting investigations at the deadline. Reporting can run
|
|
663
|
+
longer. This is not a hard timeout or a minimum runtime. The allowance covers
|
|
664
|
+
repository, path, diff, and working-tree scans; standalone custom validation and
|
|
665
|
+
post-scan instructions are outside it. Existing `--max-cost` and cancellation
|
|
666
|
+
behavior are unchanged.
|
|
667
|
+
|
|
668
|
+
The SDK setting is `maxTimeMinutes`; project files use `scan.max_time_minutes`.
|
|
669
|
+
Each launched scan or rerun gets its own allowance after setup, and reconnects
|
|
670
|
+
do not reset it. Standard scans still do not support resume. For batch and
|
|
671
|
+
component scans, the project setting applies separately to each scan attempt,
|
|
672
|
+
not to planning, result matching, or the total campaign.
|
|
673
|
+
|
|
554
674
|
### Configure deep scans
|
|
555
675
|
|
|
556
676
|
```ts
|
|
@@ -561,19 +681,27 @@ await security.run("/path/to/repository", {
|
|
|
561
681
|
stopAfterNoNew: 3,
|
|
562
682
|
stopAfterConsecutiveErrors: 2,
|
|
563
683
|
maxDiscoveryRuns: 10,
|
|
564
|
-
|
|
684
|
+
maxTimeMinutes: 90,
|
|
565
685
|
});
|
|
566
686
|
```
|
|
567
687
|
|
|
568
688
|
For `scan --mode deep`, `--workers` controls discovery concurrency and
|
|
569
689
|
`--subagents` controls subagents per worker. `--stop-after-no-new`,
|
|
570
|
-
`--max-discovery-runs`, and `--max-time
|
|
690
|
+
`--max-discovery-runs`, and `--max-time` stop discovery by novelty, count,
|
|
571
691
|
or duration. At the deadline, discovery stops; the scan then combines and returns
|
|
572
692
|
completed findings.
|
|
573
693
|
|
|
574
694
|
Use project-file `scan.deep` settings or legacy
|
|
575
695
|
`$CODEX_HOME/codex-security/config.toml` defaults. Counts must be positive except
|
|
576
|
-
that `subagents` can be zero.
|
|
696
|
+
that `subagents` can be zero. Discovery time accepts positive fractional minutes;
|
|
697
|
+
its default and maximum remain 5760 minutes (96 hours). Unlike Standard's
|
|
698
|
+
advisory allowance, this existing Deep discovery limit is enforced. Resuming a
|
|
699
|
+
Deep scan keeps its original deadline; rerunning starts a new scan.
|
|
700
|
+
`--max-time-hours`, SDK `maxTimeHours`, project `scan.deep.max_time_hours`, and
|
|
701
|
+
legacy TOML `deep_scan.max_time_hours` remain deprecated Deep-only aliases in
|
|
702
|
+
hours. Explicit settings override lower-priority configuration across units.
|
|
703
|
+
At the winning source, conflicting minute/hour durations are errors; equivalent
|
|
704
|
+
durations are accepted.
|
|
577
705
|
`stopAfterConsecutiveErrors` is an SDK/project-file setting, with no CLI flag.
|
|
578
706
|
`--codex` does not configure deep-scan settings. See
|
|
579
707
|
[Deep settings and limits](https://github.com/openai/codex-security/blob/main/docs/project-configuration.md#deep-settings-and-limits).
|
|
@@ -709,10 +837,24 @@ Finish older-version operations before upgrading. Never remove
|
|
|
709
837
|
`.codex-security-scan.sqlite3` during an operation. Stop all operations using the
|
|
710
838
|
credential home before manually removing an old `.codex-security-scan.lock`.
|
|
711
839
|
|
|
712
|
-
On Windows,
|
|
713
|
-
ancestor
|
|
714
|
-
|
|
715
|
-
|
|
840
|
+
On Windows, credential-home checks require trusted ownership and permissions
|
|
841
|
+
through every ancestor, including the volume root. Codex Security can repair
|
|
842
|
+
the credential home and its descendants; it does not change ancestor ownership
|
|
843
|
+
or ACLs. An error identifies the rejected ancestor and its underlying ACL
|
|
844
|
+
problem. A volume root owned by `Everyone` (`S-1-1-0`) is unsupported, even when
|
|
845
|
+
the credential home itself is private.
|
|
846
|
+
|
|
847
|
+
Preserve existing state, then choose a private `CODEX_SECURITY_STATE_DIR` outside
|
|
848
|
+
the rejected ancestor and the repository, with a full ancestor chain that passes
|
|
849
|
+
the same checks. If the volume root is rejected, another directory on that
|
|
850
|
+
volume cannot resolve it; use a separately provisioned volume with trusted
|
|
851
|
+
ancestry. Temporary bootstrap homes also need trusted ancestry: set `TEMP` and
|
|
852
|
+
`TMP` to a private directory on that volume before launching the CLI. Do not
|
|
853
|
+
change the system volume's owner or ACL to make a scan run. If no suitable
|
|
854
|
+
location is available, this layout cannot provision credentials safely under
|
|
855
|
+
the current checks. Sign in again if needed; a new state directory has separate
|
|
856
|
+
scan history and does not migrate credentials or reports from the old state
|
|
857
|
+
directory.
|
|
716
858
|
|
|
717
859
|
### Progress and cost
|
|
718
860
|
|
|
@@ -726,6 +868,19 @@ input. Missing cache-write usage makes the uncached/cache-write breakdown
|
|
|
726
868
|
unavailable. The CLI cannot recover missing information already recorded as zero
|
|
727
869
|
by the runtime.
|
|
728
870
|
|
|
871
|
+
Completed scan history also saves rollout observations under `usage`, alongside
|
|
872
|
+
any `cost` estimate. `byRole` separates parent tokens from combined worker tokens.
|
|
873
|
+
`window` bounds the counted events, `observedAt` records collection time, and
|
|
874
|
+
`tokensUpdatedAt` records the newest token receipt. Partial coverage means some
|
|
875
|
+
work could not be measured, including in-flight turns or missing earlier attempts.
|
|
876
|
+
The parent can continue after report completion, so final CLI tokens can exceed
|
|
877
|
+
the saved measurement window.
|
|
878
|
+
|
|
879
|
+
`usage.accountRateLimits` saves the latest observed account-wide readings with
|
|
880
|
+
their own timestamps, window durations, and reset times. These are historical
|
|
881
|
+
observations, not a live allowance check or scan-only consumption. Empty readings
|
|
882
|
+
mean allowance was unavailable. There is no token-to-allowance conversion here.
|
|
883
|
+
|
|
729
884
|
Cost displays use [standard API prices](https://developers.openai.com/api/docs/pricing)
|
|
730
885
|
and show a short/long-context range. They estimate model usage, excluding other
|
|
731
886
|
tiers, fees, surcharges, and account-specific pricing. They do not measure ChatGPT
|
|
@@ -858,6 +1013,10 @@ Concurrency defaults to four repositories. `--max-attempts` defaults to one
|
|
|
858
1013
|
attempt per pending repository per invocation. Repeating the command continues
|
|
859
1014
|
the campaign, skips completed results, and starts pending attempts. Occupied
|
|
860
1015
|
attempt directories stop that repository and suggest `--recover`.
|
|
1016
|
+
Completed results are skipped only when their saved contract and seal are valid
|
|
1017
|
+
and the manifest records a completed scan. Damaged or unsuccessful results get a
|
|
1018
|
+
new attempt, including with `--recover`, while the old artifacts remain available.
|
|
1019
|
+
Missing or invalid plugin schemas stop resume without starting another scan.
|
|
861
1020
|
Changes to project configuration, extracted knowledge-base text, staged document
|
|
862
1021
|
filenames, direct Codex overrides, or explicit `--plugin-path`/`--python` selections
|
|
863
1022
|
require a new output directory. Version 1 manifests also require a new directory
|
|
@@ -1059,7 +1218,11 @@ codex-security classify-severity --scan latest --rubric /path/to/policy.md --jso
|
|
|
1059
1218
|
codex-security classify-severity --scan-dir /path/to/completed-scan --json
|
|
1060
1219
|
```
|
|
1061
1220
|
|
|
1062
|
-
|
|
1221
|
+
For repository-free canonical records, use `classify-severity --records` alone.
|
|
1222
|
+
The [records protocol](classify-severity-records.md) accepts immutable Markdown and
|
|
1223
|
+
report snapshots and delegates model execution to the host.
|
|
1224
|
+
|
|
1225
|
+
For saved findings, use exactly one of `--scan` (ID, prefix, or `latest`) and `--scan-dir`.
|
|
1063
1226
|
Omitting `--rubric` inherits original severity without model calls. Rubrics and
|
|
1064
1227
|
repeatable `--knowledge-base` context accept text, PDF, DOCX, and directories.
|
|
1065
1228
|
Each finding is classified in a separate read-only turn using its report and
|
|
@@ -1381,31 +1544,80 @@ Progress callback failures do not stop matching.
|
|
|
1381
1544
|
|
|
1382
1545
|
## Exports and CI
|
|
1383
1546
|
|
|
1384
|
-
|
|
1385
|
-
|
|
1386
|
-
|
|
1387
|
-
|
|
1388
|
-
|
|
1547
|
+
Export saved findings and threat models without rerunning a scan or signing in.
|
|
1548
|
+
|
|
1549
|
+
### Export findings
|
|
1550
|
+
|
|
1551
|
+
To save a completed scan's findings as SARIF, run:
|
|
1552
|
+
|
|
1553
|
+
```bash
|
|
1554
|
+
codex-security export /path/to/scan-results --output results.sarif
|
|
1555
|
+
```
|
|
1556
|
+
|
|
1557
|
+
Replace `/path/to/scan-results` with the results directory printed by `scan`.
|
|
1558
|
+
The command writes `results.sarif` in the current directory. The output directory
|
|
1559
|
+
must already exist.
|
|
1560
|
+
|
|
1561
|
+
SARIF is the default format, and `./results.sarif` is the default output path.
|
|
1562
|
+
Use `--export-format json` or `--export-format csv` to choose another format.
|
|
1563
|
+
To select a saved scan by its ID and export JSON, run:
|
|
1389
1564
|
|
|
1390
1565
|
```bash
|
|
1391
1566
|
codex-security export --scan SCAN_ID --export-format json --output findings.json
|
|
1392
|
-
codex-security export --artifact threat-model --output docs/threatmodel.md
|
|
1393
|
-
codex-security export /path/to/policy-results --artifact threat-model --output -
|
|
1394
1567
|
```
|
|
1395
1568
|
|
|
1396
|
-
|
|
1397
|
-
|
|
1398
|
-
|
|
1399
|
-
|
|
1400
|
-
|
|
1401
|
-
|
|
1569
|
+
Replace `SCAN_ID` with the ID printed by `scan`. If you omit both the results
|
|
1570
|
+
directory and `--scan`, `export` uses the current repository's latest completed
|
|
1571
|
+
scan.
|
|
1572
|
+
|
|
1573
|
+
JSON preserves the saved findings. CSV marks them open, omits local triage state,
|
|
1574
|
+
and retains distinct occurrence IDs. It escapes spreadsheet-formula prefixes and
|
|
1575
|
+
leading apostrophes; import removes the escape. Use JSON to recover ambiguous
|
|
1576
|
+
apostrophes from older CSV exports.
|
|
1577
|
+
|
|
1578
|
+
For SARIF, `--source-root` adds source-line fingerprints that help tools match
|
|
1579
|
+
findings across scans. Before changing the scanned files or applying patches,
|
|
1580
|
+
run the export from the scanned repository's root:
|
|
1581
|
+
|
|
1582
|
+
```bash
|
|
1583
|
+
codex-security export /path/to/scan-results --source-root . --output results.sarif
|
|
1584
|
+
```
|
|
1585
|
+
|
|
1586
|
+
The `.` selects the current directory as the source root. Its source files must
|
|
1587
|
+
be unchanged since the scan. `--source-root` is supported only for SARIF.
|
|
1588
|
+
|
|
1589
|
+
If export fails, it exits with `2`. Fix the reported error and rerun the export;
|
|
1590
|
+
the saved scan remains available, so you don't need to run another scan.
|
|
1591
|
+
|
|
1592
|
+
### Export a threat model
|
|
1593
|
+
|
|
1594
|
+
To save a scan's threat model as Markdown, run:
|
|
1595
|
+
|
|
1596
|
+
```bash
|
|
1597
|
+
codex-security export --scan SCAN_ID --artifact threat-model --output threatmodel.md
|
|
1598
|
+
```
|
|
1599
|
+
|
|
1600
|
+
Threat-model exports default to `./threatmodel.md`. Standard, Deep, Diff, and
|
|
1601
|
+
policy workflows retain models when available; component/bulk runs save one per
|
|
1602
|
+
child. With an explicit results directory, you can export a saved threat model
|
|
1603
|
+
even if the workflow has not completed or later failed. Missing models return
|
|
1604
|
+
an error rather than generating or substituting one. Historical models in sealed
|
|
1605
|
+
scans need a matching manifest digest.
|
|
1606
|
+
|
|
1607
|
+
To print a policy workflow's saved threat model, pass its results directory and
|
|
1608
|
+
`--output -`:
|
|
1609
|
+
|
|
1610
|
+
```bash
|
|
1611
|
+
codex-security export /path/to/policy-results --artifact threat-model --output -
|
|
1612
|
+
```
|
|
1402
1613
|
|
|
1403
1614
|
`--output -` emits only artifact content, with diagnostics on stderr. Markdown
|
|
1404
1615
|
and CSV stdout cannot combine with JSON command output. Exporting into a checkout
|
|
1405
1616
|
does not make the model scan input; pass it with `--knowledge-base`.
|
|
1406
1617
|
|
|
1407
|
-
|
|
1408
|
-
|
|
1618
|
+
### Export with the SDK
|
|
1619
|
+
|
|
1620
|
+
Use `exportArtifact()` to export saved results from TypeScript:
|
|
1409
1621
|
|
|
1410
1622
|
```ts
|
|
1411
1623
|
import { exportArtifact } from "@openai/codex-security";
|
|
@@ -1422,12 +1634,12 @@ Use `artifact: "findings"` with `format: "csv" | "json" | "sarif"` for findings.
|
|
|
1422
1634
|
`output: "-"` streams stdout and returns null path/provenance. `pythonPath`
|
|
1423
1635
|
selects an interpreter; `signal` cancels.
|
|
1424
1636
|
|
|
1425
|
-
|
|
1426
|
-
|
|
1427
|
-
leading apostrophes; import removes the escape. Use JSON to recover ambiguous
|
|
1428
|
-
apostrophes from older CSV exports.
|
|
1637
|
+
`ScanResult.threatModel` and `threatModelPath` expose the retained model and
|
|
1638
|
+
document, or null. Export still works if the document could not be written.
|
|
1429
1639
|
|
|
1430
|
-
|
|
1640
|
+
### Use exports in CI
|
|
1641
|
+
|
|
1642
|
+
Save each scan's results outside the checkout and set a severity threshold:
|
|
1431
1643
|
|
|
1432
1644
|
```bash
|
|
1433
1645
|
SCAN_ROOT="$(mktemp -d)"
|
|
@@ -1443,6 +1655,21 @@ codex-security scan . --diff origin/main \
|
|
|
1443
1655
|
| `2` | Invalid input, runtime error, target change, or required-output failure. |
|
|
1444
1656
|
| `130` / `143` | Interrupt / termination. |
|
|
1445
1657
|
|
|
1658
|
+
If the scan exits with `2`, `130`, or `143`, skip export and upload. After a scan
|
|
1659
|
+
exits with `0` or `1`, use these steps:
|
|
1660
|
+
|
|
1661
|
+
1. Export from that run's results directory. Using the explicit directory keeps
|
|
1662
|
+
concurrent scans from changing which results are selected:
|
|
1663
|
+
|
|
1664
|
+
```bash
|
|
1665
|
+
codex-security export "$SCAN_ROOT/results" --source-root . \
|
|
1666
|
+
--output "$SCAN_ROOT/results.sarif"
|
|
1667
|
+
```
|
|
1668
|
+
|
|
1669
|
+
2. If export succeeds, upload the SARIF file.
|
|
1670
|
+
3. If the scan exited with `1`, keep the CI job failed so the severity threshold
|
|
1671
|
+
remains enforced.
|
|
1672
|
+
|
|
1446
1673
|
JSON scans have no interactive controls. `validate`, `login`, and `logout` reject
|
|
1447
1674
|
`--json`. Use `validate --output-schema FILE` for a schema-checked JSON assessment.
|
|
1448
1675
|
For GitHub Actions setup, see the
|
|
@@ -1530,6 +1757,10 @@ The token needs code-scanning read access; access failures reject the import.
|
|
|
1530
1757
|
|
|
1531
1758
|
## Validate and patch findings
|
|
1532
1759
|
|
|
1760
|
+
Hosts that manage their own model execution can use `codex-security validate --records`.
|
|
1761
|
+
This mode exchanges a review over JSON-RPC and checks the returned answer against a caller-provided schema.
|
|
1762
|
+
See [host-provided standalone validation](validate-records.md) for the protocol and execution requirements.
|
|
1763
|
+
|
|
1533
1764
|
`validate` assesses candidates from local source evidence without building the
|
|
1534
1765
|
target, executing application code, running tests or PoCs, or contacting services.
|
|
1535
1766
|
It uses a read-only sandbox. Standard, Deep, and diff scans retain their existing
|
|
@@ -1657,6 +1888,8 @@ Both candidate IDs remain in the output, including the unresolved claim.
|
|
|
1657
1888
|
`--scan latest` uses the current repository's latest completed scan. Patching
|
|
1658
1889
|
supports JSON for saved findings, literal text, and files. Each finding gets a
|
|
1659
1890
|
saved Codex desktop task. `--model` and `--effort` control the model.
|
|
1891
|
+
Saved-scan patching and fix verification use the complete sealed finding evidence
|
|
1892
|
+
and exclude findings that are currently closed in triage.
|
|
1660
1893
|
|
|
1661
1894
|
`--validation-prompt-file PATH` supplies setup, authorized targets, expected
|
|
1662
1895
|
results, and cleanup for dynamic validation. It works with saved findings,
|
|
@@ -1737,8 +1970,11 @@ Use `--llms` for the command manifest, `scan --schema --format json` for its
|
|
|
1737
1970
|
schema, and `completions bash|zsh|fish` for shell completions. Scan output supports
|
|
1738
1971
|
`--format toon|json|yaml|jsonl` and `--full-output`.
|
|
1739
1972
|
|
|
1740
|
-
`skills add` syncs
|
|
1741
|
-
|
|
1973
|
+
`skills add` syncs generated CLI command guidance; it does not install the full
|
|
1974
|
+
Codex Security plugin. `mcp add` registers the CLI as an MCP server, exposing
|
|
1975
|
+
only read-only `info` because the transport cannot cancel scans. For the plugin's
|
|
1976
|
+
scan, triage, patch, and verification workflows, see the
|
|
1977
|
+
[agent workflow guide](https://github.com/openai/codex-security/blob/main/docs/agent-workflows.md).
|
|
1742
1978
|
|
|
1743
1979
|
For local findings storage, deduplication, and custom endpoints, see the
|
|
1744
1980
|
[findings guide](findings-service.md).
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
# Host-provided standalone validation (protocol v1)
|
|
2
|
+
|
|
3
|
+
Run `codex-security validate --records` with that flag alone. It uses the
|
|
4
|
+
standalone validation instructions to assess existing findings against source
|
|
5
|
+
evidence. The host runs the model; the CLI does not start Codex, authenticate,
|
|
6
|
+
read scan history, or save results. Existing `validate` commands are unchanged.
|
|
7
|
+
|
|
8
|
+
Use the same JSON-RPC transport as [records deduplication](dedupe-records.md):
|
|
9
|
+
one JSON object per line, one `run` request, and `review.run` requests answered
|
|
10
|
+
by the host. Keep stdin open until the final response. Cancellation, disconnects,
|
|
11
|
+
and host errors terminate the invocation without retrying the review.
|
|
12
|
+
|
|
13
|
+
The `run` request's `params` has this shape:
|
|
14
|
+
|
|
15
|
+
```json
|
|
16
|
+
{
|
|
17
|
+
"version": 1,
|
|
18
|
+
"findings": [
|
|
19
|
+
{
|
|
20
|
+
"id": "finding-1",
|
|
21
|
+
"finding": { "title": "Example candidate", "evidence": "..." }
|
|
22
|
+
}
|
|
23
|
+
],
|
|
24
|
+
"context": "Optional deployment facts or reviewer feedback.",
|
|
25
|
+
"knowledgeBasePath": "/validation/context",
|
|
26
|
+
"outputSchema": {
|
|
27
|
+
"type": "object",
|
|
28
|
+
"properties": { "rationale": { "type": "string" } },
|
|
29
|
+
"required": ["rationale"],
|
|
30
|
+
"additionalProperties": false
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
Provide at least one finding with a unique, nonempty host ID. The `finding`
|
|
36
|
+
value preserves the caller's candidate format. Supply enough source locations
|
|
37
|
+
and evidence to assess it. `context` and `knowledgeBasePath` are optional.
|
|
38
|
+
The directory must already exist in the host's review environment; this mode
|
|
39
|
+
does not copy files. Context and notes are evidence to check against source,
|
|
40
|
+
not instructions or automatic dismissal rules.
|
|
41
|
+
|
|
42
|
+
`outputSchema` is required. It controls the returned structured answer; it does
|
|
43
|
+
not define a standard disposition or product status model. The host must verify
|
|
44
|
+
finding ID coverage and any application-specific conditions before changing
|
|
45
|
+
published findings. Optional `model` and `effort` override the SDK's default
|
|
46
|
+
model configuration. Local configuration files and CLI model flags are not read.
|
|
47
|
+
|
|
48
|
+
The CLI emits one `review.run` request containing `requestId`, `model`, `effort`,
|
|
49
|
+
`trustedInstructions`, `prompt`, and `schema`. The host supplies the authorized
|
|
50
|
+
source checkout and context directory, executes the review, and returns its
|
|
51
|
+
structured answer. The CLI checks that answer against `outputSchema` before
|
|
52
|
+
returning `{ "status": "completed", "result": <assessment> }` as the final
|
|
53
|
+
JSON-RPC `result`. Success exits with code 0; invalid input, invalid output, or
|
|
54
|
+
execution failure exits with code 2. SIGINT and SIGTERM
|
|
55
|
+
retain exit codes 130 and 143.
|
|
56
|
+
|
|
57
|
+
The host owns repository authorization, credentials, model accounting,
|
|
58
|
+
cancellation of remote work, and cleanup. It selects and enforces the review
|
|
59
|
+
environment's isolation and permissions.
|
|
60
|
+
The review instructions require source-only assessment: no builds, tests, PoCs,
|
|
61
|
+
target execution, or network investigation. This mode does not configure a local
|
|
62
|
+
Codex sandbox; regular `validate` retains its existing read-only sandbox. A
|
|
63
|
+
protocol success only proves that the answer matched the schema; it does not
|
|
64
|
+
establish assessment quality.
|
|
65
|
+
|
|
66
|
+
The SDK equivalent is `validateRecords(input, { reviewRunner, signal })`, exported
|
|
67
|
+
from `@openai/codex-security`. The runner's `run(request, { signal })` method returns
|
|
68
|
+
the structured answer. `ValidateRecordsInput`, `ValidateRecordsOptions`, and
|
|
69
|
+
`ValidationReviewRequest` are exported types.
|