Skip to content

Commit e5b19a3

Browse files
Restyle README after php2shell-check with banner and report screenshots
Adopt the php2shell-check README layout: banner, centered badges and tagline, light/dark report screenshots, status table with indicators, an IMPORTANT callout, and a logo footer. Banner and social preview were generated with Codex; report screenshots are of the synthetic example. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
1 parent 5ad74ec commit e5b19a3

6 files changed

Lines changed: 58 additions & 95 deletions

File tree

‎BRAND_ASSETS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
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
4+
including `assets/logo.png` and the images in `docs/images/`, are not licensed under the AGPL-3.0 or a commercial
55
code license.
66

77
They remain trademarks, service marks, or brand assets of CompleteTech LLC and

‎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. 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.
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, conflicting, qualified, custom-built, pre-release, 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 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.
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. 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).
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‎

306 KB
Loading

‎docs/images/report-light.png‎

286 KB
Loading

‎docs/images/social-preview.png‎

378 KB
Loading

0 commit comments

Comments
 (0)