88import argparse
99import base64
1010import csv
11+ import hashlib
1112import io
1213import html
1314import json
2829from urllib .request import HTTPRedirectHandler , ProxyHandler , Request , build_opener
2930
3031TOOL_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 ()
3136BOT = "Node2ShellChecker"
3237REDIRECTS = {301 , 302 , 303 , 307 , 308 }
3338MAX_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):
800813then 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.
802815Vendor 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
808822def 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
823841def save_report (path , rows , * , force = False , ** options ):
0 commit comments