Skip to content

Commit d2ee8a0

Browse files
authored
feat(scan): add --reach-fallback-to-regular-scan flag (#1537)
* feat(scan): add --reach-fallback-to-regular-scan flag 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. * fix(scan): make the reachability fallback leave a clean scan and a signal 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.
1 parent 2bf7fcf commit d2ee8a0

13 files changed

Lines changed: 609 additions & 37 deletions

‎CHANGELOG.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,11 @@ All notable changes to this project will be documented in this file.
44

55
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
66

7+
## [Unreleased]
8+
9+
### Added
10+
- Added the `--reach-fallback-to-regular-scan` flag to `socket scan create`, keeping the scan moving with regular SCA results when full application reachability analysis fails. The JSON and Markdown output carry a `reachabilityFallback` marker so automation can tell a downgraded scan from a full one.
11+
712
## [1.1.171](https://github.com/SocketDev/socket-cli/releases/tag/v1.1.171) - 2026-09-11
813

914
### Changed

‎src/commands/ci/handle-ci.mts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -81,6 +81,7 @@ export async function handleCi(autoManifest: boolean): Promise<void> {
8181
reachEcosystems: [],
8282
reachEnableAnalysisSplitting: false,
8383
reachExcludePaths: [],
84+
reachFallbackToRegularScan: false,
8485
reachRetainFactsFile: false,
8586
reachSkipCache: false,
8687
reachUseOnlyPregeneratedSboms: false,

‎src/commands/scan/cmd-scan-create.mts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -277,6 +277,7 @@ async function run(
277277
reachDisableAnalytics,
278278
reachDisableExternalToolChecks,
279279
reachEnableAnalysisSplitting,
280+
reachFallbackToRegularScan,
280281
reachLazyMode: _reachLazyMode,
281282
reachRetainFactsFile,
282283
reachSkipCache,
@@ -317,6 +318,7 @@ async function run(
317318
reachDisableAnalytics: boolean
318319
reachDisableExternalToolChecks: boolean
319320
reachEnableAnalysisSplitting: boolean
321+
reachFallbackToRegularScan: boolean
320322
reachLazyMode: boolean
321323
reachRetainFactsFile: boolean
322324
reachSkipCache: boolean
@@ -662,6 +664,7 @@ async function run(
662664
reachEcosystems,
663665
reachEnableAnalysisSplitting: Boolean(reachEnableAnalysisSplitting),
664666
reachExcludePaths,
667+
reachFallbackToRegularScan: Boolean(reachFallbackToRegularScan),
665668
reachRetainFactsFile: Boolean(reachRetainFactsFile),
666669
reachSkipCache: Boolean(reachSkipCache),
667670
reachUseOnlyPregeneratedSboms: Boolean(reachUseOnlyPregeneratedSboms),

‎src/commands/scan/cmd-scan-create.test.mts‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,7 @@ describe('socket scan create', async () => {
7070
--reach-disable-external-tool-checks Disable external tool checks during reachability analysis.
7171
--reach-ecosystems List of ecosystems to conduct reachability analysis on, as either a comma separated value or as multiple flags. Supported: cargo, composer, gem, golang, maven, npm, nuget, pypi. Defaults to all supported ecosystems.
7272
--reach-enable-analysis-splitting Allow the reachability analysis to partition CVEs into buckets that are processed in separate analysis runs. May improve accuracy, but not recommended by default.
73+
--reach-fallback-to-regular-scan If reachability analysis fails, continue with a regular SCA scan (without reachability results) instead of halting. By default, the CLI halts on reachability errors.
7374
--reach-retain-facts-file Keep the \`.socket.facts.json\` reachability report that the analysis writes to the scan directory instead of deleting it after a successful scan. IMPORTANT: you must delete this file before running a fresh full application reachability scan. A stale \`.socket.facts.json\` left in place is picked up as a pre-generated input and silently overrides fresh analysis, so the new scan results will not be reliable.
7475
--reach-skip-cache Skip caching-based optimizations. By default, the reachability analysis will use cached configurations from previous runs to speed up the analysis.
7576
--reach-use-only-pregenerated-sboms When using this option, the scan is created based only on pre-generated CDX and SPDX files in your project.
@@ -249,6 +250,37 @@ describe('socket scan create', async () => {
249250
},
250251
)
251252

253+
cmdit(
254+
[
255+
'scan',
256+
'create',
257+
FLAG_ORG,
258+
'fakeOrg',
259+
'target',
260+
FLAG_DRY_RUN,
261+
'--repo',
262+
'xyz',
263+
'--branch',
264+
'abc',
265+
'--reach-fallback-to-regular-scan',
266+
FLAG_CONFIG,
267+
'{"apiToken":"fakeToken"}',
268+
],
269+
'should fail when --reach-fallback-to-regular-scan is used without --reach',
270+
async cmd => {
271+
const { code, stderr, stdout } = await spawnSocketCli(binCliPath, cmd)
272+
const output = stdout + stderr
273+
expect(output).toContain(
274+
'Reachability analysis flags require --reach to be enabled',
275+
)
276+
expect(output).toContain('add --reach flag to use --reach-* options')
277+
expect(
278+
code,
279+
'should exit with non-zero code when validation fails',
280+
).not.toBe(0)
281+
},
282+
)
283+
252284
cmdit(
253285
[
254286
'scan',
@@ -690,6 +722,31 @@ describe('socket scan create', async () => {
690722
},
691723
)
692724

725+
cmdit(
726+
[
727+
'scan',
728+
'create',
729+
FLAG_ORG,
730+
'fakeOrg',
731+
'test/fixtures/commands/scan/simple-npm',
732+
FLAG_DRY_RUN,
733+
'--repo',
734+
'xyz',
735+
'--branch',
736+
'abc',
737+
'--reach',
738+
'--reach-fallback-to-regular-scan',
739+
FLAG_CONFIG,
740+
'{"apiToken":"fakeToken"}',
741+
],
742+
'should succeed when --reach-fallback-to-regular-scan is used with --reach',
743+
async cmd => {
744+
const { code, stdout } = await spawnSocketCli(binCliPath, cmd)
745+
expect(stdout).toMatchInlineSnapshot(`"[DryRun]: Bailing now"`)
746+
expect(code, 'should exit with code 0 when all flags are valid').toBe(0)
747+
},
748+
)
749+
693750
cmdit(
694751
[
695752
'scan',

‎src/commands/scan/cmd-scan-reach.mts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,14 @@ const reachabilityFlagsForReach: MeowFlags = {
4747
default: false,
4848
description: `${DYNAMIC_SBOM_INFERENCE_DESCRIPTION} The reachability analysis is split per project/module accordingly.`,
4949
},
50+
// Fallback targets scan creation, which this command never performs.
51+
reachFallbackToRegularScan: {
52+
type: 'boolean',
53+
default: false,
54+
hidden: true,
55+
description:
56+
'No-op: only `socket scan create --reach` falls back to a regular SCA scan on reachability failure.',
57+
},
5058
}
5159

5260
const generalFlags: MeowFlags = {

‎src/commands/scan/create-scan-from-github.mts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -339,6 +339,7 @@ async function scanOneRepo(
339339
reachEcosystems: [],
340340
reachEnableAnalysisSplitting: false,
341341
reachExcludePaths: [],
342+
reachFallbackToRegularScan: false,
342343
reachRetainFactsFile: false,
343344
reachSkipCache: false,
344345
reachUseOnlyPregeneratedSboms: false,

‎src/commands/scan/handle-create-new-scan.mts‎

Lines changed: 67 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,10 @@ import { performReachabilityAnalysis } from './perform-reachability-analysis.mts
1717
import { runDynamicSbomInference } from './run-dynamic-sbom-inference.mts'
1818
import constants from '../../constants.mts'
1919
import { checkCommandInput } from '../../utils/check-input.mts'
20-
import { compressSocketFactsForUpload } from '../../utils/coana.mts'
20+
import {
21+
compressSocketFactsForUpload,
22+
snapshotSocketFacts,
23+
} from '../../utils/coana.mts'
2124
import { findSocketYmlSync } from '../../utils/config.mts'
2225
import { withTmpDir } from '../../utils/fs.mts'
2326
import { getPackageFilesForScan } from '../../utils/path-resolve.mts'
@@ -27,6 +30,7 @@ import { detectManifestActions } from '../manifest/detect-manifest-actions.mts'
2730
import { generateAutoManifest } from '../manifest/generate_auto_manifest.mts'
2831
import { mergeResolvedPathsSidecars } from '../manifest/scripts/sidecar.mts'
2932

33+
import type { ReachabilityFallback } from './output-create-new-scan.mts'
3034
import type { ReachabilityOptions } from './perform-reachability-analysis.mts'
3135
import type { REPORT_LEVEL } from './types.mts'
3236
import type { OutputKind } from '../../types.mts'
@@ -84,6 +88,7 @@ export type HandleCreateNewScanConfig = {
8488
outputKind: OutputKind
8589
reach: Remap<
8690
ReachabilityOptions & {
91+
reachFallbackToRegularScan: boolean
8792
runReachabilityAnalysis: boolean
8893
}
8994
>
@@ -292,6 +297,7 @@ export async function handleCreateNewScan({
292297
let scanPaths: string[] = packagePaths
293298
let tier1ReachabilityScanId: string | undefined
294299
let reachabilityReport: string | undefined
300+
let reachabilityFallback: ReachabilityFallback | undefined
295301

296302
// If reachability is enabled, perform reachability analysis.
297303
if (reach.runReachabilityAnalysis) {
@@ -300,6 +306,12 @@ export async function handleCreateNewScan({
300306
debugFn('notice', 'Reachability analysis enabled')
301307
debugDir('inspect', { reachabilityOptions: mergedReachabilityOptions })
302308

309+
const factsSnapshot = await snapshotSocketFacts(packagePaths, {
310+
cwd,
311+
outputPath: constants.DOT_SOCKET_DOT_FACTS_JSON,
312+
tmpDir: manifestTmpDir,
313+
})
314+
303315
spinner.start()
304316

305317
const reachResult = await performReachabilityAnalysis({
@@ -318,36 +330,49 @@ export async function handleCreateNewScan({
318330
spinner.stop()
319331

320332
if (!reachResult.ok) {
321-
await outputCreateNewScan(reachResult, { interactive, outputKind })
322-
return
323-
}
324-
325-
logger.success('Reachability analysis completed successfully')
326-
327-
reachabilityReport = reachResult.data?.reachabilityReport
328-
329-
// When using only pre-generated SBOMs, build the scan from those inputs —
330-
// CycloneDX, SPDX, and Socket facts (`.socket.facts.json`) — matching
331-
// Coana's `--use-only-pregenerated-sboms` selection. Otherwise drop any
332-
// stray `.socket.facts.json`; coana's fresh reachability report (appended
333-
// below) is the authoritative facts file for the scan.
334-
const pathsForScan = reach.reachUseOnlyPregeneratedSboms
335-
? filterToPregeneratedSboms(packagePaths, supportedFiles)
336-
: packagePaths.filter(
337-
p => path.basename(p) !== constants.DOT_SOCKET_DOT_FACTS_JSON,
333+
if (reach.reachFallbackToRegularScan) {
334+
reachabilityFallback = {
335+
cause: reachResult.cause,
336+
message: reachResult.message,
337+
}
338+
// Restore the pre-analysis facts files: the regular scan must upload
339+
// the inputs it would have had without --reach, not partial output.
340+
await factsSnapshot.restore()
341+
logger.warn(
342+
`Reachability analysis failed: ${reachResult.message}${reachResult.cause ? ` — ${reachResult.cause}` : ''}. Falling back to a regular SCA scan without reachability results.`,
338343
)
339-
340-
// Append coana's reachability report, but not twice: a pre-generated facts
341-
// input can resolve to the same path coana wrote its report to.
342-
const reportPath = reachabilityReport
343-
? path.resolve(cwd, reachabilityReport)
344-
: undefined
345-
scanPaths = [
346-
...pathsForScan.filter(p => path.resolve(cwd, p) !== reportPath),
347-
...(reachabilityReport ? [reachabilityReport] : []),
348-
]
349-
350-
tier1ReachabilityScanId = reachResult.data?.tier1ReachabilityScanId
344+
} else {
345+
await outputCreateNewScan(reachResult, { interactive, outputKind })
346+
return
347+
}
348+
} else {
349+
logger.success('Reachability analysis completed successfully')
350+
351+
reachabilityReport = reachResult.data?.reachabilityReport
352+
353+
// When using only pre-generated SBOMs, build the scan from those inputs —
354+
// CycloneDX, SPDX, and Socket facts (`.socket.facts.json`) — matching
355+
// Coana's `--use-only-pregenerated-sboms` selection. Otherwise drop any
356+
// stray `.socket.facts.json`; coana's fresh reachability report (appended
357+
// below) is the authoritative facts file for the scan.
358+
const pathsForScan = reach.reachUseOnlyPregeneratedSboms
359+
? filterToPregeneratedSboms(packagePaths, supportedFiles)
360+
: packagePaths.filter(
361+
p => path.basename(p) !== constants.DOT_SOCKET_DOT_FACTS_JSON,
362+
)
363+
364+
// Append coana's reachability report, but not twice: a pre-generated facts
365+
// input can resolve to the same path coana wrote its report to.
366+
const reportPath = reachabilityReport
367+
? path.resolve(cwd, reachabilityReport)
368+
: undefined
369+
scanPaths = [
370+
...pathsForScan.filter(p => path.resolve(cwd, p) !== reportPath),
371+
...(reachabilityReport ? [reachabilityReport] : []),
372+
]
373+
374+
tier1ReachabilityScanId = reachResult.data?.tier1ReachabilityScanId
375+
}
351376
}
352377

353378
// Brotli-compress any .socket.facts.json paths in scanPaths just before
@@ -369,9 +394,10 @@ export async function handleCreateNewScan({
369394
pullRequest,
370395
repoName,
371396
branchName,
372-
scanType: reach.runReachabilityAnalysis
373-
? constants.SCAN_TYPE_SOCKET_TIER1
374-
: constants.SCAN_TYPE_SOCKET,
397+
scanType:
398+
reach.runReachabilityAnalysis && !reachabilityFallback
399+
? constants.SCAN_TYPE_SOCKET_TIER1
400+
: constants.SCAN_TYPE_SOCKET,
375401
workspace,
376402
},
377403
{
@@ -392,7 +418,8 @@ export async function handleCreateNewScan({
392418
} else if (
393419
reach.runReachabilityAnalysis &&
394420
scanId &&
395-
!tier1ReachabilityScanId
421+
!tier1ReachabilityScanId &&
422+
!reachabilityFallback
396423
) {
397424
// Reachability analysis ran and a scan was created, but no full
398425
// application reachability scan id was extracted from the facts file.
@@ -455,13 +482,18 @@ export async function handleCreateNewScan({
455482
{
456483
interactive,
457484
outputKind,
485+
reachabilityFallback,
458486
},
459487
)
460488
}
461489
} else {
462490
spinner.stop()
463491

464-
await outputCreateNewScan(fullScanCResult, { interactive, outputKind })
492+
await outputCreateNewScan(fullScanCResult, {
493+
interactive,
494+
outputKind,
495+
reachabilityFallback,
496+
})
465497
}
466498
})
467499
}

0 commit comments

Comments
 (0)