@openai/codex-security 0.1.15 → 0.1.17

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.
Files changed (109) hide show
  1. package/README.md +204 -4
  2. package/_bundled_plugin/.app.json +1 -1
  3. package/_bundled_plugin/.mcp.json +9 -3
  4. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  5. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  6. package/_bundled_plugin/references/config-preflight.md +1 -1
  7. package/_bundled_plugin/references/sarif-adapter.md +5 -1
  8. package/_bundled_plugin/scripts/deep_scan_workbench.py +34 -6
  9. package/_bundled_plugin/scripts/finalize_scan_contract.py +121 -32
  10. package/_bundled_plugin/scripts/generate_in_scope_files.py +20 -0
  11. package/_bundled_plugin/scripts/generate_rank_input.py +23 -7
  12. package/_bundled_plugin/scripts/launch_codex_security_mcp +32 -0
  13. package/_bundled_plugin/scripts/launch_codex_security_mcp.cmd +27 -0
  14. package/_bundled_plugin/scripts/workbench_cli.py +22 -15
  15. package/_bundled_plugin/scripts/workbench_db.py +35 -35
  16. package/_bundled_plugin/scripts/workbench_progress.py +6 -3
  17. package/_bundled_plugin/scripts/workbench_scan_history.py +17 -2
  18. package/_bundled_plugin/scripts/workbench_target.py +36 -5
  19. package/_bundled_plugin/scripts/workbench_validation.py +9 -0
  20. package/_bundled_plugin/skills/fix-finding/SKILL.md +17 -1
  21. package/_bundled_plugin/skills/verify-fix/SKILL.md +44 -0
  22. package/_bundled_plugin/skills/verify-fix/agents/openai.yaml +4 -0
  23. package/dist/api.d.ts +16 -1
  24. package/dist/api.d.ts.map +1 -1
  25. package/dist/api.js +180 -11
  26. package/dist/api.js.map +1 -1
  27. package/dist/cli.d.ts +12 -5
  28. package/dist/cli.d.ts.map +1 -1
  29. package/dist/cli.js +781 -62
  30. package/dist/cli.js.map +1 -1
  31. package/dist/component-plan.d.ts +15 -0
  32. package/dist/component-plan.d.ts.map +1 -0
  33. package/dist/component-plan.js +145 -0
  34. package/dist/component-plan.js.map +1 -0
  35. package/dist/component-scan.d.ts +83 -0
  36. package/dist/component-scan.d.ts.map +1 -0
  37. package/dist/component-scan.js +279 -0
  38. package/dist/component-scan.js.map +1 -0
  39. package/dist/contract.d.ts +8 -2
  40. package/dist/contract.d.ts.map +1 -1
  41. package/dist/contract.js +27 -8
  42. package/dist/contract.js.map +1 -1
  43. package/dist/cost-model.d.ts +20 -0
  44. package/dist/cost-model.d.ts.map +1 -0
  45. package/dist/cost-model.js +86 -0
  46. package/dist/cost-model.js.map +1 -0
  47. package/dist/cost.d.ts +2 -11
  48. package/dist/cost.d.ts.map +1 -1
  49. package/dist/cost.js +15 -95
  50. package/dist/cost.js.map +1 -1
  51. package/dist/custom-validation-prompt.d.ts +4 -0
  52. package/dist/custom-validation-prompt.d.ts.map +1 -0
  53. package/dist/custom-validation-prompt.js +94 -0
  54. package/dist/custom-validation-prompt.js.map +1 -0
  55. package/dist/custom-validation.d.ts +45 -0
  56. package/dist/custom-validation.d.ts.map +1 -0
  57. package/dist/custom-validation.js +292 -0
  58. package/dist/custom-validation.js.map +1 -0
  59. package/dist/errors.d.ts +1 -1
  60. package/dist/errors.d.ts.map +1 -1
  61. package/dist/errors.js +1 -1
  62. package/dist/errors.js.map +1 -1
  63. package/dist/index.d.ts +6 -1
  64. package/dist/index.d.ts.map +1 -1
  65. package/dist/index.js +2 -0
  66. package/dist/index.js.map +1 -1
  67. package/dist/multiscan.d.ts +1 -0
  68. package/dist/multiscan.d.ts.map +1 -1
  69. package/dist/multiscan.js +53 -5
  70. package/dist/multiscan.js.map +1 -1
  71. package/dist/patch-tui.js +1 -1
  72. package/dist/patch-tui.js.map +1 -1
  73. package/dist/publication.d.ts.map +1 -1
  74. package/dist/publication.js +3 -4
  75. package/dist/publication.js.map +1 -1
  76. package/dist/runtime.d.ts +4 -2
  77. package/dist/runtime.d.ts.map +1 -1
  78. package/dist/runtime.js +109 -38
  79. package/dist/runtime.js.map +1 -1
  80. package/dist/scan-comparison.d.ts +12 -5
  81. package/dist/scan-comparison.d.ts.map +1 -1
  82. package/dist/scan-comparison.js +72 -28
  83. package/dist/scan-comparison.js.map +1 -1
  84. package/dist/scan-dashboard.d.ts +9 -2
  85. package/dist/scan-dashboard.d.ts.map +1 -1
  86. package/dist/scan-dashboard.js +205 -7
  87. package/dist/scan-dashboard.js.map +1 -1
  88. package/dist/scan-logs.d.ts.map +1 -1
  89. package/dist/scan-logs.js +5 -21
  90. package/dist/scan-logs.js.map +1 -1
  91. package/dist/scan-sessions.d.ts +4 -0
  92. package/dist/scan-sessions.d.ts.map +1 -0
  93. package/dist/scan-sessions.js +35 -0
  94. package/dist/scan-sessions.js.map +1 -0
  95. package/dist/targets.d.ts.map +1 -1
  96. package/dist/targets.js +16 -1
  97. package/dist/targets.js.map +1 -1
  98. package/dist/version.d.ts.map +1 -1
  99. package/dist/version.js +2 -20
  100. package/dist/version.js.map +1 -1
  101. package/dist/windows-path.d.ts +3 -0
  102. package/dist/windows-path.d.ts.map +1 -0
  103. package/dist/windows-path.js +16 -0
  104. package/dist/windows-path.js.map +1 -0
  105. package/dist/worker-progress.d.ts +1 -0
  106. package/dist/worker-progress.d.ts.map +1 -1
  107. package/dist/worker-progress.js +12 -0
  108. package/dist/worker-progress.js.map +1 -1
  109. package/package.json +8 -2
package/README.md CHANGED
@@ -54,6 +54,11 @@ Use `security.preflight()` to validate local inputs, `onWorkerStatus` and
54
54
  `onReconnect` to observe long-running scans, and an `AbortSignal` to cancel a
55
55
  scan.
56
56
 
57
+ For separate standard scans under one project, the SDK also exports
58
+ `runComponentScans({ repository, outputDir, components })`. Each component has
59
+ a `name` and `paths` array. Use `auto: true` instead of `components` for
60
+ model-assisted planning, and `planOnly: true` to save the plan without scanning.
61
+
57
62
  Successful results include open repository findings in `repositoryFindings`,
58
63
  when available; `findings` remains the current scan. Matching earlier findings
59
64
  can make one additional model call, including with a scan cost limit.
@@ -62,6 +67,44 @@ Results can contain source excerpts, vulnerability details, and reproduction
62
67
  steps. Keep result directories and saved reports outside the repository and
63
68
  limit access to authorized reviewers.
64
69
 
70
+ ### Validate an existing finding
71
+
72
+ Use `security.validate()` to assess one finding without running a repository
73
+ scan or invoking the Codex Security CLI:
74
+
75
+ ```ts
76
+ const security = new CodexSecurity();
77
+ try {
78
+ const result = await security.validate({
79
+ repositoryPath: "/path/to/repository",
80
+ finding: {
81
+ title: "Possible SQL injection",
82
+ location: "src/query.ts:42",
83
+ },
84
+ outputDir: "/path/outside/repository/validation",
85
+ });
86
+ console.log(result.disposition);
87
+ console.log(result.report);
88
+ } finally {
89
+ await security.close();
90
+ }
91
+ ```
92
+
93
+ `finding` accepts literal text or a JSON-serializable object, never a file
94
+ path. Read files explicitly. Validation uses the CLI's validation skill and
95
+ the client's settings and authentication. It leaves repository files unchanged
96
+ and does not add a scan to scan history.
97
+
98
+ The result contains `disposition` (`reportable`, `suppressed`, `not_applicable`,
99
+ or `deferred`), a Markdown `report`, `threadId`, and `outputDir` for evidence.
100
+ The report explains root cause, exploitability, evidence, and proof gaps.
101
+ `reportable` can rely on static analysis; `deferred` means insufficient evidence.
102
+
103
+ `outputDir` must be empty and outside the enclosing Git worktree. It defaults
104
+ to the Codex Security state directory's `validations/` folder. Pass `auth` to
105
+ select authentication or `signal` to cancel. Failed, incomplete, or malformed
106
+ responses reject the promise.
107
+
65
108
  ### SDK configuration and scan options
66
109
 
67
110
  Pass runtime configuration to the `CodexSecurity` constructor:
@@ -211,6 +254,8 @@ npx @openai/codex-security scan /path/to/repository --patch --patch-severity hig
211
254
  npx @openai/codex-security scan /path/to/repository --model gpt-5.6-terra
212
255
  npx @openai/codex-security scan /path/to/repository --model gpt-5.6-terra --effort high
213
256
  npx @openai/codex-security scan /path/to/repository --path src --path tests
257
+ npx @openai/codex-security scan-components /path/to/repository --component apps/api --component apps/web --output-dir /path/outside/repository/results
258
+ npx @openai/codex-security scan-components /path/to/repository --auto --output-dir /path/outside/repository/results
214
259
  npx @openai/codex-security scan /path/to/repository --knowledge-base /path/to/threat-models --knowledge-base /path/to/architecture.pdf
215
260
  npx @openai/codex-security scan /path/to/repository --scan-prompt-file scan.md --post-scan-prompt-file follow-up.md
216
261
  npx @openai/codex-security scan /path/to/repository --diff origin/main --json
@@ -251,6 +296,9 @@ npx @openai/codex-security publish scan /path/outside/repository/results --to li
251
296
  npx @openai/codex-security publish scan --to linear --linear-team TEAM_ID
252
297
  npx @openai/codex-security validate /path/outside/repository/findings.json "Possible SQL injection in src/query.ts:42"
253
298
  npx @openai/codex-security validate "Possible SQL injection" --effort high
299
+ npx @openai/codex-security verify-fix --linear-issue SEC-123 --json
300
+ npx @openai/codex-security verify-fix --linear-project "Security backlog" --linear-filter '{"state":{"type":{"eq":"completed"}}}' --json
301
+ npx @openai/codex-security verify-fix --scan SCAN_ID --severity high --json
254
302
  npx @openai/codex-security patch /path/outside/repository/findings.json "Missing authorization check in src/routes.ts:18"
255
303
  npx @openai/codex-security patch "Missing authorization check" --effort high
256
304
  npx @openai/codex-security patch OCCURRENCE_ID
@@ -287,6 +335,75 @@ Repeat `--knowledge-base PATH` for multiple files or directories; `bulk-scan`
287
335
  shares them with every repository. Directories are searched recursively for
288
336
  Markdown, text, PDF, and Word (`.docx`) files.
289
337
 
338
+ ### Scan project components
339
+
340
+ `scan --path` runs one scan across the selected paths. Use `scan-components`
341
+ to run a separate standard scan for each component of one local project:
342
+
343
+ ```bash
344
+ npx @openai/codex-security scan-components /path/to/project \
345
+ --component apps/api --component apps/web --component packages/shared \
346
+ --workers 4 --output-dir /path/outside/project/results
347
+ ```
348
+
349
+ Use `--auth chatgpt` or `--auth api-key` to select credentials for planning,
350
+ component scans, and matching. The default is `--auth auto`, as with `scan`.
351
+ The SDK accepts the same choice through `scanOptions.auth`.
352
+
353
+ Use `--auto` instead of `--component` to let Codex propose the split. To review
354
+ or edit it first, save a plan, then run that plan into a new output directory:
355
+
356
+ ```bash
357
+ npx @openai/codex-security scan-components /path/to/project \
358
+ --auto --plan-only --output-dir /path/outside/project/plan
359
+ npx @openai/codex-security scan-components /path/to/project \
360
+ --components-file /path/outside/project/plan/components.json \
361
+ --output-dir /path/outside/project/results
362
+ ```
363
+
364
+ A component can contain several repository-relative paths:
365
+
366
+ ```json
367
+ {
368
+ "components": [
369
+ { "name": "API", "paths": ["apps/api", "packages/auth"] },
370
+ { "name": "Web", "paths": ["apps/web"] }
371
+ ]
372
+ }
373
+ ```
374
+
375
+ Automatic planning uses a local file inventory. In Git repositories it follows
376
+ Git's ignore rules. Each automatic path must cover at least one inventoried file.
377
+ Explicit `--component` and `--components-file` selections keep their existing behavior.
378
+ Inventoried files omitted by the model are added to an
379
+ `Other files` component. No source files are changed during planning.
380
+
381
+ In an interactive terminal, one dashboard shows all components and their scan
382
+ progress. Use the arrow keys to select a component, Enter to view its activity,
383
+ and Esc to return. Other scans continue while you inspect one. Finding counts
384
+ are preliminary until cross-component matching finishes. Use `--headless` for
385
+ plain status lines; CI and redirected output use those automatically.
386
+ Failed or incomplete components are also saved in `retry-components.json`.
387
+ Pass that file to `--components-file` with a new output directory to retry them.
388
+
389
+ Each component keeps its normal scan artifacts under `component-N/`.
390
+ The combined `findings.json` uses the same root-cause matcher as `scans match`.
391
+ It merges high-confidence matches even when their titles, locations, or
392
+ fingerprints differ. Each group keeps its highest-severity finding and all
393
+ original scan and occurrence IDs. Match reasons and uncertain pairs are saved;
394
+ uncertain findings stay separate. `summary.json` records scan coverage and
395
+ whether matching finished. `report.md` links to the component reports.
396
+ These combined files are a project summary, not a new sealed scan. Use the
397
+ individual scan folders with `export` and `publish`.
398
+
399
+ The output directory must be empty and outside the project. Failed components
400
+ do not stop the others. The command saves the available results and exits with
401
+ code `2` if a component fails, coverage is incomplete, or cross-component
402
+ matching fails. `--max-cost` applies to each component scan, not planning,
403
+ cross-component matching, or the whole project. `--model` and `--effort` also
404
+ apply to matching. `--knowledge-base`,
405
+ `--scan-prompt-file`, and `--post-scan-prompt-file` work as they do for bulk scans.
406
+
290
407
  ### Configure deep scans
291
408
 
292
409
  For `scan --mode deep`, `--workers` limits concurrent discovery workers,
@@ -349,11 +466,11 @@ ask whether to open a color-coded finding browser with complete finding details
349
466
  and a separate patch-instructions panel. Use the arrow keys to
350
467
  browse, `Tab` to inspect details, `Space` to select individual findings, `i` to
351
468
  edit instructions for the focused finding, `1`–`4` to select by severity, and
352
- `r` to optionally create a GitHub pull request after patching. Press `Enter` to
353
- patch or `q` to keep the checkout unchanged. Each selected finding runs in its
354
- own saved Codex desktop task. Add `--create-pr` to `scan --patch` or a
469
+ `r` to optionally create a draft GitHub pull request after patching. Press
470
+ `Enter` to patch or `q` to keep the checkout unchanged. Each selected finding
471
+ runs in its own saved Codex desktop task. Add `--create-pr` to `scan --patch` or a
355
472
  saved-finding `patch` command to commit only verified patch files and open a
356
- pull request with `gh`. If the push or pull request fails, run the printed
473
+ draft pull request with `gh`. If the push or pull request fails, run the printed
357
474
  `patch --resume-pr BRANCH` command from the same repository. It uses the saved
358
475
  commit without running Codex again and refuses to publish if the branch changed.
359
476
  JSON scan results include `patchSeverity`. Scan and
@@ -583,6 +700,72 @@ and scans stopped at their configured cost limit do not start another turn.
583
700
  invocation and defaults to `1`. Results remain under `--output-dir`; rerun the
584
701
  same command to resume.
585
702
 
703
+ ### Custom validation
704
+
705
+ Use a prompt file to replace the final validation step in a standard or diff
706
+ scan. The ordinary source review still runs. The supplied text goes directly
707
+ into a separate validation turn and is not sent to discovery workers.
708
+ The SDK adapts the bundled discovery workflow without changing the plugin.
709
+ An incompatible plugin workflow stops the scan instead of using default validation.
710
+
711
+ ```bash
712
+ npx @openai/codex-security scan . --validation-prompt-file validation.md
713
+ ```
714
+
715
+ The SDK accepts the same text as `validationPrompt`:
716
+
717
+ ```ts
718
+ const result = await security.run(repository, {
719
+ validationPrompt:
720
+ "Run scripts/validate.sh, test each candidate through the local API, and stop the test environment when finished.",
721
+ });
722
+ ```
723
+
724
+ Describe setup, allowed test targets, expected evidence, and cleanup in the
725
+ prompt. Refer to credentials through environment variables; do not put secrets
726
+ in the prompt or validation output. There are no separate setup or teardown
727
+ hooks. Deep scans reject this option. Empty candidate sets skip the custom turn.
728
+
729
+ The SDK supplies the candidate IDs and requires a `CustomValidationResult`:
730
+
731
+ ```json
732
+ {
733
+ "status": "complete",
734
+ "reason": null,
735
+ "validations": [
736
+ {
737
+ "candidateId": "candidate-1",
738
+ "validation": {
739
+ "disposition": "reportable",
740
+ "method": "integration test",
741
+ "confidence": "high",
742
+ "confidence_rationale": "The test reproduced the reported behavior.",
743
+ "rubric": "Check the protected operation.",
744
+ "evidence": ["The unauthorized request succeeded."],
745
+ "counterevidence_or_proof_gap": "",
746
+ "remaining_uncertainty": "",
747
+ "artifact_paths": []
748
+ },
749
+ "severity": null,
750
+ "impact": null
751
+ }
752
+ ]
753
+ }
754
+ ```
755
+
756
+ Each candidate needs exactly one result. The disposition is `reportable`,
757
+ `suppressed`, `not_applicable`, or `deferred`. Optional assessment changes use
758
+ `{ "level": "medium", "rationale": "..." }` in `severity` or `impact`; use
759
+ `null` to retain the original assessment. Finding identity and source locations
760
+ do not change. Deferred candidates make coverage partial. Suppressed and
761
+ deferred candidates remain in the saved validation artifacts.
762
+
763
+ The scan directory contains `artifacts/custom-validation/candidates.json` and
764
+ `results.json`. Setup failure, incomplete output, or invalid output leaves the
765
+ scan incomplete. There is no automatic fallback to default validation. When
766
+ rerunning a saved custom-validation scan, supply
767
+ `scans rerun SCAN_ID --validation-prompt-file validation.md` again.
768
+
586
769
  ### Publish completed scans to Linear
587
770
 
588
771
  Publish every finding from a completed standard, deep, or scoped scan to one
@@ -815,6 +998,23 @@ history. Imported content is always literal, and issue URLs must match the
815
998
  selected workspace. Linear access is read-only, and its credentials are not
816
999
  passed to the patch subprocess.
817
1000
 
1001
+ Use `verify-fix` to check whether an existing security fix actually closes its
1002
+ original vulnerability without modifying the repository. Pass a finding
1003
+ description, a saved finding identifier, `--scan SCAN_ID`, `--linear-issue ISSUE`,
1004
+ or `--linear-project "PROJECT"`. Linear intake uses the same credentials and
1005
+ `--linear-filter` options as `patch`; explicitly filter for completed issues when
1006
+ verifying a finished backlog. Verification runs the bundled `verify-fix` skill
1007
+ in a read-only Codex sandbox and reports `fixed`, `still_vulnerable`, or
1008
+ `inconclusive` with supporting evidence for every finding. Use `--json` for
1009
+ structured output. Exit code `0` means every finding is fixed, `1` means at
1010
+ least one finding remains vulnerable, and `2` means a result is inconclusive or
1011
+ verification could not complete.
1012
+
1013
+ Interactive verification shows the same live agent-activity dashboard used by
1014
+ scans and Linear publication. Reasoning, repository commands, and progress are
1015
+ written to stderr; redirected output and CI receive plain progress lines, and
1016
+ JSON results on stdout remain machine-readable.
1017
+
818
1018
  Exit codes are `0` for a completed report-only scan or a passing policy, `1`
819
1019
  for a completed policy violation, `2` for invalid input, incomplete coverage, or
820
1020
  a runtime/export error, `130` for interruption, and `143` for termination.
@@ -3,7 +3,7 @@
3
3
  "codex-security-access": {
4
4
  "id": "connector_openai_codex_security_access",
5
5
  "category": "Security",
6
- "required": true
6
+ "required": false
7
7
  },
8
8
  "linear": {
9
9
  "id": "asdk_app_69a089a326dc8191b32a3f2553f5be2c",
@@ -1,14 +1,18 @@
1
1
  {
2
2
  "mcpServers": {
3
3
  "codex-security": {
4
- "command": "node",
5
- "args": ["./mcp/server.mjs", "--stdio"],
4
+ "command": "./scripts/launch_codex_security_mcp",
5
+ "args": ["--stdio"],
6
6
  "cwd": ".",
7
7
  "env_vars": [
8
8
  "CODEX_HOME",
9
9
  "CODEX_SQLITE_HOME",
10
10
  "CODEX_API_KEY",
11
+ "CODEX_BROWSER_USE_NODE_PATH",
11
12
  "CODEX_CLI_PATH",
13
+ "CODEX_ELECTRON_RESOURCES_PATH",
14
+ "CODEX_MANAGED_PACKAGE_ROOT",
15
+ "CODEX_MCP_NODE_PATH",
12
16
  "OPENROUTER_API_KEY",
13
17
  "FIREWORKS_API_KEY",
14
18
  "AWS_BEARER_TOKEN_BEDROCK",
@@ -28,6 +32,7 @@
28
32
  "AWS_CONTAINER_AUTHORIZATION_TOKEN",
29
33
  "AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE",
30
34
  "PYTHON",
35
+ "PYTHONUTF8",
31
36
  "CODEX_SECURITY_KNOWLEDGE_BASE",
32
37
  "CODEX_SECURITY_DEEP_SCAN_CONFIG_PATH",
33
38
  "CODEX_SECURITY_SCAN_ROOT",
@@ -39,7 +44,8 @@
39
44
  "NO_PROXY",
40
45
  "SSL_CERT_FILE",
41
46
  "REQUESTS_CA_BUNDLE",
42
- "NODE_EXTRA_CA_CERTS"
47
+ "NODE_EXTRA_CA_CERTS",
48
+ "XDG_CACHE_HOME"
43
49
  ],
44
50
  "tool_timeout_sec": 349200
45
51
  }
@@ -60,7 +60,7 @@ When the profile includes remediation patches, present the concrete config delta
60
60
 
61
61
  Some remediation patches have `kind = "host_setting"`. Present those as host-level setup guidance, not as edits to persistent Codex config.
62
62
 
63
- Deep Security Scan uses MCP-owned SDK sessions rather than the parent thread's worker pool. Its preflight does not require a particular parent delegation runtime, ownership, capacity, or depth. Discovery workers inherit the scan's model and run under the verified read-only worker sandbox.
63
+ Deep Security Scan uses MCP-owned SDK sessions rather than the parent thread's worker pool. Its preflight does not require a particular parent delegation runtime, ownership, capacity, or depth. Discovery workers inherit the scan's model and use the reserved `codex_security_deep_scan_worker` permission profile with the parent's supported filesystem denials. The selected Codex executable must support permission-profile configuration and allowance checks. If that command fails to start or exits early, report its path and the tool's diagnostic; do not infer that its version is unsupported. If the tool identifies a missing API, ask the user to update the Codex installation at the reported path: the desktop app for an app-bundled executable, or the selected CLI otherwise. If Codex policy rejects the profile, report the tool's administrator guidance. Do not remove deny rules or select a broader sandbox to work around the error.
64
64
 
65
65
  Do not warn merely because a user's value differs from the profile's suggested patch. Warn or block only when the evaluated capability requirement is unmet.
66
66
 
@@ -8,16 +8,20 @@ The adapter:
8
8
  - stores SARIF separately from the canonical seal
9
9
  - emits SARIF 2.1.0
10
10
  - uses stable `ruleId` values
11
- - keeps rule descriptors stable across scans
11
+ - derives stable, readable rule names from `ruleId`
12
+ - includes categories, CWE tags, and canonical remediation in rule help and result messages
12
13
  - emits repository-relative POSIX paths
13
14
  - keeps the root-control location first for GitHub annotation when available and emits every distinct affected or code-evidence location in `locations`, so vulnerable sinks remain matchable
14
15
  - preserves the semantic fingerprint under `codexSecurity/v1`
15
16
  - emits GitHub's source-line `primaryLocationLineHash` when it can safely hash a bounded regular non-symlink source file inside the available source root
16
17
  - maps categorical severity to SARIF `level`
18
+ - sets GitHub's rule-level `security-severity` to the highest finding score. Unscored critical, high, medium, low, and informational findings use 9.5, 8.0, 5.0, 2.0, and 0.0. A rule with no positive score omits this field. These defaults are display values, not calculated CVSS scores.
17
19
  - preserves a deep scan's canonical `candidateId` under each child result's properties so consumers can group results without changing the original SARIF result presentation
18
20
 
19
21
  Lifecycle, rich validation evidence, attack-path context, and coverage are lossy or omitted in SARIF. Preserve them in semantic JSON.
20
22
 
23
+ SARIF `executionSuccessful` is true only for complete coverage. Incomplete scans retain findings and warnings. Integrations must read the coverage file referenced by `scan.coverageRef`; manifest status `completed` alone does not mean success.
24
+
21
25
  Automatic SARIF export during finalization is best-effort so projection errors cannot invalidate a canonical seal. Use the strict adapter entry point when a consumer requires SARIF and should surface export errors.
22
26
 
23
27
  References:
@@ -5,6 +5,7 @@ from __future__ import annotations
5
5
  import argparse
6
6
  import json
7
7
  import os
8
+ import shutil
8
9
  import sqlite3
9
10
  import sys
10
11
  import tempfile
@@ -25,7 +26,7 @@ from workbench_target import (
25
26
  git_revision,
26
27
  worktree_content_digest,
27
28
  )
28
- from workbench_validation import optional_text, require_uuid, user_text
29
+ from workbench_validation import optional_text, require_uuid, user_context_argument
29
30
 
30
31
  DEEP_SCAN_WORKER_KINDS = ("setup", "discovery", "dedup")
31
32
  DEEP_SCAN_WORKER_STATUSES = ("queued", "running", "succeeded", "failed", "canceled")
@@ -47,7 +48,9 @@ def register_subcommands(subparsers: Any, positive_int: Callable[[str], int]) ->
47
48
  begin_target.add_argument("--scan-id")
48
49
  begin_target.add_argument("--target-path")
49
50
  begin_deep_scan.add_argument("--scope", default=".")
50
- begin_deep_scan.add_argument("--user-context")
51
+ begin_user_context = begin_deep_scan.add_mutually_exclusive_group()
52
+ begin_user_context.add_argument("--user-context")
53
+ begin_user_context.add_argument("--user-context-stdin", action="store_true")
51
54
  begin_deep_scan.add_argument("--scan-root")
52
55
  begin_deep_scan.add_argument("--claim-token")
53
56
  begin_deep_scan.add_argument("--model")
@@ -328,6 +331,31 @@ def finish_staged_file(promotion: tuple[Path, Path, Path | None]) -> None:
328
331
  backup.unlink(missing_ok=True)
329
332
 
330
333
 
334
+ def create_publication_copy(source: str | Path, destination: str | Path) -> None:
335
+ try:
336
+ os.link(source, destination)
337
+ except OSError:
338
+ shutil.copy2(source, destination)
339
+
340
+
341
+ def publication_matches_snapshot(publication: Path, snapshot: Path) -> bool:
342
+ try:
343
+ if publication.samefile(snapshot):
344
+ return True
345
+ if publication.stat().st_size != snapshot.stat().st_size:
346
+ return False
347
+ with publication.open("rb") as published, snapshot.open("rb") as source:
348
+ while True:
349
+ published_chunk = published.read(1024 * 1024)
350
+ source_chunk = source.read(1024 * 1024)
351
+ if published_chunk != source_chunk:
352
+ return False
353
+ if not published_chunk:
354
+ return True
355
+ except OSError:
356
+ return False
357
+
358
+
331
359
  def canonical_discovery_artifacts(scan: sqlite3.Row) -> dict[str, str]:
332
360
  discovery_dir = Path(scan["scan_dir"]) / "artifacts" / "02_discovery"
333
361
  artifacts = {
@@ -769,7 +797,7 @@ def begin_deep_scan_for_target(
769
797
  if target_root == target or target in target_root.parents:
770
798
  raise SystemExit("The scan artifact directory must be outside the selected target.")
771
799
  target_root.mkdir(parents=True, exist_ok=True)
772
- user_context = user_text(args.user_context)
800
+ user_context = user_context_argument(args)
773
801
  model = optional_text(args.model, maximum=200)
774
802
  reasoning_effort = optional_text(args.reasoning_effort, maximum=32)
775
803
  workspace_id = str(uuid.uuid4())
@@ -858,7 +886,7 @@ def begin_deep_scan(connection: sqlite3.Connection, args: argparse.Namespace) ->
858
886
  if thread_id is None:
859
887
  raise SystemExit("thread-id is required.")
860
888
  if args.scan_id:
861
- if args.user_context is not None or args.scope != ".":
889
+ if args.user_context is not None or args.user_context_stdin or args.scope != ".":
862
890
  raise SystemExit("scan-id cannot be combined with target setup fields.")
863
891
  return begin_deep_scan_for_scan(connection, args.scan_id, thread_id, args)
864
892
  if args.claim_token is not None:
@@ -1075,7 +1103,7 @@ def recover_candidate_ledger_publication(connection: sqlite3.Connection, scan_id
1075
1103
  snapshot = Path(reducer["artifact_dir"]) / "canonical" / ledger.name
1076
1104
  if not snapshot.exists():
1077
1105
  continue
1078
- published = ledger.exists() and ledger.samefile(snapshot)
1106
+ published = publication_matches_snapshot(ledger, snapshot)
1079
1107
  interrupted = reducer["status"] != "succeeded"
1080
1108
  if not published and not (interrupted and backups and not ledger.exists()):
1081
1109
  continue
@@ -1577,7 +1605,7 @@ def commit_deep_scan_dedup_locked(
1577
1605
  publication_copy = canonical_path.with_name(
1578
1606
  f".{canonical_path.name}.{uuid.uuid4()}.publish"
1579
1607
  )
1580
- os.link(candidate_ledger_path, publication_copy)
1608
+ create_publication_copy(candidate_ledger_path, publication_copy)
1581
1609
  promotion = promote_staged_file(
1582
1610
  str(publication_copy),
1583
1611
  canonical_candidate_ledger_path,