Skip to content

feat(json): record cliVersion, scannedAt and effective options in --json payload - #1297

Merged
sonukapoor merged 4 commits into
OWASP:mainfrom
pintu544:feature/issue-1296-json-provenance
Oct 15, 2026
Merged

sonukapoor merged 4 commits into
OWASP:mainfrom
pintu544:feature/issue-1296-json-provenance

Conversation

@pintu544

@pintu544 pintu544 commented Oct 7, 2026

Copy link
Copy Markdown
Contributor

A --json artifact on its own cannot be traced back to the release or invocation that produced it. This adds cliVersion, scannedAt, and effectiveOptions at the top level of the --json payload (single-folder and multi-folder).

Effective options (src/utils/effective-options.ts): normalized booleans and enums with defaults resolved (e.g. failOn: "critical", batchSize: 100). Options whose value is a filesystem path or URL (--offline-db, --cache-dir, --osv-url, --output, --ca-cert, --audit-log, --report) are recorded only as a set-marker — the value itself is never recorded, since adopters share these artifacts.

Design: the fields are added in the scan-json.ts builders (where the issue notes the fix belongs), so --json and report.json keep sharing one schema. Additive only — nothing existing changes shape.

Verification against the issue's success criteria:

  • --json runs produce all three fields (verified end-to-end on the built CLI).
  • Two runs differing only in --check-overrides produce payloads differing in that field.
  • No option value containing a filesystem path or URL appears anywhere in the payload (unit-tested).
  • Removing any of the three fields fails a test (new + updated assertions).

Full verification run: npm ci → lint:tests → build → advisories sync → npm test — 165 suites / 2290 tests green.

Closes #1296

@pintu544
pintu544 requested a review from sonukapoor as a code owner October 7, 2026 23:04

@sonukapoor sonukapoor left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a good contribution and the redaction design is the best part of it. Recording offlineDb, cacheDir, osvUrl and caCert as presence only, with the reasoning written down about adopters sharing artifacts that can carry internal paths and mirror hostnames, is a stricter standard than the codebase currently holds itself to. The same JSON still writes projectPath with the user's home directory in it, which is ours to fix and is part of #1309. So you have set the bar here rather than met it.

It also lands in a direction we want: report.json already carries cliVersion and scannedAt while --json did not, which is one of the asymmetries #237 is about, and #1323 is the same theme from the other end.

One ask. Of the 38 keys on ParsedOptions you record 35, correctly leaving out version and help since those print and exit. The third omission is usage, and that one matters: options.usage is what gates import-reachability scanning in both scan paths, so without it no usage data exists at all. You do record onlyUsed, which filters on that data. Recording the filter and omitting the switch is the one combination that could mislead someone reading the artefact to explain a finding count, which is the artefact's whole purpose. Add usage and it is complete.

Also needs a rebase before it can merge. That is not your doing: #1271 and #1264 both landed on 10-09 and touch src/scan/single-scan.ts and tests/e2e/validation-and-outputs.test.ts, which is where the conflicts are.

On your own base the suite is green, 165 suites and 2290 tests, and the build is clean, so I am confident about the content and only the merge needs attention.

…son payload

A --json artifact on its own cannot be traced back to the release or
invocation that produced it. The payload now carries the running CLI
version, the scan timestamp, and the effective (defaults-resolved,
privacy-safe) options at the top level.

Effective options are normalized booleans and enums; options whose value
is a filesystem path or URL are recorded only as a set-marker, never the
value itself, since adopters share these artifacts.

The fields are added in the scan-json builders so --json and report.json
keep sharing one schema. Additive only: nothing existing changes shape.

Closes OWASP#1296
The usage flag gates import-reachability scanning in both scan paths.
Recording onlyUsed (which filters on that data) without the usage switch
could mislead someone reading the artefact to explain a finding count.
The rebase conflict resolution dropped the closing braces of the upstream
registry-reporting describe block. Both blocks (registry reporting + OWASP#1296
provenance) are now properly closed and sequenced.

@sonukapoor sonukapoor left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Both asks are in. usage is recorded now and the rebase is clean.

On the merge result against current main: 168 suites, 2353 tests, build clean, and all six checks green on your head.

For the redaction I scanned with --cache-dir set to a distinctive path and searched the whole emitted artefact for it. It appears nowhere, and cacheDir comes out as true. Same treatment for --output, which lands as output: true. You did that one without being asked and it matters more than it looks, because --output takes a directory, so on an adopter's CI box it is exactly the kind of value that ends up inside a file they attach to an issue.

The rest reads correctly on a real scan: cliVersion, an ISO scannedAt, and scalars carrying real values where they are safe to (minSeverity: "high", batchSize: 25, searchDepth: 4, failOn: "critical", incompletePolicy: "warn", sbom: "spdx"). Unset presence-only keys are omitted rather than written as null, which is the right call, since otherwise absent and false would look alike to anyone reading the artefact to explain a scan.

I mutation-tested the two new test files. Making cacheDir emit the real path instead of true fails a test, and neutralising usage fails a test, so both the thing the feature exists for and the thing I asked for are pinned rather than just asserted.

Approving. Two notes, neither for you to act on here.

projectPath still carries the home directory, which I flagged last time as ours. Your own #1330 closes #1309, so the two overlap there and that is probably the simpler place to deal with it.

And the --report cannot be used with --json error prints an unrelated SSL proxy hint underneath it. That reproduces on main, so it is pre-existing and not yours.

@sonukapoor
sonukapoor merged commit c5d2272 into OWASP:main Oct 15, 2026
6 checks passed
@sonukapoor

Copy link
Copy Markdown
Collaborator

Merged, thank you @pintu544, and this is your first contribution here.

A saved report now says which version produced it, when the scan ran, and which options were in effect. That sounds like bookkeeping until you are looking at a JSON file somebody attached to a ticket three weeks ago and trying to work out whether the clean result meant anything.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(json): record cliVersion, scannedAt and the effective options in the --json payload

2 participants