Add shareable score cards and embeddable grade badges

Agencies and small businesses share a result, not a JSON file. This adds two
SVG outputs rendered straight from a saved report: a 1200x630 score card sized
for link previews on social and chat, and a compact grade badge for a website
footer. Both are plain SVG with no new dependencies, and the report command now
takes --svg and --badge alongside --html.

Author: sanmaxdev

README.md

@@ -46,6 +46,13 @@ sentineldeck scan example.com --output reports/example.json
 sentineldeck report reports/example.json --html reports/example.html
 ```
 
+From a saved report you can also render a shareable SVG score card (sized for
+link previews) and a small embeddable grade badge for a site footer:
+
+```bash
+sentineldeck report reports/example.json --svg reports/example-card.svg --badge reports/example-badge.svg
+```
+
 The passive checks (DNS, HTTP, TLS, email) run concurrently, so a scan
 finishes close to the speed of the slowest single check. Use `--timeout` to
 bound how long the HTTP and TLS probes wait:

pyproject.toml

@@ -43,5 +43,6 @@ src = ["src", "tests"]
 select = ["E", "F", "I", "UP", "B"]
 
 [tool.ruff.lint.per-file-ignores]
-# The HTML report is a large inline template with long CSS declarations.
+# Report renderers are large inline templates with long markup/CSS lines.
 "src/sentineldeck/reporters/html_report.py" = ["E501"]
+"src/sentineldeck/reporters/badge.py" = ["E501"]

src/sentineldeck/cli.py

@@ -5,6 +5,7 @@
 import sys
 
 from sentineldeck import __version__
+from sentineldeck.reporters.badge import write_badge_svg, write_card_svg
 from sentineldeck.reporters.html_report import read_json_report, write_html_report
 from sentineldeck.reporters.json_report import write_json_report
 from sentineldeck.scanner import scan_domain
@@ -31,7 +32,9 @@ def build_parser() -> argparse.ArgumentParser:
 
     report = subparsers.add_parser("report", help="Render a saved JSON scan report.")
     report.add_argument("source", help="Path to a SentinelDeck JSON report.")
-    report.add_argument("--html", required=True, help="Write an HTML report to this path.")
+    report.add_argument("--html", help="Write a client-ready HTML report to this path.")
+    report.add_argument("--svg", help="Write a shareable SVG score card to this path.")
+    report.add_argument("--badge", help="Write an embeddable SVG grade badge to this path.")
     return parser
 
 
@@ -55,9 +58,16 @@ def main(argv: list[str] | None = None) -> int:
         return 0
 
     if args.command == "report":
+        if not (args.html or args.svg or args.badge):
+            print("error: choose at least one of --html, --svg, or --badge", file=sys.stderr)
+            return 2
         report = read_json_report(args.source)
-        path = write_html_report(report, args.html)
-        print(f"HTML report written: {path}")
+        if args.html:
+            print(f"HTML report written: {write_html_report(report, args.html)}")
+        if args.svg:
+            print(f"Share card written: {write_card_svg(report, args.svg)}")
+        if args.badge:
+            print(f"Badge written: {write_badge_svg(report, args.badge)}")
         return 0
 
     parser.print_help()

src/sentineldeck/reporters/badge.py

@@ -0,0 +1,126 @@
+"""Shareable SVG artifacts: an embeddable grade badge and a social share card.
+
+Small businesses and agencies share a result, not a JSON file. The badge is
+meant for a website footer ("scanned by SentinelDeck — Grade A"); the card is a
+1200x630 image sized for link previews on X, LinkedIn, and Slack.
+"""
+from __future__ import annotations
+
+from html import escape
+from pathlib import Path
+
+from sentineldeck.models import ScanReport
+
+GRADE_COLORS = {
+    "A": "#22c55e",
+    "B": "#84cc16",
+    "C": "#f59e0b",
+    "D": "#f97316",
+    "F": "#ef4444",
+}
+DEFAULT_GRADE_COLOR = "#64748b"
+SEVERITY_ORDER = ("critical", "high", "medium", "low", "info")
+
+
+def grade_color(grade: str) -> str:
+    return GRADE_COLORS.get(grade.upper(), DEFAULT_GRADE_COLOR)
+
+
+def _severity_counts(report: ScanReport) -> dict[str, int]:
+    counts = {severity: 0 for severity in SEVERITY_ORDER}
+    for finding in report.findings:
+        severity = finding.severity.lower()
+        counts[severity if severity in counts else "info"] += 1
+    return counts
+
+
+def _text_width(text: str, char_px: float) -> float:
+    # Rough average glyph width; good enough to keep a shields-style badge tidy.
+    return len(text) * char_px
+
+
+def render_badge_svg(report: ScanReport) -> str:
+    """A compact, shields-style badge: ``SentinelDeck | Grade A``."""
+    label = "SentinelDeck"
+    value = f"Grade {escape(report.grade)}"
+    color = grade_color(report.grade)
+
+    label_w = int(_text_width(label, 6.6)) + 16
+    value_w = int(_text_width(value, 6.6)) + 16
+    total_w = label_w + value_w
+    label_mid = label_w / 2
+    value_mid = label_w + value_w / 2
+
+    return f"""<svg xmlns="http://www.w3.org/2000/svg" width="{total_w}" height="20" role="img" aria-label="SentinelDeck grade {escape(report.grade)}">
+  <linearGradient id="s" x2="0" y2="100%">
+    <stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
+    <stop offset="1" stop-opacity=".1"/>
+  </linearGradient>
+  <rect rx="3" width="{total_w}" height="20" fill="#1f2937"/>
+  <rect rx="3" x="{label_w}" width="{value_w}" height="20" fill="{color}"/>
+  <rect rx="3" width="{total_w}" height="20" fill="url(#s)"/>
+  <g fill="#fff" text-anchor="middle" font-family="Verdana,DejaVu Sans,sans-serif" font-size="11">
+    <text x="{label_mid:.0f}" y="14">{escape(label)}</text>
+    <text x="{value_mid:.0f}" y="14" font-weight="bold">{value}</text>
+  </g>
+</svg>
+"""
+
+
+def render_card_svg(report: ScanReport) -> str:
+    """A 1200x630 social share card summarising the scan."""
+    counts = _severity_counts(report)
+    color = grade_color(report.grade)
+    target = escape(report.target)
+    high_total = counts["critical"] + counts["high"]
+
+    stats = [
+        ("Risk score", f"{report.risk_score}/100"),
+        ("Findings", str(len(report.findings))),
+        ("High / Critical", str(high_total)),
+        ("Medium", str(counts["medium"])),
+    ]
+    stat_cells = "".join(
+        f"""
+      <g transform="translate({80 + i * 270},430)">
+        <rect width="240" height="120" rx="18" fill="#101c2f" stroke="#1e3a5f"/>
+        <text x="24" y="46" fill="#9fb3c8" font-size="20" font-family="Inter,sans-serif">{escape(label)}</text>
+        <text x="24" y="92" fill="#edf5ff" font-size="40" font-weight="700" font-family="Inter,sans-serif">{escape(value)}</text>
+      </g>"""
+        for i, (label, value) in enumerate(stats)
+    )
+
+    return f"""<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="630" viewBox="0 0 1200 630" role="img" aria-label="SentinelDeck report for {target}">
+  <defs>
+    <radialGradient id="bg" cx="20%" cy="0%" r="90%">
+      <stop offset="0" stop-color="#12345c"/>
+      <stop offset="0.45" stop-color="#08111f"/>
+    </radialGradient>
+  </defs>
+  <rect width="1200" height="630" fill="url(#bg)"/>
+  <text x="80" y="110" fill="#38bdf8" font-size="22" letter-spacing="4" font-family="Inter,sans-serif" font-weight="700">SENTINELDECK SECURITY REPORT</text>
+  <text x="80" y="200" fill="#edf5ff" font-size="72" font-weight="800" font-family="Inter,sans-serif">{target}</text>
+  <text x="80" y="250" fill="#9fb3c8" font-size="24" font-family="Inter,sans-serif">Passive attack-surface posture</text>
+  <g transform="translate(940,90)">
+    <circle cx="90" cy="90" r="90" fill="#101c2f" stroke="{color}" stroke-width="8"/>
+    <text x="90" y="80" fill="{color}" font-size="96" font-weight="800" text-anchor="middle" font-family="Inter,sans-serif">{escape(report.grade)}</text>
+    <text x="90" y="135" fill="#9fb3c8" font-size="22" text-anchor="middle" font-family="Inter,sans-serif">Grade</text>
+  </g>
+  {stat_cells}
+  <text x="80" y="600" fill="#64748b" font-size="20" font-family="Inter,sans-serif">Generated by SentinelDeck — passive attack-surface visibility for small businesses.</text>
+</svg>
+"""
+
+
+def write_badge_svg(report: ScanReport, output: str | Path) -> Path:
+    path = Path(output)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(render_badge_svg(report), encoding="utf-8")
+    return path
+
+
+def write_card_svg(report: ScanReport, output: str | Path) -> Path:
+    path = Path(output)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(render_card_svg(report), encoding="utf-8")
+    return path

tests/test_badge.py

@@ -0,0 +1,63 @@
+from sentineldeck.models import Finding, ScanReport
+from sentineldeck.reporters.badge import (
+    grade_color,
+    render_badge_svg,
+    render_card_svg,
+    write_badge_svg,
+    write_card_svg,
+)
+
+
+def sample_report(grade="C", score=42) -> ScanReport:
+    return ScanReport(
+        target="example.com",
+        generated_at="2026-06-24T21:00:00+00:00",
+        risk_score=score,
+        grade=grade,
+        checks={},
+        findings=[
+            Finding("a", "High issue", "high", "d", "r"),
+            Finding("b", "Medium issue", "medium", "d", "r"),
+        ],
+    )
+
+
+def test_grade_color_maps_known_grades():
+    assert grade_color("A") == "#22c55e"
+    assert grade_color("F") == "#ef4444"
+    assert grade_color("?") == "#64748b"
+
+
+def test_render_badge_includes_grade_and_color():
+    svg = render_badge_svg(sample_report(grade="A"))
+
+    assert svg.startswith("<svg")
+    assert "Grade A" in svg
+    assert "#22c55e" in svg
+
+
+def test_render_card_includes_summary_fields():
+    svg = render_card_svg(sample_report(grade="C", score=42))
+
+    assert "example.com" in svg
+    assert "42/100" in svg
+    assert ">C<" in svg
+    assert "High / Critical" in svg
+
+
+def test_render_card_escapes_target():
+    report = sample_report()
+    report.target = "<script>alert(1)</script>"
+
+    svg = render_card_svg(report)
+
+    assert "<script>alert(1)</script>" not in svg
+    assert "&lt;script&gt;" in svg
+
+
+def test_write_helpers_create_files(tmp_path):
+    badge = write_badge_svg(sample_report(), tmp_path / "out" / "badge.svg")
+    card = write_card_svg(sample_report(), tmp_path / "out" / "card.svg")
+
+    assert badge.exists() and card.exists()
+    assert badge.read_text(encoding="utf-8").startswith("<svg")

tests/test_cli_report.py

@@ -22,3 +22,38 @@ def test_cli_report_writes_html_from_json_report(tmp_path):
     assert exit_code == 0
     assert output.exists()
     assert "Test finding" in output.read_text(encoding="utf-8")
+
+
+def _write_sample_report(tmp_path):
+    report = ScanReport(
+        target="example.com",
+        generated_at="2026-06-24T21:00:00+00:00",
+        risk_score=12,
+        grade="A",
+        checks={},
+        findings=[Finding("x", "Test finding", "low", "Description", "Fix it")],
+    )
+    source = tmp_path / "scan.json"
+    source.write_text(json.dumps(report.to_dict()), encoding="utf-8")
+    return source
+
+
+def test_cli_report_writes_svg_card_and_badge(tmp_path):
+    source = _write_sample_report(tmp_path)
+    card = tmp_path / "card.svg"
+    badge = tmp_path / "badge.svg"
+
+    exit_code = main(["report", str(source), "--svg", str(card), "--badge", str(badge)])
+
+    assert exit_code == 0
+    assert card.read_text(encoding="utf-8").startswith("<svg")
+    assert badge.read_text(encoding="utf-8").startswith("<svg")
+
+
+def test_cli_report_requires_an_output(tmp_path, capsys):
+    source = _write_sample_report(tmp_path)
+
+    exit_code = main(["report", str(source)])
+
+    assert exit_code == 2
+    assert "at least one" in capsys.readouterr().err