|
| 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). |
0 commit comments