Files
ARTEX/report/report.go
T
Xiaobo a0adc209ad feat(report): surface finding proof strength in the report and the export
The task report and the findings export asserted every finding with no
qualification: nothing said how far exploitation actually reached (PoE level),
whether the claim was machine-verified (verification status and note), whether
counterevidence was recorded, or whether any traffic was bound. The web UI
badges all of it (VERIFICATION_META, the detail page), so the report — the
artifact a client actually reads — was the last surface still asserting bare
claims.

Render it from one place:

- report/quality.go (new): two constructors and two pure renderers, no I/O, no
  DB handle, so the block is unit-tested without a database.
- Both surfaces call the same helpers, which is the point: the task report and
  the per-finding export cannot drift apart the way duplicated formatting does.
- Missing is explicit: a finding node with no standalone row prints
  "not assessed (no finding record)" instead of an invented zero — the honest
  gap the existing coverage work (#207) also insists on.
- Labels match the shipped UI wording (Verification, Confidence rationale,
  Counterevidence) and states are humanised ("Not assessed", "False positive"),
  with an unrecognised value printed verbatim so a new state cannot silently
  vanish from a report.
- Bound-traffic count appears once per document: as a Proof bullet in the task
  report (it has no traffic section), and in the export only when nothing is
  bound — otherwise the traffic section already states it.
- The detailed report is capped at 8 KiB in the task report only, rune-safe, with
  the cap derived into the truncation message; the export is the canonical
  per-finding document and is never silently shortened.
- The export keeps its document structure: the single-finding document gets
  "## Detailed Report" (a section like its siblings), the multi-finding summary
  gets a bold label.

Read paths only: no change to the write side of poe_level or verification_status,
no schema change (all five columns already exist), no API/DTO change (the widened
FindingMeta stays internal to the report path, and the findings list keeps
selecting only what it renders). One extra task-scoped query on GET /api/report,
because findings bodies stay off the list path.

docs/vulnerability-traffic-evidence.md §Export describes the new Markdown.
2026-11-17 08:40:37 +08:00

142 lines
4.6 KiB
Go

// Package report renders a deliverable Markdown report from the exploration
// graph: confirmed findings (with severity/evidence) (docs §15 P5).
package report
import (
"encoding/json"
"fmt"
"sort"
"strings"
"time"
"github.com/Autumn-27/artex/db"
)
// Input bundles what the report needs.
type Input struct {
Title string
Goal string
GeneratedAt time.Time
AssetCounts map[string]int
Findings []*db.Node
Coverage *db.CoverageLedger // nil when the task's coverage feature is off
// Quality carries the standalone findings-row data (poe level, verification
// state, the two attestations, both evidence versions and the reporter-written
// body) keyed by finding node id, from the report's single quality lookup. The
// exploration node payload has none of it; without this map every finding would
// render as an unqualified claim.
//
// Three states, deliberately distinct: an empty but non-nil map means the task
// has no standalone rows (nothing was assessed); a nil map means the lookup
// failed, which says nothing about the findings themselves; an entry means the
// row exists. Collapsing failure into absence would turn a database error into a
// statement about the finding.
Quality map[int64]db.FindingQuality
}
// reportMaxGaps caps the coverage gap list of the report; the rest is counted.
const reportMaxGaps = 200
type findingView struct {
VulnClass string
Name string
Severity string
Summary string
PoC string
Q Quality // proof-strength fields grafted from the standalone row
}
func parseFinding(n *db.Node) findingView {
var p struct {
VulnClass string `json:"vulnclass"`
Name string `json:"name"`
Severity string `json:"severity"`
Summary string `json:"summary"`
Evidence struct {
PoC string `json:"poc"`
} `json:"evidence"`
}
_ = json.Unmarshal(n.Payload, &p)
return findingView{VulnClass: p.VulnClass, Name: p.Name, Severity: p.Severity, Summary: p.Summary, PoC: p.Evidence.PoC}
}
var sevRank = map[string]int{"critical": 0, "high": 1, "medium": 2, "low": 3, "": 4}
// Markdown renders the report.
func Markdown(in Input) string {
var b strings.Builder
fmt.Fprintf(&b, "# Penetration Test Report — %s\n\n", nz(in.Title, "Unnamed task"))
fmt.Fprintf(&b, "- **Task goal**: %s\n", nz(in.Goal, "(unspecified)"))
fmt.Fprintf(&b, "- **Generated at**: %s\n\n", in.GeneratedAt.Format("2006-01-02 15:04:05"))
// summary
fmt.Fprintf(&b, "## Summary\n\n")
fmt.Fprintf(&b, "- Confirmed findings: **%d**\n", len(in.Findings))
fmt.Fprintf(&b, "- Assets: ")
var types []string
for t := range in.AssetCounts {
types = append(types, t)
}
sort.Strings(types)
for i, t := range types {
if i > 0 {
b.WriteString(", ")
}
fmt.Fprintf(&b, "%s %d", t, in.AssetCounts[t])
}
b.WriteString("\n\n")
// findings
fmt.Fprintf(&b, "## Findings\n\n")
if len(in.Findings) == 0 {
b.WriteString("_No vulnerabilities confirmed this time._\n\n")
} else {
fs := make([]findingView, 0, len(in.Findings))
for _, n := range in.Findings {
v := parseFinding(n)
v.Q = qualityFromRows(n.ID, in.Quality)
fs = append(fs, v)
}
sort.SliceStable(fs, func(i, j int) bool { return sevRank[fs[i].Severity] < sevRank[fs[j].Severity] })
for i, f := range fs {
fmt.Fprintf(&b, "### %d. [%s] %s\n\n", i+1, strings.ToUpper(nz(f.Severity, "info")), nz(f.Name, nz(f.VulnClass, "Uncategorized")))
fmt.Fprintf(&b, "%s\n\n", nz(f.Summary, ""))
b.WriteString(qualityBullets(f.Q, true)) // honest proof strength, including its gaps
if f.PoC != "" {
fmt.Fprintf(&b, "**PoC / Evidence:**\n\n```\n%s\n```\n\n", f.PoC)
}
b.WriteString(qualityNarrative(f.Q)) // why it holds / what failed, only when written
// The same warning, from the same helper, that the findings export prints: a
// report written against older evidence is stale on both surfaces or on neither.
b.WriteString(staleReportNotice(f.Q.ReportStale()))
b.WriteString(detailedReport(f.Q.Report, "**Detailed report:**"))
}
}
if c := in.Coverage; c != nil {
fmt.Fprintf(&b, "## Coverage gaps\n\n")
if c.Completeness != nil {
fmt.Fprintf(&b, "- **Completeness**: %s. %s\n", c.Completeness.State, c.Completeness.Caveat)
}
fmt.Fprintf(&b, "- Ledger entries: %d, open gaps: %d\n", len(c.Entries), len(c.Gaps))
for i, g := range c.Gaps {
if i == reportMaxGaps {
fmt.Fprintf(&b, "- and %d more (see the coverage API)\n", len(c.Gaps)-reportMaxGaps)
break
}
fmt.Fprintf(&b, "- %s\n", g)
}
b.WriteString("\n")
}
return b.String()
}
func nz(s, d string) string {
if strings.TrimSpace(s) == "" {
return d
}
return s
}