diff --git a/CHANGELOG.md b/CHANGELOG.md index 165e42c..8a676e7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,15 @@ # Changelog +## 2.13.3 + +### Documentation + +- `--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.2 ### Added diff --git a/docs/cli-reference.md b/docs/cli-reference.md index 3a9ebab..c0d8cd6 100644 --- a/docs/cli-reference.md +++ b/docs/cli-reference.md @@ -324,7 +324,7 @@ docs.socket.dev use `SOCKET_SECURITY_API_KEY`. Either works. If both are set, | 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 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 f26b158..b9c8c26 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -232,6 +232,25 @@ by the comparison step that follows. - 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 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: + +```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 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/socketsecurity/config.py b/socketsecurity/config.py index a11ad25..b97a26f 100644 --- a/socketsecurity/config.py +++ b/socketsecurity/config.py @@ -1119,7 +1119,9 @@ 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 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 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" },