|
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. 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 your 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 a pipeline should stop. |
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, conflicting, qualified, custom-built, pre-release, 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 ordinary `GET` requests with verified TLS, an honest User-Agent, bounded responses, and pacing. Redirects stay on the same host or its `www` counterpart. 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. It's free under [AGPL-3.0](LICENSE) for research, education, and open-source use. A commercial license is available for closed-source products and hosted services that don't publish their source; 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