Skip to content

Commit ad1ac3b

Browse files
Preserve executable provenance and completeness in every report format (#27)
1 parent 019b7b3 commit ad1ac3b

4 files changed

Lines changed: 127 additions & 12 deletions

File tree

‎README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -100,6 +100,9 @@ Dual licensed: [AGPL-3.0](LICENSE), including commercial use that meets its term
100100

101101
An interruption after a complete report is published preserves that report and exits 130.
102102
CSV rejects NUL characters before writing a report.
103+
Report schema `1.1` records the executable SHA-256 and explicit
104+
run completeness in JSON, CSV and HTML. Empty CSV reports contain a summary row;
105+
existing observation columns and inventory schema `1` remain compatible.
103106

104107
Optional release tooling: [offline TUF bundle verification](tools/signed_rules/README.md)
105108
uses separate optional dependencies and an explicitly provisioned public trust root.

‎docs/REFERENCE.md‎

Lines changed: 21 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -133,6 +133,19 @@ fields. Array values are represented as readable text. Strings that could become
133133
spreadsheet formulas are prefixed with an apostrophe. Progress and diagnostic
134134
messages go to stderr, leaving stdout available for data.
135135

136+
Report schema `1.1` preserves every existing result-column position
137+
and appends `tool`, `tool_version`, `tool_sha256`, `report_schema_version`,
138+
`generated_at`, `complete`, and `record_type`. `complete` is lowercase `true` or
139+
`false`; `record_type=result` identifies an observation. Empty runs have one
140+
`record_type=summary` row carrying build identity, rule date, completeness and
141+
`not_tested`, with no fabricated target. Consumers must distinguish summaries
142+
from observations. An interrupted zero-result CSV is therefore self-describing.
143+
The classifier's `tool_version` remains `1.0.0` for existing named-adapter
144+
compatibility; the additive report schema and exact executable digest identify
145+
this changed export. Existing bridge profile `node2shell-v1` still accepts its
146+
JSON; retain the original report for the new top-level provenance fields, which
147+
that older converter does not project. Classification thresholds are unchanged.
148+
136149
### JSON
137150

138151
JSON is an object with these top-level fields:
@@ -141,6 +154,8 @@ JSON is an object with these top-level fields:
141154
| --- | --- |
142155
| `tool` | Checker name. |
143156
| `tool_version` | Checker version used for the run. |
157+
| `tool_sha256` | SHA-256 of this standalone executable's exact bytes, captured at startup. Not a publisher signature. |
158+
| `report_schema_version` | Additive output contract, currently `1.1`; inventory schema remains `1`. |
144159
| `rules_as_of` | Date of the embedded assessment rules. |
145160
| `generated_at` | Report generation timestamp. |
146161
| `complete` | Whether all requested observations completed. Inspect individual operational outcomes as well. |
@@ -157,7 +172,10 @@ does not update its rules.
157172

158173
HTML is a single offline report with an embedded local logo, summary counts,
159174
assessment details, remediation guidance, fixed-version thresholds, source links,
160-
and run-completeness information. It supports dark/light themes and printing.
175+
and run-completeness information. Its footer identifies the tool version, report
176+
schema and executable SHA-256 even for empty reports. Observation `checked_at`,
177+
report `generated_at`, and rules verification date retain distinct meanings.
178+
It supports dark/light themes and printing.
161179
Dynamic text is escaped; the document contains no scripts or remotely loaded
162180
assets. The checked website URLs are evidence, not resources fetched by the
163181
report.
@@ -176,8 +194,8 @@ files cannot be used as the output destination, including with `--force`.
176194
The checker writes the report after the input loop or a handled keyboard
177195
interruption. Abrupt termination, process crashes, or power loss before that
178196
point can prevent report creation. It does not implement incremental checkpoints
179-
or automatic resume. CSV does not have a run-completeness envelope; retain the
180-
exit status/stderr or use JSON/HTML when that distinction matters.
197+
or automatic resume. CSV now carries run completeness on every result or empty
198+
summary row; retain the exit status/stderr as separate operational evidence.
181199

182200
## Requests made in website mode
183201

‎node2shell_check.py‎

Lines changed: 27 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@
88
import argparse
99
import base64
1010
import csv
11+
import hashlib
1112
import io
1213
import html
1314
import json
@@ -28,6 +29,10 @@
2829
from urllib.request import HTTPRedirectHandler, ProxyHandler, Request, build_opener
2930

3031
TOOL_VERSION = "1.0.0"
32+
REPORT_SCHEMA_VERSION = "1.1"
33+
# Capture the distributed executable's byte identity at module load, before a
34+
# later report could accidentally identify a changed on-disk file instead.
35+
TOOL_SHA256 = hashlib.sha256(Path(__file__).read_bytes()).hexdigest()
3136
BOT = "Node2ShellChecker"
3237
REDIRECTS = {301, 302, 303, 307, 308}
3338
MAX_BODY = 2 * 1024 * 1024
@@ -747,11 +752,19 @@ def logo_data_uri(path) -> str:
747752
return f"data:{mime};base64,{base64.b64encode(data).decode('ascii')}"
748753

749754

750-
def render_html(rows, *, logo=DEFAULT_LOGO, brand="CompleteTech LLC", generated_at=None, complete=True) -> str:
755+
def report_metadata(complete, generated_at=None):
756+
return {"tool": "node2shell-check", "tool_version": TOOL_VERSION,
757+
"tool_sha256": TOOL_SHA256, "report_schema_version": REPORT_SCHEMA_VERSION,
758+
"generated_at": generated_at or datetime.now(timezone.utc).isoformat(),
759+
"complete": complete}
760+
761+
762+
def render_html(rows, *, logo=DEFAULT_LOGO, brand="CompleteTech LLC", generated_at=None, complete=True, metadata=None) -> str:
751763
def esc(value):
752764
return html.escape("" if value is None else str(value), quote=True)
753765

754-
generated_at = generated_at or datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M UTC")
766+
metadata = metadata or report_metadata(complete, generated_at)
767+
generated_at = metadata["generated_at"]
755768
rows = sorted(rows, key=lambda row: STATUS_ORDER.get(row.get("node2shell_status"), 2))
756769
counts = {key: sum(row.get("node2shell_status") == key for row in rows) for key in STATUS_ORDER}
757770
tiles = [("", len(rows), "Inputs assessed"), ("bad", counts["potentially_affected"], "Potentially affected"),
@@ -771,7 +784,7 @@ def esc(value):
771784
f"<td>{esc(row.get('source'))}<br>{esc(row.get('status'))}</td>"
772785
f"<td>{esc(row.get('http_status') if row.get('http_status') is not None else row.get('fetch_status', '—'))}</td>"
773786
f"<td class='notes'><p>{esc(row.get('node2shell_recommendation'))}</p>"
774-
f"<details><summary>Evidence and limitations</summary><ul>{detail_html}</ul></details></td></tr>"
787+
f"<details><summary>Evidence and limitations</summary><p>Observed: {esc(row.get('checked_at'))}</p><ul>{detail_html}</ul></details></td></tr>"
775788
)
776789
fixes = "".join(f"<tr><td>{major}.x</td><td><code>{'.'.join(map(str, version))}</code></td></tr>" for major, version in NODE2SHELL_FIXES.items())
777790
logo_uri = logo_data_uri(logo)
@@ -800,24 +813,29 @@ def esc(value):
800813
then collect metadata again. An updated package lock or a patched workstation does not update a running server.</p>
801814
<p>Review incoming Brotli request parsers, responses fetched from untrusted services, and direct Brotli decompression calls.
802815
Vendor and custom builds require vendor evidence. The Brotli version string alone cannot establish patch status because fixes may be backported.</p>
803-
<footer>{esc(brand)} · node2shell-check {TOOL_VERSION} · {sources}</footer>
816+
<footer>{esc(brand)} · node2shell-check {TOOL_VERSION} · report schema {REPORT_SCHEMA_VERSION}<br>
817+
Executable SHA-256: <code>{esc(metadata['tool_sha256'])}</code> · Report complete: {str(complete).lower()}<br>{sources}</footer>
804818
</main></body></html>
805819
"""
806820

807821

808822
def write_report(output, rows, *, format="csv", logo=DEFAULT_LOGO, brand="CompleteTech LLC", complete=True):
823+
metadata = report_metadata(complete)
809824
if format == "csv":
810-
writer = csv.DictWriter(output, fieldnames=list(Result.__dataclass_fields__))
825+
writer = csv.DictWriter(output, fieldnames=[*Result.__dataclass_fields__, *metadata, "record_type"])
811826
writer.writeheader()
827+
csv_metadata = {**metadata, "complete": str(complete).lower()}
812828
for row in rows:
813-
writer.writerow({key: csv_safe(value) for key, value in row.items()})
829+
writer.writerow({key: csv_safe(value) for key, value in {**row, **csv_metadata, "record_type": "result"}.items()})
830+
if not rows:
831+
writer.writerow({**csv_metadata, "record_type": "summary", "node2shell_rules_as_of": NODE2SHELL_RULES_DATE,
832+
"node2shell_exploitability": "not_tested"})
814833
elif format == "json":
815-
json.dump({"tool": "node2shell-check", "tool_version": TOOL_VERSION, "rules_as_of": NODE2SHELL_RULES_DATE,
816-
"generated_at": datetime.now(timezone.utc).isoformat(), "complete": complete, "results": rows},
834+
json.dump({**metadata, "rules_as_of": NODE2SHELL_RULES_DATE, "results": rows},
817835
output, ensure_ascii=False, indent=2)
818836
output.write("\n")
819837
else:
820-
output.write(render_html(rows, logo=logo, brand=brand, complete=complete))
838+
output.write(render_html(rows, logo=logo, brand=brand, complete=complete, metadata=metadata))
821839

822840

823841
def save_report(path, rows, *, force=False, **options):

‎test_report_provenance.py‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
"""Portable evidence identity/completeness; synthetic rows and offline only."""
2+
import contextlib
3+
import csv
4+
from dataclasses import asdict
5+
import hashlib
6+
import io
7+
import json
8+
from pathlib import Path
9+
import subprocess
10+
import sys
11+
import tempfile
12+
import unittest
13+
from unittest import mock
14+
import node2shell_check as c
15+
16+
17+
class ProvenanceTests(unittest.TestCase):
18+
def render(self, rows, fmt, complete):
19+
stream = io.StringIO(newline="")
20+
c.write_report(stream, rows, format=fmt, complete=complete, logo=None)
21+
return stream.getvalue()
22+
23+
def test_all_formats_keep_executable_identity_and_independent_dates(self):
24+
row = asdict(c.Result("synthetic-runtime", source="version", checked_at="2026-10-25T12:00:00+00:00"))
25+
expected = hashlib.sha256(Path(c.__file__).read_bytes()).hexdigest()
26+
for complete in (False, True):
27+
data = json.loads(self.render([row], "json", complete))
28+
self.assertEqual(expected, data["tool_sha256"])
29+
self.assertEqual(c.TOOL_VERSION, data["tool_version"])
30+
self.assertEqual("1.1", data["report_schema_version"])
31+
self.assertEqual(complete, data["complete"])
32+
self.assertEqual(row["checked_at"], data["results"][0]["checked_at"])
33+
self.assertEqual(c.NODE2SHELL_RULES_DATE, data["rules_as_of"])
34+
csv_data = list(csv.DictReader(io.StringIO(self.render([row], "csv", complete))))[0]
35+
for key in ("tool", "tool_version", "tool_sha256", "report_schema_version"):
36+
self.assertEqual(data[key], csv_data[key])
37+
self.assertEqual(str(complete).lower(), csv_data["complete"])
38+
self.assertEqual(row["checked_at"], csv_data["checked_at"])
39+
self.assertEqual(c.NODE2SHELL_RULES_DATE, csv_data["node2shell_rules_as_of"])
40+
text = self.render([row], "html", complete)
41+
self.assertIn(expected, text)
42+
self.assertIn("Report complete: " + str(complete).lower(), text)
43+
44+
def test_empty_csv_has_explicit_summary_and_preserves_existing_column_positions(self):
45+
for complete in (False, True):
46+
reader = csv.DictReader(io.StringIO(self.render([], "csv", complete)))
47+
self.assertEqual(list(c.Result.__dataclass_fields__), reader.fieldnames[:len(c.Result.__dataclass_fields__)])
48+
rows = list(reader); self.assertEqual(1, len(rows))
49+
self.assertEqual("summary", rows[0]["record_type"])
50+
self.assertEqual(str(complete).lower(), rows[0]["complete"])
51+
self.assertEqual("", rows[0]["input_url"])
52+
self.assertEqual("not_tested", rows[0]["node2shell_exploitability"])
53+
self.assertEqual(c.TOOL_SHA256, rows[0]["tool_sha256"])
54+
55+
def test_interrupted_csv_is_self_describing_with_zero_or_one_completed_row(self):
56+
row = c.Result("https://example.test/", status="no_evidence", fetch_status="ok")
57+
for effects, kind in [([KeyboardInterrupt()], "summary"), ([row, KeyboardInterrupt()], "result")]:
58+
with mock.patch.object(c.Checker, "check", side_effect=effects), mock.patch("socket.socket", side_effect=AssertionError("offline fixture")):
59+
with contextlib.redirect_stdout(io.StringIO()) as out, contextlib.redirect_stderr(io.StringIO()):
60+
code = c.main(["https://example.test/", "https://other.example/", "--format", "csv"])
61+
self.assertEqual(130, code)
62+
rows = list(csv.DictReader(io.StringIO(out.getvalue())))
63+
self.assertEqual(1, len(rows)); self.assertEqual("false", rows[0]["complete"])
64+
self.assertEqual(kind, rows[0]["record_type"])
65+
66+
def test_copied_single_file_identifies_its_own_bytes(self):
67+
with tempfile.TemporaryDirectory() as directory:
68+
path = Path(directory) / "standalone.py"
69+
path.write_bytes(Path(c.__file__).read_bytes())
70+
result = subprocess.run([sys.executable, str(path), "--node-version", "24.22.1", "--format", "json"], capture_output=True, text=True)
71+
self.assertEqual(0, result.returncode, result.stderr)
72+
self.assertEqual(hashlib.sha256(path.read_bytes()).hexdigest(), json.loads(result.stdout)["tool_sha256"])
73+
74+
75+
if __name__ == "__main__":
76+
unittest.main()

0 commit comments

Comments
 (0)