@openai/codex-security 0.1.0 → 0.1.2
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 +106 -58
- 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/workbench_cli.py +5 -0
- package/_bundled_plugin/scripts/workbench_db.py +34 -98
- 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 +6 -3
- package/dist/api.d.ts.map +1 -1
- package/dist/api.js +107 -19
- package/dist/api.js.map +1 -1
- package/dist/cli.d.ts +7 -2
- package/dist/cli.d.ts.map +1 -1
- package/dist/cli.js +222 -48
- package/dist/cli.js.map +1 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.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/runtime.d.ts.map +1 -1
- package/dist/runtime.js +6 -1
- package/dist/runtime.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,73 +61,103 @@ 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.
|
|
92
|
+
|
|
93
|
+
An environment API key takes precedence over a stored sign-in by default.
|
|
94
|
+
When both a stored ChatGPT sign-in and an environment API key are available, an
|
|
95
|
+
interactive scan asks which credential to use. JSON output, dry runs, CI, and
|
|
96
|
+
other noninteractive scans never prompt and retain automatic API-key
|
|
97
|
+
precedence. Select the credential source explicitly with `--auth`:
|
|
98
|
+
|
|
99
|
+
```bash
|
|
100
|
+
npx @openai/codex-security scan . --auth chatgpt
|
|
101
|
+
npx @openai/codex-security scan . --auth api-key
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
`--auth chatgpt` uses the stored sign-in and ignores `OPENAI_API_KEY` and
|
|
105
|
+
`CODEX_API_KEY`. `--auth api-key` requires one of those environment variables.
|
|
106
|
+
Omit `--auth`, or pass `--auth auto`, to preserve automatic API-key precedence
|
|
107
|
+
for existing CI and unattended scans. The SDK accepts the same selection as
|
|
108
|
+
`security.run(repository, { auth: "chatgpt" })` and
|
|
109
|
+
`security.preflight(repository, { auth: "chatgpt" })`.
|
|
110
|
+
|
|
111
|
+
To make the stored ChatGPT sign-in the automatic default instead, unset any
|
|
112
|
+
configured API-key variables:
|
|
113
|
+
|
|
114
|
+
```bash
|
|
115
|
+
unset OPENAI_API_KEY CODEX_API_KEY
|
|
116
|
+
```
|
|
88
117
|
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
environment key is configured,
|
|
92
|
-
|
|
93
|
-
stored sign-in exists.
|
|
118
|
+
The interactive choice applies only to the current scan and is not persisted.
|
|
119
|
+
|
|
120
|
+
When an environment key is configured, ChatGPT login and
|
|
121
|
+
`codex-security login status` identify the effective scan credential source
|
|
122
|
+
without printing its value, including when no stored sign-in exists.
|
|
94
123
|
|
|
95
124
|
## CLI
|
|
96
125
|
|
|
97
126
|
```bash
|
|
98
|
-
npx codex-security scan /path/to/repository
|
|
99
|
-
npx codex-security scan /path/to/repository --model gpt-5.6-terra
|
|
100
|
-
npx codex-security scan /path/to/repository --
|
|
101
|
-
npx codex-security scan /path/to/repository --
|
|
102
|
-
npx codex-security scan /path/to/repository --
|
|
103
|
-
npx codex-security scan /path/to/repository --
|
|
104
|
-
npx codex-security scan /path/to/repository --output-dir /path/outside/repository/results
|
|
105
|
-
npx codex-security scan /path/to/repository --
|
|
106
|
-
npx codex-security scan /path/to/repository --
|
|
107
|
-
npx codex-security scan /path/to/repository --
|
|
108
|
-
npx codex-security
|
|
109
|
-
npx codex-security
|
|
110
|
-
npx codex-security bulk-scan
|
|
111
|
-
npx codex-security
|
|
112
|
-
npx codex-security
|
|
113
|
-
npx codex-security scans
|
|
114
|
-
npx codex-security scans
|
|
115
|
-
npx codex-security scans
|
|
116
|
-
npx codex-security scans
|
|
117
|
-
npx codex-security scans
|
|
118
|
-
npx codex-security
|
|
119
|
-
npx codex-security
|
|
120
|
-
npx codex-security
|
|
121
|
-
npx codex-security
|
|
122
|
-
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
|
|
123
157
|
```
|
|
124
158
|
|
|
125
|
-
Run `npx codex-security --version` for the installed CLI version or
|
|
126
|
-
`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,
|
|
127
161
|
default model, reasoning effort, and first-scan command. A scan with `--dry-run`
|
|
128
162
|
also reports its effective model and reasoning effort, including `--codex`
|
|
129
163
|
overrides, without starting Codex or contacting the network.
|
|
@@ -157,10 +191,11 @@ for a passing policy. Incomplete scans still write the available human or JSON
|
|
|
157
191
|
result to stdout and a coverage warning to stderr, including in report-only
|
|
158
192
|
mode.
|
|
159
193
|
|
|
160
|
-
Scans use `gpt-5.6-sol` with extra-high reasoning effort by default.
|
|
161
|
-
`--model gpt-5.6-terra` to switch models
|
|
162
|
-
|
|
163
|
-
`--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.
|
|
164
199
|
|
|
165
200
|
Scan progress identifies the requested paths and reports actual ranking,
|
|
166
201
|
file-review, validation, and attack-path phases as they become available.
|
|
@@ -178,10 +213,10 @@ Use `--max-cost USD` to stop a scan, including its delegated workers, when its
|
|
|
178
213
|
running cost exceeds the limit. Partial results are preserved. Requests
|
|
179
214
|
already in progress can finish above the limit.
|
|
180
215
|
|
|
181
|
-
Run `npx codex-security scan --help` or `npx codex-security bulk-scan --help`
|
|
216
|
+
Run `npx @openai/codex-security scan --help` or `npx @openai/codex-security bulk-scan --help`
|
|
182
217
|
for the complete CLI references.
|
|
183
218
|
|
|
184
|
-
Sign in with `gh auth login`, then run `npx codex-security bulk-scan` to discover
|
|
219
|
+
Sign in with `gh auth login`, then run `npx @openai/codex-security bulk-scan` to discover
|
|
185
220
|
GitHub repositories pushed in the last 90 days. Archived
|
|
186
221
|
repositories and forks are excluded. Search the repository list, select the
|
|
187
222
|
repositories to scan, and confirm before scanning.
|
|
@@ -203,7 +238,7 @@ Results remain under `--output-dir`; rerun the same command to resume.
|
|
|
203
238
|
|
|
204
239
|
### Scan history and reruns
|
|
205
240
|
|
|
206
|
-
`npx codex-security scans list` lists scans for the current repository. Pass a
|
|
241
|
+
`npx @openai/codex-security scans list` lists scans for the current repository. Pass a
|
|
207
242
|
repository path to inspect another checkout, `--scan-root DIR` to list scans
|
|
208
243
|
whose artifacts are under a particular root. `scans show SCAN_ID` includes the
|
|
209
244
|
scan configuration, results, coverage, and artifact locations.
|
|
@@ -216,6 +251,18 @@ Scan history uses the existing Codex Security workbench database at
|
|
|
216
251
|
`CODEX_SECURITY_STATE_DIR` to place the database elsewhere. Scan credentials
|
|
217
252
|
are never stored in the scan configuration.
|
|
218
253
|
|
|
254
|
+
The scan sandbox permits writes to the selected state directory so SQLite can
|
|
255
|
+
maintain its database and journal files. If the host itself cannot write to the
|
|
256
|
+
default directory, select a writable directory outside the scanned repository:
|
|
257
|
+
|
|
258
|
+
```bash
|
|
259
|
+
export CODEX_SECURITY_STATE_DIR=/path/to/writable/codex-security-state
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
Use `findings false-positive OCCURRENCE_ID --reason TEXT` to mark a finding as
|
|
263
|
+
a false positive and explain why. Later scans dismiss a matching finding only
|
|
264
|
+
when the same reason still applies.
|
|
265
|
+
|
|
219
266
|
`scans rerun SCAN_ID` repeats the original configuration against the current
|
|
220
267
|
checkout so a fixed vulnerability can be checked again.
|
|
221
268
|
|
|
@@ -246,7 +293,7 @@ nonzero:
|
|
|
246
293
|
|
|
247
294
|
```bash
|
|
248
295
|
SCAN_ROOT="$(mktemp -d)"
|
|
249
|
-
npx codex-security scan . \
|
|
296
|
+
npx @openai/codex-security scan . \
|
|
250
297
|
--diff origin/main \
|
|
251
298
|
--output-dir "$SCAN_ROOT/results" \
|
|
252
299
|
--json \
|
|
@@ -264,7 +311,7 @@ document. CSV uses the portable findings columns, marks findings as open, and
|
|
|
264
311
|
does not include local workbench triage state. The exporter validates the seal
|
|
265
312
|
before writing, accepts `--output -` for stdout, and can use
|
|
266
313
|
`--source-root /path/to/repository` with SARIF to add source-line fingerprints.
|
|
267
|
-
Run `npx codex-security export --help` for all export options.
|
|
314
|
+
Run `npx @openai/codex-security export --help` for all export options.
|
|
268
315
|
|
|
269
316
|
Use `validate` to run the bundled validation skill on candidate findings and
|
|
270
317
|
`patch` to run the bundled fix-finding skill on security issues. Each positional
|
|
@@ -272,9 +319,9 @@ input can be either a file, whose contents are read into the request, or literal
|
|
|
272
319
|
text. Both commands operate on the current directory, use the scan model
|
|
273
320
|
and reasoning defaults, ignore unrelated user configuration and plugins, and
|
|
274
321
|
print the final response without the underlying Codex event stream. Override
|
|
275
|
-
the model
|
|
276
|
-
`--codex 'model_reasoning_effort="high"'`. Inputs are
|
|
277
|
-
1 MiB total.
|
|
322
|
+
the model with `--codex 'model="gpt-5.6-sol"'` and the reasoning effort with
|
|
323
|
+
`--effort high` or `--codex 'model_reasoning_effort="high"'`. Inputs are
|
|
324
|
+
limited to 64 items and 1 MiB total.
|
|
278
325
|
|
|
279
326
|
Canonical scan documents are limited to 16 MiB for the manifest, 128 MiB for
|
|
280
327
|
findings, and 32 MiB for coverage. Oversized scans are rejected before sealing.
|
|
@@ -291,10 +338,11 @@ method and, for an environment API key, its variable name. Authentication and
|
|
|
291
338
|
model access remain unverified until a real scan starts.
|
|
292
339
|
|
|
293
340
|
Scan progress identifies the selected credential source before Codex starts.
|
|
294
|
-
|
|
295
|
-
API key overrides the stored sign-in.
|
|
296
|
-
|
|
297
|
-
|
|
341
|
+
Terminals and noninteractive CI logs also show how to retry with
|
|
342
|
+
`--auth chatgpt` when an environment API key overrides the stored sign-in.
|
|
343
|
+
Progress remains on stderr so JSON output stays machine readable. Network
|
|
344
|
+
failures and rate limits remain retryable; definitive authentication and model
|
|
345
|
+
authorization failures stop immediately.
|
|
298
346
|
|
|
299
347
|
## Documentation and security
|
|
300
348
|
|
|
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"}
|
|
@@ -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)
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
#!/usr/bin/env python3
|
|
2
|
-
"""
|
|
2
|
+
"""Codex Security workbench persistence."""
|
|
3
3
|
|
|
4
4
|
from __future__ import annotations
|
|
5
5
|
|
|
@@ -32,7 +32,7 @@ try:
|
|
|
32
32
|
except ModuleNotFoundError: # pragma: no cover - msvcrt is only available on Windows.
|
|
33
33
|
windows_file_lock = None
|
|
34
34
|
|
|
35
|
-
#
|
|
35
|
+
# Plugin hosts may enable safe-path isolation.
|
|
36
36
|
sys.path.insert(0, str(Path(__file__).resolve().parent))
|
|
37
37
|
import deep_scan_workbench as deep_scan
|
|
38
38
|
import workbench_native_indexes as native_indexes
|
|
@@ -40,7 +40,9 @@ import workbench_progress as progress
|
|
|
40
40
|
import workbench_remediation as remediation
|
|
41
41
|
import workbench_scan_history as scan_history
|
|
42
42
|
from filesystem_identity import serialize_filesystem_identity as serialize_filesystem_identity
|
|
43
|
-
from filesystem_identity import
|
|
43
|
+
from filesystem_identity import (
|
|
44
|
+
stored_filesystem_identity_matches as stored_filesystem_identity_matches,
|
|
45
|
+
)
|
|
44
46
|
from finalize_scan_contract import (
|
|
45
47
|
PRODUCER_NAME,
|
|
46
48
|
ContractError,
|
|
@@ -76,7 +78,9 @@ from workbench_constants import (
|
|
|
76
78
|
PATCH_PREVIEW_BYTES,
|
|
77
79
|
SQLITE_RETRY_ATTEMPTS,
|
|
78
80
|
)
|
|
81
|
+
from workbench_feedback import get_scan_feedback
|
|
79
82
|
from workbench_scan_start import (
|
|
83
|
+
archive_scan,
|
|
80
84
|
compact_timestamp,
|
|
81
85
|
insert_running_scan,
|
|
82
86
|
safe_segment,
|
|
@@ -97,6 +101,10 @@ from workbench_target import (
|
|
|
97
101
|
git_submodule_paths,
|
|
98
102
|
git_target_metadata,
|
|
99
103
|
git_worktree_context,
|
|
104
|
+
require_git_worktree_head,
|
|
105
|
+
require_remediation_target,
|
|
106
|
+
require_scan_target_identity,
|
|
107
|
+
scan_target_warning,
|
|
100
108
|
worktree_content_digest,
|
|
101
109
|
worktree_content_digest_for_context,
|
|
102
110
|
)
|
|
@@ -107,6 +115,7 @@ from workbench_validation import (
|
|
|
107
115
|
capability_preflight_json,
|
|
108
116
|
optional_text,
|
|
109
117
|
parse_scan_cost,
|
|
118
|
+
require_close_reason,
|
|
110
119
|
require_occurrence,
|
|
111
120
|
require_uuid,
|
|
112
121
|
)
|
|
@@ -190,8 +199,7 @@ def acquire_completion_file_lock(descriptor: int) -> None:
|
|
|
190
199
|
if windows_file_lock is None:
|
|
191
200
|
raise SystemExit("Scan completion requires operating-system file locking support.")
|
|
192
201
|
|
|
193
|
-
#
|
|
194
|
-
# first byte, and retry if another process locks that byte between our checks.
|
|
202
|
+
# Retry seeding and locking the first byte.
|
|
195
203
|
while os.fstat(descriptor).st_size == 0:
|
|
196
204
|
os.lseek(descriptor, 0, os.SEEK_SET)
|
|
197
205
|
try:
|
|
@@ -324,49 +332,6 @@ def require_target(value: str) -> Path:
|
|
|
324
332
|
return target
|
|
325
333
|
|
|
326
334
|
|
|
327
|
-
def require_remediation_target(value: str) -> Path:
|
|
328
|
-
stored = Path(value).expanduser()
|
|
329
|
-
if not stored.is_absolute():
|
|
330
|
-
raise SystemExit("Remediation target must be an absolute local directory path.")
|
|
331
|
-
try:
|
|
332
|
-
resolved = stored.resolve(strict=True)
|
|
333
|
-
except (FileNotFoundError, OSError) as exc:
|
|
334
|
-
raise SystemExit(
|
|
335
|
-
"Remediation is unavailable because the selected checkout is no longer accessible."
|
|
336
|
-
) from exc
|
|
337
|
-
if resolved != stored or not stored.is_dir():
|
|
338
|
-
raise SystemExit(
|
|
339
|
-
"Remediation is unavailable because the selected checkout path was replaced. Start a new scan."
|
|
340
|
-
)
|
|
341
|
-
return stored
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
def require_scan_target_identity(scan: sqlite3.Row) -> Path:
|
|
345
|
-
target = require_remediation_target(scan["target_path"])
|
|
346
|
-
expected_device = scan["target_device"]
|
|
347
|
-
expected_inode = scan["target_inode"]
|
|
348
|
-
if expected_device is None or expected_inode is None:
|
|
349
|
-
raise SystemExit(
|
|
350
|
-
"Remediation is unavailable because this scan does not record checkout identity. "
|
|
351
|
-
"Start a new scan."
|
|
352
|
-
)
|
|
353
|
-
try:
|
|
354
|
-
metadata = target.stat()
|
|
355
|
-
except OSError as exc:
|
|
356
|
-
raise SystemExit(
|
|
357
|
-
"Remediation is unavailable because the selected checkout is no longer accessible."
|
|
358
|
-
) from exc
|
|
359
|
-
if not (
|
|
360
|
-
stored_filesystem_identity_matches(expected_device, metadata.st_dev)
|
|
361
|
-
and stored_filesystem_identity_matches(expected_inode, metadata.st_ino)
|
|
362
|
-
):
|
|
363
|
-
raise SystemExit(
|
|
364
|
-
"Remediation is unavailable because the selected checkout path was replaced. "
|
|
365
|
-
"Start a new scan."
|
|
366
|
-
)
|
|
367
|
-
return target
|
|
368
|
-
|
|
369
|
-
|
|
370
335
|
def inspect_target(target_path: str) -> dict[str, Any]:
|
|
371
336
|
target = require_target(target_path)
|
|
372
337
|
return {
|
|
@@ -509,13 +474,6 @@ def inspect_setup(args: argparse.Namespace) -> dict[str, Any]:
|
|
|
509
474
|
)
|
|
510
475
|
|
|
511
476
|
|
|
512
|
-
def require_git_worktree_head(target: Path) -> str:
|
|
513
|
-
metadata = git_target_metadata(target)
|
|
514
|
-
if not metadata["isGit"] or not metadata["isWorktree"] or not metadata["hasHead"]:
|
|
515
|
-
raise SystemExit("Review changes requires a non-bare Git worktree with a resolvable HEAD.")
|
|
516
|
-
return str(metadata["revision"])
|
|
517
|
-
|
|
518
|
-
|
|
519
477
|
def require_review_changes_target(target: Path) -> str:
|
|
520
478
|
revision = require_git_worktree_head(target)
|
|
521
479
|
repository_root = git_output(target, "rev-parse", "--show-toplevel")
|
|
@@ -1371,42 +1329,6 @@ def start_prompt_only_scan(
|
|
|
1371
1329
|
return {**scan_context(connection, scan_id), "startDisposition": "created"}
|
|
1372
1330
|
|
|
1373
1331
|
|
|
1374
|
-
def require_unchanged_target(scan: sqlite3.Row) -> None:
|
|
1375
|
-
if scan["diff_target_kind"] != "working_tree" and not scan["target_snapshot_digest"]:
|
|
1376
|
-
return
|
|
1377
|
-
target = require_target(scan["target_path"])
|
|
1378
|
-
if scan["target_revision"] == "unversioned":
|
|
1379
|
-
current_digest = directory_content_digest(
|
|
1380
|
-
target,
|
|
1381
|
-
excluded=(Path(scan["scan_dir"]),),
|
|
1382
|
-
)
|
|
1383
|
-
if current_digest != scan["target_snapshot_digest"]:
|
|
1384
|
-
raise SystemExit(
|
|
1385
|
-
"Directory contents changed while the scan was running. Start a new scan."
|
|
1386
|
-
)
|
|
1387
|
-
return
|
|
1388
|
-
if git_revision(target) == "unversioned":
|
|
1389
|
-
raise SystemExit("The scan target revision no longer matches the selected target.")
|
|
1390
|
-
current_head = require_git_worktree_head(target)
|
|
1391
|
-
expected_head = (
|
|
1392
|
-
scan["diff_head_revision"]
|
|
1393
|
-
if scan["diff_target_kind"] == "working_tree"
|
|
1394
|
-
else scan["target_revision"]
|
|
1395
|
-
)
|
|
1396
|
-
if current_head != expected_head:
|
|
1397
|
-
raise SystemExit("Repository HEAD changed while the scan was running. Start a new scan.")
|
|
1398
|
-
current_digest = worktree_content_digest(target)
|
|
1399
|
-
expected_digest = (
|
|
1400
|
-
scan["diff_content_digest"]
|
|
1401
|
-
if scan["diff_target_kind"] == "working_tree"
|
|
1402
|
-
else scan["target_snapshot_digest"]
|
|
1403
|
-
)
|
|
1404
|
-
if current_digest != expected_digest:
|
|
1405
|
-
raise SystemExit(
|
|
1406
|
-
"Working-tree contents changed while the scan was running. Start a new scan."
|
|
1407
|
-
)
|
|
1408
|
-
|
|
1409
|
-
|
|
1410
1332
|
def scan_local_file_digest(scan_dir: Path, relative_path: str) -> str:
|
|
1411
1333
|
digest = hashlib.sha256()
|
|
1412
1334
|
with open_scan_local_file(scan_dir, relative_path) as source:
|
|
@@ -1490,7 +1412,10 @@ def complete_scan_locked(
|
|
|
1490
1412
|
)
|
|
1491
1413
|
if scan["recipe_json"] is None:
|
|
1492
1414
|
deep_scan.require_deep_scan_ready_for_parent_completion(connection, scan)
|
|
1493
|
-
|
|
1415
|
+
warnings = []
|
|
1416
|
+
warning = scan_target_warning(scan)
|
|
1417
|
+
if warning is not None:
|
|
1418
|
+
warnings.append(warning)
|
|
1494
1419
|
scan_dir = require_canonical_scan_directory(Path(scan["scan_dir"]))
|
|
1495
1420
|
completion_timestamp = now()
|
|
1496
1421
|
completion_binding = workbench_completion_binding(scan, completion_timestamp)
|
|
@@ -1506,8 +1431,9 @@ def complete_scan_locked(
|
|
|
1506
1431
|
expected_coverage_mode=expected_coverage_mode(scan),
|
|
1507
1432
|
completion_binding=completion_binding,
|
|
1508
1433
|
)
|
|
1509
|
-
|
|
1510
|
-
|
|
1434
|
+
warning = scan_target_warning(scan)
|
|
1435
|
+
if warning is not None and warning not in warnings:
|
|
1436
|
+
warnings.append(warning)
|
|
1511
1437
|
manifest, findings, _ = _write_prepared_scan_finalization(prepared)
|
|
1512
1438
|
except ContractError as exc:
|
|
1513
1439
|
raise SystemExit(str(exc)) from exc
|
|
@@ -1556,10 +1482,17 @@ def complete_scan_locked(
|
|
|
1556
1482
|
"""
|
|
1557
1483
|
UPDATE scans
|
|
1558
1484
|
SET status = 'complete', phase = 'reporting', completed_at = ?, updated_at = ?,
|
|
1559
|
-
seal_manifest_digest = ?, cost_json = ?
|
|
1485
|
+
seal_manifest_digest = ?, cost_json = ?, completion_warnings_json = ?
|
|
1560
1486
|
WHERE id = ? AND status = 'running'
|
|
1561
1487
|
""",
|
|
1562
|
-
(
|
|
1488
|
+
(
|
|
1489
|
+
timestamp,
|
|
1490
|
+
timestamp,
|
|
1491
|
+
manifest_digest,
|
|
1492
|
+
cost_json,
|
|
1493
|
+
json.dumps(warnings),
|
|
1494
|
+
scan["id"],
|
|
1495
|
+
),
|
|
1563
1496
|
)
|
|
1564
1497
|
if updated.rowcount != 1:
|
|
1565
1498
|
raise SystemExit("Only a running scan can be completed.")
|
|
@@ -1620,6 +1553,7 @@ def register_cli_scan(connection: sqlite3.Connection, args: argparse.Namespace)
|
|
|
1620
1553
|
|
|
1621
1554
|
connection.execute("BEGIN IMMEDIATE")
|
|
1622
1555
|
try:
|
|
1556
|
+
archive_scan(connection, args, scan_dir, timestamp, require_canonical_scan_directory)
|
|
1623
1557
|
target_id = ensure_security_target(connection, str(repository))
|
|
1624
1558
|
if parent_scan_id is not None:
|
|
1625
1559
|
parent = require_scan(connection, parent_scan_id)
|
|
@@ -1853,8 +1787,7 @@ def set_finding_triage(connection: sqlite3.Connection, args: argparse.Namespace)
|
|
|
1853
1787
|
if args.status == "closed" and close_reason is None:
|
|
1854
1788
|
raise SystemExit("Choose why this finding is being closed.")
|
|
1855
1789
|
note = optional_text(args.note, maximum=2400)
|
|
1856
|
-
|
|
1857
|
-
raise SystemExit("Explain why this finding will not be fixed.")
|
|
1790
|
+
require_close_reason(close_reason, note)
|
|
1858
1791
|
connection.execute("BEGIN IMMEDIATE")
|
|
1859
1792
|
try:
|
|
1860
1793
|
timestamp = now()
|
|
@@ -3072,6 +3005,7 @@ def scan_result(
|
|
|
3072
3005
|
finding_management_updated_at(connection, scan["id"]) or "",
|
|
3073
3006
|
),
|
|
3074
3007
|
"userContext": scan["user_context"],
|
|
3008
|
+
"warnings": json.loads(scan["completion_warnings_json"]),
|
|
3075
3009
|
}
|
|
3076
3010
|
|
|
3077
3011
|
|
|
@@ -3608,6 +3542,8 @@ def main() -> None:
|
|
|
3608
3542
|
result = deep_scan.fail_deep_scan(connection, args)
|
|
3609
3543
|
elif args.command == "get-scan":
|
|
3610
3544
|
result = scan_context(connection, args.scan_id, args.occurrence_id)
|
|
3545
|
+
elif args.command == "get-scan-feedback":
|
|
3546
|
+
result = get_scan_feedback(connection, require_scan(connection, args.scan_id))
|
|
3611
3547
|
elif args.command == "list-scans":
|
|
3612
3548
|
result = scan_history.list_scans(connection, args)
|
|
3613
3549
|
elif args.command == "list-unmatched-scan-pairs":
|
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
"""Load reviewed false-positive feedback for a security scan."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import argparse
|
|
6
|
+
import sqlite3
|
|
7
|
+
import sys
|
|
8
|
+
from pathlib import Path
|
|
9
|
+
from typing import Any
|
|
10
|
+
|
|
11
|
+
sys.path.insert(0, str(Path(__file__).resolve().parent))
|
|
12
|
+
from workbench_constants import (
|
|
13
|
+
FINDING_LOCATION_PATH_BYTES,
|
|
14
|
+
FINDING_SUMMARY_BYTES,
|
|
15
|
+
FINDING_TITLE_BYTES,
|
|
16
|
+
)
|
|
17
|
+
from workbench_validation import bounded_output_text
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
def get_scan_feedback(connection: sqlite3.Connection, scan: sqlite3.Row) -> dict[str, Any]:
|
|
21
|
+
rows = connection.execute(
|
|
22
|
+
"""
|
|
23
|
+
WITH ranked_decisions AS (
|
|
24
|
+
SELECT findings.id AS finding_id, findings.fingerprint, findings.rule_id,
|
|
25
|
+
findings.identity_anchor, findings.identity_instance, occurrences.title,
|
|
26
|
+
occurrences.summary, COALESCE(triage.status, 'open') AS triage_status,
|
|
27
|
+
triage.close_reason, triage.note,
|
|
28
|
+
COALESCE(triage.updated_at, source_scans.completed_at) AS updated_at,
|
|
29
|
+
source_scans.id AS source_scan_id,
|
|
30
|
+
source_scans.completed_at AS source_completed_at,
|
|
31
|
+
locations.relative_path, locations.start_line, locations.end_line, locations.role,
|
|
32
|
+
ROW_NUMBER() OVER (
|
|
33
|
+
PARTITION BY findings.id
|
|
34
|
+
ORDER BY COALESCE(triage.updated_at, source_scans.completed_at) DESC,
|
|
35
|
+
source_scans.completed_at DESC,
|
|
36
|
+
source_scans.id DESC, occurrences.id DESC
|
|
37
|
+
) AS decision_rank
|
|
38
|
+
FROM finding_occurrences AS occurrences
|
|
39
|
+
JOIN findings ON findings.id = occurrences.finding_id
|
|
40
|
+
JOIN scans AS source_scans ON source_scans.id = occurrences.scan_id
|
|
41
|
+
LEFT JOIN finding_triage AS triage ON triage.occurrence_id = occurrences.id
|
|
42
|
+
JOIN finding_locations AS locations ON locations.id = (
|
|
43
|
+
SELECT candidate.id
|
|
44
|
+
FROM finding_locations AS candidate
|
|
45
|
+
WHERE candidate.occurrence_id = occurrences.id
|
|
46
|
+
ORDER BY CASE WHEN candidate.role = 'root_control' THEN 0 ELSE 1 END,
|
|
47
|
+
candidate.sort_order
|
|
48
|
+
LIMIT 1
|
|
49
|
+
)
|
|
50
|
+
WHERE source_scans.target_id = ?
|
|
51
|
+
AND source_scans.id != ?
|
|
52
|
+
AND source_scans.status = 'complete'
|
|
53
|
+
)
|
|
54
|
+
SELECT *
|
|
55
|
+
FROM ranked_decisions
|
|
56
|
+
WHERE decision_rank = 1
|
|
57
|
+
AND triage_status = 'closed'
|
|
58
|
+
AND close_reason = 'false_positive'
|
|
59
|
+
AND note IS NOT NULL
|
|
60
|
+
AND trim(note) != ''
|
|
61
|
+
ORDER BY updated_at DESC, source_completed_at DESC, source_scan_id DESC, finding_id DESC
|
|
62
|
+
LIMIT 50
|
|
63
|
+
""",
|
|
64
|
+
(scan["target_id"], scan["id"]),
|
|
65
|
+
)
|
|
66
|
+
false_positives = []
|
|
67
|
+
for row in rows:
|
|
68
|
+
identity = {"anchor": row["identity_anchor"]}
|
|
69
|
+
if row["identity_instance"] is not None:
|
|
70
|
+
identity["instance"] = row["identity_instance"]
|
|
71
|
+
location = {
|
|
72
|
+
"path": bounded_output_text(row["relative_path"], FINDING_LOCATION_PATH_BYTES),
|
|
73
|
+
"startLine": row["start_line"],
|
|
74
|
+
"endLine": row["end_line"],
|
|
75
|
+
}
|
|
76
|
+
if row["role"] is not None:
|
|
77
|
+
location["role"] = row["role"]
|
|
78
|
+
false_positives.append(
|
|
79
|
+
{
|
|
80
|
+
"findingId": row["finding_id"],
|
|
81
|
+
"fingerprint": row["fingerprint"],
|
|
82
|
+
"ruleId": row["rule_id"],
|
|
83
|
+
"identity": identity,
|
|
84
|
+
"title": bounded_output_text(row["title"], FINDING_TITLE_BYTES),
|
|
85
|
+
"summary": bounded_output_text(row["summary"], FINDING_SUMMARY_BYTES),
|
|
86
|
+
"reason": row["note"],
|
|
87
|
+
"locations": [location],
|
|
88
|
+
"sourceScanId": row["source_scan_id"],
|
|
89
|
+
"updatedAt": row["updated_at"],
|
|
90
|
+
}
|
|
91
|
+
)
|
|
92
|
+
return {"scanId": scan["id"], "targetId": scan["target_id"], "falsePositives": false_positives}
|
|
93
|
+
|
|
94
|
+
|
|
95
|
+
if __name__ == "__main__":
|
|
96
|
+
argparse.ArgumentParser(description=__doc__).parse_args()
|