feat(scan): scan selected uv workspace members with dependency graphs (#1565)

* feat(scan): scan selected uv packages with dependency graphs

* docs(scan): remove stale and repeated upload comments

* fix(scan): preserve development scopes in uv package scans

* test(scan): give uv CLI tests the 30s CLI spawn timeout

These cases spawn the built CLI like the cmdit tests do, but ran with vitest's 5s default and timed out under parallel load.

* feat(scan): select uv workspace members by target directory

Replace --uv-package <project.name> with a boolean --uv-members flag. Each
TARGET is a member directory, and uv resolves it from the uv.lock in that
directory or its workspace root, so one scan can cover members of several
workspaces.

Each member's CycloneDX SBOM is written beside its pyproject.toml and removed
after the scan. That keeps the existing upload roots and reachability target
unchanged, so the scan handler takes a generic generateScanFiles hook and no
longer has uv-specific branches. With --reach, analysis runs on the member
directory only.

The e2e assertions now accept uv 0.12, which omits dependsOn on leaf nodes and
adds workspace-root dependency groups to members without their own.

* feat(scan): add the uv member target code, tests and docs

Completes the previous commit, which only picked up the renames and the reachability revert.

* fix(scan): remove uv member SBOMs when a scan is interrupted

The launcher SIGKILLs a signalled scan after a short grace period, and a
signal or process.exit() skips finally blocks, so Ctrl-C or a CI cancel left
socket-uv-cdx.json in the member directory. A later regular scan would then
pick it up as a pre-generated SBOM. Written SBOMs are now also removed
synchronously on exit, SIGHUP, SIGINT and SIGTERM.

The real-uv e2e tests get a 30s timeout, since each one runs uv twice per
member and the handler test sometimes passed 5s.

Author: mtorp

CHANGELOG.md

@@ -4,6 +4,12 @@ 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/).
 
+## [Unreleased]
+
+### Added
+
+- `socket scan create --uv-members <dir...>` scans selected uv workspace members with the versions and dependency relationships pinned in their shared `uv.lock`, leaving unrelated members out of the scan. Dependencies used only by dependency groups are marked as development dependencies. Requires uv with CycloneDX export support.
+
 ## [1.2.1](https://github.com/SocketDev/socket-cli/releases/tag/v1.2.1) - 2026-09-28
 
 ### Changed

README.md

@@ -63,6 +63,39 @@ All aliases support the flags and arguments of the commands they alias.
 
 - `socket ci` - Alias for `socket scan create --report` (creates report and exits with error if unhealthy)
 
+### Scanning uv workspace members
+
+Use `--uv-members` to scan selected directories of a uv workspace with the
+versions pinned in the workspace's shared `uv.lock`:
+
+```sh
+socket scan create --uv-members ./packages/api ./packages/worker
+```
+
+Each TARGET is a directory with its own `pyproject.toml`. uv finds the
+`uv.lock` in that directory or in its workspace root, so one scan can cover
+members of several workspaces. The scan includes each target's transitive and
+local workspace dependencies, all extras, and all dependency groups.
+Dependencies used only by dependency groups are marked as development
+dependencies. Unrelated members and the shared lockfile are not added to the
+scan.
+
+This mode requires uv on PATH with support for `uv export --format cyclonedx1.5`,
+which uv currently treats as a preview feature. The export runs offline with
+`--frozen`, so it uses the existing lockfile without resolving newer versions,
+installing packages, or changing the project.
+
+The CLI writes a `socket-uv-cdx.json` SBOM into each target directory, uploads
+only those SBOMs in place of regular manifest discovery, and removes them after
+the scan, including on failure, Ctrl-C, or SIGTERM. It stops if that file
+already exists.
+`--read-only` prepares the SBOMs without uploading them, and `--dry-run`
+validates the options without running uv.
+
+With `--reach`, pass a single target. Reachability analysis then runs on that
+member's directory. `--uv-members` cannot be combined with `--auto-manifest` or
+`--dynamic-sbom-inference`.
+
 ### Reachability analysis
 
 Socket reachability analysis comes in three forms:

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

@@ -4,6 +4,10 @@ import path from 'node:path'
 import { logger } from '@socketsecurity/registry/lib/logger'
 
 import { assertValidExcludePaths } from './exclude-paths.mts'
+import {
+  generateUvMemberSboms,
+  resolveUvMemberDirs,
+} from './generate-uv-member-sboms.mts'
 import { handleCreateNewScan } from './handle-create-new-scan.mts'
 import { outputCreateNewScan } from './output-create-new-scan.mts'
 import {
@@ -172,6 +176,12 @@ const generalFlags: MeowFlags = {
       'Set the visibility (true/false) of the scan in your dashboard.',
     shortFlag: 't',
   },
+  uvMembers: {
+    type: 'boolean',
+    default: false,
+    description:
+      'Scan each TARGET directory as a uv project, using the versions pinned in its uv.lock or its workspace root uv.lock. Uploads a CycloneDX dependency graph per TARGET in place of manifest discovery, including all extras and dependency groups. Requires uv on PATH.',
+  },
 }
 
 export const cmdScanCreate = {
@@ -241,6 +251,7 @@ async function run(
       $ ${command}
       $ ${command} ./proj --json
       $ ${command} --repo=test-repo --branch=main ./package.json
+      $ ${command} --uv-members ./packages/api ./packages/worker
   `,
   }
 
@@ -332,6 +343,7 @@ async function run(
   )
 
   const dryRun = !!cli.flags['dryRun']
+  const uvMembers = !!cli.flags['uvMembers']
 
   let {
     autoManifest,
@@ -472,6 +484,7 @@ async function run(
     detected.count > 0 &&
     !autoManifest &&
     !dynamicSbomInference &&
+    !uvMembers &&
     !hasFactsFile
   ) {
     logger.info(
@@ -567,6 +580,13 @@ async function run(
       message: 'At least one TARGET (e.g. `.` or `./package.json`)',
       fail: 'missing',
     },
+    {
+      nook: true,
+      test: !uvMembers || (!autoManifest && !dynamicSbomInference),
+      message:
+        '--uv-members cannot be combined with --auto-manifest or --dynamic-sbom-inference',
+      fail: 'select one source of generated SBOMs',
+    },
     {
       nook: true,
       test: !json || !markdown,
@@ -629,6 +649,8 @@ async function run(
     return
   }
 
+  const uvMemberDirs = uvMembers ? resolveUvMemberDirs(targets, cwd) : undefined
+
   if (dryRun) {
     logger.log(constants.DRY_RUN_BAILING_NOW)
     return
@@ -642,6 +664,9 @@ async function run(
     committers: (committers && String(committers)) || '',
     cwd,
     defaultBranch: Boolean(defaultBranch),
+    generateScanFiles: uvMemberDirs
+      ? () => generateUvMemberSboms(uvMemberDirs)
+      : undefined,
     interactive: Boolean(interactive),
     orgSlug,
     outputKind,

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

@@ -1,6 +1,6 @@
 import path from 'node:path'
 
-import { describe, expect } from 'vitest'
+import { describe, expect, it } from 'vitest'
 
 import constants, {
   FLAG_CONFIG,
@@ -17,6 +17,70 @@ const fixtureBaseDir = path.join(testPath, 'fixtures/commands/scan/create')
 describe('socket scan create', async () => {
   const { binCliPath } = constants
 
+  const uvFixture = path.join(testPath, 'fixtures/commands/scan/uv-workspace')
+  const uvBaseArgs = [
+    'scan',
+    'create',
+    '--cwd',
+    uvFixture,
+    '--org',
+    'test-org',
+    '--repo',
+    'test-repo',
+    '--branch',
+    'main',
+    '--dry-run',
+    '--no-interactive',
+    FLAG_CONFIG,
+    '{}',
+  ]
+
+  it(
+    'accepts uv member directories as targets',
+    { timeout: 30_000 },
+    async () => {
+      const result = await spawnSocketCli(binCliPath, [
+        ...uvBaseArgs,
+        '--uv-members',
+        'packages/api',
+        'packages/other',
+      ])
+      expect(result.code).toBe(0)
+      expect(result.stdout).toContain('[DryRun]: Bailing now')
+    },
+  )
+
+  it.each([
+    {
+      args: ['--uv-members', 'packages/missing'],
+      error: 'directory inside --cwd',
+    },
+    {
+      args: ['--uv-members', '..'],
+      error: 'directory inside --cwd',
+    },
+    {
+      args: ['--uv-members', 'packages'],
+      error: 'requires a pyproject.toml in every TARGET',
+    },
+    {
+      args: ['--uv-members', 'packages/api', '--auto-manifest'],
+      error: 'cannot be combined',
+    },
+    {
+      args: ['--uv-members', 'packages/api', '--dynamic-sbom-inference'],
+      error: 'cannot be combined',
+    },
+  ])(
+    'rejects invalid uv member options: $args',
+    { timeout: 30_000 },
+    async ({ args, error }) => {
+      const result = await spawnSocketCli(binCliPath, [...uvBaseArgs, ...args])
+      expect(result.code).not.toBe(0)
+      expect(result.stdout + result.stderr).toContain(error)
+    },
+  )
+
   cmdit(
     ['scan', 'create', FLAG_HELP, FLAG_CONFIG, '{}'],
     `should support ${FLAG_HELP}`,
@@ -54,6 +118,7 @@ describe('socket scan create', async () => {
             --report-level      Which policy level alerts should be reported (default 'error')
             --set-as-alerts-page  When true and if this is the "default branch" then this Scan will be the one reflected on your alerts page. See help for details. Defaults to true.
             --tmp               Set the visibility (true/false) of the scan in your dashboard.
+            --uv-members        Scan each TARGET directory as a uv project, using the versions pinned in its uv.lock or its workspace root uv.lock. Uploads a CycloneDX dependency graph per TARGET in place of manifest discovery, including all extras and dependency groups. Requires uv on PATH.
             --workspace         The workspace in the Socket Organization that the repository is in to associate with the full scan.
 
           Reachability Options (when --reach is used)
@@ -109,7 +174,8 @@ describe('socket scan create', async () => {
           Examples
             $ socket scan create
             $ socket scan create ./proj --json
-            $ socket scan create --repo=test-repo --branch=main ./package.json"
+            $ socket scan create --repo=test-repo --branch=main ./package.json
+            $ socket scan create --uv-members ./packages/api ./packages/worker"
       `)
       expect(`\n   ${stderr}`).toMatchInlineSnapshot(`
         "