Reports¶
The report package renders a FindingSet as a formal Markdown report. The
output is written for pandoc, so one source converts to
DOCX, PDF, or HTML.
import "github.com/plexusone/findingspec/report"
md, err := report.MarkdownString(set, report.Options{
Title: "Payments Service Security Review",
Authors: []string{"Application Security"},
Date: "2026-10-23",
Classification: "Confidential",
Summary: "No critical findings. Two high findings affect token handling.",
Scope: "Manual review of the payments service at v2.4.0.",
Sections: []report.Section{
{Title: "Recommended Remediation Order", Body: "1. Token audience\n2. Webhook signatures"},
},
})
if err != nil {
return err
}
if err := os.WriteFile("report.md", []byte(md), 0o600); err != nil {
return err
}
report.WriteMarkdown(w, set, opts) writes to any io.Writer instead.
Convert with pandoc:
pandoc report.md -o report.docx --reference-doc=template.docx
pandoc report.md -o report.pdf --pdf-engine=xelatex -V geometry:margin=1in
A --reference-doc supplies Word styles (fonts, heading colours, table style,
headers and footers), so branding stays out of the renderer.
Report structure¶
- Metadata block: title, subtitle, authors, date, classification, and a table of contents request.
- Distribution notice: the classification and the audience.
- Executive Summary:
Options.Summary, total/open/actionable counts, a severity table listing every level, and tables by repository and domain when the findings span more than one. - Scope and Methodology:
Options.Scope. - Author sections:
Options.Sections, in order. - Findings Overview: one row per finding, most severe first, with each ID linking to its detailed section.
- Detailed Findings: grouped by severity. Each finding has an attribute table (severity, status, confidence, category, CWE/CVE, CVSS, exploitability, reachability, package, fix version, component, location, source, effort) followed by description, root cause, impact, attack scenario, call paths, compensating controls, evidence, affected code, remediation, verification, related findings, and references. Empty parts are left out.
- Appendices:
Options.Appendices, in order.
Audience¶
| Content | AudienceShareable (default) |
AudienceInternal |
|---|---|---|
| Description, root cause, impact, remediation | Yes | Yes |
| Exploit preconditions, scenario, reproduction | No | Yes |
| Evidence summaries and payloads | No | Yes |
Code snippets (Location.Snippet) |
No | Yes |
| Remediation agent prompts | Only with IncludeAgentPrompts |
Only with IncludeAgentPrompts |
Use the shareable audience for anything that leaves the team that owns the
findings. Projecting a security.Vulnerability with ToFinding copies its
Exploit into the finding's detail, so the audience setting, not the data, is
what keeps attack steps out of a shared report.
Text handling¶
Finding fields such as titles, descriptions, and root-cause summaries are
treated as plain text. Characters that Markdown or pandoc would interpret
(*, _, <, @, $, |, and others) are escaped, and lines that would
start a list, heading, or block quote are guarded. Matched backtick spans such
as `ParseToken` are kept as inline code, since authors commonly mark
identifiers that way.
Options.Summary, Options.Scope, and each Section.Body are Markdown and
are written as given.
Non-security domains¶
Security findings render their VulnerabilityDetail (root cause, impact,
CVSS, package, reachability, and so on). Findings in other domains render from
the canonical Finding fields, with RuleID shown as the rule.