@openai/codex-security 0.1.25 → 0.1.26
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 +222 -8
- package/_bundled_plugin/.app.json +0 -5
- package/_bundled_plugin/.codex-plugin/plugin.json +1 -1
- package/_bundled_plugin/.mcp.json +1 -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/references/config-preflight.md +2 -2
- package/_bundled_plugin/references/final-report.md +5 -3
- package/_bundled_plugin/references/scan-artifacts.md +5 -1
- package/_bundled_plugin/references/scan-contract.md +7 -3
- package/_bundled_plugin/schemas/tools/deep-reducer.schema.json +27 -1
- package/_bundled_plugin/scripts/deep_scan_workbench.py +6 -1
- package/_bundled_plugin/scripts/finalize_scan_contract.py +2 -5
- package/_bundled_plugin/scripts/report_projection.py +1 -1
- package/_bundled_plugin/scripts/workbench_cli.py +3 -0
- package/_bundled_plugin/scripts/workbench_db.py +11 -2
- package/_bundled_plugin/scripts/workbench_saved_results.py +41 -22
- package/_bundled_plugin/scripts/workbench_scan_usage.py +7 -6
- package/_bundled_plugin/scripts/workbench_schema.py +31 -0
- package/_bundled_plugin/scripts/workbench_severity.py +119 -0
- package/_bundled_plugin/skills/deep-security-scan/SKILL.md +5 -3
- package/_bundled_plugin/skills/verify-fix/SKILL.md +5 -1
- package/dist/api.d.ts.map +1 -1
- package/dist/api.js +4 -5
- package/dist/api.js.map +1 -1
- package/dist/classify-scan-severity.d.ts +16 -0
- package/dist/classify-scan-severity.d.ts.map +1 -0
- package/dist/classify-scan-severity.js +96 -0
- package/dist/classify-scan-severity.js.map +1 -0
- package/dist/classify-severity.d.ts +38 -0
- package/dist/classify-severity.d.ts.map +1 -0
- package/dist/classify-severity.js +185 -0
- package/dist/classify-severity.js.map +1 -0
- package/dist/cli.d.ts +5 -2
- package/dist/cli.d.ts.map +1 -1
- package/dist/cli.js +323 -89
- package/dist/cli.js.map +1 -1
- package/dist/cost.js +20 -6
- package/dist/cost.js.map +1 -1
- package/dist/deduplication/deduplication-reviewer.js +1 -1
- package/dist/deduplication/deduplication-reviewer.js.map +1 -1
- package/dist/finding-catalogue.d.ts +11 -0
- package/dist/finding-catalogue.d.ts.map +1 -0
- package/dist/finding-catalogue.js +150 -0
- package/dist/finding-catalogue.js.map +1 -0
- package/dist/index.d.ts +6 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +3 -0
- package/dist/index.js.map +1 -1
- package/dist/patch-tui.js +1 -1
- package/dist/patch-tui.js.map +1 -1
- package/dist/publication-store.d.ts.map +1 -1
- package/dist/publication-store.js +9 -4
- package/dist/publication-store.js.map +1 -1
- package/dist/publication.d.ts +9 -0
- package/dist/publication.d.ts.map +1 -1
- package/dist/publication.js +45 -5
- package/dist/publication.js.map +1 -1
- package/dist/publish.d.ts +4 -2
- package/dist/publish.d.ts.map +1 -1
- package/dist/publish.js +2 -2
- package/dist/publish.js.map +1 -1
- package/dist/scan-comparison.d.ts +42 -37
- package/dist/scan-comparison.d.ts.map +1 -1
- package/dist/scan-comparison.js +535 -161
- package/dist/scan-comparison.js.map +1 -1
- package/dist/scan-history-renderer.d.ts.map +1 -1
- package/dist/scan-history-renderer.js +5 -0
- package/dist/scan-history-renderer.js.map +1 -1
- package/dist/severity-store.d.ts +2 -0
- package/dist/severity-store.d.ts.map +1 -0
- package/dist/severity-store.js +111 -0
- package/dist/severity-store.js.map +1 -0
- package/dist/thread-source.d.ts +1 -0
- package/dist/thread-source.d.ts.map +1 -1
- package/dist/thread-source.js +1 -0
- package/dist/thread-source.js.map +1 -1
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/dist/version.js.map +1 -1
- package/package.json +4 -4
package/README.md
CHANGED
|
@@ -40,7 +40,7 @@ try {
|
|
|
40
40
|
|
|
41
41
|
`result.findings` contains this scan's findings; `repositoryFindings` also
|
|
42
42
|
includes earlier open findings when available. Matching earlier findings can
|
|
43
|
-
make
|
|
43
|
+
make extra model calls; see [Progress and cost](#progress-and-cost).
|
|
44
44
|
|
|
45
45
|
Keep results outside the repository and restrict access: reports can contain
|
|
46
46
|
source code, vulnerability details, and reproduction steps.
|
|
@@ -69,6 +69,10 @@ Pass literal text or a JSON-serializable object as `finding`, not a file path.
|
|
|
69
69
|
Validation uses the client's settings and credentials without changing
|
|
70
70
|
repository files or adding a scan to history.
|
|
71
71
|
|
|
72
|
+
To disable Codex usage analytics and built-in metrics, create the client with
|
|
73
|
+
`new CodexSecurity({ codexOverrides: { analytics: { enabled: false } } })`.
|
|
74
|
+
This setting also applies to scans run by the same client.
|
|
75
|
+
|
|
72
76
|
Results include `disposition` (`reportable`, `suppressed`, `not_applicable`,
|
|
73
77
|
or `deferred`), a Markdown `report`, `threadId`, and evidence `outputDir`.
|
|
74
78
|
`reportable` may rely on static analysis; `deferred` means insufficient evidence.
|
|
@@ -515,8 +519,29 @@ or `features.plugins` are rejected, including in profiles. Multi-agent v2 must
|
|
|
515
519
|
stay enabled: `agents.max_threads` and
|
|
516
520
|
`features.multi_agent_v2.enabled=false` are rejected.
|
|
517
521
|
|
|
518
|
-
`validate` and `
|
|
519
|
-
`model_reasoning_effort` keys in `--codex`, but no
|
|
522
|
+
`validate`, `patch`, and `verify-fix` accept `--effort` and the `model`,
|
|
523
|
+
`model_reasoning_effort`, and `analytics.enabled` keys in `--codex`, but no
|
|
524
|
+
other runtime overrides.
|
|
525
|
+
|
|
526
|
+
Use `--codex 'analytics.enabled=false'` to disable Codex usage analytics and
|
|
527
|
+
built-in metrics for a command:
|
|
528
|
+
|
|
529
|
+
```bash
|
|
530
|
+
npx @openai/codex-security validate "Candidate finding" --codex 'analytics.enabled=false'
|
|
531
|
+
npx @openai/codex-security patch "Security issue" --codex 'analytics.enabled=false'
|
|
532
|
+
npx @openai/codex-security verify-fix "Security issue" --codex 'analytics.enabled=false'
|
|
533
|
+
```
|
|
534
|
+
|
|
535
|
+
The same setting works for `scan` and `bulk-scan`. An explicit setting is
|
|
536
|
+
preserved when `scan --patch` starts remediation and when
|
|
537
|
+
`patch --assess-patch-risk` starts its follow-up assessment. Boolean `true`
|
|
538
|
+
is also accepted; omitting the setting preserves the command's existing
|
|
539
|
+
configuration and Codex defaults. Validation continues to ignore user
|
|
540
|
+
configuration, while patching and verification retain their existing ambient
|
|
541
|
+
configuration and project-trust behavior.
|
|
542
|
+
|
|
543
|
+
This setting does not control explicitly configured OpenTelemetry log or trace
|
|
544
|
+
exporters, authentication, integrations, or CLI update checks.
|
|
520
545
|
|
|
521
546
|
See [Local security model](#local-security-model) for approval and filesystem
|
|
522
547
|
restrictions.
|
|
@@ -568,6 +593,10 @@ discovery has finished, the scan returns a sealed partial report without more
|
|
|
568
593
|
model calls and lists unvalidated candidates as follow-up work. Bulk scans
|
|
569
594
|
apply the limit per repository attempt.
|
|
570
595
|
|
|
596
|
+
With `--max-cost`, automatic finding-history matching makes at most one extra
|
|
597
|
+
model call. If it needs more context, the completed scan is kept and a warning
|
|
598
|
+
directs you to run `scans match --all` explicitly.
|
|
599
|
+
|
|
571
600
|
For a single scan in the interactive dashboard, reaching 80% of the limit
|
|
572
601
|
offers a higher **total** USD limit. Enter a larger amount to approve it, or
|
|
573
602
|
press Enter with an empty input or Escape to keep the current limit. The scan
|
|
@@ -826,6 +855,139 @@ Options include `projectId`, `skipExisting`, `linearApiKey` for direct API
|
|
|
826
855
|
publication, and `assigneeId` (user ID or email). `checkScanPublication` accepts
|
|
827
856
|
the same destination options for a read-only check.
|
|
828
857
|
|
|
858
|
+
### Classify finding severity
|
|
859
|
+
|
|
860
|
+
Classify findings after a scan or dedupe without repeating discovery or changing
|
|
861
|
+
the original severity, evidence, or sealed scan artifacts:
|
|
862
|
+
|
|
863
|
+
```bash
|
|
864
|
+
codex-security classify-severity --scan SCAN_ID --rubric /path/to/policy.md --json
|
|
865
|
+
codex-security classify-severity --scan latest --rubric /path/to/policy.md --json
|
|
866
|
+
codex-security classify-severity --scan-dir /path/to/completed-scan --json
|
|
867
|
+
```
|
|
868
|
+
|
|
869
|
+
`--scan` accepts a saved scan ID, unique prefix, or `latest` for the current
|
|
870
|
+
repository, matching `dedupe` and `publish scan`. `--scan-dir` accepts an external
|
|
871
|
+
completed scan without requiring local history. Supply exactly one selector.
|
|
872
|
+
Omitting `--rubric` inherits each finding's existing severity without a model call.
|
|
873
|
+
|
|
874
|
+
`--rubric PATH` supplies the classification policy. Repeat `--knowledge-base PATH`
|
|
875
|
+
to provide supporting architecture, deployment, or business context. Both accept
|
|
876
|
+
the same Markdown, text, PDF, DOCX, and directory inputs as scan knowledge bases.
|
|
877
|
+
Rubric classification uses the full supplied report and context in a separate
|
|
878
|
+
read-only Codex turn per finding, without source inspection, tools, or new
|
|
879
|
+
validation. `--model` and `--effort` select the classification model and reasoning
|
|
880
|
+
effort; otherwise Codex's configured model and the helper's medium effort apply.
|
|
881
|
+
|
|
882
|
+
The result contains one assessment per selected finding:
|
|
883
|
+
|
|
884
|
+
- `decision`: `assessed` or `excluded`; policy exclusions do not become Low.
|
|
885
|
+
- `level`: `critical`, `high`, `medium`, `low`, or `informational`; null for exclusions.
|
|
886
|
+
- `rubricLabel`: the policy's original label, such as `URGENT`, normalized to
|
|
887
|
+
`critical`; null for inherited severity or exclusions.
|
|
888
|
+
- `rationale`, separate `confidence`, and `reviewTrigger` describing a missing
|
|
889
|
+
fact that would change the classification. Inherited severity has no new
|
|
890
|
+
classification-confidence judgment.
|
|
891
|
+
- `findingId`, `occurrenceId`, and `inputSha256` binding the assessment to the
|
|
892
|
+
report. Top-level metadata includes `assessedAt`, `rubricSha256`, and
|
|
893
|
+
`knowledgeBaseSha256` for the supplied policy and context snapshots.
|
|
894
|
+
|
|
895
|
+
Scan classification saves each successful finding immediately in the local
|
|
896
|
+
workbench SQLite database. Rerunning skips assessments with matching finding
|
|
897
|
+
evidence, rubric, and knowledge-base hashes, including exclusions, and returns
|
|
898
|
+
both reused and newly generated assessments. Changed inputs are classified again.
|
|
899
|
+
Use `--reprocess` to rerun every selected finding regardless of its saved
|
|
900
|
+
assessment; each row is replaced only after its new assessment succeeds. A failed
|
|
901
|
+
or canceled run keeps completed checkpoints, so a normal retry resumes missing
|
|
902
|
+
work. Changing only the model or effort requires `--reprocess`.
|
|
903
|
+
|
|
904
|
+
SQLite is authoritative. A successful run also exports the complete selected
|
|
905
|
+
result to `severity-classification.json` alongside the sealed artifacts. The file
|
|
906
|
+
is replaced atomically and is not read for reuse or publication. The scan's
|
|
907
|
+
original findings and severity are unchanged. The database stores the requested
|
|
908
|
+
selection and policy/context hashes; publication rejects an incomplete selection
|
|
909
|
+
or assessments whose inputs no longer match. Rubric documents are read at
|
|
910
|
+
classification time, not again at publication time.
|
|
911
|
+
|
|
912
|
+
```bash
|
|
913
|
+
codex-security classify-severity --scan latest --rubric /path/to/policy.md --reprocess
|
|
914
|
+
```
|
|
915
|
+
|
|
916
|
+
Use repeatable `--finding-id ID` to classify a selected set, such as the
|
|
917
|
+
`uniqueFindingIds` returned by dedupe. With a saved classification, Linear
|
|
918
|
+
publication defaults to that selection, omits excluded records, and uses assessed
|
|
919
|
+
severity for issue priority and title. The description retains original scan
|
|
920
|
+
severity and adds classification reasoning. Without a saved classification,
|
|
921
|
+
publication retains its existing severity mapping and selection behavior.
|
|
922
|
+
Publication rejects assessments whose IDs or evidence hashes no longer match.
|
|
923
|
+
|
|
924
|
+
```bash
|
|
925
|
+
codex-security classify-severity --scan SCAN_ID --rubric /path/to/policy.md \
|
|
926
|
+
--finding-id FINDING_ID --json
|
|
927
|
+
codex-security publish scan --scan SCAN_ID --to linear --linear-team TEAM_ID \
|
|
928
|
+
--dry-run --json
|
|
929
|
+
codex-security publish scan --scan SCAN_ID --to linear --linear-team TEAM_ID \
|
|
930
|
+
--skip-existing --json
|
|
931
|
+
```
|
|
932
|
+
|
|
933
|
+
`publish scan --to linear` also accepts repeatable `--finding-id ID` to select a
|
|
934
|
+
subset directly. If a classification exists, every explicitly selected finding
|
|
935
|
+
must have an assessment. Classification does not change existing Linear tickets;
|
|
936
|
+
`--skip-existing` preserves recorded tickets and any human priority edits. It
|
|
937
|
+
retains the existing limitations around unrecorded or concurrent publications.
|
|
938
|
+
|
|
939
|
+
The SDK exposes the same operations:
|
|
940
|
+
|
|
941
|
+
```ts
|
|
942
|
+
import {
|
|
943
|
+
classifySeverity,
|
|
944
|
+
classifyScanSeverity,
|
|
945
|
+
classifyScanDirectorySeverity,
|
|
946
|
+
publishScan,
|
|
947
|
+
} from "@openai/codex-security";
|
|
948
|
+
|
|
949
|
+
// Supplied reports from any source: returns an assessment without writing files.
|
|
950
|
+
const classification = await classifySeverity(findings, {
|
|
951
|
+
rubricPath: "/path/to/policy.md",
|
|
952
|
+
knowledgeBasePaths: ["/path/to/context.md"],
|
|
953
|
+
});
|
|
954
|
+
|
|
955
|
+
// Saved IDs (including prefixes/latest), or sealed directories; saves an assessment.
|
|
956
|
+
await classifyScanSeverity("SCAN_ID", { rubricPath: "/path/to/policy.md" });
|
|
957
|
+
await classifyScanDirectorySeverity(scanDirectory, {
|
|
958
|
+
rubricPath: "/path/to/policy.md",
|
|
959
|
+
findingIds: dedupeResult.uniqueFindingIds,
|
|
960
|
+
});
|
|
961
|
+
|
|
962
|
+
await publishScan(scanDirectory, {
|
|
963
|
+
destination: "linear",
|
|
964
|
+
teamId: "TEAM_ID",
|
|
965
|
+
skipExisting: true,
|
|
966
|
+
});
|
|
967
|
+
|
|
968
|
+
// Alternatively supply a classification directly, without a saved assessment.
|
|
969
|
+
await publishScan(scanDirectory, {
|
|
970
|
+
destination: "linear",
|
|
971
|
+
teamId: "TEAM_ID",
|
|
972
|
+
classification,
|
|
973
|
+
findingIds: classification.assessments.map(({ findingId }) => findingId),
|
|
974
|
+
dryRun: true,
|
|
975
|
+
});
|
|
976
|
+
```
|
|
977
|
+
|
|
978
|
+
`classifySeverity` accepts reports with `findingId`, `title`, and `summary`, plus
|
|
979
|
+
their available evidence and metadata. Original `severity` and `occurrenceId`
|
|
980
|
+
may be absent for imported reports; reports without severity require a rubric.
|
|
981
|
+
`classifySeverity` remains an in-memory operation without database persistence.
|
|
982
|
+
The scan wrappers use the local state database (also for external scan
|
|
983
|
+
directories), accept `reprocess: true`, and accept `findingIds: []` as an
|
|
984
|
+
intentionally empty selection. Rows outside the selected set are retained.
|
|
985
|
+
Use the same `CODEX_SECURITY_STATE_DIR` for classification and publication.
|
|
986
|
+
JSON exports from versions without database checkpoints must be reclassified
|
|
987
|
+
once before they can be reused.
|
|
988
|
+
Pass `signal` to cancel any classification operation. Keep human overrides in the
|
|
989
|
+
calling workflow or issue tracker; assessments remain separate recommendations.
|
|
990
|
+
|
|
829
991
|
### Scan history and reruns
|
|
830
992
|
|
|
831
993
|
Commands default to the current repository. Select scans by full ID or a
|
|
@@ -849,6 +1011,44 @@ or unknown. Missing findings aren't resolved if the later scan is incomplete
|
|
|
849
1011
|
or excludes their original scope. With one ID, `scans compare` compares it
|
|
850
1012
|
to the latest completed scan.
|
|
851
1013
|
|
|
1014
|
+
Use `scans match --all --force` to rebuild comparisons chronologically while
|
|
1015
|
+
retaining stable finding identities. Ctrl-C keeps comparisons already saved.
|
|
1016
|
+
Only high-confidence duplicates are grouped; uncertain and independently
|
|
1017
|
+
related findings stay separate. Matching preserves triage and sealed artifacts.
|
|
1018
|
+
|
|
1019
|
+
Codex is called only when a new decision is needed, using existing authentication.
|
|
1020
|
+
Scans without sealed artifacts are skipped, but their confirmed links can still
|
|
1021
|
+
be reused. Older custom plugins save confirmed and uncertain matches; use the
|
|
1022
|
+
bundled plugin for related links and large comparisons.
|
|
1023
|
+
|
|
1024
|
+
SDK callers can compare findings without saving a workbench comparison:
|
|
1025
|
+
|
|
1026
|
+
```ts
|
|
1027
|
+
import { readFile } from "node:fs/promises";
|
|
1028
|
+
import {
|
|
1029
|
+
matchScanFindings,
|
|
1030
|
+
type FindingsDocument,
|
|
1031
|
+
} from "@openai/codex-security";
|
|
1032
|
+
|
|
1033
|
+
const before = JSON.parse(
|
|
1034
|
+
await readFile("/path/to/earlier-scan/findings.json", "utf8"),
|
|
1035
|
+
) as FindingsDocument;
|
|
1036
|
+
const after = JSON.parse(
|
|
1037
|
+
await readFile("/path/to/later-scan/findings.json", "utf8"),
|
|
1038
|
+
) as FindingsDocument;
|
|
1039
|
+
|
|
1040
|
+
const comparison = await matchScanFindings(
|
|
1041
|
+
{ before: before.findings, after: after.findings },
|
|
1042
|
+
{ workingDirectory: "/path/to/repository" },
|
|
1043
|
+
);
|
|
1044
|
+
console.log(comparison.matches, comparison.uncertain, comparison.related ?? []);
|
|
1045
|
+
```
|
|
1046
|
+
|
|
1047
|
+
Pass `knownFindingGroups` to reuse confirmed groups of stable `findingId` values
|
|
1048
|
+
from your store. Results identify the original `occurrenceId` values. Options
|
|
1049
|
+
include model, reasoning effort, `AbortSignal`, and an optional `onProgress`
|
|
1050
|
+
callback whose errors do not interrupt matching.
|
|
1051
|
+
|
|
852
1052
|
History lives in `$CODEX_SECURITY_STATE_DIR/workbench.sqlite3`, or
|
|
853
1053
|
`$CODEX_HOME/state/plugins/codex-security/workbench.sqlite3`. The CLI and
|
|
854
1054
|
workbench maintain the database and its journal files as the current user.
|
|
@@ -928,8 +1128,8 @@ assessment skill once on the completed patch. The assessment is advisory and
|
|
|
928
1128
|
does not change the patch or its merge state. Human-readable commands print the
|
|
929
1129
|
report after the patch results; saved-finding JSON output returns it as
|
|
930
1130
|
`patchRisk.report` in the same result object. When combined with `--create-pr`,
|
|
931
|
-
the draft pull request body includes only the concise Markdown
|
|
932
|
-
assessment; the validated JSON remains in the command result.
|
|
1131
|
+
the draft pull request or merge request body includes only the concise Markdown
|
|
1132
|
+
summary from the assessment; the validated JSON remains in the command result.
|
|
933
1133
|
|
|
934
1134
|
```bash
|
|
935
1135
|
npx @openai/codex-security validate "Possible SQL injection" --effort high
|
|
@@ -951,11 +1151,25 @@ to select findings and add patch instructions. Results include a `patches`
|
|
|
951
1151
|
entry per finding with status `verified`, `no_change`, `blocked`, or `failed`.
|
|
952
1152
|
Verified and already-fixed findings no longer fail `--fail-on-severity`.
|
|
953
1153
|
|
|
954
|
-
`--create-pr` commits generated patch files and opens a draft
|
|
955
|
-
|
|
1154
|
+
`--create-pr` commits generated patch files and opens a draft GitHub pull request
|
|
1155
|
+
with `gh` or a draft GitLab merge request with `glab`. Install and authenticate
|
|
1156
|
+
the appropriate CLI first (`gh auth login` or `glab auth login`). GitLab.com is
|
|
1157
|
+
selected from the `origin` push URL, including SSH URLs and subgroup projects.
|
|
1158
|
+
For self-hosted GitLab, set `GITLAB_HOST` to the host in that URL and authenticate
|
|
1159
|
+
with `glab auth login --hostname HOST`. The existing `GITLAB_URI` and `GL_HOST`
|
|
1160
|
+
aliases are also accepted, in that order after `GITLAB_HOST`. Other hosts retain
|
|
1161
|
+
the GitHub workflow.
|
|
1162
|
+
|
|
1163
|
+
```bash
|
|
1164
|
+
GITLAB_HOST=gitlab.example.com npx @openai/codex-security patch --scan SCAN_ID --create-pr
|
|
1165
|
+
```
|
|
1166
|
+
|
|
1167
|
+
Both providers use the existing `pullRequest: { branch, url }` JSON result.
|
|
1168
|
+
Supplied-issue requests require a clean working tree before patching so
|
|
956
1169
|
existing work is never included. If publication fails, run the printed
|
|
957
1170
|
`patch --resume-pr BRANCH` command in the same repository. It reuses the saved
|
|
958
1171
|
commit without rerunning Codex, but refuses to publish if the branch changed.
|
|
1172
|
+
Use the same GitLab host setting when resuming a self-hosted merge request.
|
|
959
1173
|
|
|
960
1174
|
To patch Linear issues, repeat `--linear-issue ISSUE` (ID or URL), or use
|
|
961
1175
|
`--linear-project "PROJECT"` with an optional native JSON `--linear-filter`.
|
|
@@ -1360,7 +1574,7 @@ use another workflow ID for a fresh review rather than changing that saved resul
|
|
|
1360
1574
|
2. Screen each nonempty neighborhood with `gpt-5.6-luna` at `xhigh` reasoning
|
|
1361
1575
|
effort. The review covers every anchor-neighbor pair; nominations between
|
|
1362
1576
|
neighbors are rejected.
|
|
1363
|
-
3. Independently review each nominated pair once with `gpt-5.6-sol` at `
|
|
1577
|
+
3. Independently review each nominated pair once with `gpt-5.6-sol` at `high`
|
|
1364
1578
|
reasoning effort. Only accepted pairs contribute to duplicate groups.
|
|
1365
1579
|
4. Group accepted duplicate pairs transitively unless a Luna or Sol `DISTINCT`
|
|
1366
1580
|
decision contradicts the resulting component. Contradicted components are
|
|
Binary file
|
|
Binary file
|
|
@@ -84,6 +84,6 @@ Present applicable remediation in the Codex thread. Ask before editing persisten
|
|
|
84
84
|
|
|
85
85
|
Codex CLI and other hosts use the same prompt-based preflight before substantive work. Explain the exact reasons and remediation in chat. Interactive CLI sessions ask before editing persistent config; non-interactive CLI sessions use the narrow automatic-remediation path above and continue only after a `ready` rerun.
|
|
86
86
|
|
|
87
|
-
##
|
|
87
|
+
## Daybreak Access Advisory
|
|
88
88
|
|
|
89
|
-
After capability preflight is `ready` and immediately before the workflow's first substantive scan action,
|
|
89
|
+
After capability preflight is `ready` and immediately before the workflow's first substantive scan action, call the plugin's `get_codex_security_daybreak_access` tool exactly once when available as the automatic pre-scan advisory. ChatGPT-authenticated desktop and CLI sessions both support this advisory; API-key-only sessions cannot verify account access. For Deep Security Scan, make this call immediately before `start_codex_security_deep_scan`. If this scan already performed the automatic advisory in an earlier continuation, reuse that result instead of calling it again. Report its exact `status` and available Daybreak programs. When `status` is `not_granted`, before any other scan-start progress, present a separate, prominent warning that Daybreak access is not granted for this account and protected scan outputs may not be displayable. Include the returned `enrollmentUrl` as a clickable application link; if that field is absent, use `https://chatgpt.com/cyber`. Do not bury this warning in a routine status summary. When `status` is `unknown`, `stale` is `true`, or the tool is unavailable or fails, instead warn that Daybreak access could not be verified and protected scan outputs may not be displayable. Then continue regardless. This result is advisory and must never authorize or gate the scan. Do not poll it or repeat it between scan phases. If the user explicitly asks to re-check after an account or Daybreak access change, call the tool again when available for a fresh result; this user-requested refresh is the only repeat.
|
|
@@ -16,11 +16,11 @@ Use `report.md` as the primary readable entry point. Explain report-relevant art
|
|
|
16
16
|
|
|
17
17
|
In the final response, link the generated markdown report path as the primary readable artifact.
|
|
18
18
|
|
|
19
|
-
Every scan mode uses the same final report pipeline. Workbench-owned Standard and workbench-backed diff scans submit canonical semantics with `record_codex_security_scan_draft({ scanId, handoffClaimToken?, scope?, threatModel?, findings, coverage })`; the workbench supplies authoritative metadata and writes the unsealed canonical draft. Deep
|
|
19
|
+
Every scan mode uses the same final report pipeline. Workbench-owned Standard and workbench-backed diff scans submit canonical semantics with `record_codex_security_scan_draft({ scanId, handoffClaimToken?, scope?, threatModel?, findings, coverage })`; the workbench supplies authoritative metadata and writes the unsealed canonical draft. For Deep scans, the coordinator writes the parent scan's unsealed canonical draft from its accepted aggregate. SDK-owned Standard scans instead write unsealed canonical files with the exact SDK-provided metadata and leave finalization to the SDK. Terminal scans without a `scanId` retain their existing canonical JSON workflow. No mode authors, repairs, or treats an existing `report.md` as input. Finalization validates and enriches the canonical JSON, seals the canonical JSON and evidence artifacts, then deterministically generates `report.md`. Supply report prose through structured canonical semantics rather than a separately authored report.
|
|
20
20
|
|
|
21
21
|
For each finding, supply an evidence-supported lowercase vulnerability-family `ruleId`; `taxonomy: { category, cwe }` using its exact known CWEs; verified locations; and `provenance.source`, using `"local_plugin"` only when this plugin actually discovered the finding. Preserve genuine worker or source provenance and any existing canonical candidate identity in the finding extensions. A finding with no known CWE retains `cwe: []`; never invent a classification. Include optional `codeEvidence` only when its actual code is nonempty and every referenced evidence ID is present.
|
|
22
22
|
|
|
23
|
-
|
|
23
|
+
For Standard scan drafts, including Deep worker results, and diff drafts, supply semantic coverage as `{ completeness, surfaces, explicitExclusions, deferred }`, with each surface using the actual `label` and one existing `disposition`. Mark coverage `partial` when a deferred item or `needs_follow_up` surface remains; preserve its real reason and supporting context. Each deferred item needs a meaningful reason; preserve any existing `id` or `candidateId`. The workbench derives a missing ID from its candidate identity or stable deferred-work details. Open questions may be nonempty strings or `{ question, followUpPrompt? }` objects. The workbench derives target and scope metadata, scope include and exclude paths, coverage mode and inventory strategy, finding identities and fingerprints, and surface IDs. Do not put those workbench-owned values or top-level coverage receipt references into the semantic draft.
|
|
24
24
|
|
|
25
25
|
During a host-backed scan, checkpoint saved findings and pending candidates with `complete: false`; a checkpoint is not a completed audit. After a final workbench-owned Standard or workbench-backed diff draft is accepted with `complete: true` (or the backwards-compatible omitted flag), or the Deep coordinator returns its parent scan's canonical manifest, call `complete_codex_security_scan({ scanId, handoffClaimToken? })` and use its returned completion metadata. An SDK-owned scan returns its unsealed canonical files without calling a completion tool or finalizer; the SDK owns completion and report generation. Read full canonical results only when explicitly requested. For a terminal/chat workflow without a `scanId` or completion tool, retain `python <plugin_dir>/scripts/finalize_scan_contract.py --scan-dir <scan_dir> --source-root <repo_root>` after writing the canonical JSON. Outside the SDK path, do not mark the scan goal complete until finalization succeeds and the generated report exists.
|
|
26
26
|
|
|
@@ -59,7 +59,7 @@ Group observations only when they share the same broken security control and eff
|
|
|
59
59
|
|
|
60
60
|
Set the finding category and CWE from the primary broken control. Do not add secondary support-impact CWEs, such as data exposure or missing authentication, to an injection/RCE/path/file/parser finding merely because they make exploitation worse; mention those impacts in prose or emit a separate finding if that secondary control is independently vulnerable.
|
|
61
61
|
|
|
62
|
-
|
|
62
|
+
Canonical `severity.changeConditions` must be one non-empty string; when `attack_path.change_conditions` contains multiple strings, join them into one prose string before writing `findings.json`.
|
|
63
63
|
|
|
64
64
|
For workbench-backed diff candidates, apply row outcomes in this order: validation disposition `reportable` plus attack-path decision `reportable` becomes a finding with its distinct instance and all relevant entrypoint, root-control, sink, and supporting locations; otherwise, a `deferred` result from either phase becomes `needs_follow_up` coverage and a `coverage.deferred` entry using the recorded uncertainty or proof gap; otherwise, validation disposition `not_applicable` becomes `not_applicable` coverage; otherwise, validation disposition `suppressed` or attack-path decision `ignore` becomes `rejected` coverage. A missing required phase record leaves the candidate unresolved and prevents complete coverage. Do not require phase receipts, per-candidate narratives, or another reconciliation pass.
|
|
65
65
|
|
|
@@ -73,6 +73,8 @@ Use this report structure:
|
|
|
73
73
|
|
|
74
74
|
`## Scope`
|
|
75
75
|
|
|
76
|
+
Deep reports present the configured include and exclude paths and execution outcome alongside aggregated findings, with their validation, attack paths, affected locations, and any supplied scope and threat-model context. When the discovery time limit expires before any source review completes, the report explains the incomplete review.
|
|
77
|
+
|
|
76
78
|
Populate `scan.scope` with in-scope context, artifacts reviewed, runtime or test status, validation mode, and explicit limitations. Include/exclude paths and coverage fields supply the remaining projected scope content. If the threat model was generated during Phase 1 rather than provided by the user, say that in canonical scope context. Do not call generated threat-model material an external input.
|
|
77
79
|
|
|
78
80
|
After the scope bullets, include a compact `### Scan Summary` table when the scan has findings or repository-wide coverage. Use columns `Field` and `Value`. Include the count of reportable findings, severity mix, confidence mix, coverage, and validation mode when those values are known. Keep artifact paths below this table.
|
|
@@ -40,7 +40,11 @@ End each repository-scoped threat model with these two lines:
|
|
|
40
40
|
|
|
41
41
|
### Compact Deep And Workbench-Backed Diff Discovery
|
|
42
42
|
|
|
43
|
-
Workbench-owned Standard scans submit findings and coverage through `record_codex_security_scan_draft`; SDK-owned Standard scans write unsealed canonical files directly.
|
|
43
|
+
Workbench-owned Standard scans submit findings and coverage through `record_codex_security_scan_draft`; SDK-owned Standard scans write unsealed canonical files directly. Workbench-backed diff scans use the compact artifacts described below.
|
|
44
|
+
|
|
45
|
+
Deep scans run ordinary Standard scan workers. Workers save progress with `complete: false` and submit final results through `record_codex_security_scan_draft`. Their checkpoints and results contain findings and coverage, with optional scope and threat-model context. Pending candidates and their evidence are recorded in worker coverage. Immutable checkpoints store progress across retries, cancellation, and failure. The coordinator passes completed workers' findings and context to the reducer.
|
|
46
|
+
|
|
47
|
+
Deep reducer inputs, results, and checkpoints contain findings and optional scope and threat-model context. The host writes the parent scan's unsealed `scan-manifest.json` and `findings.json` from the accepted aggregate, and derives `coverage.json` from the configured include and exclude paths and the coordinator's outcome. The parent completes the scan from these artifacts. If the discovery time limit expires before any source review completes, the parent records partial coverage with that reason. See `scan-contract.md` for canonical field definitions.
|
|
44
48
|
|
|
45
49
|
- A workbench-backed diff scan records all candidates once with `record_codex_security_discovery_candidates({ scanId, candidates })` and reads the canonical candidates with `list_codex_security_candidates({ scanId, cursor?, limit? })`.
|
|
46
50
|
- The writer validates candidates against assigned source paths, merges rows with the same CWE ids, locations, and optional instance, preserves their text, and assigns deterministic `candidate_id` values.
|
|
@@ -104,9 +104,13 @@ Use CWE taxonomy separately. Do not include file names, line numbers, scan IDs,
|
|
|
104
104
|
|
|
105
105
|
## Coverage
|
|
106
106
|
|
|
107
|
-
`coverage.json`
|
|
107
|
+
`coverage.json` records scan scope and completion information. Standard and diff summaries also describe reviewed surfaces and outstanding work.
|
|
108
108
|
|
|
109
|
-
|
|
109
|
+
For a Deep parent scan, the host copies the configured paths into `includePaths` and `excludePaths` and sets `completeness` from the coordinator's outcome. A successful aggregate uses `complete`; `surfaces`, `explicitExclusions`, and `deferred` are empty arrays, and `openQuestions` is omitted. If the configured time limit expires before any review completes, the coordinator writes `partial` and records the explanation in `deferred`. Stopped outcomes follow the [stopped-result recovery rules](#stopped-result-recovery).
|
|
110
|
+
|
|
111
|
+
Each Deep worker writes an ordinary Standard result, including its own coverage. A reducer submits `record_codex_security_deep_reduction({ scanId, findings, scope?, threatModel? })`; its saved results and checkpoints contain the accepted findings and optional scope and threat-model context.
|
|
112
|
+
|
|
113
|
+
For Standard and diff scans, record:
|
|
110
114
|
|
|
111
115
|
- scan mode and inventory strategy
|
|
112
116
|
- included and excluded paths
|
|
@@ -140,7 +144,7 @@ For a whole-repository Deep scan, keep `inventoryStrategy` as `repository`; repe
|
|
|
140
144
|
| `directory` | Deterministic non-Git directory inventory |
|
|
141
145
|
| `custom` | Producer-defined inventory described by detailed receipts |
|
|
142
146
|
|
|
143
|
-
|
|
147
|
+
For Standard and diff scans, use `complete` when the requested scope was fully reviewed, `partial` when in-scope work was deferred, and `unknown` when the producer cannot establish enough coverage to make that distinction.
|
|
144
148
|
|
|
145
149
|
Map detailed ledger closure into completed surface summaries in this order:
|
|
146
150
|
|
|
@@ -9,7 +9,33 @@
|
|
|
9
9
|
"additionalProperties": false
|
|
10
10
|
},
|
|
11
11
|
"reductionInput": {
|
|
12
|
-
"
|
|
12
|
+
"type": "object",
|
|
13
|
+
"properties": {
|
|
14
|
+
"complete": {
|
|
15
|
+
"type": "boolean",
|
|
16
|
+
"description": "Omit or set true when submitting the finished aggregate."
|
|
17
|
+
},
|
|
18
|
+
"scanId": {
|
|
19
|
+
"$ref": "codex-security://schemas/tools/scan-draft.schema.json#/$defs/scanId"
|
|
20
|
+
},
|
|
21
|
+
"handoffClaimToken": {
|
|
22
|
+
"$ref": "codex-security://schemas/tools/scan-draft.schema.json#/$defs/handoffClaimToken"
|
|
23
|
+
},
|
|
24
|
+
"scope": {
|
|
25
|
+
"$ref": "codex-security://schemas/tools/scan-draft.schema.json#/$defs/scope"
|
|
26
|
+
},
|
|
27
|
+
"threatModel": {
|
|
28
|
+
"$ref": "codex-security://schemas/tools/scan-draft.schema.json#/$defs/threatModel"
|
|
29
|
+
},
|
|
30
|
+
"findings": {
|
|
31
|
+
"$ref": "codex-security://schemas/tools/scan-draft.schema.json#/$defs/scanDraftInput/properties/findings"
|
|
32
|
+
}
|
|
33
|
+
},
|
|
34
|
+
"required": [
|
|
35
|
+
"scanId",
|
|
36
|
+
"findings"
|
|
37
|
+
],
|
|
38
|
+
"additionalProperties": false
|
|
13
39
|
}
|
|
14
40
|
}
|
|
15
41
|
}
|
|
@@ -1877,6 +1877,7 @@ def finish_deep_scan_locked(
|
|
|
1877
1877
|
"""
|
|
1878
1878
|
SELECT 1 FROM deep_scan_workers AS failed
|
|
1879
1879
|
WHERE failed.scan_id = ? AND failed.status = 'failed'
|
|
1880
|
+
AND (? != 'saturated' OR failed.kind != 'discovery')
|
|
1880
1881
|
AND (
|
|
1881
1882
|
failed.kind != 'dedup'
|
|
1882
1883
|
OR NOT EXISTS (
|
|
@@ -1902,10 +1903,14 @@ def finish_deep_scan_locked(
|
|
|
1902
1903
|
)
|
|
1903
1904
|
LIMIT 1
|
|
1904
1905
|
""",
|
|
1905
|
-
(scan_id,),
|
|
1906
|
+
(scan_id, args.terminal_reason),
|
|
1906
1907
|
).fetchone()
|
|
1907
1908
|
if failed_worker is not None and not failure_capped:
|
|
1908
1909
|
raise SystemExit("Deep Scan cannot finish after a worker has failed.")
|
|
1910
|
+
if args.terminal_reason == "saturated":
|
|
1911
|
+
# Mark any remaining workers canceled, including those whose own
|
|
1912
|
+
# cancellation writes failed, so they cannot block completion.
|
|
1913
|
+
cancel_active_workers(connection, scan_id, now())
|
|
1909
1914
|
active_worker = connection.execute(
|
|
1910
1915
|
"""
|
|
1911
1916
|
SELECT 1 FROM deep_scan_workers
|
|
@@ -1252,12 +1252,9 @@ def _normalize_unsealed_deep_repository_inventory_strategy(
|
|
|
1252
1252
|
*,
|
|
1253
1253
|
expected_coverage_mode: str | None,
|
|
1254
1254
|
) -> None:
|
|
1255
|
-
"""
|
|
1255
|
+
"""Label whole-repository Deep scans as using the repository inventory."""
|
|
1256
1256
|
|
|
1257
|
-
if
|
|
1258
|
-
expected_coverage_mode == "deep_repository"
|
|
1259
|
-
and coverage.get("inventoryStrategy") == "deep_repository_repeated_discovery"
|
|
1260
|
-
):
|
|
1257
|
+
if expected_coverage_mode == "deep_repository":
|
|
1261
1258
|
coverage["inventoryStrategy"] = "repository"
|
|
1262
1259
|
|
|
1263
1260
|
|
|
@@ -814,7 +814,7 @@ def build_report_markdown(
|
|
|
814
814
|
"",
|
|
815
815
|
_text(
|
|
816
816
|
scope.get("summary"),
|
|
817
|
-
"The scan
|
|
817
|
+
"The scan was configured for the include paths and exclusions listed below.",
|
|
818
818
|
),
|
|
819
819
|
"",
|
|
820
820
|
f"- Scan mode: {coverage['mode']}",
|
|
@@ -354,6 +354,9 @@ def parse_args(description: str) -> argparse.Namespace:
|
|
|
354
354
|
subparsers.add_parser("database-info")
|
|
355
355
|
subparsers.add_parser("dashboard")
|
|
356
356
|
subparsers.add_parser("finding-workflow")
|
|
357
|
+
subparsers.add_parser("severity-classification")
|
|
358
|
+
severity = subparsers.add_parser("read-severity-classification")
|
|
359
|
+
severity.add_argument("--scan-id", required=True)
|
|
357
360
|
subparsers.add_parser("store-findings")
|
|
358
361
|
subparsers.add_parser("store-dedupe-groups")
|
|
359
362
|
dedupe_groups = subparsers.add_parser("list-dedupe-groups")
|
|
@@ -40,6 +40,7 @@ import workbench_remediation as remediation
|
|
|
40
40
|
import workbench_saved_results as saved_results
|
|
41
41
|
import workbench_scan_history as scan_history
|
|
42
42
|
import workbench_scan_usage as scan_usage
|
|
43
|
+
import workbench_severity as severity
|
|
43
44
|
from filesystem_identity import (
|
|
44
45
|
serialize_filesystem_identity as serialize_filesystem_identity,
|
|
45
46
|
)
|
|
@@ -1535,7 +1536,9 @@ def complete_scan_locked(
|
|
|
1535
1536
|
scan_dir,
|
|
1536
1537
|
expected_coverage_mode=expected_coverage_mode(scan),
|
|
1537
1538
|
completion_binding=completion_binding,
|
|
1538
|
-
|
|
1539
|
+
# Save the finished Deep result as submitted. Worker drafts and
|
|
1540
|
+
# recovery repairs belong to the stopped-scan path.
|
|
1541
|
+
completion_warnings=warnings if scan["mode"] != "deep" else None,
|
|
1539
1542
|
draft_documents=saved_results.merge_saved_results(
|
|
1540
1543
|
scan_dir,
|
|
1541
1544
|
scan["id"],
|
|
@@ -1548,7 +1551,7 @@ def complete_scan_locked(
|
|
|
1548
1551
|
stopped=False,
|
|
1549
1552
|
reason="",
|
|
1550
1553
|
)
|
|
1551
|
-
if current_manifest_path is not None and not already_sealed
|
|
1554
|
+
if scan["mode"] != "deep" and current_manifest_path is not None and not already_sealed
|
|
1552
1555
|
else None,
|
|
1553
1556
|
)
|
|
1554
1557
|
add_warning()
|
|
@@ -3451,6 +3454,10 @@ def main() -> None:
|
|
|
3451
3454
|
result = inspect_setup(args)
|
|
3452
3455
|
print(json.dumps(result, allow_nan=False, sort_keys=True))
|
|
3453
3456
|
return
|
|
3457
|
+
if args.command == "read-severity-classification":
|
|
3458
|
+
result = severity.read_classification(database_path(), args.scan_id)
|
|
3459
|
+
print(json.dumps(result, allow_nan=False, sort_keys=True))
|
|
3460
|
+
return
|
|
3454
3461
|
if args.command == "inspect-linear-publication":
|
|
3455
3462
|
result = inspect_linear_publication(args)
|
|
3456
3463
|
print(json.dumps(result, allow_nan=False, sort_keys=True))
|
|
@@ -3621,6 +3628,8 @@ def main() -> None:
|
|
|
3621
3628
|
result = export_findings(connection, args)
|
|
3622
3629
|
elif args.command == "database-info":
|
|
3623
3630
|
result = {"databasePath": str(database_path())}
|
|
3631
|
+
elif args.command == "severity-classification":
|
|
3632
|
+
result = severity.checkpoint(connection, json.load(sys.stdin), now())
|
|
3624
3633
|
elif args.command == "finding-workflow":
|
|
3625
3634
|
result = finding_workflow(connection, json.load(sys.stdin), now())
|
|
3626
3635
|
elif args.command == "dashboard":
|