@openai/codex-security 0.1.3 → 0.1.5
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 +224 -14
- package/_bundled_plugin/examples/completed-scan/findings.json +6 -0
- package/_bundled_plugin/examples/completed-scan/scan-manifest.json +1 -1
- package/_bundled_plugin/references/finding-detail-fields.md +10 -2
- package/_bundled_plugin/references/scan-contract.md +2 -0
- package/_bundled_plugin/scripts/finalize_scan_contract.py +18 -0
- package/_bundled_plugin/scripts/workbench_cli.py +4 -0
- package/_bundled_plugin/scripts/workbench_db.py +93 -23
- package/_bundled_plugin/scripts/workbench_scan_start.py +13 -0
- package/_bundled_plugin/scripts/workbench_target.py +14 -1
- package/dist/api.d.ts +3 -2
- package/dist/api.d.ts.map +1 -1
- package/dist/api.js +288 -70
- package/dist/api.js.map +1 -1
- package/dist/auth.d.ts.map +1 -1
- package/dist/auth.js +262 -44
- package/dist/auth.js.map +1 -1
- package/dist/cli.d.ts +4 -3
- package/dist/cli.d.ts.map +1 -1
- package/dist/cli.js +364 -154
- package/dist/cli.js.map +1 -1
- package/dist/config.d.ts.map +1 -1
- package/dist/config.js +29 -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 +33 -22
- package/dist/contract.js.map +1 -1
- package/dist/cost.d.ts.map +1 -1
- package/dist/cost.js +57 -14
- package/dist/cost.js.map +1 -1
- package/dist/errors.d.ts +2 -0
- package/dist/errors.d.ts.map +1 -1
- package/dist/errors.js +48 -0
- package/dist/errors.js.map +1 -1
- package/dist/multiscan.d.ts.map +1 -1
- package/dist/multiscan.js +2 -7
- package/dist/multiscan.js.map +1 -1
- package/dist/runtime.d.ts +34 -0
- package/dist/runtime.d.ts.map +1 -1
- package/dist/runtime.js +655 -20
- 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,9 +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
|
+
|
|
200
302
|
These overrides do not change the scan's approval policy or filesystem
|
|
201
303
|
permissions. See [Local security model](#local-security-model).
|
|
202
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
|
+
|
|
203
369
|
Scan progress identifies the requested paths and reports actual ranking,
|
|
204
370
|
file-review, validation, and attack-path phases as they become available.
|
|
205
371
|
Completion summarizes findings, severity, coverage, elapsed time, available
|
|
@@ -214,7 +380,9 @@ including cached input and cache writes; fees and surcharges are not included.
|
|
|
214
380
|
|
|
215
381
|
Use `--max-cost USD` to stop a scan, including its delegated workers, when its
|
|
216
382
|
running cost exceeds the limit. Partial results are preserved. Requests
|
|
217
|
-
already in progress can finish above the limit.
|
|
383
|
+
already in progress can finish above the limit. Cost tracking accepts Codex
|
|
384
|
+
session events up to 1 MiB; an oversized event stops the scan because its
|
|
385
|
+
running cost can no longer be verified safely.
|
|
218
386
|
|
|
219
387
|
Run `npx @openai/codex-security scan --help` or `npx @openai/codex-security bulk-scan --help`
|
|
220
388
|
for the complete CLI references.
|
|
@@ -244,7 +412,8 @@ Results remain under `--output-dir`; rerun the same command to resume.
|
|
|
244
412
|
`npx @openai/codex-security scans list` lists scans for the current repository. Pass a
|
|
245
413
|
repository path to inspect another checkout, `--scan-root DIR` to list scans
|
|
246
414
|
whose artifacts are under a particular root. `scans show SCAN_ID` includes the
|
|
247
|
-
scan configuration, results, coverage, and artifact locations.
|
|
415
|
+
scan configuration, results, coverage, and artifact locations. Add
|
|
416
|
+
`--show-linked-findings` to include finding links from previous scans.
|
|
248
417
|
|
|
249
418
|
Every scan history command accepts a full scan ID or a unique prefix of at
|
|
250
419
|
least eight characters.
|
|
@@ -274,10 +443,10 @@ cause; `scans match --all` matches all completed scans of the current repository
|
|
|
274
443
|
including other worktrees and clones. Saved matches appear in `scans show` and
|
|
275
444
|
are reused unless `--force` is passed. Scans without sealed artifacts are skipped.
|
|
276
445
|
|
|
277
|
-
`scans compare BEFORE_SCAN_ID AFTER_SCAN_ID`
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
their original scope.
|
|
446
|
+
`scans compare BEFORE_SCAN_ID AFTER_SCAN_ID` automatically matches findings by
|
|
447
|
+
root cause, reuses saved matches, and reports findings as new, persisting,
|
|
448
|
+
reopened, resolved, or unknown. Missing findings are not treated as resolved when
|
|
449
|
+
the later scan is incomplete or does not cover their original scope.
|
|
281
450
|
|
|
282
451
|
The CLI uses [Incur](https://github.com/wevm/incur) for agent-friendly discovery
|
|
283
452
|
and structured output. Inspect the command manifest with `--llms`, inspect a
|
|
@@ -347,6 +516,47 @@ Progress remains on stderr so JSON output stays machine readable. Network
|
|
|
347
516
|
failures and rate limits remain retryable; definitive authentication and model
|
|
348
517
|
authorization failures stop immediately.
|
|
349
518
|
|
|
519
|
+
## Containerized bulk scans
|
|
520
|
+
|
|
521
|
+
Create `repositories.csv` with one full, immutable Git commit per repository:
|
|
522
|
+
|
|
523
|
+
```csv
|
|
524
|
+
id,repository,revision
|
|
525
|
+
payments,https://github.com/example/payments.git,0123456789abcdef0123456789abcdef01234567
|
|
526
|
+
```
|
|
527
|
+
|
|
528
|
+
Once the approved image has been published, prepare private results and
|
|
529
|
+
authentication directories, sign in, and run the Docker Compose configuration
|
|
530
|
+
from the root of the Codex Security repository:
|
|
531
|
+
|
|
532
|
+
```bash
|
|
533
|
+
mkdir -p results state
|
|
534
|
+
chmod 700 results state
|
|
535
|
+
export CODEX_SECURITY_USER="$(id -u):$(id -g)"
|
|
536
|
+
export CODEX_SECURITY_IMAGE=ghcr.io/openai/codex-security:0.1.4
|
|
537
|
+
docker compose pull codex-security
|
|
538
|
+
docker compose run --rm codex-security login --device-auth
|
|
539
|
+
docker compose run --rm codex-security
|
|
540
|
+
```
|
|
541
|
+
|
|
542
|
+
Reports and resumable scan results are written to `results/`; the reusable
|
|
543
|
+
device login remains in `state/`. For unattended scans, set `OPENAI_API_KEY`
|
|
544
|
+
or `CODEX_API_KEY` instead. Set `GH_TOKEN` or `GITHUB_TOKEN` for private
|
|
545
|
+
GitHub repositories.
|
|
546
|
+
|
|
547
|
+
On Ubuntu hosts that restrict unprivileged user namespaces, an administrator
|
|
548
|
+
can install the optional, narrowly scoped AppArmor profile once:
|
|
549
|
+
|
|
550
|
+
```bash
|
|
551
|
+
sudo install -m 0644 docker/codex-security.apparmor /etc/apparmor.d/codex-security-container
|
|
552
|
+
sudo apparmor_parser -r -W /etc/apparmor.d/codex-security-container
|
|
553
|
+
docker compose -f compose.yaml -f compose.apparmor.yaml run --rm codex-security
|
|
554
|
+
```
|
|
555
|
+
|
|
556
|
+
The override preserves the nonroot user, dropped capabilities,
|
|
557
|
+
no-new-privileges, and hardened seccomp policy. Other Docker hosts do not need
|
|
558
|
+
the profile or override.
|
|
559
|
+
|
|
350
560
|
## Local security model
|
|
351
561
|
|
|
352
562
|
Codex Security runs with your local operating-system permissions. Scan only
|
|
@@ -42,6 +42,12 @@
|
|
|
42
42
|
"remediation": "Normalize destinations and reject entries that escape the extraction root.",
|
|
43
43
|
"validation": null,
|
|
44
44
|
"attackPath": null,
|
|
45
|
+
"remediationTests": [
|
|
46
|
+
"Assert that extracting an archive entry named `../escape.txt` fails without writing outside the extraction root."
|
|
47
|
+
],
|
|
48
|
+
"preventiveControls": [
|
|
49
|
+
"Route all archive extraction through one helper that normalizes and validates destination paths."
|
|
50
|
+
],
|
|
45
51
|
"provenance": {
|
|
46
52
|
"source": "local_plugin"
|
|
47
53
|
},
|
|
@@ -23,7 +23,7 @@ The finding detail view is a decision-focused projection of the canonical findin
|
|
|
23
23
|
- dataflow source, meaningful transformations, dangerous sink, and concrete outcome;
|
|
24
24
|
- realistic attacker, entry point, access requirements, preconditions, and attacker outcome;
|
|
25
25
|
- severity rationale plus the specific evidence that would raise or lower the rating;
|
|
26
|
-
- the minimal remediation invariant
|
|
26
|
+
- the minimal remediation invariant (`remediation`, a single string), plus `remediationTests` and `preventiveControls`, each an array of short strings with one regression test or preventive control per entry.
|
|
27
27
|
|
|
28
28
|
Keep background exposition, alternate exploit research, full PoC instructions, representative command output, and long source walkthroughs in the detailed write-up. Do not copy them into canonical fields merely to make the workspace report longer. The workspace should stay self-contained enough to support triage while avoiding duplicated or speculative prose.
|
|
29
29
|
|
|
@@ -155,7 +155,15 @@ The following shape shows how to encode the `environment/add` reserved-environme
|
|
|
155
155
|
"limitations": [
|
|
156
156
|
"This overwrite does not directly execute code on the victim host."
|
|
157
157
|
]
|
|
158
|
-
}
|
|
158
|
+
},
|
|
159
|
+
"remediation": "Reuse the startup reserved-ID check inside `EnvironmentManager::upsert_environment()` so the runtime mutation path rejects the reserved `local` identifier.",
|
|
160
|
+
"remediationTests": [
|
|
161
|
+
"Assert that `environment/add` with `environmentId: \"local\"` returns a protocol error.",
|
|
162
|
+
"Assert that `default_environment()` still resolves the manager-owned local runtime after a rejected upsert."
|
|
163
|
+
],
|
|
164
|
+
"preventiveControls": [
|
|
165
|
+
"Centralize reserved-identifier validation so every environment mutation path shares one guard."
|
|
166
|
+
]
|
|
159
167
|
}
|
|
160
168
|
```
|
|
161
169
|
|
|
@@ -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` |
|
|
@@ -796,6 +796,12 @@ def _recover_unsealed_findings(
|
|
|
796
796
|
writeup_schema = _require_dict(
|
|
797
797
|
finding_properties, "writeup", "findings.schema.properties.findings.items.properties"
|
|
798
798
|
)
|
|
799
|
+
auxiliary_schemas = {
|
|
800
|
+
name: _require_dict(
|
|
801
|
+
finding_properties, name, "findings.schema.properties.findings.items.properties"
|
|
802
|
+
)
|
|
803
|
+
for name in ("remediationTests", "preventiveControls")
|
|
804
|
+
}
|
|
799
805
|
scan = _require_dict(manifest, "scan", "manifest")
|
|
800
806
|
scan_id = _require_str(scan, "id", "manifest.scan")
|
|
801
807
|
if findings.get("scanId") != scan_id:
|
|
@@ -854,6 +860,18 @@ def _recover_unsealed_findings(
|
|
|
854
860
|
except ContractError as exc:
|
|
855
861
|
finding.pop("writeup")
|
|
856
862
|
warnings.append(f"Skipped malformed writeup for finding {index + 1}: {exc}.")
|
|
863
|
+
for auxiliary, auxiliary_schema in auxiliary_schemas.items():
|
|
864
|
+
if auxiliary not in finding:
|
|
865
|
+
continue
|
|
866
|
+
try:
|
|
867
|
+
_validate_schema_node(
|
|
868
|
+
finding[auxiliary], auxiliary_schema, f"{context}.{auxiliary}"
|
|
869
|
+
)
|
|
870
|
+
except ContractError as exc:
|
|
871
|
+
finding.pop(auxiliary)
|
|
872
|
+
warnings.append(
|
|
873
|
+
f"Skipped malformed {auxiliary} for finding {index + 1}: {exc}."
|
|
874
|
+
)
|
|
857
875
|
_validate_schema_node(finding, finding_schema, context)
|
|
858
876
|
except ContractError as exc:
|
|
859
877
|
warning = f"Skipped malformed finding {index + 1}: {exc}."
|
|
@@ -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")
|
|
@@ -86,6 +86,7 @@ from workbench_scan_start import (
|
|
|
86
86
|
safe_segment,
|
|
87
87
|
scan_diff_identity,
|
|
88
88
|
scan_target_identity,
|
|
89
|
+
stored_diff_target,
|
|
89
90
|
)
|
|
90
91
|
from workbench_schema import MIGRATIONS, normalize_pre_release_migrations, sql_statements
|
|
91
92
|
from workbench_source_excerpt import finding_source_excerpt
|
|
@@ -504,19 +505,6 @@ def expected_target_kinds(scan: sqlite3.Row) -> list[str]:
|
|
|
504
505
|
return ["git_worktree"]
|
|
505
506
|
|
|
506
507
|
|
|
507
|
-
def stored_diff_target(row: sqlite3.Row) -> dict[str, str] | None:
|
|
508
|
-
if not row["diff_target_kind"]:
|
|
509
|
-
return None
|
|
510
|
-
target = {
|
|
511
|
-
"baseRevision": row["diff_base_revision"],
|
|
512
|
-
"headRevision": row["diff_head_revision"],
|
|
513
|
-
"kind": row["diff_target_kind"],
|
|
514
|
-
}
|
|
515
|
-
if row["diff_content_digest"]:
|
|
516
|
-
target["contentDigest"] = row["diff_content_digest"]
|
|
517
|
-
return target
|
|
518
|
-
|
|
519
|
-
|
|
520
508
|
def requested_scan_paths(scan: sqlite3.Row) -> list[str]:
|
|
521
509
|
if "recipe_json" in scan.keys() and scan["recipe_json"] is not None:
|
|
522
510
|
recipe = json.loads(scan["recipe_json"], parse_constant=reject_non_finite_json)
|
|
@@ -1374,11 +1362,15 @@ def pin_legacy_manifest_digest(
|
|
|
1374
1362
|
raise
|
|
1375
1363
|
|
|
1376
1364
|
|
|
1377
|
-
def complete_scan(
|
|
1365
|
+
def complete_scan(
|
|
1366
|
+
connection: sqlite3.Connection, args: argparse.Namespace, *, prepare_only: bool = False
|
|
1367
|
+
) -> dict[str, Any]:
|
|
1378
1368
|
scan_id = require_uuid(args.scan_id, "scan-id")
|
|
1379
|
-
cost_json = parse_scan_cost(args.cost_json)
|
|
1369
|
+
cost_json = None if prepare_only else parse_scan_cost(args.cost_json)
|
|
1380
1370
|
with scan_completion_lock(scan_id):
|
|
1381
|
-
return complete_scan_locked(
|
|
1371
|
+
return complete_scan_locked(
|
|
1372
|
+
connection, scan_id, args.claim_token, cost_json, prepare_only=prepare_only
|
|
1373
|
+
)
|
|
1382
1374
|
|
|
1383
1375
|
|
|
1384
1376
|
def complete_scan_locked(
|
|
@@ -1386,6 +1378,8 @@ def complete_scan_locked(
|
|
|
1386
1378
|
scan_id: str,
|
|
1387
1379
|
claim_token: str | None,
|
|
1388
1380
|
cost_json: str | None,
|
|
1381
|
+
*,
|
|
1382
|
+
prepare_only: bool = False,
|
|
1389
1383
|
) -> dict[str, Any]:
|
|
1390
1384
|
scan = require_scan(connection, scan_id)
|
|
1391
1385
|
if scan["status"] == "complete":
|
|
@@ -1412,15 +1406,36 @@ def complete_scan_locked(
|
|
|
1412
1406
|
)
|
|
1413
1407
|
if scan["recipe_json"] is None:
|
|
1414
1408
|
deep_scan.require_deep_scan_ready_for_parent_completion(connection, scan)
|
|
1415
|
-
warnings = []
|
|
1409
|
+
warnings = json.loads(scan["completion_warnings_json"])
|
|
1416
1410
|
warning = scan_target_warning(scan)
|
|
1417
|
-
if warning is not None:
|
|
1411
|
+
if warning is not None and warning not in warnings:
|
|
1418
1412
|
warnings.append(warning)
|
|
1419
1413
|
scan_dir = require_canonical_scan_directory(Path(scan["scan_dir"]))
|
|
1420
1414
|
completion_timestamp = now()
|
|
1421
1415
|
completion_binding = workbench_completion_binding(scan, completion_timestamp)
|
|
1422
1416
|
if scan["recipe_json"] is not None:
|
|
1423
|
-
|
|
1417
|
+
draft_artifacts: dict[str, Path] = {}
|
|
1418
|
+
missing_drafts = []
|
|
1419
|
+
for file_name in (
|
|
1420
|
+
ARTIFACTS["manifest"],
|
|
1421
|
+
ARTIFACTS["findings"],
|
|
1422
|
+
ARTIFACTS["coverage"],
|
|
1423
|
+
):
|
|
1424
|
+
try:
|
|
1425
|
+
(scan_dir / file_name).lstat()
|
|
1426
|
+
except FileNotFoundError:
|
|
1427
|
+
missing_drafts.append(file_name)
|
|
1428
|
+
continue
|
|
1429
|
+
draft_path = artifact_path(scan_dir, file_name, required=True)
|
|
1430
|
+
if draft_path is not None:
|
|
1431
|
+
draft_artifacts[file_name] = draft_path
|
|
1432
|
+
if missing_drafts:
|
|
1433
|
+
raise SystemExit(
|
|
1434
|
+
"Scan agent did not create required draft artifacts: "
|
|
1435
|
+
f"{', '.join(missing_drafts)}. Check that the scan agent can run shell "
|
|
1436
|
+
"commands and write to the scan directory before retrying."
|
|
1437
|
+
)
|
|
1438
|
+
manifest = read_json_object(draft_artifacts[ARTIFACTS["manifest"]])
|
|
1424
1439
|
manifest_scan = manifest.get("scan")
|
|
1425
1440
|
if isinstance(manifest_scan, dict) and manifest_scan.get("sealedAt") is not None:
|
|
1426
1441
|
completion_binding["startedAt"] = manifest_scan.get("startedAt")
|
|
@@ -1443,9 +1458,23 @@ def complete_scan_locked(
|
|
|
1443
1458
|
for kind, filename in ARTIFACTS.items()
|
|
1444
1459
|
}
|
|
1445
1460
|
manifest_digest = published_manifest_digest(scan_dir, manifest)
|
|
1461
|
+
if prepare_only:
|
|
1462
|
+
connection.execute("BEGIN IMMEDIATE")
|
|
1463
|
+
try:
|
|
1464
|
+
updated = connection.execute(
|
|
1465
|
+
"UPDATE scans SET completion_warnings_json = ? WHERE id = ? AND status = 'running'",
|
|
1466
|
+
(json.dumps(warnings), scan["id"]),
|
|
1467
|
+
)
|
|
1468
|
+
if updated.rowcount != 1:
|
|
1469
|
+
raise SystemExit("Only a running scan can be prepared for completion.")
|
|
1470
|
+
connection.commit()
|
|
1471
|
+
except BaseException:
|
|
1472
|
+
connection.rollback()
|
|
1473
|
+
raise
|
|
1474
|
+
return scan_context(connection, scan["id"])
|
|
1446
1475
|
connection.execute("BEGIN IMMEDIATE")
|
|
1447
1476
|
try:
|
|
1448
|
-
timestamp =
|
|
1477
|
+
timestamp = manifest["scan"]["completedAt"]
|
|
1449
1478
|
scan = require_scan(connection, scan["id"])
|
|
1450
1479
|
if scan["status"] == "complete":
|
|
1451
1480
|
connection.commit()
|
|
@@ -1609,7 +1638,14 @@ def register_cli_scan(connection: sqlite3.Connection, args: argparse.Namespace)
|
|
|
1609
1638
|
except BaseException:
|
|
1610
1639
|
connection.rollback()
|
|
1611
1640
|
raise
|
|
1612
|
-
|
|
1641
|
+
scan = require_scan(connection, scan_id)
|
|
1642
|
+
return {
|
|
1643
|
+
"contract": scan_contract(scan),
|
|
1644
|
+
"scanDir": str(scan_dir),
|
|
1645
|
+
"scanId": scan_id,
|
|
1646
|
+
"targetId": target_id,
|
|
1647
|
+
"targetRevision": scan["target_revision"],
|
|
1648
|
+
}
|
|
1613
1649
|
|
|
1614
1650
|
|
|
1615
1651
|
def parse_scan_recipe(value: str, repository: Path) -> dict[str, Any]:
|
|
@@ -3454,6 +3490,38 @@ def require_canonical_scan_directory(scan_dir: Path) -> Path:
|
|
|
3454
3490
|
scan_dir
|
|
3455
3491
|
):
|
|
3456
3492
|
raise SystemExit("Scan directory must be an existing canonical non-symlink directory.")
|
|
3493
|
+
# Re-check privacy on every resolution so a mid-scan rename/replace under a
|
|
3494
|
+
# shared parent cannot substitute another user's forged artifact tree.
|
|
3495
|
+
if os.name != "nt":
|
|
3496
|
+
if stat.S_IMODE(metadata.st_mode) & 0o077:
|
|
3497
|
+
raise SystemExit(
|
|
3498
|
+
"Scan directory must not be accessible to other users (chmod 700)."
|
|
3499
|
+
)
|
|
3500
|
+
geteuid = getattr(os, "geteuid", None)
|
|
3501
|
+
effective_uid = geteuid() if geteuid is not None else None
|
|
3502
|
+
if effective_uid is not None and metadata.st_uid != effective_uid:
|
|
3503
|
+
raise SystemExit("Scan directory must be owned by the current user.")
|
|
3504
|
+
for parent in scan_dir.parents:
|
|
3505
|
+
try:
|
|
3506
|
+
parent_metadata = parent.lstat()
|
|
3507
|
+
except OSError as exc:
|
|
3508
|
+
raise SystemExit("Scan output parent could not be inspected.") from exc
|
|
3509
|
+
if not stat.S_ISDIR(parent_metadata.st_mode) or stat.S_ISLNK(
|
|
3510
|
+
parent_metadata.st_mode
|
|
3511
|
+
):
|
|
3512
|
+
raise SystemExit("Scan output parent must be a non-symlink directory.")
|
|
3513
|
+
if effective_uid is not None and parent_metadata.st_uid not in {
|
|
3514
|
+
0,
|
|
3515
|
+
effective_uid,
|
|
3516
|
+
}:
|
|
3517
|
+
raise SystemExit("Scan output parent must have a trusted owner.")
|
|
3518
|
+
if (
|
|
3519
|
+
stat.S_IMODE(parent_metadata.st_mode) & 0o022
|
|
3520
|
+
and not parent_metadata.st_mode & stat.S_ISVTX
|
|
3521
|
+
):
|
|
3522
|
+
raise SystemExit(
|
|
3523
|
+
"Scan output parent must not be group- or world-writable without the sticky bit."
|
|
3524
|
+
)
|
|
3457
3525
|
return scan_dir
|
|
3458
3526
|
|
|
3459
3527
|
|
|
@@ -3596,8 +3664,10 @@ def main() -> None:
|
|
|
3596
3664
|
require_scan=require_scan,
|
|
3597
3665
|
scan_context=scan_context,
|
|
3598
3666
|
)
|
|
3599
|
-
elif args.command
|
|
3600
|
-
result = complete_scan(
|
|
3667
|
+
elif args.command in {"prepare-scan-completion", "complete-scan"}:
|
|
3668
|
+
result = complete_scan(
|
|
3669
|
+
connection, args, prepare_only=args.command == "prepare-scan-completion"
|
|
3670
|
+
)
|
|
3601
3671
|
elif args.command == "cancel-scan":
|
|
3602
3672
|
result = cancel_scan(connection, args)
|
|
3603
3673
|
elif args.command == "fail-scan":
|
|
@@ -72,6 +72,19 @@ def scan_diff_identity(
|
|
|
72
72
|
)
|
|
73
73
|
|
|
74
74
|
|
|
75
|
+
def stored_diff_target(row: sqlite3.Row) -> dict[str, str] | None:
|
|
76
|
+
if not row["diff_target_kind"]:
|
|
77
|
+
return None
|
|
78
|
+
target = {
|
|
79
|
+
"baseRevision": row["diff_base_revision"],
|
|
80
|
+
"headRevision": row["diff_head_revision"],
|
|
81
|
+
"kind": row["diff_target_kind"],
|
|
82
|
+
}
|
|
83
|
+
if row["diff_content_digest"]:
|
|
84
|
+
target["contentDigest"] = row["diff_content_digest"]
|
|
85
|
+
return target
|
|
86
|
+
|
|
87
|
+
|
|
75
88
|
def archive_scan(
|
|
76
89
|
connection: sqlite3.Connection,
|
|
77
90
|
args: argparse.Namespace,
|
|
@@ -143,6 +143,13 @@ def worktree_content_digest_for_context(
|
|
|
143
143
|
b"untracked-content",
|
|
144
144
|
os.fsencode(os.readlink(path)),
|
|
145
145
|
)
|
|
146
|
+
elif stat.S_ISDIR(metadata.st_mode):
|
|
147
|
+
update_digest_field(digest, b"untracked-kind", b"directory")
|
|
148
|
+
update_digest_field(
|
|
149
|
+
digest,
|
|
150
|
+
b"untracked-content",
|
|
151
|
+
directory_content_digest(path.resolve()).encode(),
|
|
152
|
+
)
|
|
146
153
|
elif stat.S_ISREG(metadata.st_mode):
|
|
147
154
|
content_digest = hashlib.sha256()
|
|
148
155
|
content_size = 0
|
|
@@ -419,7 +426,13 @@ def copy_git_worktree_files(source: Path, destination: Path, excluded: tuple[Pat
|
|
|
419
426
|
destination_path.symlink_to(os.readlink(source_path))
|
|
420
427
|
elif stat.S_ISREG(metadata.st_mode):
|
|
421
428
|
shutil.copy2(source_path, destination_path, follow_symlinks=False)
|
|
422
|
-
elif
|
|
429
|
+
elif stat.S_ISDIR(metadata.st_mode):
|
|
430
|
+
nested_git_dir = git_output(source_path, "rev-parse", "--absolute-git-dir")
|
|
431
|
+
if nested_git_dir is None:
|
|
432
|
+
raise SystemExit(f"Could not inspect nested Git working tree: {relative}")
|
|
433
|
+
copy_git_worktree_files(source_path, destination_path, excluded)
|
|
434
|
+
(destination_path / ".git").write_text(f"gitdir: {nested_git_dir}\n")
|
|
435
|
+
else:
|
|
423
436
|
raise SystemExit(f"Unsupported Git working-tree file type: {relative}")
|
|
424
437
|
copied_target = destination if pathspec == "." else destination / pathspec
|
|
425
438
|
copied_target.mkdir(parents=True, exist_ok=True)
|