@openai/codex-security 0.1.1 → 0.1.3
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 +92 -51
- package/_bundled_plugin/mcp/mcp-app.html.br +0 -0
- 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/scripts/config_preflight.py +1 -1
- 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 +5 -0
- package/_bundled_plugin/scripts/workbench_db.py +39 -100
- package/_bundled_plugin/scripts/workbench_feedback.py +96 -0
- package/_bundled_plugin/scripts/workbench_scan_history.py +11 -1
- package/_bundled_plugin/scripts/workbench_scan_start.py +76 -0
- package/_bundled_plugin/scripts/workbench_schema.py +8 -0
- package/_bundled_plugin/scripts/workbench_target.py +95 -0
- package/_bundled_plugin/scripts/workbench_validation.py +7 -0
- package/_bundled_plugin/skills/validation/SKILL.md +2 -0
- package/dist/api.d.ts +2 -1
- package/dist/api.d.ts.map +1 -1
- package/dist/api.js +49 -5
- 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 +4 -1
- package/dist/cli.d.ts.map +1 -1
- package/dist/cli.js +162 -45
- package/dist/cli.js.map +1 -1
- package/dist/config.d.ts.map +1 -1
- package/dist/config.js +4 -0
- package/dist/config.js.map +1 -1
- package/dist/multiscan.d.ts.map +1 -1
- package/dist/multiscan.js +3 -1
- package/dist/multiscan.js.map +1 -1
- package/dist/scan-history-renderer.d.ts.map +1 -1
- package/dist/scan-history-renderer.js +8 -0
- package/dist/scan-history-renderer.js.map +1 -1
- package/dist/version.d.ts +14 -0
- package/dist/version.d.ts.map +1 -1
- package/dist/version.js +102 -0
- package/dist/version.js.map +1 -1
- package/package.json +2 -1
package/README.md
CHANGED
|
@@ -12,7 +12,7 @@ executable, and the matching Codex runtime.
|
|
|
12
12
|
|
|
13
13
|
```bash
|
|
14
14
|
npm install @openai/codex-security
|
|
15
|
-
npx codex-security --version
|
|
15
|
+
npx @openai/codex-security --version
|
|
16
16
|
```
|
|
17
17
|
|
|
18
18
|
The package supports macOS, Linux, and Windows and requires Node.js 22 or
|
|
@@ -20,9 +20,13 @@ later. Scanning and exporting findings also require Python 3.10 or later. If
|
|
|
20
20
|
you use Python 3.10, install the `tomli` package. Select another interpreter
|
|
21
21
|
with `--python`, `pythonPath`, or `PYTHON` when needed.
|
|
22
22
|
|
|
23
|
+
When a newer version is available, the CLI shows the update command for your
|
|
24
|
+
installation method. Set `CODEX_SECURITY_NO_UPDATE_NOTICE=1` to hide the
|
|
25
|
+
notice. Notices are also disabled in CI and when stderr is not a terminal.
|
|
26
|
+
|
|
23
27
|
## Run a scan from TypeScript
|
|
24
28
|
|
|
25
|
-
Sign in with `npx codex-security login` or set `OPENAI_API_KEY` or
|
|
29
|
+
Sign in with `npx @openai/codex-security login` or set `OPENAI_API_KEY` or
|
|
26
30
|
`CODEX_API_KEY`. Then create a client and scan a repository you own or have
|
|
27
31
|
permission to assess:
|
|
28
32
|
|
|
@@ -57,34 +61,34 @@ limit access to authorized reviewers.
|
|
|
57
61
|
For local use, sign in with ChatGPT:
|
|
58
62
|
|
|
59
63
|
```bash
|
|
60
|
-
npx codex-security login
|
|
61
|
-
npx codex-security scan .
|
|
64
|
+
npx @openai/codex-security login
|
|
65
|
+
npx @openai/codex-security scan .
|
|
62
66
|
```
|
|
63
67
|
|
|
64
68
|
On a remote or headless machine, use device authentication:
|
|
65
69
|
|
|
66
70
|
```bash
|
|
67
|
-
npx codex-security login --device-auth
|
|
71
|
+
npx @openai/codex-security login --device-auth
|
|
68
72
|
```
|
|
69
73
|
|
|
70
74
|
For CI, set `OPENAI_API_KEY` or `CODEX_API_KEY`. To store an API key instead,
|
|
71
75
|
pass it on stdin:
|
|
72
76
|
|
|
73
77
|
```bash
|
|
74
|
-
printenv OPENAI_API_KEY | npx codex-security login --with-api-key
|
|
78
|
+
printenv OPENAI_API_KEY | npx @openai/codex-security login --with-api-key
|
|
75
79
|
```
|
|
76
80
|
|
|
77
81
|
On Windows, set the API key in PowerShell:
|
|
78
82
|
|
|
79
83
|
```powershell
|
|
80
84
|
$env:OPENAI_API_KEY = "<your-api-key>"
|
|
81
|
-
npx codex-security scan C:\code\repository
|
|
85
|
+
npx @openai/codex-security scan C:\code\repository
|
|
82
86
|
```
|
|
83
87
|
|
|
84
|
-
Check or remove the stored sign-in with `npx codex-security login status` and
|
|
85
|
-
`npx codex-security logout`. Codex Security reuses an existing file-based Codex
|
|
88
|
+
Check or remove the stored sign-in with `npx @openai/codex-security login status` and
|
|
89
|
+
`npx @openai/codex-security logout`. Codex Security reuses an existing file-based Codex
|
|
86
90
|
sign-in. If Codex stores credentials in the system keyring, run
|
|
87
|
-
`npx codex-security login` once before scanning.
|
|
91
|
+
`npx @openai/codex-security login` once before scanning.
|
|
88
92
|
|
|
89
93
|
An environment API key takes precedence over a stored sign-in by default.
|
|
90
94
|
When both a stored ChatGPT sign-in and an environment API key are available, an
|
|
@@ -93,8 +97,8 @@ other noninteractive scans never prompt and retain automatic API-key
|
|
|
93
97
|
precedence. Select the credential source explicitly with `--auth`:
|
|
94
98
|
|
|
95
99
|
```bash
|
|
96
|
-
npx codex-security scan . --auth chatgpt
|
|
97
|
-
npx codex-security scan . --auth api-key
|
|
100
|
+
npx @openai/codex-security scan . --auth chatgpt
|
|
101
|
+
npx @openai/codex-security scan . --auth api-key
|
|
98
102
|
```
|
|
99
103
|
|
|
100
104
|
`--auth chatgpt` uses the stored sign-in and ignores `OPENAI_API_KEY` and
|
|
@@ -120,35 +124,40 @@ without printing its value, including when no stored sign-in exists.
|
|
|
120
124
|
## CLI
|
|
121
125
|
|
|
122
126
|
```bash
|
|
123
|
-
npx codex-security scan /path/to/repository
|
|
124
|
-
npx codex-security scan /path/to/repository --model gpt-5.6-terra
|
|
125
|
-
npx codex-security scan /path/to/repository --
|
|
126
|
-
npx codex-security scan /path/to/repository --
|
|
127
|
-
npx codex-security scan /path/to/repository --
|
|
128
|
-
npx codex-security scan /path/to/repository --
|
|
129
|
-
npx codex-security scan /path/to/repository --output-dir /path/outside/repository/results
|
|
130
|
-
npx codex-security scan /path/to/repository --
|
|
131
|
-
npx codex-security scan /path/to/repository --
|
|
132
|
-
npx codex-security scan /path/to/repository --
|
|
133
|
-
npx codex-security
|
|
134
|
-
npx codex-security
|
|
135
|
-
npx codex-security bulk-scan
|
|
136
|
-
npx codex-security
|
|
137
|
-
npx codex-security
|
|
138
|
-
npx codex-security scans
|
|
139
|
-
npx codex-security scans
|
|
140
|
-
npx codex-security scans
|
|
141
|
-
npx codex-security scans
|
|
142
|
-
npx codex-security scans
|
|
143
|
-
npx codex-security
|
|
144
|
-
npx codex-security
|
|
145
|
-
npx codex-security
|
|
146
|
-
npx codex-security
|
|
147
|
-
npx codex-security
|
|
127
|
+
npx @openai/codex-security scan /path/to/repository
|
|
128
|
+
npx @openai/codex-security scan /path/to/repository --model gpt-5.6-terra
|
|
129
|
+
npx @openai/codex-security scan /path/to/repository --model gpt-5.6-terra --effort high
|
|
130
|
+
npx @openai/codex-security scan /path/to/repository --path src --path tests
|
|
131
|
+
npx @openai/codex-security scan /path/to/repository --knowledge-base /path/to/threat-models --knowledge-base /path/to/architecture.pdf
|
|
132
|
+
npx @openai/codex-security scan /path/to/repository --diff origin/main --json
|
|
133
|
+
npx @openai/codex-security scan /path/to/repository --output-dir /path/outside/repository/results
|
|
134
|
+
npx @openai/codex-security scan /path/to/repository --output-dir /path/outside/repository/results --archive-existing
|
|
135
|
+
npx @openai/codex-security scan /path/to/repository --dry-run
|
|
136
|
+
npx @openai/codex-security scan /path/to/repository --fail-on-severity high
|
|
137
|
+
npx @openai/codex-security scan /path/to/repository --max-cost 5
|
|
138
|
+
npx @openai/codex-security install-hook
|
|
139
|
+
npx @openai/codex-security bulk-scan
|
|
140
|
+
npx @openai/codex-security bulk-scan --model gpt-5.6-terra --effort high
|
|
141
|
+
npx @openai/codex-security bulk-scan repositories.csv --output-dir /path/outside/repositories/security-scans --workers 4
|
|
142
|
+
npx @openai/codex-security scans list /path/to/repository
|
|
143
|
+
npx @openai/codex-security scans list --scan-root /path/outside/repository/results
|
|
144
|
+
npx @openai/codex-security scans show SCAN_ID
|
|
145
|
+
npx @openai/codex-security scans rerun SCAN_ID
|
|
146
|
+
npx @openai/codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID
|
|
147
|
+
npx @openai/codex-security scans match --all
|
|
148
|
+
npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID
|
|
149
|
+
npx @openai/codex-security findings false-positive OCCURRENCE_ID --reason "The route already checks permissions"
|
|
150
|
+
npx @openai/codex-security export /path/outside/repository/results --export-format sarif --output /path/outside/repository/results.sarif
|
|
151
|
+
npx @openai/codex-security export /path/outside/repository/results --export-format csv --output /path/outside/repository/findings.csv
|
|
152
|
+
npx @openai/codex-security export /path/outside/repository/results --export-format json --output /path/outside/repository/findings.json
|
|
153
|
+
npx @openai/codex-security validate /path/outside/repository/findings.json "Possible SQL injection in src/query.ts:42"
|
|
154
|
+
npx @openai/codex-security validate "Possible SQL injection" --effort high
|
|
155
|
+
npx @openai/codex-security patch /path/outside/repository/findings.json "Missing authorization check in src/routes.ts:18"
|
|
156
|
+
npx @openai/codex-security patch "Missing authorization check" --effort high
|
|
148
157
|
```
|
|
149
158
|
|
|
150
|
-
Run `npx codex-security --version` for the installed CLI version or
|
|
151
|
-
`npx codex-security info --json` for the package, bundled plugin, Codex runtime,
|
|
159
|
+
Run `npx @openai/codex-security --version` for the installed CLI version or
|
|
160
|
+
`npx @openai/codex-security info --json` for the package, bundled plugin, Codex runtime,
|
|
152
161
|
default model, reasoning effort, and first-scan command. A scan with `--dry-run`
|
|
153
162
|
also reports its effective model and reasoning effort, including `--codex`
|
|
154
163
|
overrides, without starting Codex or contacting the network.
|
|
@@ -182,10 +191,14 @@ for a passing policy. Incomplete scans still write the available human or JSON
|
|
|
182
191
|
result to stdout and a coverage warning to stderr, including in report-only
|
|
183
192
|
mode.
|
|
184
193
|
|
|
185
|
-
Scans use `gpt-5.6-sol` with extra-high reasoning effort by default.
|
|
186
|
-
`--model gpt-5.6-terra` to switch models
|
|
187
|
-
|
|
188
|
-
`--codex
|
|
194
|
+
Scans use `gpt-5.6-sol` with extra-high reasoning effort by default. OpenAI is
|
|
195
|
+
the implied provider. Use `--model gpt-5.6-terra` to switch models and
|
|
196
|
+
`--effort minimal|low|medium|high|xhigh` to set reasoning effort. Repeat
|
|
197
|
+
`--codex KEY=VALUE` for other Codex settings; existing
|
|
198
|
+
`--codex 'model_reasoning_effort="high"'` overrides remain supported.
|
|
199
|
+
|
|
200
|
+
These overrides do not change the scan's approval policy or filesystem
|
|
201
|
+
permissions. See [Local security model](#local-security-model).
|
|
189
202
|
|
|
190
203
|
Scan progress identifies the requested paths and reports actual ranking,
|
|
191
204
|
file-review, validation, and attack-path phases as they become available.
|
|
@@ -203,10 +216,10 @@ Use `--max-cost USD` to stop a scan, including its delegated workers, when its
|
|
|
203
216
|
running cost exceeds the limit. Partial results are preserved. Requests
|
|
204
217
|
already in progress can finish above the limit.
|
|
205
218
|
|
|
206
|
-
Run `npx codex-security scan --help` or `npx codex-security bulk-scan --help`
|
|
219
|
+
Run `npx @openai/codex-security scan --help` or `npx @openai/codex-security bulk-scan --help`
|
|
207
220
|
for the complete CLI references.
|
|
208
221
|
|
|
209
|
-
Sign in with `gh auth login`, then run `npx codex-security bulk-scan` to discover
|
|
222
|
+
Sign in with `gh auth login`, then run `npx @openai/codex-security bulk-scan` to discover
|
|
210
223
|
GitHub repositories pushed in the last 90 days. Archived
|
|
211
224
|
repositories and forks are excluded. Search the repository list, select the
|
|
212
225
|
repositories to scan, and confirm before scanning.
|
|
@@ -228,7 +241,7 @@ Results remain under `--output-dir`; rerun the same command to resume.
|
|
|
228
241
|
|
|
229
242
|
### Scan history and reruns
|
|
230
243
|
|
|
231
|
-
`npx codex-security scans list` lists scans for the current repository. Pass a
|
|
244
|
+
`npx @openai/codex-security scans list` lists scans for the current repository. Pass a
|
|
232
245
|
repository path to inspect another checkout, `--scan-root DIR` to list scans
|
|
233
246
|
whose artifacts are under a particular root. `scans show SCAN_ID` includes the
|
|
234
247
|
scan configuration, results, coverage, and artifact locations.
|
|
@@ -249,6 +262,10 @@ default directory, select a writable directory outside the scanned repository:
|
|
|
249
262
|
export CODEX_SECURITY_STATE_DIR=/path/to/writable/codex-security-state
|
|
250
263
|
```
|
|
251
264
|
|
|
265
|
+
Use `findings false-positive OCCURRENCE_ID --reason TEXT` to mark a finding as
|
|
266
|
+
a false positive and explain why. Later scans dismiss a matching finding only
|
|
267
|
+
when the same reason still applies.
|
|
268
|
+
|
|
252
269
|
`scans rerun SCAN_ID` repeats the original configuration against the current
|
|
253
270
|
checkout so a fixed vulnerability can be checked again.
|
|
254
271
|
|
|
@@ -279,7 +296,7 @@ nonzero:
|
|
|
279
296
|
|
|
280
297
|
```bash
|
|
281
298
|
SCAN_ROOT="$(mktemp -d)"
|
|
282
|
-
npx codex-security scan . \
|
|
299
|
+
npx @openai/codex-security scan . \
|
|
283
300
|
--diff origin/main \
|
|
284
301
|
--output-dir "$SCAN_ROOT/results" \
|
|
285
302
|
--json \
|
|
@@ -297,7 +314,7 @@ document. CSV uses the portable findings columns, marks findings as open, and
|
|
|
297
314
|
does not include local workbench triage state. The exporter validates the seal
|
|
298
315
|
before writing, accepts `--output -` for stdout, and can use
|
|
299
316
|
`--source-root /path/to/repository` with SARIF to add source-line fingerprints.
|
|
300
|
-
Run `npx codex-security export --help` for all export options.
|
|
317
|
+
Run `npx @openai/codex-security export --help` for all export options.
|
|
301
318
|
|
|
302
319
|
Use `validate` to run the bundled validation skill on candidate findings and
|
|
303
320
|
`patch` to run the bundled fix-finding skill on security issues. Each positional
|
|
@@ -305,9 +322,9 @@ input can be either a file, whose contents are read into the request, or literal
|
|
|
305
322
|
text. Both commands operate on the current directory, use the scan model
|
|
306
323
|
and reasoning defaults, ignore unrelated user configuration and plugins, and
|
|
307
324
|
print the final response without the underlying Codex event stream. Override
|
|
308
|
-
the model
|
|
309
|
-
`--codex 'model_reasoning_effort="high"'`. Inputs are
|
|
310
|
-
1 MiB total.
|
|
325
|
+
the model with `--codex 'model="gpt-5.6-sol"'` and the reasoning effort with
|
|
326
|
+
`--effort high` or `--codex 'model_reasoning_effort="high"'`. Inputs are
|
|
327
|
+
limited to 64 items and 1 MiB total.
|
|
311
328
|
|
|
312
329
|
Canonical scan documents are limited to 16 MiB for the manifest, 128 MiB for
|
|
313
330
|
findings, and 32 MiB for coverage. Oversized scans are rejected before sealing.
|
|
@@ -330,6 +347,30 @@ Progress remains on stderr so JSON output stays machine readable. Network
|
|
|
330
347
|
failures and rate limits remain retryable; definitive authentication and model
|
|
331
348
|
authorization failures stop immediately.
|
|
332
349
|
|
|
350
|
+
## Local security model
|
|
351
|
+
|
|
352
|
+
Codex Security runs with your local operating-system permissions. Scan only
|
|
353
|
+
repositories you trust and either own or are authorized to assess. Your
|
|
354
|
+
repository, Git installation, configured tools, and other scans under the
|
|
355
|
+
same account are not separate security principals.
|
|
356
|
+
|
|
357
|
+
Every scan uses the `codex_security_scan` filesystem profile and
|
|
358
|
+
`approvalPolicy: "never"`. It can read the local filesystem and write to
|
|
359
|
+
workspace roots and the selected scan state directory. Scans do not request
|
|
360
|
+
interactive approval. Setting `approval_policy`, `sandbox_mode`, or permissions
|
|
361
|
+
through `--codex` or SDK `codexOverrides` does not replace these controls or
|
|
362
|
+
make them more restrictive. Independently enforced host and network
|
|
363
|
+
restrictions still apply.
|
|
364
|
+
|
|
365
|
+
Scan and workbench subprocesses can inherit your environment, including
|
|
366
|
+
unrelated API tokens and cloud credentials. Start a scan with only the
|
|
367
|
+
credentials it needs.
|
|
368
|
+
|
|
369
|
+
The scanner must stay within the target and output paths you authorize and
|
|
370
|
+
must not disclose private data beyond the operation you requested. Its results
|
|
371
|
+
must accurately report the scan mode, reviewed files, and exclusions. Consult
|
|
372
|
+
the security policy for the full threat model and private reporting process.
|
|
373
|
+
|
|
333
374
|
## Documentation and security
|
|
334
375
|
|
|
335
376
|
- [CLI quickstart](https://developers.openai.com/codex/security/cli)
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
@@ -19,7 +19,7 @@ except ModuleNotFoundError: # pragma: no cover - Python 3.10 only
|
|
|
19
19
|
|
|
20
20
|
PLUGIN_ROOT = Path(__file__).resolve().parents[1]
|
|
21
21
|
DEFAULT_REGISTRY = PLUGIN_ROOT / "preflight" / "capability-profiles.toml"
|
|
22
|
-
DEFAULT_CODEX_HOME = Path(os.environ.get("CODEX_HOME",
|
|
22
|
+
DEFAULT_CODEX_HOME = Path(os.environ.get("CODEX_HOME", "~/.codex")).expanduser()
|
|
23
23
|
SYSTEM_CONFIG = Path("/etc/codex/config.toml")
|
|
24
24
|
DEFAULT_CONFIG = DEFAULT_CODEX_HOME / "config.toml"
|
|
25
25
|
VALID_SEVERITIES = {"block", "warn", "suggest"}
|
|
@@ -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)
|
|
@@ -136,6 +136,9 @@ def parse_args(description: str) -> argparse.Namespace:
|
|
|
136
136
|
get_scan.add_argument("--scan-id", required=True)
|
|
137
137
|
get_scan.add_argument("--occurrence-id")
|
|
138
138
|
|
|
139
|
+
get_scan_feedback = subparsers.add_parser("get-scan-feedback")
|
|
140
|
+
get_scan_feedback.add_argument("--scan-id", required=True)
|
|
141
|
+
|
|
139
142
|
list_scans = subparsers.add_parser("list-scans")
|
|
140
143
|
list_scans.add_argument("--query")
|
|
141
144
|
list_scans.add_argument("--target-id")
|
|
@@ -155,6 +158,8 @@ def parse_args(description: str) -> argparse.Namespace:
|
|
|
155
158
|
register_cli_scan.add_argument("--repository", required=True)
|
|
156
159
|
register_cli_scan.add_argument("--recipe-json", required=True)
|
|
157
160
|
register_cli_scan.add_argument("--parent-scan-id")
|
|
161
|
+
register_cli_scan.add_argument("--archive-existing", action="store_true")
|
|
162
|
+
register_cli_scan.add_argument("--archived-scan-dir")
|
|
158
163
|
|
|
159
164
|
get_scan_recipe = subparsers.add_parser("get-scan-recipe")
|
|
160
165
|
get_scan_recipe.add_argument("--scan-id", required=True)
|