|
| 1 | +# Optional Node.js family metadata |
| 2 | + |
| 3 | +These tools support the one-repository-per-advisory roadmap. They do not combine |
| 4 | +advisory scanners or change the Node2Shell CLI, schema 1 inventory, assessment |
| 5 | +thresholds, dates or existing collector. Both collectors remain independently |
| 6 | +usable by copying their own file. Use an explicitly trusted Node binary; this |
| 7 | +project cannot attest that binary's vendor provenance or isolate hostile preload |
| 8 | +hooks outside the collector. No application module is imported. |
| 9 | + |
| 10 | +## Runtime and builtin capability report |
| 11 | + |
| 12 | +```sh |
| 13 | +node tools/collect-node-capabilities.cjs > node-capabilities.json |
| 14 | +``` |
| 15 | + |
| 16 | +The distinct `node-capabilities/1` report contains an allowlist of Node/platform/ |
| 17 | +architecture metadata, OpenSSL/c-ares/Brotli/V8 version strings, TLS build feature |
| 18 | +booleans, and builtin API availability for HTTP/2, TLS, DNS, Permission Model, |
| 19 | +startup snapshots, SEA and Brotli. SEA's `isSea()` is the only queried builtin |
| 20 | +function; other APIs are inspected by type and never invoked as tests. Unsupported |
| 21 | +modules/API state remain null/unknown. The collector does not create sockets or |
| 22 | +servers, resolve DNS, perform TLS, decompress data, build/load snapshots, enumerate |
| 23 | +SEA assets, run shell commands, read application files or collect environment, |
| 24 | +arguments, hostnames, credentials or application data. Build source remains unknown. |
| 25 | + |
| 26 | +API availability is **not** application use, configuration, attacker-controlled |
| 27 | +input, permission enforcement, mitigation, reachability or an advisory precondition. |
| 28 | +The Permission API field does not attest active policy or its permissions. The |
| 29 | +snapshot field does not identify the snapshot a process was started with. Library |
| 30 | +versions do not establish Node cherry-pick/backport patch state. Runtime identity |
| 31 | +is limited to the explicitly invoked collector process; it may differ from a |
| 32 | +service's process. Reports keep application_use/reachability unknown and local |
| 33 | +exploitability not_tested. Never automatically map a capability boolean to a |
| 34 | +precondition in any of the advisory-specific checkers. |
| 35 | + |
| 36 | +The old `collect-runtime.cjs` still emits exactly its schema 1 input accepted by |
| 37 | +`node2shell_check.py --inventory`. The optional report is a separate evidence |
| 38 | +artifact and is **not** accepted as that inventory. Continue using the old |
| 39 | +collector for Node2Shell assessment; retain the new artifact for explicit |
| 40 | +per-advisory review. No public schema or CLI migration is required. |
| 41 | + |
| 42 | +Primary API references reviewed 2026-10-25: |
| 43 | +[process.features](https://nodejs.org/api/process.html#processfeatures), |
| 44 | +[Permission Model](https://nodejs.org/api/permissions.html), |
| 45 | +[SEA isSea](https://nodejs.org/api/single-executable-applications.html#seaissea), |
| 46 | +[HTTP/2](https://nodejs.org/api/http2.html), [TLS](https://nodejs.org/api/tls.html), |
| 47 | +[DNS](https://nodejs.org/api/dns.html), [startup snapshots](https://nodejs.org/api/v8.html#startup-snapshot-api), |
| 48 | +[Brotli](https://nodejs.org/api/zlib.html). |
| 49 | + |
| 50 | +## Existing npm build context |
| 51 | + |
| 52 | +```sh |
| 53 | +python tools/inspect-node-build-context.py --input docs/examples/node-package-lock.json |
| 54 | +python tools/inspect-node-build-context.py --help |
| 55 | +``` |
| 56 | + |
| 57 | +Read an explicitly supplied package.json or npm lock v1/v2/v3 as JSON only. |
| 58 | +`node-build-context/1` retains bounded `engines.node` declarations and relative |
| 59 | +package paths. Version 2/3 use the primary packages map; version 1 traverses its |
| 60 | +legacy dependency tree. This is compatibility/declaration context: even a plain |
| 61 | +exact `engines.node` value is not the runtime that is installed or deployed. The |
| 62 | +report always has an empty runtime_version, unknown runtime_state on observations, |
| 63 | +and exploitability not_tested. Missing declarations establish no absence. Conflicts |
| 64 | +at different package paths remain distinct; no range is solved into a runtime. |
| 65 | + |
| 66 | +A narrow semver-range character vocabulary prevents arbitrary strings, URLs and |
| 67 | +credentials from being echoed as declarations; unsupported strings become empty |
| 68 | +unknown declarations. Registry URLs, resolved/integrity data, lifecycle scripts, |
| 69 | +package names outside relative metadata paths and application contents are not |
| 70 | +emitted or executed. Package paths themselves can be private; keep reports local. |
| 71 | +No npm command, install, package load or network request occurs. These are metadata |
| 72 | +artifacts for human review, not compatible scanner inventories or patch verdicts. |
| 73 | + |
| 74 | +Limits: four MiB regular non-symlink input, supported lock versions only, depth 64, |
| 75 | +100,000 visited package records, 512-character relative package paths, 10,000 |
| 76 | +observations and 256-character declarations. Duplicate JSON keys, invalid encoding, |
| 77 | +malformed structures and limits fail with exit 2; interruption is 130 with no output |
| 78 | +retry. JSON is ASCII escaped for portable redirected streams. Stdout is the only |
| 79 | +output path; use shell redirection cautiously to avoid overwriting an input. |
| 80 | + |
| 81 | +Primary format sources: |
| 82 | +[npm package-lock](https://docs.npmjs.com/cli/v11/configuring-npm/package-lock-json/), |
| 83 | +[npm engines](https://docs.npmjs.com/cli/v11/configuring-npm/package-json/#engines). |
| 84 | + |
| 85 | +## Container and advisory integration |
| 86 | + |
| 87 | +The optional [OCI inventory](https://github.com/CompleTetech-Security/oci-runtime-inventory) |
| 88 | +reads existing image archives/SBOMs separately; it does not execute or pull images. |
| 89 | +Node package observations and unverified provenance can be exported to the existing |
| 90 | +Node2Shell inventory contract. A tag, manifest declaration or filesystem binary |
| 91 | +name never supplies an exact runtime. Consult the named advisory matrix and each |
| 92 | +checker's own embedded rules and precondition contract; none of these artifacts |
| 93 | +attest a deployed application. The standalone scanners require no shared collector, |
| 94 | +container tool, feed or installed runtime dependency for offline assessment. |
| 95 | + |
| 96 | +Validation includes existing classification/collector regressions, guarded |
| 97 | +synthetic Node VM fixtures that throw on sensitive property or active API access, |
| 98 | +missing-module uncertainty, a local builtin report, lock v1/v2/v3 declarations, |
| 99 | +malformed inputs, bounds and privacy. Hosted jobs explicitly install Node 24 so |
| 100 | +collector checks run; the Python checker itself remains standard-library-only. |
0 commit comments