v2.3.4 Polish: visuals, donuts+heatmap, evidence CSV, README/CHANGELOG

[LuCamachoJr]

Pull Request — ForenSynth AI v2.3.4 (Polish)

Summary

This PR delivers v2.3.4 (Polish) — a visual and UX refresh, improved runtime stability, and evidence export enhancements for large detection hunts.

---

Changes

🖥️ Visuals

• Added 3× donut charts by MITRE ATT&CK phase (counts + percentages).
• Introduced “Unmapped / Multiple” segment for detections outside canonical phase mapping.
• Updated heatmap with caption, legend, and consistent blue palette for visual continuity.
• Added EventID footnote — quick reference for common IDs
  (e.g., 1 = Sysmon Process Create, 13 = Registry, 4104 = PowerShell ScriptBlock).

📊 Reporting

• New Evidence CSV export (IOCs + entity tables for pivoting).
• Displays actual OpenAI billing usage tokens (input/output) in the cost section for accuracy.
• Added micro-cap governor + “Selected micros: N / M” banner for bounded cost and predictable runtime.
• Inline billing summary with live token and dollar conversion.

📘 Documentation

• Updated README.md with new CLI flags and quick-start usage examples.
• Added CHANGELOG.md entry for v2.3.4.
• Added new run artifacts under examples/2025-10-26-polish-run/.

---

Motivation

Improves executive readability and visual appeal while stabilizing runtime and cost performance for large detection datasets (1k–3k+ detections).
Provides reproducible, pivotable evidence tables and cost transparency for DFIR analysts.

---

Run Example

python3 src/forensynth_ai_v2_3_4_polish.py \
  --two-pass --micro-workers 3 --rpm 90 --chunk-size 90 \
  --llm-timeout 60 --llm-retries 2 --stream off \
  --make-html --branding on --toc on --chart-style both \
  --max-input-tokens 60000 --integrity on \
  --limit-detections 1000 --sample-step 3

---

Testing

• Verified full HTML rendering with legend, captions, and donut charts.

• Token cost validated against OpenAI dashboard usage data.

• Confirmed CSV export and runtime stability with 1k – 2.7k detection samples.

• Tested both single- and two-pass summarization modes under --integrity on.

---

Notes

• Backward compatible: previous versions run unchanged unless new flags are used.

• No sensitive data in sample artifacts.

• CSV / JSON / HTML outputs stored under examples/2025-10-26-polish-run/.

---

CHANGELOG.md Snippet

[2.3.4] – 2025-10-26

Added

• Evidence CSV export with IOC + entity data.
• Three MITRE-phase donut charts (counts + percentages) with “Unmapped / Multiple” bucket.
• Heatmap caption + legend; EventID reference footnote.
• Actual OpenAI usage tokens and cost breakdown in report footer.

Changed

• Introduced micro-cap governor + Selected-micros banner to stabilize runtime and cost.
• Updated README with new flags / usage examples.
• Added new example artifacts and screenshots.

Fixed

• Minor HTML truncation and legend readability on low-DPI systems.

---

Artifacts

• 📄 examples/2025-11-2-polish-run/forensynth_summary_2025-11-02.md

• 🌐 examples/2025-11-2-polish-run/forensynth_report_2025-11-02.html

• 📊 examples/2025-11-2-polish-run/evidence_2025-11-02.csv

• 🧩 examples/2025-11-2-polish-run/detections.json

• 🖼️ Screenshots under samples/runs/

---