Skip to content

Document what --include-module-folders does - #463

Draft
David Larsen (dc-larsen) wants to merge 6 commits into
mainfrom
docs/include-module-folders-behavior
Draft

David Larsen (dc-larsen) wants to merge 6 commits into
mainfrom
docs/include-module-folders-behavior

Conversation

@dc-larsen

@dc-larsen David Larsen (dc-larsen) commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Docs only. The --include-module-folders help text is "Enabling including module folders like node_modules", which reads as "scan what's installed". It doesn't do that, and turning it on can add hundreds of packages to a scan while still missing the package a user was looking for.

What the flag does, from the source:

  • socketcli.py removes module_folder_dirs (node_modules, bower_components, jspm_packages) from core.config.excluded_dirs before any find_files call. Same effect as --include-dirs node_modules,bower_components,jspm_packages.
  • find_files then descends into those folders, at any depth, and keeps every file matching a supported manifest pattern. In practice that is mostly each package's package.json (nested node_modules and scoped packages included), plus any other manifest or lockfile a package ships, such as a requirements.txt or yarn.lock. The hidden node_modules/.package-lock.json doesn't match the package-lock.json pattern, so it is not picked up.
  • Those files are uploaded as extra manifests in the same scan (no separate Dashboard project), and Socket resolves the dependencies they declare, devDependencies included. The installed package's own name and version is not recorded as a dependency.
  • With --reach, the same find_files result feeds the manifest upload for reachability, so the extra manifests go there too. The flag passes nothing to the reachability engine itself.
  • vendor, .venv and the other default exclusions are not affected; --include-dirs covers those.

Checked on 2.13.0 against a small npm project whose dependency's postinstall installs an extra package into node_modules: with the flag, the scan gained 504 packages from the installed packages' devDependencies (15 with CVE alerts) and still didn't report the postinstalled package. A CycloneDX SBOM generated from the installed tree (@cyclonedx/cyclonedx-npm 7.0.1) and saved as installed.cdx.json in the scan root was uploaded with the lockfile, and the package showed up with its alerts.

Changes:

Testing: uv run pytest -q -o addopts= (1001 passed), ruff check ., uv lock --locked --offline, hatch build and twine check pass. socketcli --help renders the new text.

Public Changelog

Documented what --include-module-folders does: it adds every supported manifest under node_modules (and bower_components, jspm_packages), at any depth, to the scan and 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.

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.
@lelia lelia changed the title Document what --include-module-folders does Document what --include-module-folders does Nov 20, 2026
@lelia lelia self-assigned this Nov 20, 2026
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.

This branch was successfully deployed

1 active deployment
socket-firewall — 2cad7fab Deployed Nov 20, 2026 by dc-larsen via python-sfw-smoke-enterprise #662
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants