@openai/codex-security 0.1.16 → 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.
- package/README.md +184 -4
- package/_bundled_plugin/.app.json +1 -1
- package/_bundled_plugin/.mcp.json +9 -3
- 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/config-preflight.md +1 -1
- package/_bundled_plugin/references/sarif-adapter.md +2 -0
- package/_bundled_plugin/scripts/deep_scan_workbench.py +34 -6
- package/_bundled_plugin/scripts/finalize_scan_contract.py +54 -26
- package/_bundled_plugin/scripts/generate_in_scope_files.py +20 -0
- package/_bundled_plugin/scripts/generate_rank_input.py +23 -7
- package/_bundled_plugin/scripts/launch_codex_security_mcp +32 -0
- package/_bundled_plugin/scripts/launch_codex_security_mcp.cmd +27 -0
- package/_bundled_plugin/scripts/workbench_cli.py +22 -15
- package/_bundled_plugin/scripts/workbench_db.py +35 -35
- package/_bundled_plugin/scripts/workbench_progress.py +6 -3
- package/_bundled_plugin/scripts/workbench_scan_history.py +17 -2
- package/_bundled_plugin/scripts/workbench_target.py +36 -5
- package/_bundled_plugin/scripts/workbench_validation.py +9 -0
- package/_bundled_plugin/skills/fix-finding/SKILL.md +17 -1
- package/dist/api.d.ts +16 -1
- package/dist/api.d.ts.map +1 -1
- package/dist/api.js +180 -11
- package/dist/api.js.map +1 -1
- package/dist/cli.d.ts +5 -3
- package/dist/cli.d.ts.map +1 -1
- package/dist/cli.js +335 -43
- package/dist/cli.js.map +1 -1
- package/dist/component-plan.d.ts +15 -0
- package/dist/component-plan.d.ts.map +1 -0
- package/dist/component-plan.js +145 -0
- package/dist/component-plan.js.map +1 -0
- package/dist/component-scan.d.ts +83 -0
- package/dist/component-scan.d.ts.map +1 -0
- package/dist/component-scan.js +279 -0
- package/dist/component-scan.js.map +1 -0
- package/dist/contract.d.ts +8 -2
- package/dist/contract.d.ts.map +1 -1
- package/dist/contract.js +27 -8
- package/dist/contract.js.map +1 -1
- package/dist/cost-model.d.ts +20 -0
- package/dist/cost-model.d.ts.map +1 -0
- package/dist/cost-model.js +86 -0
- package/dist/cost-model.js.map +1 -0
- package/dist/cost.d.ts +2 -11
- package/dist/cost.d.ts.map +1 -1
- package/dist/cost.js +15 -98
- package/dist/cost.js.map +1 -1
- package/dist/custom-validation-prompt.d.ts +4 -0
- package/dist/custom-validation-prompt.d.ts.map +1 -0
- package/dist/custom-validation-prompt.js +94 -0
- package/dist/custom-validation-prompt.js.map +1 -0
- package/dist/custom-validation.d.ts +45 -0
- package/dist/custom-validation.d.ts.map +1 -0
- package/dist/custom-validation.js +292 -0
- package/dist/custom-validation.js.map +1 -0
- package/dist/errors.d.ts +1 -1
- package/dist/errors.d.ts.map +1 -1
- package/dist/errors.js +1 -1
- package/dist/errors.js.map +1 -1
- package/dist/index.d.ts +6 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +2 -0
- package/dist/index.js.map +1 -1
- package/dist/multiscan.d.ts +1 -0
- package/dist/multiscan.d.ts.map +1 -1
- package/dist/multiscan.js +53 -5
- package/dist/multiscan.js.map +1 -1
- package/dist/patch-tui.js +1 -1
- package/dist/patch-tui.js.map +1 -1
- package/dist/publication.d.ts.map +1 -1
- package/dist/publication.js +3 -4
- package/dist/publication.js.map +1 -1
- package/dist/runtime.d.ts +4 -2
- package/dist/runtime.d.ts.map +1 -1
- package/dist/runtime.js +109 -38
- package/dist/runtime.js.map +1 -1
- package/dist/scan-comparison.d.ts +12 -5
- package/dist/scan-comparison.d.ts.map +1 -1
- package/dist/scan-comparison.js +72 -28
- package/dist/scan-comparison.js.map +1 -1
- package/dist/scan-dashboard.d.ts +9 -2
- package/dist/scan-dashboard.d.ts.map +1 -1
- package/dist/scan-dashboard.js +198 -3
- package/dist/scan-dashboard.js.map +1 -1
- package/dist/scan-logs.d.ts.map +1 -1
- package/dist/scan-logs.js +5 -21
- package/dist/scan-logs.js.map +1 -1
- package/dist/scan-sessions.d.ts +4 -0
- package/dist/scan-sessions.d.ts.map +1 -0
- package/dist/scan-sessions.js +35 -0
- package/dist/scan-sessions.js.map +1 -0
- package/dist/targets.d.ts.map +1 -1
- package/dist/targets.js +16 -1
- package/dist/targets.js.map +1 -1
- package/dist/version.d.ts.map +1 -1
- package/dist/version.js +2 -20
- package/dist/version.js.map +1 -1
- package/dist/windows-path.d.ts +3 -0
- package/dist/windows-path.d.ts.map +1 -0
- package/dist/windows-path.js +16 -0
- package/dist/windows-path.js.map +1 -0
- package/dist/worker-progress.d.ts +1 -0
- package/dist/worker-progress.d.ts.map +1 -1
- package/dist/worker-progress.js +12 -0
- package/dist/worker-progress.js.map +1 -1
- 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
|
|
@@ -290,6 +335,75 @@ Repeat `--knowledge-base PATH` for multiple files or directories; `bulk-scan`
|
|
|
290
335
|
shares them with every repository. Directories are searched recursively for
|
|
291
336
|
Markdown, text, PDF, and Word (`.docx`) files.
|
|
292
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
|
+
|
|
293
407
|
### Configure deep scans
|
|
294
408
|
|
|
295
409
|
For `scan --mode deep`, `--workers` limits concurrent discovery workers,
|
|
@@ -352,11 +466,11 @@ ask whether to open a color-coded finding browser with complete finding details
|
|
|
352
466
|
and a separate patch-instructions panel. Use the arrow keys to
|
|
353
467
|
browse, `Tab` to inspect details, `Space` to select individual findings, `i` to
|
|
354
468
|
edit instructions for the focused finding, `1`–`4` to select by severity, and
|
|
355
|
-
`r` to optionally create a GitHub pull request after patching. Press
|
|
356
|
-
patch or `q` to keep the checkout unchanged. Each selected finding
|
|
357
|
-
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
|
|
358
472
|
saved-finding `patch` command to commit only verified patch files and open a
|
|
359
|
-
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
|
|
360
474
|
`patch --resume-pr BRANCH` command from the same repository. It uses the saved
|
|
361
475
|
commit without running Codex again and refuses to publish if the branch changed.
|
|
362
476
|
JSON scan results include `patchSeverity`. Scan and
|
|
@@ -586,6 +700,72 @@ and scans stopped at their configured cost limit do not start another turn.
|
|
|
586
700
|
invocation and defaults to `1`. Results remain under `--output-dir`; rerun the
|
|
587
701
|
same command to resume.
|
|
588
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
|
+
|
|
589
769
|
### Publish completed scans to Linear
|
|
590
770
|
|
|
591
771
|
Publish every finding from a completed standard, deep, or scoped scan to one
|
|
@@ -1,14 +1,18 @@
|
|
|
1
1
|
{
|
|
2
2
|
"mcpServers": {
|
|
3
3
|
"codex-security": {
|
|
4
|
-
"command": "
|
|
5
|
-
"args": ["
|
|
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
|
}
|
|
Binary file
|
|
Binary file
|
|
@@ -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
|
|
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
|
|
|
@@ -20,6 +20,8 @@ The adapter:
|
|
|
20
20
|
|
|
21
21
|
Lifecycle, rich validation evidence, attack-path context, and coverage are lossy or omitted in SARIF. Preserve them in semantic JSON.
|
|
22
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
|
+
|
|
23
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.
|
|
24
26
|
|
|
25
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,
|
|
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.
|
|
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 =
|
|
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
|
|
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
|
-
|
|
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,
|
|
@@ -73,6 +73,10 @@ EXPORT_PATHS = {
|
|
|
73
73
|
"json": "exports/findings.json",
|
|
74
74
|
"sarif": "exports/results.sarif",
|
|
75
75
|
}
|
|
76
|
+
WINDOWS_UNSAFE_PATH_COMPONENT_RE = re.compile(
|
|
77
|
+
r'[<>:"|?*\x00-\x1f]|[ .]$|^(?:con|prn|aux|nul|conin\$|conout\$|com[1-9¹²³]|lpt[1-9¹²³])(?:\..*)?$',
|
|
78
|
+
re.IGNORECASE,
|
|
79
|
+
)
|
|
76
80
|
|
|
77
81
|
|
|
78
82
|
class ContractError(ValueError):
|
|
@@ -225,10 +229,12 @@ def _require_safe_relative_path(value: str, context: str, *, allow_dot: bool = F
|
|
|
225
229
|
path = PurePosixPath(value)
|
|
226
230
|
normalized = path.as_posix()
|
|
227
231
|
if (
|
|
228
|
-
not value
|
|
232
|
+
not value.strip()
|
|
229
233
|
or (normalized == "." and not allow_dot)
|
|
234
|
+
or (len(value) >= 2 and value[0].isalpha() and value[1] == ":")
|
|
230
235
|
or "\\" in value
|
|
231
236
|
or "\0" in value
|
|
237
|
+
or any(ord(character) < 32 for character in value)
|
|
232
238
|
or path.is_absolute()
|
|
233
239
|
or ".." in path.parts
|
|
234
240
|
):
|
|
@@ -236,6 +242,21 @@ def _require_safe_relative_path(value: str, context: str, *, allow_dot: bool = F
|
|
|
236
242
|
return normalized
|
|
237
243
|
|
|
238
244
|
|
|
245
|
+
def _require_portable_relative_path(
|
|
246
|
+
value: str, context: str, *, allow_dot: bool = False
|
|
247
|
+
) -> str:
|
|
248
|
+
normalized = _require_safe_relative_path(value, context, allow_dot=allow_dot)
|
|
249
|
+
if any(_windows_unsafe_path_component(part) for part in value.split("/")):
|
|
250
|
+
raise ContractError(f"{context}: expected a safe scan-relative POSIX path")
|
|
251
|
+
return normalized
|
|
252
|
+
|
|
253
|
+
|
|
254
|
+
def _windows_unsafe_path_component(value: str) -> bool:
|
|
255
|
+
if not value or value == ".":
|
|
256
|
+
return False
|
|
257
|
+
return WINDOWS_UNSAFE_PATH_COMPONENT_RE.search(value) is not None
|
|
258
|
+
|
|
259
|
+
|
|
239
260
|
def _require_scan_directory(scan_dir: Path) -> Path:
|
|
240
261
|
scan_dir = scan_dir.absolute()
|
|
241
262
|
try:
|
|
@@ -347,7 +368,7 @@ def _open_scan_local_directory(root_fd: int, parts: tuple[str, ...], *, create:
|
|
|
347
368
|
|
|
348
369
|
def open_scan_local_file_descriptor(scan_dir: Path, relative_path: str, context: str) -> int:
|
|
349
370
|
scan_dir = _require_scan_directory(scan_dir)
|
|
350
|
-
relative_path =
|
|
371
|
+
relative_path = _require_portable_relative_path(relative_path, context)
|
|
351
372
|
if not _descriptor_relative_reads_available():
|
|
352
373
|
if not _is_windows():
|
|
353
374
|
raise ContractError("scan-local input requires descriptor-relative file operations")
|
|
@@ -478,7 +499,7 @@ def write_scan_local_bytes(
|
|
|
478
499
|
if relative_path in {"", ".", ".."} or "/" in relative_path or "\0" in relative_path:
|
|
479
500
|
raise ContractError("external output path: expected a safe file name")
|
|
480
501
|
else:
|
|
481
|
-
relative_path =
|
|
502
|
+
relative_path = _require_portable_relative_path(relative_path, "scan-local output path")
|
|
482
503
|
path = scan_dir / relative_path
|
|
483
504
|
if not _descriptor_relative_writes_available():
|
|
484
505
|
if not _is_windows():
|
|
@@ -529,7 +550,7 @@ def write_scan_local_bytes(
|
|
|
529
550
|
|
|
530
551
|
def _remove_scan_local_file_if_exists(scan_dir: Path, relative_path: str) -> None:
|
|
531
552
|
scan_dir = _require_scan_directory(scan_dir)
|
|
532
|
-
relative_path =
|
|
553
|
+
relative_path = _require_portable_relative_path(relative_path, "scan-local cleanup path")
|
|
533
554
|
if not _descriptor_relative_writes_available():
|
|
534
555
|
if not _is_windows():
|
|
535
556
|
raise ContractError("scan-local cleanup requires descriptor-relative file operations")
|
|
@@ -936,7 +957,7 @@ def _recover_unsealed_coverage(
|
|
|
936
957
|
try:
|
|
937
958
|
if not isinstance(ref, str):
|
|
938
959
|
raise ContractError(f"{ref_context}: expected a string")
|
|
939
|
-
normalized_ref =
|
|
960
|
+
normalized_ref = _require_portable_relative_path(ref, ref_context)
|
|
940
961
|
if not normalized_ref.startswith("artifacts/"):
|
|
941
962
|
raise ContractError(
|
|
942
963
|
f"{ref_context}: expected a file under artifacts/"
|
|
@@ -1322,7 +1343,9 @@ def _validate_coverage(manifest: dict[str, Any], coverage: dict[str, Any], scan_
|
|
|
1322
1343
|
for ref_index, ref in enumerate(receipt_refs):
|
|
1323
1344
|
if not isinstance(ref, str):
|
|
1324
1345
|
raise ContractError(f"{context}.receiptRefs[{ref_index}]: expected a string")
|
|
1325
|
-
normalized_ref =
|
|
1346
|
+
normalized_ref = _require_portable_relative_path(
|
|
1347
|
+
ref, f"{context}.receiptRefs[{ref_index}]"
|
|
1348
|
+
)
|
|
1326
1349
|
if not normalized_ref.startswith("artifacts/"):
|
|
1327
1350
|
raise ContractError(
|
|
1328
1351
|
f"{context}.receiptRefs[{ref_index}]: expected a file under artifacts/"
|
|
@@ -1367,16 +1390,19 @@ def _validate_manifest(manifest: dict[str, Any]) -> None:
|
|
|
1367
1390
|
if not artifacts:
|
|
1368
1391
|
raise ContractError("manifest.scan.artifacts: expected generated artifact records")
|
|
1369
1392
|
artifact_paths: set[str] = set()
|
|
1393
|
+
artifact_collision_keys: set[str] = set()
|
|
1370
1394
|
for index, artifact in enumerate(artifacts):
|
|
1371
1395
|
context = f"manifest.scan.artifacts[{index}]"
|
|
1372
1396
|
if not isinstance(artifact, dict):
|
|
1373
1397
|
raise ContractError(f"{context}: expected an object")
|
|
1374
|
-
path =
|
|
1398
|
+
path = _require_portable_relative_path(
|
|
1375
1399
|
_require_str(artifact, "path", context), f"{context}.path"
|
|
1376
1400
|
)
|
|
1377
|
-
|
|
1401
|
+
collision_key = path.lower()
|
|
1402
|
+
if collision_key in artifact_collision_keys:
|
|
1378
1403
|
raise ContractError(f"{context}.path: duplicate artifact path")
|
|
1379
1404
|
artifact_paths.add(path)
|
|
1405
|
+
artifact_collision_keys.add(collision_key)
|
|
1380
1406
|
_require_str(artifact, "sha256", context)
|
|
1381
1407
|
_require_str(artifact, "mediaType", context)
|
|
1382
1408
|
for required_path in ("findings.json", "coverage.json"):
|
|
@@ -1593,6 +1619,7 @@ def _legacy_sealed_findings_for_validation(findings: dict[str, Any]) -> dict[str
|
|
|
1593
1619
|
and evidence["id"]
|
|
1594
1620
|
}
|
|
1595
1621
|
for section_name, list_fields in (
|
|
1622
|
+
("rootCause", ("evidenceRefs", "evidence_refs")),
|
|
1596
1623
|
("root_cause", ("evidenceRefs", "evidence_refs")),
|
|
1597
1624
|
(
|
|
1598
1625
|
"validation",
|
|
@@ -2146,7 +2173,7 @@ def _validate_sarif(sarif: dict[str, Any]) -> None:
|
|
|
2146
2173
|
def _artifact_record(
|
|
2147
2174
|
scan_dir: Path, relative_path: str, media_type: str, contents: bytes | None = None
|
|
2148
2175
|
) -> dict[str, str]:
|
|
2149
|
-
relative_path =
|
|
2176
|
+
relative_path = _require_portable_relative_path(relative_path, "artifact path")
|
|
2150
2177
|
if contents is not None:
|
|
2151
2178
|
_require_scan_local_file(scan_dir, relative_path, relative_path)
|
|
2152
2179
|
return {
|
|
@@ -2167,7 +2194,7 @@ def _coverage_receipt_refs(coverage: dict[str, Any]) -> list[str]:
|
|
|
2167
2194
|
|
|
2168
2195
|
def _validate_sealed_coverage_receipts(scan: dict[str, Any], coverage: dict[str, Any]) -> None:
|
|
2169
2196
|
artifact_paths = {
|
|
2170
|
-
|
|
2197
|
+
_require_portable_relative_path(artifact["path"], "sealed artifact path")
|
|
2171
2198
|
for artifact in scan["artifacts"]
|
|
2172
2199
|
}
|
|
2173
2200
|
for ref in _coverage_receipt_refs(coverage):
|
|
@@ -2190,16 +2217,19 @@ def _validate_existing_seal(
|
|
|
2190
2217
|
if not isinstance(artifacts, list) or not artifacts:
|
|
2191
2218
|
raise ContractError("manifest.scan.artifacts: sealed manifest requires artifact records")
|
|
2192
2219
|
artifact_paths: set[str] = set()
|
|
2220
|
+
artifact_collision_keys: set[str] = set()
|
|
2193
2221
|
for index, artifact in enumerate(artifacts):
|
|
2194
2222
|
context = f"manifest.scan.artifacts[{index}]"
|
|
2195
2223
|
if not isinstance(artifact, dict):
|
|
2196
2224
|
raise ContractError(f"{context}: expected an object")
|
|
2197
|
-
path =
|
|
2225
|
+
path = _require_portable_relative_path(
|
|
2198
2226
|
_require_str(artifact, "path", context), f"{context}.path"
|
|
2199
2227
|
)
|
|
2200
|
-
|
|
2228
|
+
collision_key = path.lower()
|
|
2229
|
+
if collision_key in artifact_collision_keys:
|
|
2201
2230
|
raise ContractError(f"{context}.path: duplicate artifact path")
|
|
2202
2231
|
artifact_paths.add(path)
|
|
2232
|
+
artifact_collision_keys.add(collision_key)
|
|
2203
2233
|
expected_sha256 = _require_str(artifact, "sha256", context)
|
|
2204
2234
|
contents = (artifact_contents or {}).get(path)
|
|
2205
2235
|
actual_sha256 = (
|
|
@@ -2260,19 +2290,17 @@ def build_sarif_projection(
|
|
|
2260
2290
|
raise ContractError("source root: expected an existing directory")
|
|
2261
2291
|
manifest, findings, coverage, _ = _read_sealed_scan(scan_dir, schema_dir, "SARIF projection")
|
|
2262
2292
|
sarif = build_sarif(manifest, findings, source_root)
|
|
2263
|
-
|
|
2264
|
-
|
|
2265
|
-
|
|
2266
|
-
|
|
2267
|
-
|
|
2268
|
-
|
|
2269
|
-
|
|
2270
|
-
|
|
2271
|
-
|
|
2272
|
-
|
|
2273
|
-
|
|
2274
|
-
}
|
|
2275
|
-
]
|
|
2293
|
+
run = sarif["runs"][0]
|
|
2294
|
+
completeness = coverage["completeness"]
|
|
2295
|
+
run["invocations"] = [{"executionSuccessful": completeness == "complete"}]
|
|
2296
|
+
if completeness != "complete":
|
|
2297
|
+
run["properties"]["codexSecurityCoverageCompleteness"] = completeness
|
|
2298
|
+
reasons = [item["reason"] for item in coverage["deferred"]] or [
|
|
2299
|
+
f"Scan coverage is {completeness}; results may be incomplete."
|
|
2300
|
+
]
|
|
2301
|
+
run["invocations"][0]["toolExecutionNotifications"] = [
|
|
2302
|
+
{"level": "warning", "message": {"text": reason}} for reason in reasons
|
|
2303
|
+
]
|
|
2276
2304
|
_validate_sarif(sarif)
|
|
2277
2305
|
return sarif
|
|
2278
2306
|
|
|
@@ -2424,7 +2452,7 @@ def write_export_output(scan_dir: Path, output: Path, export_format: str, conten
|
|
|
2424
2452
|
scan = _require_dict(manifest, "scan", "manifest")
|
|
2425
2453
|
artifacts = _require_list(scan, "artifacts", "manifest.scan")
|
|
2426
2454
|
artifact_paths = [
|
|
2427
|
-
|
|
2455
|
+
_require_portable_relative_path(
|
|
2428
2456
|
_require_str(artifact, "path", f"manifest.scan.artifacts[{index}]"),
|
|
2429
2457
|
f"manifest.scan.artifacts[{index}].path",
|
|
2430
2458
|
)
|
|
@@ -15,6 +15,21 @@ class InventoryError(ValueError):
|
|
|
15
15
|
"""Raised when the repository, scope, or inventory cannot be used safely."""
|
|
16
16
|
|
|
17
17
|
|
|
18
|
+
def windows_stream_component(path: Path) -> str | None:
|
|
19
|
+
"""Return the first NTFS alternate-data-stream component."""
|
|
20
|
+
|
|
21
|
+
if os.name != "nt":
|
|
22
|
+
return None
|
|
23
|
+
return next(
|
|
24
|
+
(
|
|
25
|
+
component
|
|
26
|
+
for component in path.parts
|
|
27
|
+
if component != path.anchor and ":" in component
|
|
28
|
+
),
|
|
29
|
+
None,
|
|
30
|
+
)
|
|
31
|
+
|
|
32
|
+
|
|
18
33
|
def resolve_repository(value: str) -> Path:
|
|
19
34
|
"""Resolve the repository once so every scope is bound to its real root."""
|
|
20
35
|
try:
|
|
@@ -32,6 +47,11 @@ def resolve_scope(repository: Path, value: str) -> str:
|
|
|
32
47
|
raise InventoryError("--scope: expected a non-empty file or directory")
|
|
33
48
|
|
|
34
49
|
requested = Path(value).expanduser()
|
|
50
|
+
stream = windows_stream_component(requested)
|
|
51
|
+
if stream is not None:
|
|
52
|
+
raise InventoryError(
|
|
53
|
+
f"--scope: NTFS alternate data streams are not supported: {stream}"
|
|
54
|
+
)
|
|
35
55
|
scope = requested if requested.is_absolute() else repository / requested
|
|
36
56
|
try:
|
|
37
57
|
resolved = scope.resolve(strict=True)
|