@openai/codex-security 0.1.2 → 0.1.4
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 +203 -9
- package/_bundled_plugin/references/scan-contract.md +2 -0
- package/_bundled_plugin/scripts/deep_scan_workbench.py +1 -1
- package/_bundled_plugin/scripts/finalize_scan_contract.py +289 -4
- package/_bundled_plugin/scripts/workbench_cli.py +4 -0
- package/_bundled_plugin/scripts/workbench_db.py +44 -24
- package/_bundled_plugin/scripts/workbench_scan_start.py +13 -0
- package/dist/api.d.ts +2 -1
- package/dist/api.d.ts.map +1 -1
- package/dist/api.js +173 -51
- package/dist/api.js.map +1 -1
- package/dist/bulk-scan-discovery.js +10 -11
- package/dist/bulk-scan-discovery.js.map +1 -1
- package/dist/cli.d.ts +3 -2
- package/dist/cli.d.ts.map +1 -1
- package/dist/cli.js +116 -49
- package/dist/cli.js.map +1 -1
- package/dist/config.d.ts.map +1 -1
- package/dist/config.js +33 -1
- package/dist/config.js.map +1 -1
- package/dist/contract.d.ts +1 -0
- package/dist/contract.d.ts.map +1 -1
- package/dist/contract.js +19 -22
- package/dist/contract.js.map +1 -1
- package/dist/runtime.d.ts +11 -0
- package/dist/runtime.d.ts.map +1 -1
- package/dist/runtime.js +462 -8
- package/dist/runtime.js.map +1 -1
- package/dist/scan-comparison.d.ts +2 -0
- package/dist/scan-comparison.d.ts.map +1 -1
- package/dist/scan-comparison.js +26 -2
- package/dist/scan-comparison.js.map +1 -1
- package/dist/trusted-executable.js +1 -1
- package/dist/trusted-executable.js.map +1 -1
- package/package.json +5 -4
package/README.md
CHANGED
|
@@ -15,10 +15,11 @@ npm install @openai/codex-security
|
|
|
15
15
|
npx @openai/codex-security --version
|
|
16
16
|
```
|
|
17
17
|
|
|
18
|
-
The package supports macOS, Linux, and Windows and requires Node.js 22 or
|
|
19
|
-
later
|
|
20
|
-
|
|
21
|
-
|
|
18
|
+
The package supports macOS, Linux, and Windows and requires Node.js 22.13.0 or
|
|
19
|
+
later in the 22.x release line, Node.js 24.x, or Node.js 26.x. Scanning and
|
|
20
|
+
exporting findings also require Python 3.10 or later. If you use Python 3.10,
|
|
21
|
+
install the `tomli` package. Select another interpreter with `--python`,
|
|
22
|
+
`pythonPath`, or `PYTHON` when needed.
|
|
22
23
|
|
|
23
24
|
When a newer version is available, the CLI shows the update command for your
|
|
24
25
|
installation method. Set `CODEX_SECURITY_NO_UPDATE_NOTICE=1` to hide the
|
|
@@ -56,6 +57,39 @@ Results can contain source excerpts, vulnerability details, and reproduction
|
|
|
56
57
|
steps. Keep result directories and saved reports outside the repository and
|
|
57
58
|
limit access to authorized reviewers.
|
|
58
59
|
|
|
60
|
+
### SDK configuration and scan options
|
|
61
|
+
|
|
62
|
+
Pass runtime configuration to the `CodexSecurity` constructor:
|
|
63
|
+
|
|
64
|
+
| Option | Description |
|
|
65
|
+
| ---------------- | --------------------------------------------------------------------------- |
|
|
66
|
+
| `pluginPath` | Use a Codex Security plugin directory or ZIP instead of the bundled plugin. |
|
|
67
|
+
| `pythonPath` | Select the Python interpreter before consulting `PYTHON`. |
|
|
68
|
+
| `codexOverrides` | Deep-merge supported settings into the isolated Codex configuration. |
|
|
69
|
+
|
|
70
|
+
Pass scan configuration to `security.run(repository, options)` or
|
|
71
|
+
`security.preflight(repository, options)`:
|
|
72
|
+
|
|
73
|
+
| Option | Description |
|
|
74
|
+
| ----------------------- | ------------------------------------------------------------------------------------- |
|
|
75
|
+
| `auth` | Select `"auto"`, `"chatgpt"`, or `"api-key"`. |
|
|
76
|
+
| `target` | Select a repository, repository-relative paths, committed diff, or working-tree diff. |
|
|
77
|
+
| `mode` | Select `"standard"` or `"deep"`; deep mode supports repositories and paths. |
|
|
78
|
+
| `knowledgeBasePaths` | Add architecture documents, security policies, threat models, or directories. |
|
|
79
|
+
| `outputDir` | Choose an artifact directory outside the enclosing Git worktree. |
|
|
80
|
+
| `archiveExisting` | Archive results already in `outputDir` before starting a scan. |
|
|
81
|
+
| `maxCostUsd` | Stop after the estimated model cost exceeds a positive USD amount. |
|
|
82
|
+
| `failureSeverity` | Record a finding-severity policy in the saved scan recipe. |
|
|
83
|
+
| `parentScanId` | Link a rerun to an existing parent scan. |
|
|
84
|
+
| `expectedPluginVersion` | Require the original plugin version when replaying a scan. |
|
|
85
|
+
| `signal` | Cancel a scan with an `AbortSignal`. |
|
|
86
|
+
|
|
87
|
+
Progress and lifecycle callbacks are `onAuthentication`, `onCost`,
|
|
88
|
+
`onOutputArchived`, `onOutputDirReady`, `onScanStarted`, `onReconnect`,
|
|
89
|
+
`onWorkerStatus`, `onWarning`, and `onObserverError`. Preflight does not start
|
|
90
|
+
the runtime, authenticate, resolve Python, inspect the plugin, or run those
|
|
91
|
+
scan-lifecycle callbacks.
|
|
92
|
+
|
|
59
93
|
## Authentication
|
|
60
94
|
|
|
61
95
|
For local use, sign in with ChatGPT:
|
|
@@ -78,6 +112,14 @@ pass it on stdin:
|
|
|
78
112
|
printenv OPENAI_API_KEY | npx @openai/codex-security login --with-api-key
|
|
79
113
|
```
|
|
80
114
|
|
|
115
|
+
Environment API keys are supplied directly to the current scan and are never
|
|
116
|
+
saved to the Codex credential home or system keyring. Only an explicit
|
|
117
|
+
`login --with-api-key` stores an API key.
|
|
118
|
+
|
|
119
|
+
To pass a Codex access token explicitly, use
|
|
120
|
+
`login --with-access-token` and provide the token on stdin. An access token
|
|
121
|
+
environment variable is not automatically used as a scan API key.
|
|
122
|
+
|
|
81
123
|
On Windows, set the API key in PowerShell:
|
|
82
124
|
|
|
83
125
|
```powershell
|
|
@@ -85,10 +127,16 @@ $env:OPENAI_API_KEY = "<your-api-key>"
|
|
|
85
127
|
npx @openai/codex-security scan C:\code\repository
|
|
86
128
|
```
|
|
87
129
|
|
|
88
|
-
Check or remove the stored sign-in with `npx @openai/codex-security login status`
|
|
89
|
-
`npx @openai/codex-security logout`. Codex Security
|
|
90
|
-
|
|
91
|
-
|
|
130
|
+
Check or remove the stored sign-in with `npx @openai/codex-security login status`
|
|
131
|
+
and `npx @openai/codex-security logout`. Codex Security keeps its sign-in in a
|
|
132
|
+
private, stable Codex home at `$CODEX_SECURITY_STATE_DIR/codex-home`, or at
|
|
133
|
+
`$CODEX_HOME/state/plugins/codex-security/codex-home` when no state directory is
|
|
134
|
+
configured. Login, status, logout, and scans use the same home. Codex manages
|
|
135
|
+
credentials using its configured file or system-keyring backend and honors
|
|
136
|
+
managed-device policies. An existing file-based Codex sign-in is imported only
|
|
137
|
+
when the dedicated home does not already contain stored credentials. Logging
|
|
138
|
+
out prevents later scans from automatically reimporting that ambient sign-in
|
|
139
|
+
until you explicitly log in again.
|
|
92
140
|
|
|
93
141
|
An environment API key takes precedence over a stored sign-in by default.
|
|
94
142
|
When both a stored ChatGPT sign-in and an environment API key are available, an
|
|
@@ -197,6 +245,127 @@ the implied provider. Use `--model gpt-5.6-terra` to switch models and
|
|
|
197
245
|
`--codex KEY=VALUE` for other Codex settings; existing
|
|
198
246
|
`--codex 'model_reasoning_effort="high"'` overrides remain supported.
|
|
199
247
|
|
|
248
|
+
### Runtime configuration and worker limits
|
|
249
|
+
|
|
250
|
+
The standalone CLI and SDK do not load an unrelated user or repository Codex
|
|
251
|
+
configuration. Each scan starts with a private runtime and these Codex
|
|
252
|
+
defaults:
|
|
253
|
+
|
|
254
|
+
```toml
|
|
255
|
+
cli_auth_credentials_store = "file"
|
|
256
|
+
model = "gpt-5.6-sol"
|
|
257
|
+
model_reasoning_effort = "xhigh"
|
|
258
|
+
|
|
259
|
+
[features]
|
|
260
|
+
plugins = true
|
|
261
|
+
goals = true
|
|
262
|
+
|
|
263
|
+
[features.multi_agent_v2]
|
|
264
|
+
enabled = true
|
|
265
|
+
max_concurrent_threads_per_session = 9
|
|
266
|
+
|
|
267
|
+
[windows]
|
|
268
|
+
sandbox = "unelevated"
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
Use `--model` and `--effort` for model selection. Repeat
|
|
272
|
+
`--codex KEY=VALUE` to deep-merge other TOML values into this isolated
|
|
273
|
+
configuration:
|
|
274
|
+
|
|
275
|
+
```bash
|
|
276
|
+
npx @openai/codex-security scan . \
|
|
277
|
+
--model gpt-5.6-terra \
|
|
278
|
+
--effort high \
|
|
279
|
+
--codex features.multi_agent_v2.max_concurrent_threads_per_session=4
|
|
280
|
+
```
|
|
281
|
+
|
|
282
|
+
The session thread limit includes the parent agent: the default of `9`
|
|
283
|
+
provides up to eight delegated worker slots. This limit is separate from
|
|
284
|
+
`bulk-scan --workers`, which controls how many repositories run concurrently.
|
|
285
|
+
A configured limit is a maximum, not evidence that every worker started.
|
|
286
|
+
|
|
287
|
+
Quote string values as TOML, for example
|
|
288
|
+
`--codex 'model_reasoning_effort="high"'`. Do not pass both `--model` and
|
|
289
|
+
`--codex 'model="..."'`, or both `--effort` and
|
|
290
|
+
`--codex 'model_reasoning_effort="..."'`: conflicting or repeated keys are
|
|
291
|
+
rejected.
|
|
292
|
+
|
|
293
|
+
Plugin and marketplace loading belong to Codex Security. Overrides of
|
|
294
|
+
`plugins`, `marketplaces`, or `features.plugins`, including profile-specific
|
|
295
|
+
plugin overrides, are rejected; choose `--plugin-path` instead. Native
|
|
296
|
+
multi-agent v2 must remain enabled. The legacy `agents.max_threads` setting
|
|
297
|
+
and `features.multi_agent_v2.enabled=false` are incompatible and rejected.
|
|
298
|
+
`validate` and `patch` accept `--effort` and only the `model` and
|
|
299
|
+
`model_reasoning_effort` `--codex` keys; they do not accept general scan
|
|
300
|
+
runtime overrides.
|
|
301
|
+
|
|
302
|
+
These overrides do not change the scan's approval policy or filesystem
|
|
303
|
+
permissions. See [Local security model](#local-security-model).
|
|
304
|
+
|
|
305
|
+
### Deep-scan engine configuration
|
|
306
|
+
|
|
307
|
+
When the bundled plugin runs in a normal Codex host, its repeated-discovery
|
|
308
|
+
engine reads `$CODEX_HOME/codex-security/config.toml`, defaulting to
|
|
309
|
+
`~/.codex/codex-security/config.toml`:
|
|
310
|
+
|
|
311
|
+
```toml
|
|
312
|
+
[deep_scan]
|
|
313
|
+
workers = "auto"
|
|
314
|
+
subagents = 3
|
|
315
|
+
stop_after_no_new = 6
|
|
316
|
+
max_discovery_runs = 60
|
|
317
|
+
```
|
|
318
|
+
|
|
319
|
+
`workers = "auto"` uses half the available parallelism, with a minimum of one
|
|
320
|
+
and a maximum of six discovery workers. Set `workers` to a positive integer to
|
|
321
|
+
choose an explicit count. `subagents` must be a nonnegative integer;
|
|
322
|
+
`stop_after_no_new` and `max_discovery_runs` must be positive integers. Unknown
|
|
323
|
+
`[deep_scan]` keys are rejected.
|
|
324
|
+
|
|
325
|
+
These settings are separate from Codex's
|
|
326
|
+
`features.multi_agent_v2.max_concurrent_threads_per_session` and
|
|
327
|
+
`bulk-scan --workers`. Importantly, standalone CLI and SDK scans create an
|
|
328
|
+
isolated `CODEX_HOME` and do not import the ambient deep-scan configuration
|
|
329
|
+
file. Consequently, `scan --mode deep` currently uses the deep engine's
|
|
330
|
+
defaults; there are no standalone CLI flags for these four settings. Use
|
|
331
|
+
`--codex` to adjust the Codex session thread limit, not to set `[deep_scan]`
|
|
332
|
+
values.
|
|
333
|
+
|
|
334
|
+
### Environment variables
|
|
335
|
+
|
|
336
|
+
The CLI and SDK recognize the following user-configurable environment:
|
|
337
|
+
|
|
338
|
+
| Variable | Effect |
|
|
339
|
+
| --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
|
|
340
|
+
| `OPENAI_API_KEY`, `CODEX_API_KEY` | Scan authentication; `OPENAI_API_KEY` wins when both are present. |
|
|
341
|
+
| `CODEX_SECURITY_STATE_DIR` | Override the private scan-history, workbench, and default artifact directory. |
|
|
342
|
+
| `CODEX_HOME` | Set the ambient Codex home for file-backed sign-in and default state; defaults to `~/.codex`. |
|
|
343
|
+
| `PYTHON` | Select a Python interpreter when `--python` or SDK `pythonPath` is not set. |
|
|
344
|
+
| `GH_HOST` | Select a GitHub Enterprise host during interactive `bulk-scan` discovery. |
|
|
345
|
+
| `CODEX_SECURITY_NO_UPDATE_NOTICE`, `NO_UPDATE_NOTIFIER` | Disable interactive update notices when either variable is defined. |
|
|
346
|
+
| `CODEX_SECURITY_NPM_REGISTRY`, `npm_config_registry`, `NPM_CONFIG_REGISTRY` | Select the update-check registry, in the listed precedence order. |
|
|
347
|
+
| `CI` | Disable interactive update notices in automated environments. |
|
|
348
|
+
| `NO_COLOR`, `TERM` | Disable colored scan-history output when `NO_COLOR` is defined or `TERM=dumb`. |
|
|
349
|
+
|
|
350
|
+
Interpreter discovery uses `--python` or `pythonPath` first, then `PYTHON`,
|
|
351
|
+
the managed Codex runtime, and finally `python3` or `python` from `PATH`.
|
|
352
|
+
`CODEX_SECURITY_STATE_DIR` takes precedence over `CODEX_HOME`; keep both
|
|
353
|
+
state and result paths outside the scanned repository.
|
|
354
|
+
|
|
355
|
+
The repository's Docker Compose workflow additionally recognizes
|
|
356
|
+
`CODEX_SECURITY_IMAGE`, `CODEX_SECURITY_USER`, `CODEX_SECURITY_SECCOMP`,
|
|
357
|
+
`CODEX_SECURITY_CSV`, `CODEX_SECURITY_RESULTS`, and `CODEX_SECURITY_STATE` for
|
|
358
|
+
its image, runtime user, seccomp profile, input, results, and state mounts.
|
|
359
|
+
Provide `GH_TOKEN` or `GITHUB_TOKEN` for private GitHub checkouts and
|
|
360
|
+
`CODEX_SECURITY_GIT_HOST` for a GitHub Enterprise host in the container.
|
|
361
|
+
These container settings are distinct from standalone CLI flags and
|
|
362
|
+
interactive discovery's `GH_HOST`.
|
|
363
|
+
|
|
364
|
+
Variables such as `CODEX_SECURITY_SCAN_ID`, `CODEX_SECURITY_SCAN_DIR`,
|
|
365
|
+
`CODEX_SECURITY_PLUGIN_ROOT`, `CODEX_SECURITY_CONFIG_PATH`, and
|
|
366
|
+
`CODEX_SECURITY_TARGET_PATHS_FILE` are generated by an active scan. They are
|
|
367
|
+
internal runtime data, not supported user configuration.
|
|
368
|
+
|
|
200
369
|
Scan progress identifies the requested paths and reports actual ranking,
|
|
201
370
|
file-review, validation, and attack-path phases as they become available.
|
|
202
371
|
Completion summarizes findings, severity, coverage, elapsed time, available
|
|
@@ -241,7 +410,8 @@ Results remain under `--output-dir`; rerun the same command to resume.
|
|
|
241
410
|
`npx @openai/codex-security scans list` lists scans for the current repository. Pass a
|
|
242
411
|
repository path to inspect another checkout, `--scan-root DIR` to list scans
|
|
243
412
|
whose artifacts are under a particular root. `scans show SCAN_ID` includes the
|
|
244
|
-
scan configuration, results, coverage, and artifact locations.
|
|
413
|
+
scan configuration, results, coverage, and artifact locations. Add
|
|
414
|
+
`--show-linked-findings` to include finding links from previous scans.
|
|
245
415
|
|
|
246
416
|
Every scan history command accepts a full scan ID or a unique prefix of at
|
|
247
417
|
least eight characters.
|
|
@@ -344,6 +514,30 @@ Progress remains on stderr so JSON output stays machine readable. Network
|
|
|
344
514
|
failures and rate limits remain retryable; definitive authentication and model
|
|
345
515
|
authorization failures stop immediately.
|
|
346
516
|
|
|
517
|
+
## Local security model
|
|
518
|
+
|
|
519
|
+
Codex Security runs with your local operating-system permissions. Scan only
|
|
520
|
+
repositories you trust and either own or are authorized to assess. Your
|
|
521
|
+
repository, Git installation, configured tools, and other scans under the
|
|
522
|
+
same account are not separate security principals.
|
|
523
|
+
|
|
524
|
+
Every scan uses the `codex_security_scan` filesystem profile and
|
|
525
|
+
`approvalPolicy: "never"`. It can read the local filesystem and write to
|
|
526
|
+
workspace roots and the selected scan state directory. Scans do not request
|
|
527
|
+
interactive approval. Setting `approval_policy`, `sandbox_mode`, or permissions
|
|
528
|
+
through `--codex` or SDK `codexOverrides` does not replace these controls or
|
|
529
|
+
make them more restrictive. Independently enforced host and network
|
|
530
|
+
restrictions still apply.
|
|
531
|
+
|
|
532
|
+
Scan and workbench subprocesses can inherit your environment, including
|
|
533
|
+
unrelated API tokens and cloud credentials. Start a scan with only the
|
|
534
|
+
credentials it needs.
|
|
535
|
+
|
|
536
|
+
The scanner must stay within the target and output paths you authorize and
|
|
537
|
+
must not disclose private data beyond the operation you requested. Its results
|
|
538
|
+
must accurately report the scan mode, reviewed files, and exclusions. Consult
|
|
539
|
+
the security policy for the full threat model and private reporting process.
|
|
540
|
+
|
|
347
541
|
## Documentation and security
|
|
348
542
|
|
|
349
543
|
- [CLI quickstart](https://developers.openai.com/codex/security/cli)
|
|
@@ -31,6 +31,8 @@ A sealed manifest records the completed timestamp and hashes for the canonical d
|
|
|
31
31
|
Choose the target kind based on the reviewed content, not the scan invocation:
|
|
32
32
|
`git_worktree` for a checked-out Git workspace, `directory_snapshot` for a non-Git directory, `git_diff` for a Git-backed change set, and `git_revision` for an exact immutable Git tree.
|
|
33
33
|
|
|
34
|
+
For a workbench-backed scan, use the recorded target contract instead of inferring the kind from the checkout. A clean Git checkout has `allowedKinds: ["git_revision"]`: use its recorded revision and omit `snapshotDigest`. A dirty checkout has `allowedKinds: ["git_worktree"]`: copy `requiredSnapshotDigest` exactly.
|
|
35
|
+
|
|
34
36
|
| Kind | Required snapshot fields |
|
|
35
37
|
| --- | --- |
|
|
36
38
|
| `git_revision` | `revision` |
|
|
@@ -239,7 +239,7 @@ def deep_scan_path(
|
|
|
239
239
|
resolved.relative_to(scan_dir)
|
|
240
240
|
except (OSError, RuntimeError, ValueError) as exc:
|
|
241
241
|
raise SystemExit(f"{label} must be an existing path inside the scan directory.") from exc
|
|
242
|
-
if resolved != supplied.absolute():
|
|
242
|
+
if os.path.normcase(resolved) != os.path.normcase(supplied.absolute()):
|
|
243
243
|
raise SystemExit(f"{label} must be a canonical non-symlink path.")
|
|
244
244
|
if kind == "file" and not resolved.is_file():
|
|
245
245
|
raise SystemExit(f"{label} must be a regular file.")
|
|
@@ -316,7 +316,7 @@ def _require_scan_directory(scan_dir: Path) -> Path:
|
|
|
316
316
|
resolved = scan_dir.resolve(strict=True)
|
|
317
317
|
except OSError as exc:
|
|
318
318
|
raise ContractError("scan directory: expected an existing non-symlink directory") from exc
|
|
319
|
-
if resolved != scan_dir:
|
|
319
|
+
if os.path.normcase(resolved) != os.path.normcase(scan_dir):
|
|
320
320
|
raise ContractError("scan directory: expected a canonical non-symlink directory")
|
|
321
321
|
return resolved
|
|
322
322
|
|
|
@@ -327,7 +327,10 @@ def _validate_scan_local_output_path(scan_dir: Path, path: Path, relative_path:
|
|
|
327
327
|
resolved_parent.relative_to(scan_dir)
|
|
328
328
|
except (OSError, RuntimeError, ValueError) as exc:
|
|
329
329
|
raise ContractError(f"{relative_path}: expected a path inside the scan directory") from exc
|
|
330
|
-
if
|
|
330
|
+
if (
|
|
331
|
+
os.path.normcase(resolved_parent) != os.path.normcase(path.parent)
|
|
332
|
+
or path.is_symlink()
|
|
333
|
+
):
|
|
331
334
|
raise ContractError(
|
|
332
335
|
f"{relative_path}: expected a non-symlink path inside the scan directory"
|
|
333
336
|
)
|
|
@@ -767,6 +770,267 @@ def _populate_unsealed_finding_identities(
|
|
|
767
770
|
finding["fingerprints"] = fingerprints
|
|
768
771
|
|
|
769
772
|
|
|
773
|
+
def _finding_strength(finding: dict[str, Any]) -> tuple[int, int, int]:
|
|
774
|
+
return (
|
|
775
|
+
("informational", "low", "medium", "high", "critical").index(finding["severity"]["level"]),
|
|
776
|
+
("low", "medium", "high").index(finding["confidence"]["level"]),
|
|
777
|
+
len(finding.get("codeEvidence") or []),
|
|
778
|
+
)
|
|
779
|
+
|
|
780
|
+
|
|
781
|
+
def _recover_unsealed_findings(
|
|
782
|
+
manifest: dict[str, Any],
|
|
783
|
+
findings: dict[str, Any],
|
|
784
|
+
schema_dir: Path,
|
|
785
|
+
scan_dir: Path,
|
|
786
|
+
warnings: list[str],
|
|
787
|
+
) -> list[str]:
|
|
788
|
+
schema = _read_json(schema_dir / "findings.schema.json")
|
|
789
|
+
_require_safe_schema(schema, "findings.schema.json")
|
|
790
|
+
properties = _require_dict(schema, "properties", "findings.schema")
|
|
791
|
+
finding_array = _require_dict(properties, "findings", "findings.schema.properties")
|
|
792
|
+
finding_schema = _require_dict(finding_array, "items", "findings.schema.properties.findings")
|
|
793
|
+
finding_properties = _require_dict(
|
|
794
|
+
finding_schema, "properties", "findings.schema.properties.findings.items"
|
|
795
|
+
)
|
|
796
|
+
writeup_schema = _require_dict(
|
|
797
|
+
finding_properties, "writeup", "findings.schema.properties.findings.items.properties"
|
|
798
|
+
)
|
|
799
|
+
scan = _require_dict(manifest, "scan", "manifest")
|
|
800
|
+
scan_id = _require_str(scan, "id", "manifest.scan")
|
|
801
|
+
if findings.get("scanId") != scan_id:
|
|
802
|
+
raise ContractError("findings.scanId: must match manifest scan id")
|
|
803
|
+
|
|
804
|
+
recovered: list[dict[str, Any]] = []
|
|
805
|
+
discarded: list[str] = []
|
|
806
|
+
finding_positions: dict[str, int] = {}
|
|
807
|
+
writeup_paths: set[str] = set()
|
|
808
|
+
for index, finding in enumerate(_require_list(findings, "findings", "findings")):
|
|
809
|
+
context = f"findings.findings[{index}]"
|
|
810
|
+
try:
|
|
811
|
+
if not isinstance(finding, dict):
|
|
812
|
+
raise ContractError(f"{context}: expected an object")
|
|
813
|
+
identity = _require_dict(finding, "identity", context)
|
|
814
|
+
fields: list[tuple[dict[str, Any], str, str, str]] = [
|
|
815
|
+
(finding, "ruleId", context, "rule identifier"),
|
|
816
|
+
(identity, "anchor", f"{context}.identity", "semantic anchor"),
|
|
817
|
+
]
|
|
818
|
+
if "instance" in identity:
|
|
819
|
+
fields.append((identity, "instance", f"{context}.identity", "instance"))
|
|
820
|
+
normalized_fields = []
|
|
821
|
+
for parent, field, field_context, label in fields:
|
|
822
|
+
value = _require_str(parent, field, field_context)
|
|
823
|
+
if SLUG_RE.fullmatch(value):
|
|
824
|
+
continue
|
|
825
|
+
normalized = re.sub(r"[^a-z0-9._/-]+", "-", value.lower()).strip("._/-")
|
|
826
|
+
if not SLUG_RE.fullmatch(normalized):
|
|
827
|
+
raise ContractError(
|
|
828
|
+
f"{field_context}.{field}: expected a stable lowercase semantic slug"
|
|
829
|
+
)
|
|
830
|
+
parent[field] = normalized
|
|
831
|
+
normalized_fields.append(label)
|
|
832
|
+
|
|
833
|
+
_populate_unsealed_finding_identities(
|
|
834
|
+
manifest,
|
|
835
|
+
{"scanId": scan_id, "findings": [finding]},
|
|
836
|
+
)
|
|
837
|
+
finding_id = finding["findingId"]
|
|
838
|
+
previous_position = finding_positions.get(finding_id)
|
|
839
|
+
_validate_finding(finding, context)
|
|
840
|
+
if "writeup" in finding:
|
|
841
|
+
try:
|
|
842
|
+
_validate_schema_node(finding["writeup"], writeup_schema, f"{context}.writeup")
|
|
843
|
+
report_path = finding["writeup"]["reportPath"]
|
|
844
|
+
previous_writeup = (
|
|
845
|
+
recovered[previous_position].get("writeup")
|
|
846
|
+
if previous_position is not None
|
|
847
|
+
else None
|
|
848
|
+
)
|
|
849
|
+
if report_path in writeup_paths and (
|
|
850
|
+
previous_writeup is None or previous_writeup["reportPath"] != report_path
|
|
851
|
+
):
|
|
852
|
+
raise ContractError(f"{context}.writeup.reportPath: duplicate report path")
|
|
853
|
+
_require_scan_local_file(scan_dir, report_path, f"{context}.writeup.reportPath")
|
|
854
|
+
except ContractError as exc:
|
|
855
|
+
finding.pop("writeup")
|
|
856
|
+
warnings.append(f"Skipped malformed writeup for finding {index + 1}: {exc}.")
|
|
857
|
+
_validate_schema_node(finding, finding_schema, context)
|
|
858
|
+
except ContractError as exc:
|
|
859
|
+
warning = f"Skipped malformed finding {index + 1}: {exc}."
|
|
860
|
+
warnings.append(warning)
|
|
861
|
+
discarded.append(warning)
|
|
862
|
+
continue
|
|
863
|
+
|
|
864
|
+
if previous_position is not None:
|
|
865
|
+
previous = recovered[previous_position]
|
|
866
|
+
if _finding_strength(finding) <= _finding_strength(previous):
|
|
867
|
+
warnings.append(
|
|
868
|
+
f"Skipped malformed finding {index + 1}: duplicate logical finding."
|
|
869
|
+
)
|
|
870
|
+
continue
|
|
871
|
+
previous_writeup = previous.get("writeup")
|
|
872
|
+
if previous_writeup is not None:
|
|
873
|
+
writeup_paths.discard(previous_writeup["reportPath"])
|
|
874
|
+
recovered[previous_position] = finding
|
|
875
|
+
warnings.append(
|
|
876
|
+
f"Recovered finding {index + 1}: retained stronger duplicate logical finding."
|
|
877
|
+
)
|
|
878
|
+
else:
|
|
879
|
+
finding_positions[finding_id] = len(recovered)
|
|
880
|
+
recovered.append(finding)
|
|
881
|
+
|
|
882
|
+
if "writeup" in finding:
|
|
883
|
+
writeup_paths.add(finding["writeup"]["reportPath"])
|
|
884
|
+
if normalized_fields:
|
|
885
|
+
warnings.append(
|
|
886
|
+
f"Recovered finding {index + 1}: normalized {', '.join(normalized_fields)}."
|
|
887
|
+
)
|
|
888
|
+
|
|
889
|
+
findings["findings"] = recovered
|
|
890
|
+
return discarded
|
|
891
|
+
|
|
892
|
+
|
|
893
|
+
def _recover_unsealed_coverage(
|
|
894
|
+
coverage: dict[str, Any],
|
|
895
|
+
schema_dir: Path,
|
|
896
|
+
scan_dir: Path,
|
|
897
|
+
warnings: list[str],
|
|
898
|
+
discarded_findings: list[str],
|
|
899
|
+
) -> None:
|
|
900
|
+
schema = _read_json(schema_dir / "coverage.schema.json")
|
|
901
|
+
_require_safe_schema(schema, "coverage.schema.json")
|
|
902
|
+
properties = _require_dict(schema, "properties", "coverage.schema")
|
|
903
|
+
completeness = coverage.get("completeness")
|
|
904
|
+
partial = completeness not in ("complete", "partial", "unknown")
|
|
905
|
+
if partial:
|
|
906
|
+
warnings.append("Recovered malformed coverage completeness; marked coverage as partial.")
|
|
907
|
+
|
|
908
|
+
surface_ids: set[str] = set()
|
|
909
|
+
for field, label in (
|
|
910
|
+
("surfaces", "coverage surface"),
|
|
911
|
+
("explicitExclusions", "coverage exclusion"),
|
|
912
|
+
("deferred", "deferred coverage item"),
|
|
913
|
+
):
|
|
914
|
+
array_schema = _require_dict(properties, field, "coverage.schema.properties")
|
|
915
|
+
item_schema = _require_dict(array_schema, "items", f"coverage.schema.properties.{field}")
|
|
916
|
+
items = coverage.get(field)
|
|
917
|
+
if not isinstance(items, list):
|
|
918
|
+
warnings.append(f"Skipped malformed {label} records: expected an array.")
|
|
919
|
+
coverage[field] = []
|
|
920
|
+
partial = True
|
|
921
|
+
continue
|
|
922
|
+
|
|
923
|
+
recovered: list[dict[str, Any]] = []
|
|
924
|
+
for index, item in enumerate(items):
|
|
925
|
+
context = f"coverage.{field}[{index}]"
|
|
926
|
+
try:
|
|
927
|
+
if not isinstance(item, dict):
|
|
928
|
+
raise ContractError(f"{context}: expected an object")
|
|
929
|
+
if field == "surfaces":
|
|
930
|
+
surface_id = _require_str(item, "id", context)
|
|
931
|
+
if surface_id in surface_ids:
|
|
932
|
+
raise ContractError(f"{context}.id: duplicate surface id")
|
|
933
|
+
disposition = item.get("disposition")
|
|
934
|
+
surface_recovered = False
|
|
935
|
+
if not isinstance(disposition, str) or disposition not in DISPOSITIONS:
|
|
936
|
+
warnings.append(
|
|
937
|
+
f"Recovered coverage surface {index + 1}: "
|
|
938
|
+
"the review disposition could not be verified."
|
|
939
|
+
)
|
|
940
|
+
item["disposition"] = "needs_follow_up"
|
|
941
|
+
surface_recovered = True
|
|
942
|
+
|
|
943
|
+
receipt_refs = item.get("receiptRefs")
|
|
944
|
+
if not isinstance(receipt_refs, list):
|
|
945
|
+
warnings.append(
|
|
946
|
+
f"Skipped malformed receipt references for coverage surface "
|
|
947
|
+
f"{index + 1}: expected an array."
|
|
948
|
+
)
|
|
949
|
+
receipt_refs = []
|
|
950
|
+
surface_recovered = True
|
|
951
|
+
|
|
952
|
+
recovered_receipts: list[str] = []
|
|
953
|
+
for ref_index, ref in enumerate(receipt_refs):
|
|
954
|
+
ref_context = f"{context}.receiptRefs[{ref_index}]"
|
|
955
|
+
try:
|
|
956
|
+
if not isinstance(ref, str):
|
|
957
|
+
raise ContractError(f"{ref_context}: expected a string")
|
|
958
|
+
normalized_ref = _require_safe_relative_path(ref, ref_context)
|
|
959
|
+
if not normalized_ref.startswith("artifacts/"):
|
|
960
|
+
raise ContractError(
|
|
961
|
+
f"{ref_context}: expected a file under artifacts/"
|
|
962
|
+
)
|
|
963
|
+
_require_scan_local_file(scan_dir, normalized_ref, ref_context)
|
|
964
|
+
except ContractError as exc:
|
|
965
|
+
warnings.append(
|
|
966
|
+
f"Skipped malformed coverage receipt "
|
|
967
|
+
f"{index + 1}.{ref_index + 1}: {exc}."
|
|
968
|
+
)
|
|
969
|
+
surface_recovered = True
|
|
970
|
+
continue
|
|
971
|
+
recovered_receipts.append(normalized_ref)
|
|
972
|
+
|
|
973
|
+
item["receiptRefs"] = recovered_receipts
|
|
974
|
+
if surface_recovered or item["disposition"] == "needs_follow_up":
|
|
975
|
+
if not surface_recovered and completeness != "partial":
|
|
976
|
+
warnings.append(
|
|
977
|
+
f"Coverage surface {index + 1} requires follow-up; "
|
|
978
|
+
"marked coverage as partial."
|
|
979
|
+
)
|
|
980
|
+
item["disposition"] = "needs_follow_up"
|
|
981
|
+
partial = True
|
|
982
|
+
|
|
983
|
+
_validate_schema_node(item, item_schema, context)
|
|
984
|
+
except ContractError as exc:
|
|
985
|
+
warnings.append(f"Skipped malformed {label} {index + 1}: {exc}.")
|
|
986
|
+
partial = True
|
|
987
|
+
continue
|
|
988
|
+
|
|
989
|
+
if field == "surfaces":
|
|
990
|
+
surface_ids.add(surface_id)
|
|
991
|
+
recovered.append(item)
|
|
992
|
+
|
|
993
|
+
coverage[field] = recovered
|
|
994
|
+
|
|
995
|
+
if discarded_findings:
|
|
996
|
+
for surface in coverage["surfaces"]:
|
|
997
|
+
surface["disposition"] = "needs_follow_up"
|
|
998
|
+
coverage["deferred"].extend(
|
|
999
|
+
{"id": f"discarded-finding-{index}", "reason": warning}
|
|
1000
|
+
for index, warning in enumerate(discarded_findings, 1)
|
|
1001
|
+
)
|
|
1002
|
+
partial = True
|
|
1003
|
+
|
|
1004
|
+
if coverage["deferred"] and completeness != "partial":
|
|
1005
|
+
if not discarded_findings:
|
|
1006
|
+
warnings.append("Coverage has deferred review work; marked coverage as partial.")
|
|
1007
|
+
partial = True
|
|
1008
|
+
if partial:
|
|
1009
|
+
coverage["completeness"] = "partial"
|
|
1010
|
+
|
|
1011
|
+
|
|
1012
|
+
def _recover_unsealed_hardening(
|
|
1013
|
+
manifest: dict[str, Any],
|
|
1014
|
+
scan_dir: Path,
|
|
1015
|
+
warnings: list[str],
|
|
1016
|
+
) -> None:
|
|
1017
|
+
scan = _require_dict(manifest, "scan", "manifest")
|
|
1018
|
+
if "hardening" not in scan:
|
|
1019
|
+
return
|
|
1020
|
+
|
|
1021
|
+
try:
|
|
1022
|
+
hardening = _require_dict(scan, "hardening", "manifest.scan")
|
|
1023
|
+
portfolio_path = _require_str(hardening, "portfolioPath", "manifest.scan.hardening")
|
|
1024
|
+
if portfolio_path != "hardening/hardening.md":
|
|
1025
|
+
raise ContractError(
|
|
1026
|
+
"manifest.scan.hardening.portfolioPath: expected hardening/hardening.md"
|
|
1027
|
+
)
|
|
1028
|
+
_require_hardening_portfolio_file(scan_dir, scan)
|
|
1029
|
+
except ContractError as exc:
|
|
1030
|
+
scan.pop("hardening")
|
|
1031
|
+
warnings.append(f"Skipped malformed hardening portfolio: {exc}.")
|
|
1032
|
+
|
|
1033
|
+
|
|
770
1034
|
def _validate_derived_finding_identities(
|
|
771
1035
|
manifest: dict[str, Any],
|
|
772
1036
|
findings: dict[str, Any],
|
|
@@ -1792,8 +2056,21 @@ def build_sarif_projection(
|
|
|
1792
2056
|
source_root_is_directory = False
|
|
1793
2057
|
if not source_root_is_directory:
|
|
1794
2058
|
raise ContractError("source root: expected an existing directory")
|
|
1795
|
-
manifest, findings,
|
|
2059
|
+
manifest, findings, coverage, _ = _read_sealed_scan(scan_dir, schema_dir, "SARIF projection")
|
|
1796
2060
|
sarif = build_sarif(manifest, findings, source_root)
|
|
2061
|
+
if coverage["completeness"] != "complete":
|
|
2062
|
+
run = sarif["runs"][0]
|
|
2063
|
+
run["properties"]["codexSecurityCoverageCompleteness"] = coverage["completeness"]
|
|
2064
|
+
if coverage["deferred"]:
|
|
2065
|
+
run["invocations"] = [
|
|
2066
|
+
{
|
|
2067
|
+
"executionSuccessful": True,
|
|
2068
|
+
"toolExecutionNotifications": [
|
|
2069
|
+
{"level": "warning", "message": {"text": item["reason"]}}
|
|
2070
|
+
for item in coverage["deferred"]
|
|
2071
|
+
],
|
|
2072
|
+
}
|
|
2073
|
+
]
|
|
1797
2074
|
_validate_sarif(sarif)
|
|
1798
2075
|
return sarif
|
|
1799
2076
|
|
|
@@ -2009,6 +2286,7 @@ def _prepare_scan_finalization(
|
|
|
2009
2286
|
*,
|
|
2010
2287
|
expected_coverage_mode: str | None = None,
|
|
2011
2288
|
completion_binding: dict[str, Any] | None = None,
|
|
2289
|
+
completion_warnings: list[str] | None = None,
|
|
2012
2290
|
) -> PreparedScanFinalization:
|
|
2013
2291
|
"""Read, populate, and validate a scan without writing any output files."""
|
|
2014
2292
|
|
|
@@ -2061,8 +2339,15 @@ def _prepare_scan_finalization(
|
|
|
2061
2339
|
_validate_completion_binding(manifest, findings, coverage, completion_binding)
|
|
2062
2340
|
if was_sealed:
|
|
2063
2341
|
_validate_findings(manifest, findings)
|
|
2064
|
-
if was_sealed:
|
|
2065
2342
|
_validate_derived_finding_identities(manifest, findings)
|
|
2343
|
+
elif completion_warnings is not None:
|
|
2344
|
+
discarded_findings = _recover_unsealed_findings(
|
|
2345
|
+
manifest, findings, schema_dir, scan_dir, completion_warnings
|
|
2346
|
+
)
|
|
2347
|
+
_recover_unsealed_coverage(
|
|
2348
|
+
coverage, schema_dir, scan_dir, completion_warnings, discarded_findings
|
|
2349
|
+
)
|
|
2350
|
+
_recover_unsealed_hardening(manifest, scan_dir, completion_warnings)
|
|
2066
2351
|
else:
|
|
2067
2352
|
_populate_unsealed_finding_identities(manifest, findings)
|
|
2068
2353
|
_validate_findings(manifest, findings)
|
|
@@ -210,6 +210,10 @@ def parse_args(description: str) -> argparse.Namespace:
|
|
|
210
210
|
update_progress.add_argument("--deep-review-pass", type=positive_int)
|
|
211
211
|
update_progress.add_argument("--claim-token")
|
|
212
212
|
|
|
213
|
+
prepare_scan_completion = subparsers.add_parser("prepare-scan-completion")
|
|
214
|
+
prepare_scan_completion.add_argument("--scan-id", required=True)
|
|
215
|
+
prepare_scan_completion.add_argument("--claim-token")
|
|
216
|
+
|
|
213
217
|
complete_scan = subparsers.add_parser("complete-scan")
|
|
214
218
|
complete_scan.add_argument("--scan-id", required=True)
|
|
215
219
|
complete_scan.add_argument("--claim-token")
|