feat(scan): add --reach-retain-facts-file to keep the reachability report (1.1.124) (#1372)

* feat(scan): add --reach-retain-facts-file to keep the reachability report (1.1.124)

By default `socket scan create --reach` deletes the `.socket.facts.json` report from the scan directory after a successful scan. The new `--reach-retain-facts-file` flag opts out of that cleanup so the report can be inspected, with a clear warning that the file must be deleted before the next tier 1 scan: a stale facts file is picked up as a pre-generated input and would make those results unreliable.

* upgrading coana to version 15.5.4

Author: mtorp

CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [1.1.124](https://github.com/SocketDev/socket-cli/releases/tag/v1.1.124) - 2026-06-19
+
+### Added
+- `socket scan create --reach` accepts a new `--reach-retain-facts-file` flag. By default the CLI deletes the `.socket.facts.json` reachability report from the scan directory after a successful scan; pass this flag to keep it (e.g. for inspection or debugging). **Important:** you must delete the retained `.socket.facts.json` before running a fresh tier 1 reachability scan — a stale file 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.
+
+### Changed
+- Updated the Coana CLI to v `15.5.4`.
+
 ## [1.1.123](https://github.com/SocketDev/socket-cli/releases/tag/v1.1.123) - 2026-06-18
 
 ### Added

package.json

@@ -1,6 +1,6 @@
 {
   "name": "socket",
-  "version": "1.1.123",
+  "version": "1.1.124",
   "description": "CLI for Socket.dev",
   "homepage": "https://github.com/SocketDev/socket-cli",
   "license": "MIT",
@@ -96,7 +96,7 @@
     "@babel/preset-typescript": "7.27.1",
     "@babel/runtime": "7.28.4",
     "@biomejs/biome": "2.2.4",
-    "@coana-tech/cli": "15.5.0",
+    "@coana-tech/cli": "15.5.4",
     "@cyclonedx/cdxgen": "12.1.2",
     "@dotenvx/dotenvx": "1.49.0",
     "@eslint/compat": "1.3.2",

pnpm-lock.yaml

@@ -67,6 +67,7 @@ export async function handleCi(autoManifest: boolean): Promise<void> {
       reachEnableAnalysisSplitting: false,
       reachExcludePaths: [],
       reachLazyMode: false,
+      reachRetainFactsFile: false,
       reachSkipCache: false,
       reachUseOnlyPregeneratedSboms: false,
       reachVersion: undefined,

src/commands/ci/handle-ci.mts

@@ -264,6 +264,7 @@ async function run(
     reachDisableExternalToolChecks,
     reachEnableAnalysisSplitting,
     reachLazyMode,
+    reachRetainFactsFile,
     reachSkipCache,
     reachUseOnlyPregeneratedSboms,
     reachVersion,
@@ -302,6 +303,7 @@ async function run(
     reachDisableExternalToolChecks: boolean
     reachEnableAnalysisSplitting: boolean
     reachLazyMode: boolean
+    reachRetainFactsFile: boolean
     reachSkipCache: boolean
     reachUseOnlyPregeneratedSboms: boolean
     reachVersion: string | undefined
@@ -659,6 +661,7 @@ async function run(
       reachEnableAnalysisSplitting: Boolean(reachEnableAnalysisSplitting),
       reachExcludePaths,
       reachLazyMode: Boolean(reachLazyMode),
+      reachRetainFactsFile: Boolean(reachRetainFactsFile),
       reachSkipCache: Boolean(reachSkipCache),
       reachUseOnlyPregeneratedSboms: Boolean(reachUseOnlyPregeneratedSboms),
       reachVersion,

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

@@ -69,6 +69,7 @@ describe('socket scan create', async () => {
             --reach-disable-external-tool-checks  Disable external tool checks during reachability analysis.
             --reach-ecosystems  List of ecosystems to conduct reachability analysis on, as either a comma separated value or as multiple flags. Defaults to all ecosystems.
             --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.
+            --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 tier 1 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.
             --reach-skip-cache  Skip caching-based optimizations. By default, the reachability analysis will use cached configurations from previous runs to speed up the analysis.
             --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.
             --reach-version     Override the version of @coana-tech/cli used for reachability analysis. Default: <coana-version>.

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

@@ -137,6 +137,7 @@ async function run(
     reachDisableExternalToolChecks,
     reachEnableAnalysisSplitting,
     reachLazyMode,
+    reachRetainFactsFile,
     reachSkipCache,
     reachUseOnlyPregeneratedSboms,
     reachVersion,
@@ -161,6 +162,7 @@ async function run(
     reachDisableExternalToolChecks: boolean
     reachEnableAnalysisSplitting: boolean
     reachLazyMode: boolean
+    reachRetainFactsFile: boolean
     reachSkipCache: boolean
     reachUseOnlyPregeneratedSboms: boolean
     reachVersion: string | undefined
@@ -292,6 +294,7 @@ async function run(
       reachEnableAnalysisSplitting: Boolean(reachEnableAnalysisSplitting),
       reachExcludePaths,
       reachLazyMode: Boolean(reachLazyMode),
+      reachRetainFactsFile: Boolean(reachRetainFactsFile),
       reachSkipCache: Boolean(reachSkipCache),
       reachUseOnlyPregeneratedSboms: Boolean(reachUseOnlyPregeneratedSboms),
       reachVersion,

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

@@ -51,6 +51,7 @@ describe('socket scan reach', async () => {
             --reach-disable-external-tool-checks  Disable external tool checks during reachability analysis.
             --reach-ecosystems  List of ecosystems to conduct reachability analysis on, as either a comma separated value or as multiple flags. Defaults to all ecosystems.
             --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.
+            --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 tier 1 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.
             --reach-skip-cache  Skip caching-based optimizations. By default, the reachability analysis will use cached configurations from previous runs to speed up the analysis.
             --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.
             --reach-version     Override the version of @coana-tech/cli used for reachability analysis. Default: <coana-version>.

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

@@ -266,6 +266,7 @@ async function scanOneRepo(
       reachEnableAnalysisSplitting: false,
       reachExcludePaths: [],
       reachLazyMode: false,
+      reachRetainFactsFile: false,
       reachSkipCache: false,
       reachUseOnlyPregeneratedSboms: false,
       reachVersion: undefined,

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

@@ -30,6 +30,7 @@ function makeReachOptions(
     reachEnableAnalysisSplitting: false,
     reachExcludePaths: [],
     reachLazyMode: false,
+    reachRetainFactsFile: false,
     reachSkipCache: false,
     reachUseOnlyPregeneratedSboms: false,
     reachVersion: undefined,