Skip to content

Commit d799825

Browse files
Merge pull request #1 from CompleteTech-LLC/docs/readme-banners
Restyle README after php2shell-check with banner and report screenshots
2 parents 5ad74ec + e6d6c01 commit d799825

6 files changed

Lines changed: 59 additions & 96 deletions

File tree

‎BRAND_ASSETS.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
# Brand assets
22

33
CompleteTech LLC names, logos, and brand assets included in this repository,
4-
including `assets/logo.png`, are not licensed under the AGPL-3.0 or a commercial
5-
code license.
4+
including `assets/logo.png` and the images in `docs/images/`, are not licensed
5+
under the AGPL-3.0 or a commercial code license.
66

77
They remain trademarks, service marks, or brand assets of CompleteTech LLC and
88
may not be reused in a way that suggests endorsement, affiliation, sponsorship,

‎README.md‎

Lines changed: 57 additions & 94 deletions
Original file line numberDiff line numberDiff line change
@@ -1,134 +1,97 @@
11
<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%">
33
</p>
44

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>
611

7-
[![Tests](https://github.com/CompleteTech-LLC/node2shell-check/actions/workflows/tests.yml/badge.svg)](https://github.com/CompleteTech-LLC/node2shell-check/actions/workflows/tests.yml)
8-
![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-1E3A8A)
9-
![No dependencies](https://img.shields.io/badge/dependencies-none-067647)
10-
[![AGPL-3.0 or commercial license](https://img.shields.io/badge/license-AGPL--3.0%20%7C%20commercial-64748B)](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>
1116

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+
---
1518

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".
1920

2021
## Quick start
2122

2223
```sh
2324
git clone https://github.com/CompleteTech-LLC/node2shell-check.git
2425
cd node2shell-check
2526

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
3129
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.
3730
python node2shell_check.py --input websites.txt --format html --output websites-report.html
3831
```
3932

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.
4349

4450
## What the results mean
4551

4652
| Status | Meaning |
4753
| --- | --- |
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. |
5258

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 |
8362

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**.
8564

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.
9067
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
10069

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.
10273

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.
10875

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.
11277

113-
## Documentation and development
78+
## Documentation
11479

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
11782
- [Contributing](CONTRIBUTING.md) · [Security policy](SECURITY.md)
118-
- [Repository instructions for agents](AGENTS.md)
11983

12084
```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
12386
```
12487

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.
12789

12890
## License
12991

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).
13393

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>

‎docs/images/banner.png‎

222 KB
Loading

‎docs/images/report-dark.png‎

328 KB
Loading

‎docs/images/report-light.png‎

302 KB
Loading

‎docs/images/social-preview.png‎

378 KB
Loading

0 commit comments

Comments
 (0)