generating-executive-summary

Generating Executive Summary

Overview

The vulnerability report is comprehensive — every finding, full detail, every reference. The C-level reader doesn't open it. They ask their security lead "what should I tell the board?" The security lead needs a one-page answer.

That one-page answer is the executive summary. It states the engagement's bottom line:

• A single risk score (0-100)
• Headline counts by severity
• Top-3 remediation priorities, each with rough effort + impact
• OWASP Top 10 coverage (where the work landed)
• Engagement scope and authorization summary (what was tested, under what authority, in what window)
• Next steps the customer's organization should take

The summary doesn't omit anything important; it just compresses. The vulnerability report remains the deep artifact for anyone who needs the technical detail.

This skill consumes the enriched findings JSONL (after OWASP mapping) + the OWASP coverage report + the ROE, computes the risk score, picks the top remediation priorities deterministically, and renders the document.

When the skill produces findings

Finding	Severity	Threshold	Affected control
Input findings file missing	CRITICAL	Source JSONL doesn't exist	(operational)
OWASP coverage report missing	HIGH	Coverage referenced but not present	(operational)
ROE missing	MEDIUM	Can still generate summary but lacks scope/authz context	(operational)
Exec summary written cleanly	INFO	Confirmation	(informational)
Risk score >75 (high engagement risk)	HIGH	Computed risk score elevated	(advisory)
Risk score >90 (critical engagement risk)	CRITICAL	Engagement exposed material risk; needs urgent action	(advisory)

Risk score (0-100) composition

The single risk score is the headline number on the exec summary. The composition is deterministic and documented:

risk = clamp(0, 100,
    20 * count(CRITICAL)
  + 10 * count(HIGH)
  +  3 * count(MEDIUM)
  +  1 * count(LOW)
  +  0 * count(INFO)
  +  5 * (count(distinct OWASP categories touched) - 5 if >5 else 0)
  - 10 * 1 if engagement was authorized cleanly and in-scope (governance bonus)
)

The first five terms weight by severity. The OWASP-coverage term adds 5 points per category beyond 5 (a broader-finding engagement implies broader risk surface). The governance bonus is a -10 adjustment when ROE was clean — explicit recognition that finding problems in a well-governed engagement is HEALTHIER than finding the same problems in a chaotic engagement.

Score interpretation:

Score	Reading
0-25	Low risk: clean engagement OR very narrow scope
26-50	Moderate risk: typical engagement with manageable findings
51-75	Elevated risk: significant findings, remediation planning required
76-90	High risk: material findings; executive attention warranted
91-100	Critical risk: urgent remediation required; consider treating as incident

Top-3 remediation priorities

The skill picks top-3 priorities deterministically by:

1. Severity (CRITICAL > HIGH > MEDIUM > LOW)
2. Reachability — findings affecting many targets weight higher
3. Tie-breaker: alphabetical by title for stable output

Each priority gets:

• A one-line headline
• Estimated effort (Hours / Days / Weeks)
• Estimated impact (Limited / Significant / Material)
• Pointer to the corresponding finding section in the vulnerability report

Effort + impact are heuristic estimates based on the source skill's category — operator can override via --priority-overrides for cases where the heuristic is wrong.

Prerequisites

• Python 3.9+
• Findings JSONL at engagement/findings/all-with-owasp.jsonl (output of mapping-findings-to-owasp-top10) OR an explicit --source FILE
• OWASP coverage report at engagement/reports/owasp-coverage.md (referenced; optional)
• ROE at engagement/roe.yaml (referenced for scope summary)

Instructions

Step 1 — Verify the inputs are present

ls engagements/acme-2026-q2/findings/all-with-owasp.jsonl
ls engagements/acme-2026-q2/reports/owasp-coverage.md
ls engagements/acme-2026-q2/roe.yaml

All three should exist for a complete summary. The skill works without the coverage report or ROE but the summary is less complete.

Step 2 — Generate the summary

python3 ./scripts/exec_summary.py engagements/acme-2026-q2/

Options:

Usage: exec_summary.py PATH [OPTIONS]

Options:
  --source FILE              Findings JSONL (default: PATH/findings/all-with-owasp.jsonl)
  --coverage FILE            OWASP coverage report (default: PATH/reports/owasp-coverage.md)
  --roe FILE                 ROE (default: PATH/roe.yaml)
  --summary-output FILE      Output path (default: PATH/reports/executive-summary.md)
  --output FILE              Operational findings output
  --format FMT               json | jsonl | markdown (default: markdown)
  --min-severity SEV         default info
  --priority-overrides FILE  YAML overriding the top-3 priorities

Step 3 — Review the risk score

If the score is in 76-100 range, the operator should sanity-check before delivering: did the underlying findings actually warrant the elevated reading, or did a few INFO-tagged findings get mis-categorized as HIGH?

Step 4 — Hand off

The exec summary is intended as a standalone artifact. Deliver to the customer's exec readout meeting, along with the full vulnerability report.

Examples

Example 1 — End-of-engagement summary

python3 ./scripts/exec_summary.py engagements/acme-2026-q2/

Example 2 — Board-ready summary (force-includes governance section)

python3 ./scripts/exec_summary.py engagements/acme-2026-q2/ \
    --summary-output engagements/acme-2026-q2/reports/board-summary.md

Example 3 — Override priorities

# priorities-override.yaml
- title: "Hardcoded AWS access key in source"
  effort: Hours
  impact: Material
  rationale: This is the single highest-priority remediation regardless of count.

python3 ./scripts/exec_summary.py engagements/acme-2026-q2/ \
    --priority-overrides priorities-override.yaml

Output

JSON / JSONL / Markdown per lib/report.py for operational findings. PRIMARY output: the executive-summary markdown document.

Operational Finding includes:

• id — exec::<issue>
• severity — varies
• category — executive-summary
• summary — what was generated
• evidence — risk score, finding count, top priorities, output path

Error Handling

• No findings source → CRITICAL operational finding, exits 1.
• Source JSONL unparseable → HIGH, exits 1.
• No findings at all → emits LOW operational finding noting the empty engagement; the document is generated but says so.
• Coverage report missing → MEDIUM, document is generated without the coverage-narrative section.
• ROE missing → MEDIUM, document is generated without the scope/authorization section.

Resources

• references/THEORY.md — Executive-summary writing as a technical-communication discipline, single-number risk scoring tradeoffs, why deterministic priority selection beats human-curated for reproducibility, how the score interpretation bands were chosen, comparison with CVSS / DREAD / STRIDE risk models
• references/PLAYBOOK.md — Per-audience customizations (board, C-suite, security leadership, customer auditor), summary length guidelines, common rewrite patterns, integration with the composing + mapping skills, post-delivery follow-up cadence