findingspec

type Confidence string

type Domain string

type Evidence struct {
	// Kind categorizes the evidence, e.g. "screenshot", "html", "log",
	// "trace", "http-response", "code".
	Kind string `json:"kind"`
	// Summary is a short human-readable description of the evidence.
	Summary string `json:"summary,omitempty"`
	// Data holds inline evidence content; binary content should be base64.
	Data string `json:"data,omitempty"`
	// URI points to externally-stored evidence when it is not inlined.
	URI string `json:"uri,omitempty"`
	// MediaType is the IANA media type of Data or the URI target, if known.
	MediaType string `json:"mediaType,omitempty"`
}

type Finding struct {
	// ID is a stable identifier for this finding, unique within its producer.
	ID string `json:"id"`
	// Domain is the broad problem space this finding belongs to.
	Domain Domain `json:"domain"`
	// Type is the finding class within the domain — the scanner or test kind,
	// e.g. "sast", "sca", "secret", "container", "wcag", "e2e", "apm", "cis".
	// Together with Domain it forms the two-level type taxonomy and, when set,
	// tells a consumer how to decode Detail.
	Type string `json:"type,omitempty"`
	// RuleID identifies the domain rule or check that produced the finding,
	// e.g. a CWE ID, a WCAG success criterion, or a lint rule name.
	RuleID string `json:"ruleId,omitempty"`
	// Title is a short human-readable summary.
	Title string `json:"title"`
	// Description explains the finding in detail.
	Description string `json:"description,omitempty"`
	// Severity is the impact of the finding on the shared severity scale.
	Severity Severity `json:"severity"`
	// Confidence expresses certainty that the finding is a true positive.
	Confidence Confidence `json:"confidence,omitempty"`
	// Status is the lifecycle state of the finding.
	Status Status `json:"status,omitempty"`
	// Source identifies the producing tool.
	Source Source `json:"source,omitempty"`
	// Location is where the finding was observed.
	Location *Location `json:"location,omitempty"`
	// Evidence holds supporting artifacts.
	Evidence []Evidence `json:"evidence,omitempty"`
	// Remediation describes how to fix the finding.
	Remediation *Remediation `json:"remediation,omitempty"`
	// References links to external material.
	References []Reference `json:"references,omitempty"`
	// Tags are free-form labels for filtering and grouping.
	Tags []string `json:"tags,omitempty"`
	// DetectedAt is when the finding was observed.
	DetectedAt *time.Time `json:"detectedAt,omitempty"`
	// Detail is the typed, per-type subsection carrying the domain- and
	// type-specific payload (e.g. package/CVE/CVSS for an SCA finding, or
	// detector/entropy for a secret). It is opaque at the core layer; decode it
	// with DetailAs once Type is known. Set it with SetDetail.
	Detail json.RawMessage `json:"detail,omitempty"`
}

type FindingSet struct {
	Findings []Finding `json:"findings"`
}

type Location struct {
	// Repo identifies the repository or workspace a finding belongs to, when
	// a producer scans more than one (e.g. a multi-repo sweep, or a monorepo
	// workspace) — a path, URL, or module name, at the producer's discretion.
	// Empty when a producer only ever scans a single, implicit repository.
	Repo string `json:"repo,omitempty"`
	// File is a repository-relative source path.
	File string `json:"file,omitempty"`
	// Line is a 1-indexed line number within File.
	Line int `json:"line,omitempty"`
	// Column is a 1-indexed column within Line.
	Column int `json:"column,omitempty"`
	// URL is the address of the page or endpoint where the finding was observed.
	URL string `json:"url,omitempty"`
	// Selector is a CSS or XPath selector identifying a DOM element.
	Selector string `json:"selector,omitempty"`
	// Component is a logical component, module, or capability name.
	Component string `json:"component,omitempty"`
	// Pointer is an RFC 6901 JSON Pointer identifying a node within a structured
	// document (JSON/YAML), e.g. "/servers/0/variables/apiKey/default" in an
	// OpenAPI document or "/item/2/request/header/1/value" in a Postman
	// collection. It is a stable, format-independent locator preferable to
	// Line/Column for structured files.
	Pointer string `json:"pointer,omitempty"`
	// DocFormat names the structured-document format the File and Pointer refer
	// to, when relevant, e.g. "openapi", "postman", "json", "yaml".
	DocFormat string `json:"docFormat,omitempty"`
	// Snippet is a short excerpt of the offending code or markup.
	Snippet string `json:"snippet,omitempty"`
}

type Reference struct {
	Title string `json:"title,omitempty"`
	URL   string `json:"url"`
}

type Remediation struct {
	// Summary is a concise statement of the fix.
	Summary string `json:"summary"`
	// Detail is an optional longer explanation.
	Detail string `json:"detail,omitempty"`
	// AgentPrompt is an instruction suitable for handing to an AI code builder
	// (e.g. "fix this without changing application behavior").
	AgentPrompt string `json:"agentPrompt,omitempty"`
	// Effort is a coarse estimate, e.g. "low", "medium", "high".
	Effort string `json:"effort,omitempty"`
	// References supports the remediation with external links.
	References []Reference `json:"references,omitempty"`
}

type Severity string

type Source struct {
	// Tool is the producer name, e.g. "govex", "agent-a11y", "w3pilot".
	Tool string `json:"tool"`
	// Version is the producer version, if known.
	Version string `json:"version,omitempty"`
	// RuleSet names the rule catalog or standard the producer applied, e.g.
	// "WCAG-2.2", "CWE", "OWASP-ASVS".
	RuleSet string `json:"ruleSet,omitempty"`
}

type Status string

type Summary struct {
	// Total is the number of findings.
	Total int `json:"total"`
	// Open is the number of findings whose status still needs attention.
	Open int `json:"open"`
	// Actionable is the number of findings whose severity is actionable
	// (i.e. not Informational).
	Actionable int `json:"actionable"`
	// BySeverity counts findings per severity.
	BySeverity map[Severity]int `json:"bySeverity,omitempty"`
	// ByDomain counts findings per domain (the finding "type").
	ByDomain map[Domain]int `json:"byDomain,omitempty"`
	// ByStatus counts findings per lifecycle status.
	ByStatus map[Status]int `json:"byStatus,omitempty"`
	// ByRepo counts findings per top-level location (Location.Repo).
	ByRepo map[string]int `json:"byRepo,omitempty"`
}