Skip to content

feat(scan): add --reach-fallback-to-regular-scan flag - #1537

Merged
Martin Torp (mtorp) merged 2 commits into
v1.xfrom
martin/flag-to-fall-back-to-regular-sca-when-re
Sep 14, 2026
Merged

Martin Torp (mtorp) merged 2 commits into
v1.xfrom
martin/flag-to-fall-back-to-regular-sca-when-re

Conversation

@mtorp

@mtorp Martin Torp (mtorp) commented Sep 14, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Adds an opt-in --reach-fallback-to-regular-scan flag to socket scan create. When full application reachability analysis fails (e.g. a backend gateway disconnect during compute-artifacts), the CLI currently aborts the entire scan. With the flag set, a failed reachability run logs a warning and the scan continues as a regular SCA scan, so the rest of the pipeline still completes.

Behavior

  • New boolean flag --reach-fallback-to-regular-scan (default false), part of the reachability flag family, so it requires --reach.
  • On any reachability failure: warning with the failure details, then the scan proceeds with scan_type: socket using the plain manifest set, skipping tier1 finalize and the missing-reachability-ID warning.
  • Without the flag the behavior is unchanged: the CLI halts on reachability errors.
  • Hidden on socket scan reach (standalone analysis has no scan to fall back to).

Facts-file handling on fallback

Coana writes its report over .socket.facts.json in place, so an analysis that fails part way leaves partial output where the scan's inputs were. Two consequences the fallback has to handle:

  • The regular scan would upload that partial output instead of the inputs it would have had without --reach.
  • The file would survive a scan that exits 0, and the next --reach run reads a stale .socket.facts.json as a pre-generated input, silently overriding fresh analysis.

snapshotSocketFacts (src/utils/coana.mts) copies every .socket.facts.json in the scan set — plus the analysis output path — aside before the analysis runs. On fallback, restore() rolls captured files back to their pre-analysis bytes and removes paths that did not exist beforehand. A producer-written facts file (socket manifest gradle --facts) is user-owned input, and for Gradle/Maven it is the manifest, so it is restored rather than deleted.

Machine-readable signal

A fallback previously reported an unqualified success, so nothing downstream could tell a degraded scan from a full one. scan create output now carries the failure alongside the scan result:

{
  "ok": true,
  "data": { "id": "…", "html_report_url": "…" },
  "reachabilityFallback": {
    "cause": "upstream gateway disconnected",
    "message": "Failed to fetch artifacts from Socket API"
  }
}

The Markdown report gains a matching line. --report output is unchanged — it comes from the shared scan-report path that socket scan report also uses.

Testing

  • Unit tests for the fallback path (regular scan type, no finalize, warning emitted, reachabilityFallback set) and the unchanged halt path.
  • Tests that the pre-analysis facts file is what gets uploaded after the analysis overwrites it, and that a report a failed analysis created is removed.
  • snapshotSocketFacts unit tests: restore, remove-if-created, and non-facts paths left alone.
  • outputCreateNewScan tests for the JSON and Markdown payloads with and without the marker.
  • New CLI tests: flag requires --reach, accepted with --reach in dry-run, help output updated.
  • pnpm run check and the scan/ci test suites pass.

Note

Medium Risk
Changes reachability failure handling and scan upload inputs (facts rollback and scan type), which affects CI pipelines that rely on tier1 scans or assume reach failure is fatal.

Overview
Adds --reach-fallback-to-regular-scan to socket scan create (requires --reach). When full application reachability analysis fails, the CLI can warn and continue with a normal SCA upload instead of exiting—scan_type becomes regular socket, tier1 finalize is skipped, and the missing-reachability-ID warning is suppressed on fallback.

Before analysis, snapshotSocketFacts backs up .socket.facts.json paths Coana may overwrite; on fallback restore() puts pre-analysis inputs back (or removes files the failed run created) so the degraded scan does not upload partial facts or leave stale artifacts.

Successful create output can include a reachabilityFallback object (message, optional cause) in JSON and a note in Markdown, so automation can distinguish a downgraded scan from a full tier1 run. The flag is hidden/no-op on socket scan reach. CI and GitHub-driven scan entry points default it to false; changelog and tests cover CLI validation, handler behavior, snapshot/restore, and output formatting.

Reviewed by Cursor Bugbot for commit 27c53cd. Configure here.

When reachability analysis fails (e.g. backend gateway disconnect during
compute-artifacts), �[34m?�[39m �[1mNo TARGET given. Do you want to use the current directory?�[22m �[2m(Use arrow keys)�[22m
�[36m❯ Yes�[39m
  No
�[36mTarget the current directory�[39m�[?25l�[29G
�[?25h currently aborts the
whole scan. The new opt-in flag continues with a regular SCA scan
instead, so the rest of the scan still ships when reachability errors
out.
…gnal

The --reach-fallback-to-regular-scan path had three gaps.

Coana writes its report over `.socket.facts.json` in place, so an analysis
that fails part way leaves partial output where the scan's inputs were. The
fallback uploaded that file as-is and left it on disk, where the next --reach
run reads it as a pre-generated input. Snapshot the facts files before the
analysis runs and restore them on fallback: captured files are rolled back to
their pre-analysis bytes, and files the analysis created are removed. A
producer-written facts file (socket manifest gradle --facts) is user-owned
input and is restored rather than deleted.

The JSON and Markdown output reported an unqualified success, so nothing
downstream could tell a degraded scan from a full one. Carry the failure in a
`reachabilityFallback` field alongside the scan result.
@mtorp
Martin Torp (mtorp) merged commit d2ee8a0 into v1.x Sep 14, 2026
5 checks passed
@mtorp
Martin Torp (mtorp) deleted the martin/flag-to-fall-back-to-regular-sca-when-re branch September 14, 2026 13:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

2 participants