|
1 | 1 | <p align="center"> |
2 | | - <a href="https://complete.tech"><img src="assets/logo.png" alt="CompleteTech LLC" width="160"></a> |
| 2 | + <img src="docs/images/banner.png" alt="node2shell-check by CompleteTech LLC" width="100%"> |
3 | 3 | </p> |
4 | 4 |
|
5 | | -# node2shell-check |
| 5 | +<p align="center"> |
| 6 | + <a href="https://github.com/CompleteTech-LLC/node2shell-check/actions/workflows/tests.yml"><img src="https://github.com/CompleteTech-LLC/node2shell-check/actions/workflows/tests.yml/badge.svg" alt="Tests"></a> |
| 7 | + <img src="https://img.shields.io/badge/python-3.10%2B-1E3A8A" alt="Python 3.10+"> |
| 8 | + <img src="https://img.shields.io/badge/dependencies-none-067647" alt="No dependencies"> |
| 9 | + <a href="LICENSING.md"><img src="https://img.shields.io/badge/license-AGPL--3.0%20%7C%20commercial-64748B" alt="AGPL-3.0 or commercial license"></a> |
| 10 | +</p> |
6 | 11 |
|
7 | | -[](https://github.com/CompleteTech-LLC/node2shell-check/actions/workflows/tests.yml) |
8 | | - |
9 | | - |
10 | | -[](LICENSING.md) |
| 12 | +<p align="center"> |
| 13 | + <b>Find Node.js runtimes and websites reporting a version affected by Node2Shell</b><br> |
| 14 | + CVE-2026-111497 · offline runtime assessment · passive, single-file, dependency-free |
| 15 | +</p> |
11 | 16 |
|
12 | | -**Node2Shell exposure triage for CVE-2026-111497.** Assess reported Node.js |
13 | | -versions, collect runtime metadata locally, or inspect ordinary public website |
14 | | -responses. Export CSV, JSON, or a branded offline HTML report. |
| 17 | +--- |
15 | 18 |
|
16 | | -Built on the approach used by [php2shell-check](https://github.com/CompleteTech-LLC/php2shell-check): |
17 | | -one Python file, no third-party dependencies, no exploit payloads, and explicit |
18 | | -uncertainty. Python 3.10+ runs the checker on Windows, macOS, and Linux. |
| 19 | +`node2shell-check` compares the Node.js version a runtime or website reports with the official upstream fix for each supported branch. Assess a version you already know, collect metadata inside a deployed service, or inspect a website's ordinary public response. It sends **no exploit payloads**, never decodes Brotli, and reports uncertainty honestly: a hidden, vendor-built, or conflicting version is `unknown`, never "safe". |
19 | 20 |
|
20 | 21 | ## Quick start |
21 | 22 |
|
22 | 23 | ```sh |
23 | 24 | git clone https://github.com/CompleteTech-LLC/node2shell-check.git |
24 | 25 | cd node2shell-check |
25 | 26 |
|
26 | | -# Assess a version you have obtained from the deployed runtime; no network calls. |
27 | | -python node2shell_check.py --node-version 24.22.0 |
28 | | - |
29 | | -# Collect metadata inside the actual service/container, then assess it offline. |
30 | | -node collect-runtime.cjs > runtime.json |
| 27 | +python node2shell_check.py --node-version 24.22.0 # offline, no network calls |
| 28 | +node collect-runtime.cjs > runtime.json # run inside the deployed service |
31 | 29 | python node2shell_check.py --inventory runtime.json --format html --output report.html |
32 | | - |
33 | | -# Inspect an authorized website's public response metadata. |
34 | | -python node2shell_check.py https://example.com --format json |
35 | | - |
36 | | -# Process a list of authorized websites. |
37 | 30 | python node2shell_check.py --input websites.txt --format html --output websites-report.html |
38 | 31 | ``` |
39 | 32 |
|
40 | | -The optional collector requires Node.js only when you run it. The Python checker |
41 | | -does not install packages, invoke Node.js, run your application, or decode Brotli. |
42 | | -Existing report files are preserved unless you pass `--force`. |
| 33 | +Python 3.10+ on Windows, macOS, or Linux. Nothing to install; use `python3` where `python` is not Python 3. Node.js is needed only to run the optional collector. |
| 34 | + |
| 35 | +## The report |
| 36 | + |
| 37 | +`--format html` produces a single offline, script-free file with a logo, summary tiles, every result with its evidence and next step, and the upstream fix table. It follows the reader's light or dark theme and prints cleanly. |
| 38 | + |
| 39 | +<p align="center"> |
| 40 | + <picture> |
| 41 | + <source media="(prefers-color-scheme: dark)" srcset="docs/images/report-dark.png"> |
| 42 | + <img src="docs/images/report-light.png" alt="Example Node2Shell exposure report with the CompleteTech LLC logo" width="900"> |
| 43 | + </picture> |
| 44 | +</p> |
| 45 | + |
| 46 | +<p align="center"><sub>Synthetic example built from reserved <code>example.*</code> domains and invented runtimes. <a href="docs/example-report.html">View the HTML</a>.</sub></p> |
| 47 | + |
| 48 | +Use `--logo path/to/logo.png` and `--brand "Your Company"` to brand it for your own organization. CSV and JSON remain available for spreadsheets and pipelines. `--fail-on-finding` exits 1 when any result is `potentially_affected` or `unsupported_runtime`; operational errors exit 2. |
43 | 49 |
|
44 | 50 | ## What the results mean |
45 | 51 |
|
46 | 52 | | Status | Meaning | |
47 | 53 | | --- | --- | |
48 | | -| `potentially_affected` | A plain Node.js version is below its supported branch's upstream fix. Verify the actual deployed build and prioritize remediation. | |
49 | | -| `fixed_version_reported` | A reported version meets the branch's fix threshold. This is not independent verification of installed patches. | |
50 | | -| `unsupported_runtime` | The reported version is on an older, unsupported upstream line. Verify vendor support and move to a supported, patched runtime. | |
51 | | -| `unknown` | Evidence is missing, conflicting, qualified, custom-built, prerelease, or outside this rule snapshot. | |
| 54 | +| 🔴 `potentially_affected` | A plain Node.js version below its branch's fix is reported. Verify the deployed build and prioritize remediation. | |
| 55 | +| 🟠 `unsupported_runtime` | The version is on an older, unsupported upstream line. Verify vendor support and move to a supported, patched runtime. | |
| 56 | +| 🟢 `fixed_version_reported` | The reported version meets the fix. Not independent verification of installed patches. | |
| 57 | +| ⚪ `unknown` | Version missing, malformed, conflicting, vendor-qualified, custom-built, pre-release, possibly backported, or outside this rule snapshot. | |
52 | 58 |
|
53 | | -| Node.js branch | Fixed release | |
54 | | -| --- | --- | |
55 | | -| 22.x | 22.23.4 | |
56 | | -| 24.x | 24.22.1 | |
57 | | -| 26.x | 26.12.1 | |
58 | | - |
59 | | -The [Node.js security advisory](https://nodejs.org/en/blog/vulnerability/october-2026-security-releases) |
60 | | -and release notes for [22.23.4](https://nodejs.org/en/blog/release/v22.23.4), |
61 | | -[24.22.1](https://nodejs.org/en/blog/release/v24.22.1), and |
62 | | -[26.12.1](https://nodejs.org/en/blog/release/v26.12.1) establish these fixes, |
63 | | -released October 21, 2026. The embedded rule snapshot is dated **2026-10-23**. |
64 | | - |
65 | | -**Every result keeps exploitability as `not_tested`.** The vulnerability involves |
66 | | -decoding attacker-controlled Brotli data; a runtime version alone cannot show |
67 | | -whether an application reaches that code path. See the |
68 | | -[assessment methodology](docs/NODE2SHELL.md). |
69 | | - |
70 | | -## Choose the evidence that answers your question |
71 | | - |
72 | | -- **Runtime inventory:** run the collector in each deployed runtime or container. |
73 | | - It records version/build metadata without hostnames, environment variables, |
74 | | - tokens, or application data. It cannot establish vendor patch provenance. |
75 | | -- **Known version:** use repeatable `--node-version` arguments for an offline |
76 | | - comparison. Record where your versions came from outside the report if needed. |
77 | | -- **Website metadata:** inspect an authorized URL with ordinary GET requests. |
78 | | - Hidden Node.js versions remain `unknown`. Express or Next.js hints never become |
79 | | - Node.js version evidence. Response compression does not prove request decoding. |
80 | | - |
81 | | -You can combine these input modes in one report. Each observation retains its |
82 | | -own evidence; an offline version is never silently attached to a website. |
| 59 | +| Node.js branch | 22.x | 24.x | 26.x | |
| 60 | +| --- | --- | --- | --- | |
| 61 | +| **Fixed in** | 22.23.4 | 24.22.1 | 26.12.1 | |
83 | 62 |
|
84 | | -## The report |
| 63 | +Thresholds come from the [Node.js October 2026 security releases](https://nodejs.org/en/blog/vulnerability/october-2026-security-releases) and the release notes for [22.23.4](https://nodejs.org/en/blog/release/v22.23.4), [24.22.1](https://nodejs.org/en/blog/release/v24.22.1), and [26.12.1](https://nodejs.org/en/blog/release/v26.12.1), released 2026-10-21. The embedded rule snapshot is dated **2026-10-23**. |
85 | 64 |
|
86 | | -`--format html` writes a self-contained, script-free report with summary counts, |
87 | | -assessment details, remediation guidance, and source links. It supports light |
88 | | -and dark themes and printing. The [example report](docs/example-report.html) |
89 | | -contains only synthetic observations. |
| 65 | +> [!IMPORTANT] |
| 66 | +> **Potential exposure is not confirmed exploitability.** Every result keeps exploitability `not_tested`. The vulnerability involves decoding attacker-controlled Brotli data, and a version alone cannot show whether an application reaches that code path. Treat every result as a prompt for an administrator to check. |
90 | 67 |
|
91 | | -```sh |
92 | | -python node2shell_check.py --node-version 22.23.3 --node-version 24.22.1 \ |
93 | | - --format html --output report.html --brand "Your Company" --logo your-logo.png |
94 | | -``` |
95 | | - |
96 | | -CSV supports spreadsheets; JSON preserves structured evidence and includes a |
97 | | -`complete` flag. Use `--fail-on-finding` in a pipeline when potentially affected |
98 | | -or unsupported runtimes should produce exit code 1. Operational failures use |
99 | | -exit code 2; interruption uses 130. See the [full reference](docs/REFERENCE.md). |
| 68 | +## How it works |
100 | 69 |
|
101 | | -## Website request boundaries |
| 70 | +- **Known version:** `--node-version` (repeatable) compares a version you obtained elsewhere. No network calls. |
| 71 | +- **Runtime inventory:** `collect-runtime.cjs` records version and build metadata from the Node.js binary that runs the service. It never loads application code, reads environment variables, decompresses data, or opens a connection, and it cannot attest vendor patch provenance. |
| 72 | +- **Website metadata:** reads `robots.txt`, then makes an ordinary `GET` request to the page if allowed, with verified TLS, an honest User-Agent, bounded responses, and pacing. Redirects stay on the same host or its `www` counterpart, and HTTPS downgrades stop. It fetches nothing else and sends no compressed bodies, credentials, or crafted requests. |
102 | 73 |
|
103 | | -The checker reads `robots.txt`, then the supplied page if allowed. It uses |
104 | | -verified TLS, a descriptive User-Agent, bounded response sizes, and request |
105 | | -pacing. Redirects are restricted to the same host or its `www` counterpart; |
106 | | -HTTPS downgrades stop. It sends no compressed bodies, exploit probes, credentials, |
107 | | -or automatic retries, and it does not fetch linked assets or decompress responses. |
| 74 | +Input modes can be combined in one report; each observation keeps its own evidence. Express or Next.js hints never become Node.js version evidence, and Brotli response compression does not prove request decoding. |
108 | 75 |
|
109 | | -Use it only for targets you are authorized to assess. Private/local addresses are |
110 | | -supported for authorized internal checks. This local CLI is not an arbitrary-URL |
111 | | -web scanning service. Proxy environment variables are ignored. |
| 76 | +Check only targets you are authorized to assess, and keep real target lists, inventories, and results out of version control. |
112 | 77 |
|
113 | | -## Documentation and development |
| 78 | +## Documentation |
114 | 79 |
|
115 | | -- [Assessment methodology and sources](docs/NODE2SHELL.md) |
116 | | -- [CLI, inventory, outputs, and request reference](docs/REFERENCE.md) |
| 80 | +- [Full reference](docs/REFERENCE.md): every CLI option, inventory field, output field, and request rule |
| 81 | +- [Assessment methodology](docs/NODE2SHELL.md): how each version is classified, with sources |
117 | 82 | - [Contributing](CONTRIBUTING.md) · [Security policy](SECURITY.md) |
118 | | -- [Repository instructions for agents](AGENTS.md) |
119 | 83 |
|
120 | 84 | ```sh |
121 | | -python -m unittest -v |
122 | | -python node2shell_check.py --help |
| 85 | +python -m unittest -v # local-only tests; no external websites are contacted |
123 | 86 | ``` |
124 | 87 |
|
125 | | -Tests use synthetic data, mocks, and loopback HTTP fixtures. They do not scan |
126 | | -external websites. |
| 88 | +For agents contributing to this repository, [AGENTS.md](AGENTS.md) contains the shared development instructions; [CLAUDE.md](CLAUDE.md) points Claude to them. |
127 | 89 |
|
128 | 90 | ## License |
129 | 91 |
|
130 | | -Available under [GNU AGPL-3.0](LICENSE) or a commercial license from CompleteTech |
131 | | -LLC; see [LICENSING.md](LICENSING.md). Brand assets have separate terms in |
132 | | -[BRAND_ASSETS.md](BRAND_ASSETS.md). |
| 92 | +Dual licensed: [AGPL-3.0](LICENSE), including commercial use that meets its terms, or a [commercial license](LICENSING.md#commercial-license) from CompleteTech LLC for closed-source products and services that don't fit the AGPL model. See [LICENSING.md](LICENSING.md) for details. The CompleteTech LLC name and logo are covered by neither license; see [BRAND_ASSETS.md](BRAND_ASSETS.md). |
133 | 93 |
|
134 | | -Built by [CompleteTech LLC](https://complete.tech) · Innovation at Every Integration |
| 94 | +<p align="center"> |
| 95 | + <a href="https://complete.tech"><img src="assets/logo.png" alt="CompleteTech LLC" width="160"></a><br> |
| 96 | + <sub>Built by <a href="https://complete.tech">CompleteTech LLC</a> · Innovation at Every Integration</sub> |
| 97 | +</p> |
0 commit comments