Publish every outcome in a repeatable report
Write complete CSV and JSON outputs without dropping failed or empty assessments.
Reports should preserve the assessment
Successful connections are only part of a scan. Refused, timed-out and failed probes also describe what was observed and where evidence remains incomplete. Keep all four states in the CSV and include each count in the summary, even when it is zero. The total must equal the sum of the state counts.
Validate every row and duplicate identity before opening output files. Otherwise a malformed late row can overwrite a useful prior report before the failure is discovered. This exercise requires validation-before-write, not a transactional commit across multiple files. A storage failure can still leave a partial output set and should be reported by the caller.
Determinism makes comparison useful
Canonicalize addresses through ProbeResult, sort by IP family, numeric address and port, and use a fixed CSV field order. Reversing input order should not change output bytes. Use csv.DictWriter rather than joining fields manually: diagnostic text may contain commas, quotes, Unicode or embedded newlines.
Open files with replacement mode. An empty successful assessment still writes the CSV header and zero-valued summary; retaining rows from a previous run would create a misleading result. Include a final newline in JSON for ordinary text-tool behavior.
The report records observations, not confirmed vulnerabilities or application health. It contains no credentials or network payloads. These same output principles support the capstone's fleet, exposure, maintenance and error reports.
import csv, io
buffer=io.StringIO(newline="")
writer=csv.DictWriter(buffer,fieldnames=["state","detail"])
writer.writeheader();writer.writerow({"state":"error","detail":"Café, 東京"})
print(buffer.getvalue())
Put it into practice.
Define write_scan_report(rows, output). Normalize/validate each row using the supplied ProbeResult contract; ignore extra fields and default detail to empty. Reject duplicate canonical address/port identities before writing. Sort by numeric IP family/address and port. Write UTF-8 probes.csv with columns address, port, state, elapsed_ms, detail, and summary.json with total plus open, refused, timed_out, error counts, including zeros. Return the summary. Use proper CSV escaping and stable bytes for equivalent row order. Replace files on successful reruns, including empty input. Preserve existing reports when validation fails; I/O failures propagate.
See an explained solution
import csv,json
from dataclasses import asdict
from ipaddress import ip_address
from pathlib import Path
from scan_rules import ProbeResult
def write_scan_report(rows, output):
prepared=[];seen=set()
for row in rows:
result=ProbeResult(row["address"],row["port"],row["state"],row["elapsed_ms"],row.get("detail",""))
key=(result.address,result.port)
if key in seen:raise ValueError("Duplicate endpoint")
seen.add(key);prepared.append(asdict(result))
prepared.sort(key=lambda row:(ip_address(row["address"]).version,int(ip_address(row["address"])),row["port"]))
summary={"total":len(prepared),**{state:sum(row["state"]==state for row in prepared) for state in ("open","refused","timed_out","error")}}
destination=Path(output);destination.mkdir(parents=True,exist_ok=True)
with (destination/"probes.csv").open("w",encoding="utf-8",newline="") as handle:
writer=csv.DictWriter(handle,fieldnames=["address","port","state","elapsed_ms","detail"]);writer.writeheader();writer.writerows(prepared)
(destination/"summary.json").write_text(json.dumps(summary,sort_keys=True)+"\n",encoding="utf-8")
return summary
if __name__ == "__main__":
print(write_scan_report([{"address":"192.0.2.10","port":443,"state":"open","elapsed_ms":3}], "reports"))
The report preserves every observation and makes totals reconcile. Stable serialization and replacement prevent stale rows from masquerading as current evidence.