@openai/codex-security 0.1.7 → 0.1.9
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 +23 -11
- package/_bundled_plugin/.codex-plugin/plugin.json +1 -1
- package/_bundled_plugin/mcp/server.mjs +1 -1
- 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/preflight/capability-profiles.toml +2 -2
- package/_bundled_plugin/references/config-preflight.md +6 -6
- package/_bundled_plugin/references/desktop-config-preflight.md +11 -0
- package/_bundled_plugin/references/final-report.md +10 -14
- package/_bundled_plugin/references/scan-artifacts.md +17 -17
- package/_bundled_plugin/references/shared-hard-rules.md +2 -2
- package/_bundled_plugin/scripts/deep_scan_workbench.py +422 -48
- package/_bundled_plugin/scripts/generate_rank_input.py +118 -1
- package/_bundled_plugin/scripts/workbench_cli.py +1 -50
- package/_bundled_plugin/scripts/workbench_constants.py +0 -3
- package/_bundled_plugin/scripts/workbench_db.py +7 -297
- package/_bundled_plugin/scripts/workbench_progress.py +11 -0
- package/_bundled_plugin/scripts/workbench_scan_history.py +8 -64
- package/_bundled_plugin/scripts/workbench_target.py +2 -6
- package/_bundled_plugin/scripts/workbench_validation.py +0 -211
- package/_bundled_plugin/skills/attack-path-analysis/SKILL.md +10 -10
- package/_bundled_plugin/skills/deep-security-scan/SKILL.md +25 -43
- package/_bundled_plugin/skills/finding-discovery/SKILL.md +2 -4
- package/_bundled_plugin/skills/security-diff-scan/SKILL.md +11 -23
- package/_bundled_plugin/skills/security-scan/SKILL.md +89 -26
- package/_bundled_plugin/skills/security-scan/references/desktop-scan.md +25 -0
- package/_bundled_plugin/skills/security-scan/references/repository-wide-scan.md +11 -38
- package/_bundled_plugin/skills/security-scan/references/scan-artifacts-and-ledger.md +5 -6
- package/_bundled_plugin/skills/triage-finding/SKILL.md +6 -14
- package/_bundled_plugin/skills/validation/SKILL.md +9 -9
- package/dist/api.d.ts +3 -1
- package/dist/api.d.ts.map +1 -1
- package/dist/api.js +113 -82
- package/dist/api.js.map +1 -1
- package/dist/auth.d.ts.map +1 -1
- package/dist/auth.js +18 -71
- package/dist/auth.js.map +1 -1
- package/dist/cli.d.ts +1 -1
- package/dist/cli.d.ts.map +1 -1
- package/dist/cli.js +57 -136
- package/dist/cli.js.map +1 -1
- package/dist/contract.d.ts.map +1 -1
- package/dist/contract.js +7 -228
- package/dist/contract.js.map +1 -1
- package/dist/cost.d.ts.map +1 -1
- package/dist/cost.js +0 -4
- package/dist/cost.js.map +1 -1
- package/dist/knowledge-base.js +4 -4
- package/dist/knowledge-base.js.map +1 -1
- package/dist/multiscan.d.ts +5 -1
- package/dist/multiscan.d.ts.map +1 -1
- package/dist/multiscan.js +232 -26
- package/dist/multiscan.js.map +1 -1
- package/dist/runtime.d.ts +13 -1
- package/dist/runtime.d.ts.map +1 -1
- package/dist/runtime.js +136 -242
- package/dist/runtime.js.map +1 -1
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/dist/version.js.map +1 -1
- package/dist/worker-progress.d.ts.map +1 -1
- package/dist/worker-progress.js +8 -29
- package/dist/worker-progress.js.map +1 -1
- package/package.json +3 -3
- package/_bundled_plugin/mcp/mcp-app.html.br +0 -0
package/README.md
CHANGED
|
@@ -200,6 +200,7 @@ npx @openai/codex-security scan /path/to/repository --model gpt-5.6-terra
|
|
|
200
200
|
npx @openai/codex-security scan /path/to/repository --model gpt-5.6-terra --effort high
|
|
201
201
|
npx @openai/codex-security scan /path/to/repository --path src --path tests
|
|
202
202
|
npx @openai/codex-security scan /path/to/repository --knowledge-base /path/to/threat-models --knowledge-base /path/to/architecture.pdf
|
|
203
|
+
npx @openai/codex-security scan /path/to/repository --scan-prompt-file scan.md --post-scan-prompt-file follow-up.md
|
|
203
204
|
npx @openai/codex-security scan /path/to/repository --diff origin/main --json
|
|
204
205
|
npx @openai/codex-security scan /path/to/repository --output-dir /path/outside/repository/results
|
|
205
206
|
npx @openai/codex-security scan /path/to/repository --output-dir /path/outside/repository/results --archive-existing
|
|
@@ -211,7 +212,9 @@ npx @openai/codex-security scan /path/to/repository --mode deep --workers 2 --su
|
|
|
211
212
|
npx @openai/codex-security install-hook
|
|
212
213
|
npx @openai/codex-security bulk-scan
|
|
213
214
|
npx @openai/codex-security bulk-scan --model gpt-5.6-terra --effort high
|
|
215
|
+
npx @openai/codex-security bulk-scan --workers 4 --mode deep --max-attempts 3
|
|
214
216
|
npx @openai/codex-security bulk-scan repositories.csv --output-dir /path/outside/repositories/security-scans --workers 4 --knowledge-base /path/to/threat-models --knowledge-base /path/to/architecture.pdf
|
|
217
|
+
npx @openai/codex-security bulk-scan repositories.csv --output-dir /path/outside/repositories/security-scans --scan-prompt-file scan.md --post-scan-prompt-file follow-up.md
|
|
215
218
|
npx @openai/codex-security scans list /path/to/repository
|
|
216
219
|
npx @openai/codex-security scans list --scan-root /path/outside/repository/results
|
|
217
220
|
npx @openai/codex-security scans show SCAN_ID
|
|
@@ -461,9 +464,7 @@ including cached input and cache writes; fees and surcharges are not included.
|
|
|
461
464
|
|
|
462
465
|
Use `--max-cost USD` to stop a scan, including its delegated workers, when its
|
|
463
466
|
running cost exceeds the limit. Partial results are preserved. Requests
|
|
464
|
-
already in progress can finish above the limit.
|
|
465
|
-
session events up to 1 MiB; an oversized event stops the scan because its
|
|
466
|
-
running cost can no longer be verified safely.
|
|
467
|
+
already in progress can finish above the limit.
|
|
467
468
|
|
|
468
469
|
Run `npx @openai/codex-security scan --help` or `npx @openai/codex-security bulk-scan --help`
|
|
469
470
|
for the complete CLI references.
|
|
@@ -476,15 +477,26 @@ Private checkouts reuse your GitHub CLI sign-in without changing your global Git
|
|
|
476
477
|
configuration. The selected repositories are saved to
|
|
477
478
|
`<output-dir>/repositories.csv` for review or resumption.
|
|
478
479
|
|
|
480
|
+
Interactive discovery accepts the same `--workers`, `--mode`, `--max-attempts`,
|
|
481
|
+
`--model`, `--effort`, `--plugin-path`, `--python`, and `--codex` settings as
|
|
482
|
+
CSV-driven scans. It prompts for the output directory; `--output-dir` is only
|
|
483
|
+
valid when a repository CSV is supplied.
|
|
484
|
+
|
|
479
485
|
To use an existing repository list or run in CI, pass a CSV with required `id`,
|
|
480
486
|
`repository`, and `revision` columns. Revisions must be full commit hashes;
|
|
481
|
-
optional `scope` and `
|
|
487
|
+
optional `scope`, `mode`, and `prompt` columns customize individual scans:
|
|
482
488
|
|
|
483
489
|
```csv
|
|
484
|
-
id,repository,revision,scope,mode
|
|
485
|
-
service,https://github.com/acme/service.git,0123456789abcdef0123456789abcdef01234567,src,standard
|
|
490
|
+
id,repository,revision,scope,mode,prompt
|
|
491
|
+
service,https://github.com/acme/service.git,0123456789abcdef0123456789abcdef01234567,src,standard,Focus on authentication and authorization.
|
|
486
492
|
```
|
|
487
493
|
|
|
494
|
+
Use `--scan-prompt-file PATH` to add instructions to a scan or every bulk scan.
|
|
495
|
+
Bulk scans append each repository's CSV `prompt` after the shared instructions.
|
|
496
|
+
Use `--post-scan-prompt-file PATH` to run a follow-up in the same authenticated
|
|
497
|
+
session after each scan, including incomplete or failed scans. Canceled scans
|
|
498
|
+
and scans stopped at their configured cost limit do not start another turn.
|
|
499
|
+
|
|
488
500
|
`--workers` limits concurrent scans and `--max-attempts` retries failures.
|
|
489
501
|
Results remain under `--output-dir`; rerun the same command to resume.
|
|
490
502
|
|
|
@@ -573,11 +585,7 @@ text. Both commands operate on the current directory, use the scan model
|
|
|
573
585
|
and reasoning defaults, ignore unrelated user configuration and plugins, and
|
|
574
586
|
print the final response without the underlying Codex event stream. Override
|
|
575
587
|
the model with `--codex 'model="gpt-5.6-sol"'` and the reasoning effort with
|
|
576
|
-
`--effort high` or `--codex 'model_reasoning_effort="high"'`.
|
|
577
|
-
limited to 64 items and 1 MiB total.
|
|
578
|
-
|
|
579
|
-
Canonical scan documents are limited to 16 MiB for the manifest, 128 MiB for
|
|
580
|
-
findings, and 32 MiB for coverage. Oversized scans are rejected before sealing.
|
|
588
|
+
`--effort high` or `--codex 'model_reasoning_effort="high"'`.
|
|
581
589
|
|
|
582
590
|
Exit codes are `0` for a completed report-only scan or a passing policy, `1`
|
|
583
591
|
for a completed policy violation, `2` for invalid input, incomplete coverage, or
|
|
@@ -625,6 +633,10 @@ device login remains in `state/`. For unattended scans, set `OPENAI_API_KEY`
|
|
|
625
633
|
or `CODEX_API_KEY` instead. Set `GH_TOKEN` or `GITHUB_TOKEN` for private
|
|
626
634
|
GitHub repositories.
|
|
627
635
|
|
|
636
|
+
The container accepts the repository CSV before or after bulk-scan options.
|
|
637
|
+
Interactive repository discovery remains disabled, including when global CLI
|
|
638
|
+
options appear before `bulk-scan`.
|
|
639
|
+
|
|
628
640
|
On Ubuntu hosts that restrict unprivileged user namespaces, an administrator
|
|
629
641
|
can install the optional, narrowly scoped AppArmor profile once:
|
|
630
642
|
|
|
@@ -9,7 +9,7 @@ const runtimeChunkNames = (await readdir(new URL("./", import.meta.url)))
|
|
|
9
9
|
.filter((name) => name.startsWith("server.mjs.br.part-"))
|
|
10
10
|
.sort();
|
|
11
11
|
if (!runtimeChunkNames.length) {
|
|
12
|
-
throw new Error("Missing compressed Codex Security MCP
|
|
12
|
+
throw new Error("Missing compressed Codex Security MCP server runtime chunks.");
|
|
13
13
|
}
|
|
14
14
|
const compressedRuntime = Buffer.concat(
|
|
15
15
|
await Promise.all(runtimeChunkNames.map((name) => readFile(new URL(`./${name}`, import.meta.url))))
|
|
Binary file
|
|
Binary file
|
|
@@ -58,12 +58,12 @@ description = "Capabilities for repository-wide or scoped-path Codex Security sc
|
|
|
58
58
|
[[profiles.security_scan.requirements]]
|
|
59
59
|
capability = "delegated_workers"
|
|
60
60
|
severity = "warn"
|
|
61
|
-
reason = "
|
|
61
|
+
reason = "Standard scans use an independent baseline auditor and focused investigation workers when delegation is available."
|
|
62
62
|
|
|
63
63
|
[[profiles.security_scan.requirements]]
|
|
64
64
|
capability = "usable_worker_slots_6"
|
|
65
65
|
severity = "warn"
|
|
66
|
-
reason = "
|
|
66
|
+
reason = "A six-thread cap provides room for an independent baseline and parallel investigators; it does not require six running workers."
|
|
67
67
|
|
|
68
68
|
[[profiles.security_scan.requirements]]
|
|
69
69
|
capability = "goal_tools"
|
|
@@ -2,6 +2,8 @@
|
|
|
2
2
|
|
|
3
3
|
Codex Security top-level scan skills should run the read-only helper before substantive scan work:
|
|
4
4
|
|
|
5
|
+
Load `desktop-config-preflight.md` only after the host explicitly identifies itself as the Codex desktop app.
|
|
6
|
+
|
|
5
7
|
Resolve `<python_command>` to the configured Python interpreter (`$PYTHON` when one is provided), otherwise use `python` on Windows and `python3` on Unix-like hosts. Before constructing the first helper command, inspect the current tool surface once and use that discovery result for both the runtime checks and `<verified-multi-agent-runtime-arguments>`. Do not omit active runtime facts from the first invocation and wait for an `incomplete` result before supplying them. The command is written on one line so it works in PowerShell, Command Prompt, and POSIX shells:
|
|
6
8
|
|
|
7
9
|
```text
|
|
@@ -66,11 +68,9 @@ Do not warn merely because a user's value differs from the profile's suggested p
|
|
|
66
68
|
|
|
67
69
|
If a runtime capability is `unknown`, establish it from the current tool surface and rerun the helper with an explicit `--runtime-check`. Do not treat an `incomplete` result or unknown value as evidence that the capability is available.
|
|
68
70
|
|
|
69
|
-
##
|
|
70
|
-
|
|
71
|
-
The onboarding workspace opens before capability preflight and does not display or enforce configuration capability results. If `open_codex_security_workspace` returns a workspace with `setup.submitted=false`, that is the app setup wait state. Do not run this helper, do not call `set_codex_security_capability_preflight`, do not create or adopt a scan goal, and do not reclassify the scan as terminal/chat fallback merely because no `scanId` exists yet. Stop and wait for the user to review setup and press Start scan.
|
|
71
|
+
## Durable scan handoff
|
|
72
72
|
|
|
73
|
-
After
|
|
73
|
+
After a native handoff or direct conversation start provides a `scanId`, use its authoritative scan context and run this preflight for the validated target and selected scan mode. The dedicated preflight worker described above should finish before goal setup, threat modeling, scan/discovery worker creation, or other substantive analysis.
|
|
74
74
|
|
|
75
75
|
For standard and diff scans, the app handoff starts preflight without an item count. After every structured helper result, call `update_codex_security_scan_progress` without changing phase and set `preflightChecks` to every entry from the helper's `results` array, projecting each entry to only `capability`, `reason`, `severity`, and `status`. Do not send `phaseItemsTotal`, `phaseItemsCompleted`, or `phaseProgressUnit` with `preflightChecks`: the server derives the total from the array length, counts `pass` and `fail` as completed, excludes `unknown` from completed, and derives the visible `block` or `warn` attention items. Send the full fresh results array after a clean rerun so stale issues disappear. Do not interpret item-count completion as readiness: remain in preflight for every blocked, incomplete, or error result while remediation or retry remains pending, even when every returned check was evaluated. Only after a `ready` result has published its fresh `preflightChecks` should a separate progress call advance to `threat_model`. These counts and issues belong to the current scan rather than the legacy setup-time workspace preflight, and remain visible after the scan advances. Deep Scan preflight and discovery progress remain owned by `start_codex_security_deep_scan`.
|
|
76
76
|
|
|
@@ -110,6 +110,6 @@ In a non-interactive Codex session, do not leave the run waiting for an answer i
|
|
|
110
110
|
|
|
111
111
|
For any non-ready result, do not fail automatically. If an interactive chat fallback declines required remediation without choosing whether to cancel or leave the scan running, ask that follow-up before taking either action. If remediation is unavailable, the helper cannot run, the helper returns an error envelope, or a rerun remains blocked or incomplete, preserve a durable running scan and retry or hand off while recovery may still be possible. Call `fail_codex_security_scan` with the exact reasons only after the documented recovery path is exhausted and the blocker is confirmed unrecoverable, or when the user explicitly cancels.
|
|
112
112
|
|
|
113
|
-
Present applicable remediation in the Codex thread. Ask before editing persistent user configuration in interactive sessions; use the narrow automatic-remediation path above in non-interactive sessions.
|
|
113
|
+
Present applicable remediation in the Codex thread. Ask before editing persistent user configuration in interactive sessions; use the narrow automatic-remediation path above in non-interactive sessions.
|
|
114
114
|
|
|
115
|
-
Codex CLI and hosts
|
|
115
|
+
Codex CLI and other hosts use the same prompt-based preflight before substantive work. Explain the exact reasons and remediation in chat. Interactive CLI sessions ask before editing persistent config; non-interactive CLI sessions use the narrow automatic-remediation path above and continue only after a `ready` rerun.
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
# Codex Desktop Capability Preflight
|
|
2
|
+
|
|
3
|
+
Read this reference only after the host explicitly identifies itself as the Codex desktop app. The shared helper invocation, runtime checks, remediation limits, and non-interactive fallback remain in `config-preflight.md`.
|
|
4
|
+
|
|
5
|
+
Run preflight only after the scan has authoritative target and scan context.
|
|
6
|
+
|
|
7
|
+
After an app-backed Standard or diff scan has its authoritative `scanId`, publish every structured preflight result through `update_codex_security_scan_progress` without changing phase. Set `preflightChecks` to all current results, keeping only `capability`, `reason`, `severity`, and `status`; do not send separate phase totals. The server derives completed and total checks. Stay in preflight until the helper returns `ready`, then advance in a separate progress update. Deep discovery owns its own preflight and progress.
|
|
8
|
+
|
|
9
|
+
When an interactive desktop scan needs remediation, present the exact helper-provided config changes and offer **Apply and retry (Recommended)**, **Leave paused**, and **Cancel scan**. Prefer native `request_user_input`; if it is unavailable or errors, use `request_codex_security_user_input` with the same choices, and fall back to chat only when that tool is unavailable or errors. Never set automatic resolution or infer a choice from a declined or cancelled input request. Wait without creating a goal, then apply only explicitly approved changes, leave the durable scan running, or cancel only when the user explicitly selects cancellation.
|
|
10
|
+
|
|
11
|
+
Never use desktop input tools from a headless or non-interactive session.
|
|
@@ -16,23 +16,23 @@ Use `report.md` as the primary readable entry point. Explain report-relevant art
|
|
|
16
16
|
|
|
17
17
|
In the final response, link the generated markdown report path as the primary readable artifact.
|
|
18
18
|
|
|
19
|
-
Every scan mode uses the same final report pipeline.
|
|
19
|
+
Every scan mode uses the same final report pipeline. Workbench-owned Standard and Deep scans submit canonical semantics with `record_codex_security_scan_draft({ scanId, handoffClaimToken?, scope?, threatModel?, findings, coverage })`; the workbench supplies authoritative metadata and writes the unsealed canonical draft. SDK-owned Standard scans instead write unsealed canonical files with the exact SDK-provided metadata and leave finalization to the SDK. Other modes retain their existing canonical JSON workflow. No mode authors, repairs, or treats an existing `report.md` as input. Finalization validates and enriches the canonical JSON, seals the canonical JSON and evidence artifacts, then deterministically generates `report.md`. Supply report prose through structured canonical semantics rather than a separately authored report.
|
|
20
20
|
|
|
21
|
-
For each
|
|
21
|
+
For each finding, supply an evidence-supported lowercase vulnerability-family `ruleId`; `taxonomy: { category, cwe }` using its exact known CWEs; verified locations; and `provenance.source`, using `"local_plugin"` only when this plugin actually discovered the finding. Preserve genuine worker or source provenance and any existing canonical candidate identity in the finding extensions. A finding with no known CWE retains `cwe: []`; never invent a classification. Include optional `codeEvidence` only when its actual code is nonempty and every referenced evidence ID is present.
|
|
22
22
|
|
|
23
23
|
Supply semantic coverage as `{ completeness, surfaces, explicitExclusions, deferred }`, with each surface using the actual `label` and one existing `disposition`. Mark coverage `partial` when a deferred item or `needs_follow_up` surface remains; preserve its real reason and supporting context. Each deferred item needs a meaningful reason; preserve any existing `id` or `candidateId`. The workbench derives a missing ID from its candidate identity or stable deferred-work details. Open questions may be nonempty strings or `{ question, followUpPrompt? }` objects. The workbench derives target and scope metadata, scope include and exclude paths, coverage mode and inventory strategy, finding identities and fingerprints, and surface IDs. Do not put those workbench-owned values or top-level coverage receipt references into the semantic draft.
|
|
24
24
|
|
|
25
|
-
After a
|
|
25
|
+
After a workbench-owned Standard or Deep draft is accepted, call `complete_codex_security_scan({ scanId, handoffClaimToken? })` and use its returned completion metadata. An SDK-owned scan returns its unsealed canonical files without calling a completion tool or finalizer; the SDK owns completion and report generation. Read full canonical results only when explicitly requested. For diff or another terminal/chat workflow without a completion tool, retain `python <plugin_dir>/scripts/finalize_scan_contract.py --scan-dir <scan_dir> --source-root <repo_root>` after writing the canonical JSON. Outside the SDK path, do not mark the scan goal complete until finalization succeeds and the generated report exists.
|
|
26
26
|
|
|
27
27
|
After `complete_codex_security_scan` succeeds, include its returned `usage.totalTokens`, `usage.inputTokens`, and `usage.cachedInputTokens` in the final response when `usage.coverage` is `complete` or `partial`; explicitly label a partial measurement. If coverage is `unavailable`, say that token usage could not be measured instead of reporting zero or estimating a cost. Report only measured completion metadata in a terminal/chat host. Token usage is workbench metadata, not a reason to modify sealed scan artifacts or the deterministic report.
|
|
28
28
|
|
|
29
|
-
Before
|
|
29
|
+
Before workbench-owned Standard or Deep completion, require `record_codex_security_scan_draft` to succeed. SDK-owned Standard and existing diff workflows instead verify their canonical JSON before the appropriate owner finalizes it. Completion validates and seals existing canonical artifacts and generates `report.md`; it does not create missing artifacts or run skipped scan phases.
|
|
30
30
|
|
|
31
31
|
An MCP `-32602` input rejection, an `isError: true` result reporting `Input validation error`, or an explicit pre-write rejection of complete coverage containing deferred work or a follow-up surface makes no draft write. Correct only the named paths in the same draft, preserving all valid findings, fields, evidence, and deferred work; retry the same scan at most twice. Stop after the first accepted draft. Do not blindly retry an ambiguous transport or write failure.
|
|
32
32
|
|
|
33
|
-
For any other required scan phase, canonical-artifact write, or on-disk existence check that fails before completion, stop the current response and surface the exact workflow blocker. Do not call completion with missing artifacts, return a final report or no-findings result, satisfy a structured output schema
|
|
33
|
+
For any other required scan phase, canonical-artifact write, or on-disk existence check that fails before completion, stop the current response and surface the exact workflow blocker. Do not call completion with missing artifacts, return a final report or no-findings result, or satisfy a structured output schema. Leave the durable scan available for a later continuation instead of canceling or failing it solely because canonical assembly is blocked.
|
|
34
34
|
|
|
35
|
-
If `complete_codex_security_scan` or the terminal/chat finalizer fails, stop the current response and surface the exact MCP or finalizer error. Do not retry completion in the same response, return a final report or no-findings result, satisfy a structured output schema
|
|
35
|
+
If `complete_codex_security_scan` or the terminal/chat finalizer fails, stop the current response and surface the exact MCP or finalizer error. Do not retry completion in the same response, return a final report or no-findings result, or satisfy a structured output schema. Leave the durable scan available for a later continuation instead of canceling or failing it solely because completion failed.
|
|
36
36
|
|
|
37
37
|
Canonical report semantics live in these fields:
|
|
38
38
|
|
|
@@ -53,19 +53,15 @@ When there are no reportable findings, include a short `No findings` section tha
|
|
|
53
53
|
When there are reportable findings, render them as readable markdown findings rather than raw JSON or a dumped schema object.
|
|
54
54
|
Order findings from highest severity to lowest severity: `critical`, then `high`, then `medium`, then `low`.
|
|
55
55
|
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
If validation or attack-path analysis provides a broad family row with multiple independently triggerable sink, parser, helper, API-mode, or protected-action lines, split it into child final findings before writing the report. Multiple affected lines inside one finding are appropriate for one inseparable proof tuple, such as a wrapper plus its shared sink, but not as a substitute for separate findings when sibling operations can be triggered independently.
|
|
56
|
+
Group observations only when they share the same broken security control and effective remediation. Preserve every affected route, operation, sink, and supporting source location; keep distinct security failures separate even when they share a CWE.
|
|
59
57
|
|
|
60
58
|
Set the finding category and CWE from the primary broken control. Do not add secondary support-impact CWEs, such as data exposure or missing authentication, to an injection/RCE/path/file/parser finding merely because they make exploitation worse; mention those impacts in prose or emit a separate finding if that secondary control is independently vulnerable.
|
|
61
59
|
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
For a Standard or Deep repository or scoped-path scan, read the same enriched candidates with `list_codex_security_candidates`. Map each nested `validation` record into the finding's validation fields, map its confidence and rationale into top-level `confidence.level` and `confidence.rationale`, and map each nested `attack_path` record into dataflow, reachability, severity, and change conditions. Submit those semantics through `record_codex_security_scan_draft`. Canonical `severity.changeConditions` must be one non-empty string; when `attack_path.change_conditions` contains multiple strings, join them into one prose string before writing `findings.json`.
|
|
60
|
+
Workbench-owned Standard scans submit their source-backed final findings and coverage directly through `record_codex_security_scan_draft`; SDK-owned Standard scans write the same semantics into unsealed canonical files. Neither reads candidate ledgers or uses Deep-only candidate tools. Deep scans read enriched candidates with `list_codex_security_candidates`, map nested `validation` and `attack_path` records into their final findings, and submit one semantic draft. Canonical `severity.changeConditions` must be one non-empty string; when `attack_path.change_conditions` contains multiple strings, join them into one prose string before writing `findings.json`.
|
|
65
61
|
|
|
66
|
-
|
|
62
|
+
For Deep candidates, apply row outcomes in this order: validation disposition `reportable` plus attack-path decision `reportable` becomes a finding with its distinct instance and all relevant entrypoint, root-control, sink, and supporting locations; otherwise, a `deferred` result from either phase becomes `needs_follow_up` coverage and a `coverage.deferred` entry using the recorded uncertainty or proof gap; otherwise, validation disposition `not_applicable` becomes `not_applicable` coverage; otherwise, validation disposition `suppressed` or attack-path decision `ignore` becomes `rejected` coverage. A missing required phase record leaves the candidate unresolved and prevents complete coverage. Do not require phase receipts, per-candidate narratives, or another reconciliation pass.
|
|
67
63
|
|
|
68
|
-
Diff
|
|
64
|
+
Diff scans may provide per-candidate ledgers, validation closure tables, and repository coverage ledgers. When those artifacts exist, retain their traceability: start from reportable/surviving rows, preserve exact affected locations, and map suppressed, not-applicable, or deferred rows to public-facing coverage outcomes. Do not silently drop a seeded row because a same-family neighbor survived.
|
|
69
65
|
|
|
70
66
|
## Report Structure
|
|
71
67
|
|
|
@@ -11,7 +11,7 @@ Use these shared path conventions for Codex Security scan workflows unless the u
|
|
|
11
11
|
- `security_scans_dir=<system_temp_dir>/codex-security-scans/<repo_name>`
|
|
12
12
|
- `scan_id=<commit>_<scan timestamp>`
|
|
13
13
|
- `scan_dir=<security_scans_dir>/<scan_id>`
|
|
14
|
-
- `target_paths_file=$CODEX_SECURITY_TARGET_PATHS_FILE` for SDK scoped-path scans; this read-only scope input lives in the isolated Codex home outside the model-writable scan directory. Pass it directly to `make-repo-
|
|
14
|
+
- `target_paths_file=$CODEX_SECURITY_TARGET_PATHS_FILE` for SDK scoped-path scans; this read-only scope input lives in the isolated Codex home outside the model-writable scan directory. Pass it directly to `make-repo-scope-input --scopes-file` and `bind-repo-scopes --scopes-file` before finalization, and do not print, evaluate, modify, or treat its contents as shell syntax.
|
|
15
15
|
- `artifacts_dir=<scan_dir>/artifacts`
|
|
16
16
|
- `context_dir=<artifacts_dir>/01_context`
|
|
17
17
|
- `discovery_dir=<artifacts_dir>/02_discovery`
|
|
@@ -19,7 +19,7 @@ Use these shared path conventions for Codex Security scan workflows unless the u
|
|
|
19
19
|
- `reconciliation_dir=<artifacts_dir>/04_reconciliation`
|
|
20
20
|
- `findings_dir=<artifacts_dir>/05_findings`
|
|
21
21
|
|
|
22
|
-
The
|
|
22
|
+
The plugin resolves the platform temporary directory automatically. For a manual workflow, use the active process temporary directory (for example, `%TEMP%` on Windows or `$TMPDIR` when configured on Unix-like hosts) instead of hardcoding `/tmp`.
|
|
23
23
|
|
|
24
24
|
Resolve `<python_command>` to the configured Python interpreter (`$PYTHON` when one is provided), otherwise use `python` on Windows and `python3` on Unix-like hosts.
|
|
25
25
|
|
|
@@ -38,26 +38,25 @@ End each repository-scoped threat model with these two lines:
|
|
|
38
38
|
|
|
39
39
|
## Finding Discovery (Phase 2) Paths
|
|
40
40
|
|
|
41
|
-
###
|
|
41
|
+
### Deep Scan Discovery
|
|
42
42
|
|
|
43
|
-
-
|
|
44
|
-
|
|
45
|
-
|
|
43
|
+
Workbench-owned Standard scans submit findings and coverage through `record_codex_security_scan_draft`; SDK-owned Standard scans write unsealed canonical files directly. Neither creates a source inventory or candidate ledger. Deep scans use the following compact artifacts.
|
|
44
|
+
|
|
45
|
+
- The Deep coordinator prepares the source inventory. A bound discovery worker reads its assigned source paths with `list_codex_security_review_items({ cursor?, limit? })`.
|
|
46
|
+
- Each discovery worker calls its bound `record_codex_security_discovery_candidates({ candidates })` tool once. After semantic reduction, the parent reads the canonical candidates with `list_codex_security_candidates({ scanId, cursor?, limit? })`.
|
|
47
|
+
- The writer validates candidates against assigned source paths, merges rows with the same CWE ids, locations, and optional instance, preserves their text, and assigns deterministic `candidate_id` values.
|
|
46
48
|
- After normalization, compact validation adds exactly one `validation` object to every row with `disposition` (`reportable`, `suppressed`, `not_applicable`, or `deferred`), `method`, `confidence` (`high`, `medium`, or `low`), `confidence_rationale`, concise `rubric` and `evidence`, `counterevidence_or_proof_gap`, `remaining_uncertainty`, and optional `artifact_paths`. Add `source`, `control`, `sink`, or `preconditions` only when they clarify or differ from the discovery fields.
|
|
47
49
|
- Compact attack-path analysis adds exactly one `attack_path` object to each validation row marked `reportable` or `deferred`, with `decision` (`reportable`, `ignore`, or `deferred`), `dataflow`, `reachability`, `counterevidence`, `impact` and `likelihood` (`high`, `medium`, `low`, `ignore`, or `unknown`), `severity` (`critical`, `high`, `medium`, `low`, `ignore`, or `unknown`), `severity_rationale`, `change_conditions`, and `proof_gap` when deferred. A `reportable` decision requires severity `critical`, `high`, `medium`, or `low`; `ignore` requires severity `ignore`; `deferred` uses a provisional reportable severity or `unknown`.
|
|
48
|
-
- Record all validations through `record_codex_security_candidate_validations` and all eligible attack-path decisions through `
|
|
50
|
+
- Record all validations through `record_codex_security_candidate_validations` and all eligible attack-path decisions through `record_candidate_attack_paths`. The tools atomically preserve all discovery fields and candidate order.
|
|
49
51
|
- Optional compact validation evidence: `<discovery_dir>/validation_artifacts/<candidate_id>/`
|
|
50
52
|
- Create this directory only for actual PoCs, crafted inputs, or logs and reference those paths from the row's `validation` object. Do not create placeholder per-candidate directories or narrative reports.
|
|
51
53
|
|
|
52
|
-
The
|
|
54
|
+
The worklist, per-finding receipt, and phase-report paths below apply to diff scans. Deep scans use the compact candidate records above; Standard scans assemble validated findings directly.
|
|
53
55
|
|
|
54
|
-
### Coverage
|
|
56
|
+
### Diff Discovery And Coverage
|
|
55
57
|
|
|
56
58
|
- Advisory seed research: `<context_dir>/seed_research.md`
|
|
57
|
-
-
|
|
58
|
-
- Scoped ranking shards: `<discovery_dir>/rank_shards/rank-shard-NNNN.input.jsonl` and matching worker-local `.output.jsonl` files if ranking applies
|
|
59
|
-
- Scoped ranking worker assignments: `<discovery_dir>/rank_worker_assignments.json` if ranking applies
|
|
60
|
-
- Scoped ranking output: `<discovery_dir>/rank_output.jsonl` if applicable
|
|
59
|
+
- Changed source input: `<discovery_dir>/rank_input.jsonl`
|
|
61
60
|
- Scoped deep-review input: `<discovery_dir>/deep_review_input.jsonl` if applicable
|
|
62
61
|
- Finding discovery report: `<discovery_dir>/finding_discovery_report.md`
|
|
63
62
|
|
|
@@ -82,7 +81,7 @@ The legacy ranking, raw/deduped candidate, per-finding receipt, and phase-report
|
|
|
82
81
|
|
|
83
82
|
## Validation (Phase 3) Paths
|
|
84
83
|
|
|
85
|
-
|
|
84
|
+
Deep scans use the nested candidate `validation` record and optional compact evidence path above. Standard scans include validation directly in their final finding semantics. Diff scans use these paths:
|
|
86
85
|
|
|
87
86
|
- Scan-level validation summary: `<findings_dir>/validation_summary.md` if applicable
|
|
88
87
|
- Per-finding validation report: `<findings_dir>/<candidate_id>/validation_report.md`
|
|
@@ -90,15 +89,16 @@ Compact Standard and Deep scans use the nested `validation` record and optional
|
|
|
90
89
|
|
|
91
90
|
## Attack-Path Analysis (Phase 4) Paths
|
|
92
91
|
|
|
93
|
-
|
|
92
|
+
Deep scans use the nested candidate `attack_path` record above. Standard scans include attack-path analysis directly in their final finding semantics. Diff scans use these paths:
|
|
94
93
|
|
|
95
94
|
- Scan-level attack-path analysis report: `<findings_dir>/attack_path_analysis_report.md` if applicable
|
|
96
95
|
- Per-finding attack-path analysis report: `<findings_dir>/<candidate_id>/attack_path_analysis_report.md`
|
|
97
96
|
|
|
98
97
|
## Final Report Paths
|
|
99
98
|
|
|
100
|
-
-
|
|
101
|
-
-
|
|
99
|
+
- Workbench-owned Standard and Deep draft: `record_codex_security_scan_draft({ scanId, handoffClaimToken?, scope?, threatModel?, findings, coverage })`
|
|
100
|
+
- SDK-owned Standard draft: unsealed `scan-manifest.json`, `findings.json`, and `coverage.json` under the SDK-provided scan directory
|
|
101
|
+
- Deep or explicitly requested Standard completed results: `get_codex_security_completed_scan({ scanId, handoffClaimToken? })`
|
|
102
102
|
- Final scan report: `<scan_dir>/report.md`
|
|
103
103
|
- Detailed vulnerability write-up: `<scan_dir>/findings/<slug>/<slug>.md`
|
|
104
104
|
- Per-finding PoC and supporting files: `<scan_dir>/findings/<slug>/poc/...`
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Shared Hard Rules
|
|
2
2
|
|
|
3
|
-
Apply these rules
|
|
3
|
+
Apply these rules to diff scans before their scan-mode-specific hard rules. Standard and Deep scans follow their own workflows.
|
|
4
4
|
|
|
5
5
|
- Keep the phases separate.
|
|
6
6
|
- Follow the execution plan in order.
|
|
@@ -8,7 +8,7 @@ Apply these rules for diff, deep, and resumed legacy Codex Security scans before
|
|
|
8
8
|
- Candidate-finding coverage is required. Do not finalize a candidate finding until `findings/<candidate_id>/candidate_ledger.jsonl` shows discovery, validation, and attack-path receipts for that exact candidate, or an explicit deferred reason for the missing proof.
|
|
9
9
|
- Avoid destructive commands, interactive editors, and broad unbounded scans.
|
|
10
10
|
- Prefer targeted, reversible shell commands.
|
|
11
|
-
- `fail_codex_security_scan` is terminal and cannot be resumed. Use it only for an unrecoverable blocker after documented recovery is exhausted
|
|
11
|
+
- `fail_codex_security_scan` is terminal and cannot be resumed. Use it only for an unrecoverable blocker after documented recovery is exhausted. Use `cancel_codex_security_scan` for explicit user cancellation. Do not fail a scan merely because work remains, discovery or workers are still running, partial artifacts exist, or a turn, context window, or goal run is ending. Record meaningful progress and leave the durable scan running so a later continuation can resume.
|
|
12
12
|
- For Phase 1 fallback threat model generation, produce a repository-level threat model that would still make sense for an unrelated diff in the same repository.
|
|
13
13
|
- Do not let the current scan target bias Phase 1 unless the user explicitly requests a target-scoped threat model.
|
|
14
14
|
- For later phases, stay grounded in repository evidence and the actual in-scope code.
|