#!/usr/bin/env python3
"""
Render scan reports from update.json using Reports/email_html.jinja2,
full_vulnerable_reports.jinja2, and email_body.jinja2 (short client email).
Filename stem: {TargetNameSlug}_{YYYY-MM-DD} using JSON keys target_name,
client_name, or project_name when set; otherwise derived from the URL host.
Dependencies:
pip install jinja2
pip install playwright && playwright install chromium # for --pdf / --send-email
Environment (optional):
SCAN_REPORT_CTA_URL, SCAN_REPORT_CTA_LABEL, SCAN_REPORT_CTA_LEDE
SCAN_REPORT_SIGNOFF_NAME, SCAN_REPORT_SIGNOFF_EMAIL
SCAN_REPORT_EMAIL_TO (default jaco@overdrive.co.za), SCAN_REPORT_SMTP_FROM
Bcc on the first mail: jaco@overdrive.co.za. After that send succeeds, a second
mail (To jaco only) goes with the full HTML report attached.
SCAN_REPORT_EMAIL_SUBJECT (override auto subject for first mail)
SCAN_REPORT_FULL_EMAIL_SUBJECT (override subject for full-report follow-up)
SCAN_REPORT_SMTP_HOST, SCAN_REPORT_SMTP_PORT (465 or 587),
SCAN_REPORT_SMTP_USER, SCAN_REPORT_SMTP_PASSWORD
Generic fallbacks (e.g. appnotify): SMTP_HOST, SMTP_PORT, SMTP_USER,
SMTP_PASSWORD, SMTP_FROM — used when SCAN_REPORT_* is unset.
Optional: place KEY=VAL pairs in `.env` next to this script (loaded if not
already in the process environment). Keep `.env` out of git.
"""
from __future__ import annotations
import argparse
import html
import json
import os
import re
import smtplib
from datetime import datetime, timezone
from email.message import EmailMessage
from pathlib import Path
from urllib.parse import urlparse
from load_env import load_env_files, log_smtp_config, mail_from_header
from report_branding import report_logo_context
try:
from jinja2 import Environment, FileSystemLoader, select_autoescape
except ImportError as e: # pragma: no cover
raise SystemExit(
"Missing dependency: jinja2. Install with: pip install jinja2"
) from e
# Internal copy address (Bcc on summary mail; To on follow-up full report).
REPORT_EMAIL_JACO = "jaco@overdrive.co.za"
REPORT_EMAIL_BCC = REPORT_EMAIL_JACO
OPS_ALERT_EMAIL = os.environ.get("SCAN_OPS_ALERT_EMAIL", REPORT_EMAIL_JACO)
REPORT_BRAND_NAME = os.environ.get("SCAN_REPORT_BRAND_NAME", "Silicon Overdrive")
def report_brand_name() -> str:
return (os.environ.get("SCAN_REPORT_BRAND_NAME") or REPORT_BRAND_NAME).strip() or "Silicon Overdrive"
SEVERITY_ORDER = ("critical", "high", "medium", "low", "info")
SEVERITY_RANK = {s: i for i, s in enumerate(SEVERITY_ORDER)}
PILL_CLASS = {
"critical": "crit",
"high": "high",
"medium": "med",
"low": "low",
"info": "info",
}
EMAIL_BADGE = {
"critical": ("#fbe9e7", "#8b1a1a"),
"high": ("#fdecdb", "#c2410c"),
"medium": ("#fbf2cf", "#a16207"),
"low": ("#e0e7ff", "#1d4ed8"),
"info": ("#e8eaef", "#475569"),
}
def _parse_iso(dt: str) -> datetime:
s = (dt or "").strip()
if s.endswith("Z"):
s = s[:-1] + "+00:00"
return datetime.fromisoformat(s)
def friendly_target_name(data: dict, target: str) -> str:
"""Display name: JSON target_name / client_name / project_name, else derived from host."""
for key in ("target_name", "client_name", "project_name"):
v = data.get(key)
if v and str(v).strip():
return str(v).strip()
h = host_display(target)
if not h:
return "Scan"
first = h.split(".")[0].replace("-", " ").replace("_", " ")
return first.title() if first else "Scan"
def slug_stem(name: str) -> str:
"""Filesystem-safe stem fragment from a display name (e.g. Shorts of Practise → Shorts_of_Practise)."""
s = re.sub(r"[^a-zA-Z0-9]+", "_", (name or "").strip()).strip("_")
return s or "Scan"
def file_stem_from_data(data: dict, scan_date: str) -> str:
"""{TargetNameSlug}_{YYYY-MM-DD} — starts with client/target name when set in JSON."""
target = str(data.get("target") or "")
display = friendly_target_name(data, target)
dt = _parse_iso(scan_date)
stamp = dt.strftime("%Y-%m-%d")
return f"{slug_stem(display)}_{stamp}"
def host_display(target: str) -> str:
p = urlparse((target or "").strip())
return re.sub(r"^www\.", "", p.hostname or p.netloc or target, flags=re.I)
def resolved_ip(findings: list, target: str) -> str:
for f in findings:
raw = f.get("raw") or {}
if f.get("tool") == "httpx" and raw.get("host_ip"):
return str(raw["host_ip"])
if f.get("tool") == "nmap" and raw.get("host"):
return str(raw["host"])
p = urlparse(target)
return p.hostname or "—"
def tools_line(findings: list) -> str:
tools = sorted({str(f.get("tool") or "?") for f in findings})
return " · ".join(tools)
def sort_findings(findings: list) -> list:
def key(f):
sev = (f.get("severity") or "info").lower()
return (SEVERITY_RANK.get(sev, 99), (f.get("title") or ""))
return sorted(findings, key=key)
def instance_count(f: dict) -> int:
raw = f.get("raw") or {}
if raw.get("count") is not None:
try:
return int(str(raw["count"]))
except ValueError:
pass
inst = raw.get("instances")
if isinstance(inst, list):
return len(inst)
return 1
def confidence_label(raw: dict) -> str:
c = str(raw.get("confidence", ""))
if c == "3":
return "High"
if c == "2":
return "Medium"
if c == "1":
return "Low"
return "—"
def difficulty_badge(raw: dict) -> tuple[str | None, str | None]:
sol = (raw.get("solution") or "").lower()
if any(x in sol for x in ("easy", "simple", "x-frame-options", "same-site")):
return ("easy", "Easy fix")
if any(x in sol for x in ("difficult", "complex", "hard to")):
return ("hard", "Hard fix")
if raw.get("solution"):
return ("mod", "Moderate fix")
return (None, None)
def wrap_plain_description(text: str) -> str:
t = (text or "").strip()
if not t:
return "(No description)
"
if "<" in t and ">" in t:
return t
return f"{html.escape(t)}
"
def evidence_blocks(f: dict) -> str:
raw = f.get("raw") or {}
parts: list[str] = []
inst = raw.get("instances")
if isinstance(inst, list) and inst:
for it in inst[:12]:
uri = html.escape(str(it.get("uri") or it.get("nodeName") or ""))
ev = it.get("evidence") or it.get("param") or ""
evs = html.escape(str(ev)[:2000])
parts.append(f'{uri}{evs}
')
if len(inst) > 12:
parts.append(f'… {len(inst) - 12} more instance(s)
')
elif f.get("tool") == "nuclei":
line = html.escape(json.dumps(raw, indent=2)[:4000])
parts.append(f'nuclei raw{line}
')
elif f.get("tool") == "nmap":
r = raw
line = f"{r.get('host')}:{r.get('port')}/{r.get('protocol')} {r.get('service')} {r.get('product') or ''}"
parts.append(f'{html.escape(line.strip())}
')
if not parts and f.get("endpoint"):
parts.append(f'{html.escape(str(f.get("endpoint")))}
')
if not parts:
return ""
return '' + "".join(parts) + "
"
def references_html(raw: dict) -> str:
ref = raw.get("reference") or ""
if not ref.strip():
return ""
# ZAP often wraps links in
if "
" in ref or " and split URLs
text = re.sub(r"]*>", "\n", ref, flags=re.I)
lines = [ln.strip() for ln in re.sub(r"<[^>]+>", "", text).splitlines() if ln.strip()]
if not lines:
return ""
items = "".join(f"{html.escape(ln)}" for ln in lines[:20])
return f''
def is_network_finding(f: dict) -> bool:
t = f.get("tool")
if t == "nmap":
return True
if t == "httpx":
return True
return False
def is_detail_finding(f: dict) -> bool:
if f.get("tool") == "nmap":
return False
if f.get("tool") == "httpx":
return False
if f.get("tool") == "zap" and (f.get("severity") or "").lower() == "info":
return False
return True
def is_info_zap(f: dict) -> bool:
return f.get("tool") == "zap" and (f.get("severity") or "").lower() == "info"
def build_detail_row(f: dict, display_id: str) -> dict:
raw = f.get("raw") or {}
sev = (f.get("severity") or "info").lower()
desc = f.get("description") or raw.get("desc") or f.get("title") or ""
sol = raw.get("solution") or ""
diff_c, diff_l = difficulty_badge(raw)
cweid = raw.get("cweid")
cwe = f"CVE-{cweid}" if cweid else ""
endpoint_line = f.get("endpoint") or ""
if not endpoint_line and isinstance(raw.get("instances"), list) and raw["instances"]:
endpoint_line = str(raw["instances"][0].get("uri") or "")
param_line = ""
if isinstance(raw.get("instances"), list) and raw["instances"]:
p0 = raw["instances"][0].get("param")
if p0 and len(str(p0)) < 200:
param_line = str(p0)
systemic = "Yes" if raw.get("systemic") else ("No" if raw.get("systemic") is False else "—")
return {
"display_id": display_id,
"title": f.get("title") or "Finding",
"severity_label": sev.title(),
"pill": PILL_CLASS.get(sev, "info"),
"diff_class": diff_c,
"diff_label": diff_l,
"tool": f.get("tool") or "?",
"cwe": cwe,
"confidence": confidence_label(raw),
"instances": instance_count(f),
"systemic": systemic,
"endpoint_line": endpoint_line,
"param_line": param_line,
"description_html": wrap_plain_description(str(desc)),
"evidence_html": evidence_blocks(f),
"solution_html": sol if sol else "",
"references_html": references_html(raw),
}
def next_display_id(sev: str, counters: dict) -> str:
counters[sev] = counters.get(sev, 0) + 1
prefix = {"critical": "C", "high": "H", "medium": "M", "low": "L", "info": "I"}.get(sev, "X")
return f"{prefix}-{counters[sev]:02d}"
def build_network_rows(findings: list) -> list[dict]:
rows = []
nf = [f for f in sort_findings(findings) if is_network_finding(f)]
for i, f in enumerate(nf, start=1):
raw = f.get("raw") or {}
if f.get("tool") == "nmap":
svc = str(raw.get("service") or "?")
detail = str(raw.get("product") or "") or str(f.get("description") or "")
ep = str(f.get("endpoint") or f"{raw.get('host')}:{raw.get('port')}")
rows.append(
{
"idx": f"N-{i:02d}",
"endpoint": ep,
"service": svc,
"detail": detail[:500],
}
)
else:
title = str(f.get("title") or "httpx")
loc = raw.get("location") or ""
tech = ", ".join(raw.get("tech") or [])[:200]
ep = str(f.get("endpoint") or raw.get("url") or "")
detail = " ".join(x for x in (loc, tech) if x)
rows.append(
{
"idx": f"N-{i:02d}",
"endpoint": ep,
"service": title,
"detail": detail[:500],
}
)
return rows
def build_info_zap_rows(findings: list, target: str) -> list[dict]:
rows = []
for i, f in enumerate([x for x in sort_findings(findings) if is_info_zap(x)], start=1):
raw = f.get("raw") or {}
aff = str(f.get("endpoint") or raw.get("alert") or host_display(target) or "—")
rows.append(
{
"idx": f"I-{i:02d}",
"title": str(f.get("title") or "Finding"),
"affected": aff[:300],
"instances": instance_count(f),
}
)
return rows
def collect_top_mediums(findings: list, limit: int = 5) -> list[dict]:
"""Short list for the email_body highlight box."""
rows: list[dict] = []
n = 0
for f in sort_findings(findings):
if (f.get("severity") or "").lower() != "medium":
continue
n += 1
rows.append({"row_id": f"M-{n:02d}", "title": str(f.get("title") or "")})
if len(rows) >= limit:
break
return rows
def hook_line(summary: dict) -> str:
c = int(summary.get("critical") or 0)
h = int(summary.get("high") or 0)
m = int(summary.get("medium") or 0)
if c or h:
return "Critical or high items need urgent review; see the attached PDF for detail."
if m:
return (
f"There are {m} medium-severity item(s)—often header or configuration fixes. "
"No critical or high issues in this run."
)
return "No critical, high, or medium issues in this run; remaining findings are low or informational."
def summary_email_text(summary: dict, total: int) -> str:
c, h, m, l, i = (
summary.get("critical", 0),
summary.get("high", 0),
summary.get("medium", 0),
summary.get("low", 0),
summary.get("info", 0),
)
parts = [
f"The latest scan identified {total} findings across the public-facing infrastructure."
]
if c or h:
parts.append(f"Critical: {c}, High: {h} — review urgently.")
elif m:
parts.append(
f"No critical or high-severity issues were observed in this run. "
f"{m} medium-severity item(s) should be scheduled for the next change window."
)
else:
parts.append("No critical, high, or medium-severity issues were observed in this run.")
parts.append(f"Low: {l}, Informational: {i}.")
return " ".join(parts)
def build_info_nuclei_rows(findings: list, limit: int = 20) -> list[dict]:
"""Tabloid PDF rows for informational Nuclei matches (template detections, headers, etc.)."""
rows = []
nuclei_info = [
f
for f in sort_findings(findings)
if f.get("tool") == "nuclei" and (f.get("severity") or "").lower() == "info"
]
for i, f in enumerate(nuclei_info[:limit], start=1):
ep = str(f.get("endpoint") or "")[:120]
rows.append(
{
"row_id": f"N-{i:02d}",
"title": str(f.get("title") or "Finding"),
"subline": ep or "—",
}
)
return rows
def info_rollups(findings: list, resolved: str) -> tuple[str, str]:
nmap = [f for f in findings if f.get("tool") == "nmap"]
httpx = [f for f in findings if f.get("tool") == "httpx"]
nuclei = [f for f in findings if f.get("tool") == "nuclei"]
zap_info = [f for f in findings if is_info_zap(f)]
ports = []
for f in nmap[:20]:
raw = f.get("raw") or {}
ports.append(f"{raw.get('service')}/{raw.get('port')}")
primary = (
f"{len(nmap)} network observation(s) on {resolved}"
+ (f": {', '.join(ports)}" if ports else "")
+ ("." if not httpx else f" plus httpx ({len(httpx)}).")
)
if nuclei:
primary += f" Nuclei: {len(nuclei)} detection(s)."
secondary = ""
if zap_info:
titles = [str(x.get("title") or "") for x in zap_info[:8]]
secondary = "Additional ZAP informational items: " + "; ".join(titles)
if len(zap_info) > 8:
secondary += f" … (+{len(zap_info) - 8} more)"
return primary, secondary
def extract_article_wrapper(detailed_html_path: Path) -> tuple[str, str]:
"""Return (prefix up to and including , closing suffix)."""
text = detailed_html_path.read_text(encoding="utf-8")
tag = ''
i0 = text.index(tag) + len(tag)
prefix = text[:i0]
suffix = "\n\n\n \n