mirror of
https://github.com/BaaRai/ARTEX.git
synced 2026-11-18 14:10:54 +08:00
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.
142 lines
4.6 KiB
Go
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
|
|
}
|