Skip to content

Commit fee7830

Browse files
Collect optional Node capabilities and declared build context (#22)
* Collect optional Node builtin capabilities and declared npm build context * Reject dot-segment package identities in legacy npm metadata
1 parent bf48b9b commit fee7830

8 files changed

Lines changed: 336 additions & 0 deletions

File tree

‎.github/workflows/tests.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,10 @@ jobs:
2727
uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
2828
with:
2929
python-version: ${{ matrix.python }}
30+
- name: Set up Node for optional builtin metadata checks
31+
uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6
32+
with:
33+
node-version: '24'
3034
- name: Run local-only tests
3135
run: python -m unittest -v
3236
- name: Check CLI help

‎README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -100,3 +100,7 @@ Dual licensed: [AGPL-3.0](LICENSE), including commercial use that meets its term
100100

101101
An interruption after a complete report is published preserves that report and exits 130.
102102
CSV rejects NUL characters before writing a report.
103+
104+
Optional family metadata tools: [Node capability and build-context collection](docs/NODE_METADATA.md).
105+
These separate formats do not change the Node2Shell inventory schema or infer
106+
application exposure from available APIs, lockfile declarations or image tags.

‎docs/NODE_METADATA.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
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.

‎docs/examples/node-package-lock.json‎

Lines changed: 1 addition & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎test_build_context.py‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
from pathlib import Path
2+
import importlib.util
3+
import json
4+
import tempfile
5+
import unittest
6+
spec=importlib.util.spec_from_file_location('context',Path(__file__).parent/'tools/inspect-node-build-context.py')
7+
c=importlib.util.module_from_spec(spec);spec.loader.exec_module(c)
8+
9+
10+
class BuildContextTests(unittest.TestCase):
11+
def test_engine_declarations_are_not_runtime_versions(self):
12+
with tempfile.TemporaryDirectory() as directory:
13+
path=Path(directory)/'metadata.json'
14+
for data in ({'engines':{'node':'>=22 <27'},'scripts':{'postinstall':'NEVER-EXECUTE'},'resolved':'https://SECRET.invalid'},
15+
{'lockfileVersion':1,'dependencies':{'outer':{'engines':{'node':'>=22 <27'}}}},
16+
{'lockfileVersion':2,'packages':{'node_modules/outer':{'engines':{'node':'>=22 <27'}}}},
17+
{'lockfileVersion':3,'packages':{'node_modules/outer':{'engines':{'node':'>=22 <27'}}}}):
18+
path.write_text(json.dumps(data),encoding='utf-8');result=c.inspect(path)
19+
self.assertEqual('',result['runtime_version']);self.assertEqual('>=22 <27',result['observations'][0]['declared_node_range'])
20+
self.assertNotIn('SECRET',json.dumps(result));self.assertNotIn('NEVER-EXECUTE',json.dumps(result))
21+
path.write_text('{"engines":{"node":"https://SECRET.invalid"}}',encoding='utf-8')
22+
self.assertEqual('',c.inspect(path)['observations'][0]['declared_node_range'])
23+
24+
def test_malformed_bounds_paths_and_absence(self):
25+
with tempfile.TemporaryDirectory() as directory:
26+
path=Path(directory)/'metadata.json'
27+
for text in ('{"engines":{},"engines":{}}','{"lockfileVersion":true}','{"lockfileVersion":3,"packages":{"../outside":{}}}','{"engines":[]}'):
28+
path.write_text(text,encoding='utf-8')
29+
with self.assertRaises(ValueError):c.inspect(path)
30+
for name in ('.','..','@scope/.','@scope/..'):
31+
path.write_text(json.dumps(dict(lockfileVersion=1,dependencies={name:dict(engines=dict(node='>=22'))})),encoding='utf-8')
32+
with self.assertRaises(ValueError):c.inspect(path)
33+
path.write_text('{}',encoding='utf-8');self.assertEqual([],c.inspect(path)['observations'])
34+
path.write_bytes(b' '*(4*1024**2+1))
35+
with self.assertRaises(ValueError):c.inspect(path)
36+
37+
38+
if __name__=='__main__':unittest.main()

‎test_capabilities.py‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
"""Optional metadata collector guards. Builtin APIs are never exercised as probes."""
2+
import json
3+
from pathlib import Path
4+
import shutil
5+
import subprocess
6+
import unittest
7+
8+
9+
@unittest.skipUnless(shutil.which('node'),'Node.js unavailable')
10+
class CapabilityTests(unittest.TestCase):
11+
def test_builtin_metadata_without_sensitive_or_active_api_access(self):
12+
source=Path(__file__).with_name('tools').joinpath('collect-node-capabilities.cjs')
13+
# Run collector source in an isolated VM with an allowlisted builtin loader.
14+
# Throw on every sensitive property/active operation, rather than checking prose.
15+
harness=r'''
16+
const vm=require('node:vm'),fs=require('node:fs');
17+
const code=fs.readFileSync(process.argv[1],'utf8').replace(/^#!.*\n/,'');
18+
const forbidden=()=>{throw Error('active/sensitive access forbidden');};
19+
const noop=()=>{};
20+
const modules={
21+
'node:http2':{connect:forbidden,createServer:forbidden},
22+
'node:tls':{connect:forbidden,createServer:forbidden},
23+
'node:dns':{lookup:forbidden,resolve:forbidden},
24+
'node:v8':{startupSnapshot:{isBuildingSnapshot:forbidden}},
25+
'node:sea':{isSea:()=>false},
26+
'node:zlib':{brotliDecompress:forbidden,brotliDecompressSync:forbidden,createBrotliDecompress:forbidden},
27+
};
28+
let output='';const calls=[];
29+
const observed={versions:{node:'24.22.1',openssl:'3.5.0',PRIVATE:'SECRET'},platform:'synthetic',arch:'synthetic',features:{tls:true},permission:{has:forbidden},stdout:{write:value=>{output+=value;}},stderr:{write:forbidden}};
30+
for(const key of ['env','argv','execArgv','execPath','config']) Object.defineProperty(observed,key,{get:forbidden});
31+
vm.runInNewContext(code,{process:observed,require:name=>{calls.push(name);if(!(name in modules))throw Error('non-allowlisted import');return modules[name];}},{timeout:1000});
32+
if(calls.some(name=>!(name in modules)))throw Error('unexpected import');
33+
const data=JSON.parse(output);if(JSON.stringify(data).includes('SECRET'))throw Error('leaked');
34+
if(data.capabilities.http2_api_available!==true||data.capabilities.sea_is_sea!==false)throw Error('metadata mismatch');
35+
modules['node:sea']=null;modules['node:http2']=null;observed.permission=null;output='';
36+
vm.runInNewContext(code,{process:observed,require:name=>modules[name]},{timeout:1000});
37+
if(JSON.parse(output).capabilities.http2_api_available!==null)throw Error('absence must remain unknown');
38+
console.log('guarded metadata verified');
39+
'''
40+
result=subprocess.run([shutil.which('node'),'-e',harness,str(source)],capture_output=True,text=True,timeout=10)
41+
self.assertEqual(0,result.returncode,result.stderr)
42+
self.assertIn('guarded metadata verified',result.stdout)
43+
44+
def test_real_local_builtin_report_shape_and_separate_legacy_contract(self):
45+
root=Path(__file__).parent
46+
result=subprocess.run([shutil.which('node'),str(root/'tools/collect-node-capabilities.cjs')],capture_output=True,text=True,check=True,timeout=10)
47+
data=json.loads(result.stdout)
48+
self.assertEqual('node-capabilities/1',data['schema_version'])
49+
self.assertEqual('unknown',data['application_use']);self.assertEqual('unknown',data['reachability'])
50+
self.assertEqual('not_tested',data['exploitability']);self.assertEqual('unknown',data['build_source'])
51+
self.assertEqual({'openssl','cares','brotli','v8'},set(data['library_versions']))
52+
self.assertTrue(all(type(value) is bool or value is None for value in data['capabilities'].values()))
53+
legacy=subprocess.run([shutil.which('node'),str(root/'collect-runtime.cjs')],capture_output=True,text=True,check=True,timeout=10)
54+
self.assertEqual(1,json.loads(legacy.stdout)['schema_version'])
55+
56+
57+
if __name__=='__main__':unittest.main()
Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
#!/usr/bin/env node
2+
// SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-CompleteTech-Commercial
3+
// Copyright (c) 2026 CompleteTech LLC. See LICENSING.md.
4+
'use strict';
5+
// Explicit optional collector: builtins only, no app imports, arguments, environment,
6+
// hostnames, filesystem reads, sockets, DNS queries, shell, TLS connections or decoding.
7+
const versions = process.versions || {};
8+
if (!versions.node || versions.bun || versions.deno || versions.electron) {
9+
process.stderr.write('A standalone Node.js runtime is required.\n');
10+
process.exitCode = 2;
11+
} else {
12+
const builtin = name => { try { return require(name); } catch (_) { return null; } };
13+
const h2 = builtin('node:http2');
14+
const tls = builtin('node:tls');
15+
const dns = builtin('node:dns');
16+
const v8 = builtin('node:v8');
17+
const sea = builtin('node:sea');
18+
const zlib = builtin('node:zlib');
19+
const available = (object, names) => object ? names.every(name => typeof object[name] === 'function') : null;
20+
const features = process.features || {};
21+
const bool = value => typeof value === 'boolean' ? value : null;
22+
let isSea = null;
23+
try { if (sea && typeof sea.isSea === 'function') isSea = bool(sea.isSea()); } catch (_) { /* unknown */ }
24+
const report = {
25+
schema_version: 'node-capabilities/1',
26+
runtime: 'node',
27+
node_version: versions.node,
28+
build_source: 'unknown',
29+
platform: process.platform,
30+
architecture: process.arch,
31+
library_versions: Object.fromEntries(['openssl', 'cares', 'brotli', 'v8'].map(name => [name, typeof versions[name] === 'string' ? versions[name] : ''])),
32+
build_features: {tls: bool(features.tls), tls_alpn: bool(features.tls_alpn), tls_sni: bool(features.tls_sni), tls_ocsp: bool(features.tls_ocsp)},
33+
capabilities: {
34+
http2_api_available: available(h2, ['connect', 'createServer']),
35+
tls_api_available: available(tls, ['connect', 'createServer']),
36+
dns_api_available: available(dns, ['lookup', 'resolve']),
37+
permission_api_available: process.permission ? typeof process.permission.has === 'function' : null,
38+
startup_snapshot_api_available: v8 && v8.startupSnapshot ? available(v8.startupSnapshot, ['isBuildingSnapshot']) : null,
39+
sea_api_available: available(sea, ['isSea']),
40+
sea_is_sea: isSea,
41+
brotli_decoder_api_available: available(zlib, ['brotliDecompress', 'brotliDecompressSync', 'createBrotliDecompress']),
42+
},
43+
application_use: 'unknown',
44+
reachability: 'unknown',
45+
exploitability: 'not_tested',
46+
};
47+
process.stdout.write(JSON.stringify(report, null, 2) + '\n');
48+
}

0 commit comments

Comments
 (0)