From a8d72cc029c015a89eb927cf0ad68daae22824fd Mon Sep 17 00:00:00 2001 From: David Larsen Date: Fri, 20 Nov 2026 15:34:17 -0500 Subject: [PATCH 1/3] Document what --include-module-folders does The help text said "Enabling including module folders like node_modules", which doesn't say what a scan gains. The flag removes node_modules, bower_components and jspm_packages from the directories manifest discovery skips. Every package.json under them is then uploaded as its own project, and Socket resolves the dependencies each one declares, devDependencies included. The installed packages themselves are never recorded, so the flag can add hundreds of packages a project never installs and still misses a package that a postinstall script put in node_modules without a lockfile entry. Say that in the help text and the CLI reference, and add a troubleshooting entry for packages installed outside the lockfile: a CycloneDX SBOM of the installed tree saved in the scan root is picked up by manifest discovery and uploaded with the other manifests. No behavior change. Bumps the version to 2.13.1 for the version check. --- CHANGELOG.md | 10 ++++++++++ docs/cli-reference.md | 2 +- docs/troubleshooting.md | 19 +++++++++++++++++++ pyproject.toml | 2 +- socketsecurity/__init__.py | 2 +- socketsecurity/config.py | 7 ++++++- uv.lock | 2 +- 7 files changed, 39 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ff28e72..6a183fd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,15 @@ # Changelog +## 2.13.1 + +### Docs + +- `--include-module-folders` help and docs now say what the flag does: each + `package.json` under `node_modules`, `bower_components` or `jspm_packages` is + uploaded as its own project, and Socket resolves the dependencies it declares. + It does not list installed packages. The troubleshooting guide covers scanning + packages installed outside the lockfile with a CycloneDX SBOM. + ## 2.13.0 ### Upgrade notes diff --git a/docs/cli-reference.md b/docs/cli-reference.md index 066820d..888b4d5 100644 --- a/docs/cli-reference.md +++ b/docs/cli-reference.md @@ -308,7 +308,7 @@ If you don't want to provide the Socket API Token every time then you can use th | Parameter | Required | Default | Description | |:-------------------------|:---------|:--------|:------------------------------------------------------------------------------------------------------| | `--default-branch` | False | *auto* | Make this branch the default branch (auto-detected from git and CI environment when not specified) | -| `--include-module-folders` | False | False | If enabled, re-includes the JS/TS module folders (`node_modules`, `bower_components`, `jspm_packages`) in manifest discovery. For other excluded directories, use `--include-dirs`. | +| `--include-module-folders` | False | False | Also discovers manifests inside the JS module folders (`node_modules`, `bower_components`, `jspm_packages`), which are skipped by default. Same as `--include-dirs node_modules,bower_components,jspm_packages`. Each `package.json` found there is uploaded as its own project, and Socket resolves the dependencies it declares, `devDependencies` included, so a scan can gain hundreds of packages your project never installs. It does not record the installed packages themselves, so it won't find packages missing from your lockfile; see [Packages installed outside the lockfile](troubleshooting.md#packages-installed-outside-the-lockfile). With `--reach`, the extra manifests are uploaded for reachability analysis too. For `vendor`, `.venv` and other excluded directories, use `--include-dirs`. | #### Output Configuration | Parameter | Required | Default | Description | diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index c2a1b02..a803ac5 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -74,6 +74,25 @@ total before assuming either path is at fault. - Every vulnerability reported as `INSTALL ERROR`: the engine could not install your dependencies. Allow the ecosystem's package registry, or install dependencies in the target path before running `--reach`. - See **Reachability network access** in the [CLI reference](cli-reference.md) for the full list of hosts. +## Packages installed outside the lockfile + +The CLI scans manifests and lockfiles. A package that a `postinstall` script installs into `node_modules` has no lockfile entry, so it is not in the scan. + +`--include-module-folders` does not fix this. It uploads each `node_modules/*/package.json` as a separate project, and Socket resolves the dependencies those files declare (`devDependencies` included). The installed packages themselves are not recorded, and the scan can gain hundreds of packages your project never installs. + +To scan what is installed, generate a CycloneDX SBOM of the installed `node_modules` tree and save it in the scan root before running the CLI: + +```bash +npm ci +npx @cyclonedx/cyclonedx-npm --omit dev --ignore-npm-errors --output-format JSON --output-file installed.cdx.json +socketcli --target-path . +``` + +The CLI uploads CycloneDX files named `bom.json`, `*.cdx.json` or `*.cyclonedx.json` (and the `.xml` forms) with your other manifests. No flag is needed. + +- Generate the SBOM on default-branch scans as well as pull request scans. Otherwise packages that only the SBOM lists show up as new in every comparison. +- Packages fetched at runtime, for example by `npx`, are not in `node_modules` and are not covered. + ## Dashboard vs CLI result counts Differences in result counts can be valid, even when filtering appears similar. diff --git a/pyproject.toml b/pyproject.toml index 0924672..2ba92fb 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -6,7 +6,7 @@ build-backend = "hatchling.build" [project] name = "socketsecurity" -version = "2.13.0" +version = "2.13.1" requires-python = ">= 3.11" license = {"file" = "LICENSE"} dependencies = [ diff --git a/socketsecurity/__init__.py b/socketsecurity/__init__.py index 08835ec..a3c8f69 100644 --- a/socketsecurity/__init__.py +++ b/socketsecurity/__init__.py @@ -1,4 +1,4 @@ __author__ = 'socket.dev' -__version__ = '2.13.0' +__version__ = '2.13.1' USER_AGENT_NAME = 'socket-python-cli' USER_AGENT = f'{USER_AGENT_NAME}/{__version__}' diff --git a/socketsecurity/config.py b/socketsecurity/config.py index a11ad25..07e3008 100644 --- a/socketsecurity/config.py +++ b/socketsecurity/config.py @@ -1119,7 +1119,12 @@ def create_argument_parser() -> argparse.ArgumentParser: dest="include_module_folders", action="store_true", default=False, - help="Enabling including module folders like node_modules" + help="Also discover manifests inside node_modules, bower_components and jspm_packages, " + "which are skipped by default (same as --include-dirs with those names). Each " + "package.json found there is uploaded as its own project, and Socket resolves the " + "dependencies it declares, devDependencies included. This does not list the " + "installed packages themselves, so it does not find packages that are missing from " + "your lockfile. See docs/troubleshooting.md." ) # Reachability Configuration diff --git a/uv.lock b/uv.lock index a6271a3..aea1ca6 100644 --- a/uv.lock +++ b/uv.lock @@ -1334,7 +1334,7 @@ wheels = [ [[package]] name = "socketsecurity" -version = "2.13.0" +version = "2.13.1" source = { editable = "." } dependencies = [ { name = "beautifulsoup4" }, From d4bec77011ffe37256a40aec1b2a81bc695124fb Mon Sep 17 00:00:00 2001 From: David Larsen Date: Fri, 20 Nov 2026 17:07:07 -0500 Subject: [PATCH 2/3] Say every manifest under module folders is scanned, and shorten the help The flag adds every supported manifest under node_modules, bower_components and jspm_packages, at any depth, not only each package's top-level package.json. Those files are added to the same scan; no separate project is created. Say that in the reference, troubleshooting entry and changelog. Cut the help text to two sentences and point to the troubleshooting section on GitHub, since pip installs don't include the docs folder. --- CHANGELOG.md | 8 ++++---- docs/cli-reference.md | 2 +- docs/troubleshooting.md | 2 +- socketsecurity/config.py | 9 +++------ 4 files changed, 9 insertions(+), 12 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6a183fd..d8b4f96 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,10 +4,10 @@ ### Docs -- `--include-module-folders` help and docs now say what the flag does: each - `package.json` under `node_modules`, `bower_components` or `jspm_packages` is - uploaded as its own project, and Socket resolves the dependencies it declares. - It does not list installed packages. The troubleshooting guide covers scanning +- `--include-module-folders` help and docs now say what the flag does: every + supported manifest under `node_modules`, `bower_components` or `jspm_packages`, + nested folders included, is added to the scan, and Socket resolves the + dependencies those files declare. It does not list installed packages. The troubleshooting guide covers scanning packages installed outside the lockfile with a CycloneDX SBOM. ## 2.13.0 diff --git a/docs/cli-reference.md b/docs/cli-reference.md index 888b4d5..0869b67 100644 --- a/docs/cli-reference.md +++ b/docs/cli-reference.md @@ -308,7 +308,7 @@ If you don't want to provide the Socket API Token every time then you can use th | Parameter | Required | Default | Description | |:-------------------------|:---------|:--------|:------------------------------------------------------------------------------------------------------| | `--default-branch` | False | *auto* | Make this branch the default branch (auto-detected from git and CI environment when not specified) | -| `--include-module-folders` | False | False | Also discovers manifests inside the JS module folders (`node_modules`, `bower_components`, `jspm_packages`), which are skipped by default. Same as `--include-dirs node_modules,bower_components,jspm_packages`. Each `package.json` found there is uploaded as its own project, and Socket resolves the dependencies it declares, `devDependencies` included, so a scan can gain hundreds of packages your project never installs. It does not record the installed packages themselves, so it won't find packages missing from your lockfile; see [Packages installed outside the lockfile](troubleshooting.md#packages-installed-outside-the-lockfile). With `--reach`, the extra manifests are uploaded for reachability analysis too. For `vendor`, `.venv` and other excluded directories, use `--include-dirs`. | +| `--include-module-folders` | False | False | Also discovers manifests anywhere under `node_modules`, `bower_components` and `jspm_packages`, nested folders included (skipped by default; same as `--include-dirs` with those names). Every supported manifest found there is added to the scan, and Socket resolves the dependencies those files declare, `devDependencies` included. The installed packages themselves are not recorded; see [Packages installed outside the lockfile](troubleshooting.md#packages-installed-outside-the-lockfile). For `vendor`, `.venv` and other excluded directories, use `--include-dirs`. | #### Output Configuration | Parameter | Required | Default | Description | diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index a803ac5..ad3158f 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -78,7 +78,7 @@ total before assuming either path is at fault. The CLI scans manifests and lockfiles. A package that a `postinstall` script installs into `node_modules` has no lockfile entry, so it is not in the scan. -`--include-module-folders` does not fix this. It uploads each `node_modules/*/package.json` as a separate project, and Socket resolves the dependencies those files declare (`devDependencies` included). The installed packages themselves are not recorded, and the scan can gain hundreds of packages your project never installs. +`--include-module-folders` does not fix this. It adds every supported manifest under `node_modules` to the scan, at any depth: each package's `package.json`, including nested `node_modules` and scoped packages, plus any other manifest or lockfile a package ships. Socket resolves the dependencies those files declare (`devDependencies` included), so the scan can gain hundreds of packages your project never installs. The installed packages themselves are not recorded. With `--reach`, these manifests are uploaded for reachability analysis too. To scan what is installed, generate a CycloneDX SBOM of the installed `node_modules` tree and save it in the scan root before running the CLI: diff --git a/socketsecurity/config.py b/socketsecurity/config.py index 07e3008..b97a26f 100644 --- a/socketsecurity/config.py +++ b/socketsecurity/config.py @@ -1119,12 +1119,9 @@ def create_argument_parser() -> argparse.ArgumentParser: dest="include_module_folders", action="store_true", default=False, - help="Also discover manifests inside node_modules, bower_components and jspm_packages, " - "which are skipped by default (same as --include-dirs with those names). Each " - "package.json found there is uploaded as its own project, and Socket resolves the " - "dependencies it declares, devDependencies included. This does not list the " - "installed packages themselves, so it does not find packages that are missing from " - "your lockfile. See docs/troubleshooting.md." + help="Also scan manifests anywhere under node_modules, bower_components and jspm_packages " + "(same as --include-dirs with those names). Adds the dependencies they declare, not the " + "installed packages. See https://github.com/SocketDev/socket-python-cli/blob/main/docs/troubleshooting.md#packages-installed-outside-the-lockfile" ) # Reachability Configuration From 2cad7fabe15851ecdb992c4020fac422fb420fe6 Mon Sep 17 00:00:00 2001 From: David Larsen Date: Fri, 20 Nov 2026 18:08:17 -0500 Subject: [PATCH 3/3] Bump version to 2.13.3 2.13.2 was released from main, so this change needs the next patch version. --- pyproject.toml | 2 +- socketsecurity/__init__.py | 2 +- uv.lock | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index 5c88c15..82c5bbf 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -6,7 +6,7 @@ build-backend = "hatchling.build" [project] name = "socketsecurity" -version = "2.13.2" +version = "2.13.3" requires-python = ">= 3.11" license = {"file" = "LICENSE"} dependencies = [ diff --git a/socketsecurity/__init__.py b/socketsecurity/__init__.py index 7ba49e1..0871ade 100644 --- a/socketsecurity/__init__.py +++ b/socketsecurity/__init__.py @@ -1,4 +1,4 @@ __author__ = 'socket.dev' -__version__ = '2.13.2' +__version__ = '2.13.3' USER_AGENT_NAME = 'socket-python-cli' USER_AGENT = f'{USER_AGENT_NAME}/{__version__}' diff --git a/uv.lock b/uv.lock index 196ae3c..b3681e4 100644 --- a/uv.lock +++ b/uv.lock @@ -1334,7 +1334,7 @@ wheels = [ [[package]] name = "socketsecurity" -version = "2.13.2" +version = "2.13.3" source = { editable = "." } dependencies = [ { name = "beautifulsoup4" },