Skip to content

Commit 5ad74ec

Browse files
Build Node2Shell exposure checker and offline runtime assessment
Add dependency-free Python CLI, metadata-only Node collector, CSV/JSON/branded HTML reports, source-linked guidance, and 58 local-only behavior tests. Preserve uncertainty for hidden, conflicting, vendor, and future versions; never send exploit payloads or decode Brotli. Use upstream Node.js fixes 22.23.4, 24.22.1, and 26.12.1 with a 2026-10-23 rule snapshot. Adapt CompleteTech's php2shell-check reporting and licensing conventions.
1 parent cca67c2 commit 5ad74ec

21 files changed

Lines changed: 3059 additions & 1 deletion

‎.gitattributes‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
* text=auto
2+
*.py text eol=lf
3+
*.cjs text eol=lf
4+
*.md text eol=lf
5+
*.yml text eol=lf
6+
*.json text eol=lf
7+
*.html text eol=lf
8+
*.txt text eol=lf
9+
*.png binary
10+
*.jpg binary
11+
*.jpeg binary
12+
*.webp binary

‎.github/workflows/tests.yml‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
name: Tests
2+
3+
on:
4+
push:
5+
pull_request:
6+
workflow_dispatch:
7+
8+
permissions:
9+
contents: read
10+
11+
jobs:
12+
test:
13+
name: Python ${{ matrix.python }} on ${{ matrix.os }}
14+
runs-on: ${{ matrix.os }}
15+
timeout-minutes: 10
16+
strategy:
17+
fail-fast: false
18+
matrix:
19+
os: [ubuntu-latest, windows-latest]
20+
python: ['3.10', '3.14']
21+
steps:
22+
- name: Check out repository
23+
uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
24+
with:
25+
persist-credentials: false
26+
- name: Set up Python
27+
uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
28+
with:
29+
python-version: ${{ matrix.python }}
30+
- name: Run local-only tests
31+
run: python -m unittest -v
32+
- name: Check CLI help
33+
run: python node2shell_check.py --help

‎.gitignore‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
__pycache__/
2+
*.py[cod]
3+
.venv/
4+
venv/
5+
.DS_Store
6+
Thumbs.db
7+
websites.txt
8+
runtime.json
9+
inventory.json
10+
report.html
11+
results.csv
12+
results.json
13+
reports/
14+
inventories/
15+
*.partial

‎AGENTS.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# Repository instructions
2+
3+
Read [README.md](README.md), [CONTRIBUTING.md](CONTRIBUTING.md), and
4+
[SECURITY.md](SECURITY.md) before changing this project.
5+
6+
## Project map
7+
8+
- `node2shell_check.py`: standalone Python 3.10+ CLI, passive fetcher, offline
9+
version/inventory assessment, and CSV/JSON/HTML rendering.
10+
- `collect-runtime.cjs`: optional Node.js metadata collector; emits schema v1
11+
inventory without loading application code or decompressing data.
12+
- `test_*.py`: focused local-only behavior tests.
13+
- `docs/NODE2SHELL.md`: dated, source-linked classification methodology.
14+
- `docs/REFERENCE.md`: CLI, inventory, outputs, and network behavior.
15+
- `docs/example-report.html`: synthetic example; never replace with real data.
16+
- `.github/workflows/tests.yml`: Python checks on Linux and Windows.
17+
18+
## Implementation constraints
19+
20+
Keep the Python checker usable as one file without third-party runtime or test
21+
dependencies. Preserve verified TLS, robots policy, descriptive User-Agent,
22+
pacing, response-size bounds, conservative redirects, and no environment-proxy
23+
inheritance. Do not add payload probes, authentication bypasses, automatic
24+
retries around access restrictions, or external requests to offline modes.
25+
Editing code and running tests do not authorize scanning real websites.
26+
27+
Reported versions are evidence, not verified runtime state. Keep missing,
28+
conflicting, malformed, prerelease, vendor/custom-build, and uncovered-future
29+
cases uncertain. Preserve `unsupported_runtime` as an upgrade/review result.
30+
Never present `potentially_affected` as confirmed exploitability or
31+
`fixed_version_reported` as a safety guarantee. Exploitability remains
32+
`not_tested`. Framework hints and response Brotli encoding must not be converted
33+
into Node.js version or request-decoder exposure evidence.
34+
35+
Keep the collector limited to runtime/build metadata. Do not collect hostnames,
36+
environment variables, credentials, process arguments, or application data.
37+
It cannot attest vendor patch provenance; keep its default build source unknown.
38+
39+
Update the fix table and rule date only after verifying official sources. Update
40+
focused boundary tests and methodology together. Keep CLI, schema, README, and
41+
reference documentation aligned. Preserve valid completed-result output after
42+
interruptions and avoid silent overwriting of existing reports.
43+
44+
## Validation and delivery
45+
46+
```sh
47+
python -m unittest -v
48+
python node2shell_check.py --help
49+
git diff --check
50+
```
51+
52+
Use mocks, synthetic inventories, and loopback HTTP fixtures. Do not contact
53+
external targets in tests or add tests merely asserting prose. Check
54+
documentation commands against real help/source and verify referenced paths.
55+
56+
Use focused changes, preserve unrelated work, and keep real targets, inventories,
57+
reports, workbooks, and secrets out of commits. Verify hosted CI for the actual
58+
published commit when available; report local checks and hosted CI separately.
59+
Repository creation does not authorize publishing private assessment data.
60+
Follow [LICENSING.md](LICENSING.md) and [BRAND_ASSETS.md](BRAND_ASSETS.md).

‎BRAND_ASSETS.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Brand assets
2+
3+
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.
6+
7+
They remain trademarks, service marks, or brand assets of CompleteTech LLC and
8+
may not be reused in a way that suggests endorsement, affiliation, sponsorship,
9+
or ownership without written permission.
10+
11+
Use `--brand` and `--logo` to supply your organization's own identity in reports.

‎CHANGELOG.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Changelog
2+
3+
## 1.0.0 — 2026-10-23
4+
5+
- Added dependency-free Node2Shell (CVE-2026-111497) version assessment with
6+
branch-specific fixes for Node.js 22, 24, and 26.
7+
- Added offline reported-version and collector-inventory inputs, alongside
8+
conservative public website metadata checks.
9+
- Added an optional local runtime collector with limited metadata collection.
10+
- Added CSV, structured JSON, and branded offline HTML reports with explicit
11+
uncertainty, source provenance, and run-completeness information.
12+
- Added report overwrite protection, optional finding exit codes, local tests,
13+
cross-platform Python CI, and operational/reference documentation.
14+
- Adopted the CompleteTech LLC AGPL-3.0 / commercial licensing model used by
15+
php2shell-check.

‎CLAUDE.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Shared repository guidance
2+
3+
Read [AGENTS.md](AGENTS.md) for the project map, implementation constraints,
4+
validation commands, and delivery requirements. Keep shared policy there rather
5+
than duplicating it in this file.

‎CONTRIBUTING.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# Contributing
2+
3+
Open an issue for a bug or focused improvement, then submit a pull request.
4+
For a security flaw in this checker, follow [SECURITY.md](SECURITY.md).
5+
6+
## Local development
7+
8+
Python 3.10+ is sufficient for the checker and Python tests. There are no
9+
third-party Python runtime or test dependencies. The optional runtime collector
10+
uses Node.js when explicitly invoked.
11+
12+
```sh
13+
python -m unittest -v
14+
python node2shell_check.py --help
15+
git diff --check
16+
```
17+
18+
Keep the Python checker usable as one file. Preserve verified TLS, robots
19+
checks, descriptive User-Agent, pacing, bounded bodies and redirects, direct
20+
connections without environment-proxy inheritance, and explicit uncertainty.
21+
Do not add exploit payloads, compressed-body probes, authentication bypasses, or
22+
automatic retries around restrictions.
23+
24+
Assessment changes must cite official Node.js advisories and include focused
25+
branch-boundary and qualifier tests. Keep version provenance, vendor/custom
26+
build uncertainty, unsupported runtimes, and future branches distinct.
27+
`fixed_version_reported` does not mean independently verified patch state.
28+
Exploitability must remain `not_tested`.
29+
30+
Framework markers and Brotli response encoding are not Node.js version or
31+
decoder-exposure evidence. Keep offline version/inventory assessment free from
32+
network requests and process execution. Preserve the collector's limited scope:
33+
runtime metadata only, without environment variables, credentials, hostnames,
34+
or application data.
35+
36+
Use local fixtures and mocks for meaningful behavior tests. Automated tests must
37+
not scan external websites. Reduce real-world cases to synthetic examples
38+
without personal data, cookies, tokens, or private URLs. Do not add tests that
39+
only assert documentation wording.
40+
41+
Document CLI, schema, and output changes. Keep real lists, inventories, reports,
42+
and credentials out of commits. Follow [AGENTS.md](AGENTS.md) for repository work.
43+
44+
## Licensing of contributions
45+
46+
node2shell-check follows the AGPL-3.0 / commercial licensing model described in
47+
[LICENSING.md](LICENSING.md). By submitting a contribution, you confirm that you
48+
have the right to submit it. You license it to the public under AGPL-3.0 and
49+
grant CompleteTech LLC a perpetual, worldwide, royalty-free, irrevocable license
50+
to use, modify, sublicense, and distribute it under any license, including a
51+
commercial license. You keep the copyright in your contribution.

0 commit comments

Comments
 (0)