importer

type ArchiveFile struct {
	// The file's path inside the archive, cleaned. It is only a label: it is
	// never used to create a file.
	Name string
	// Uncompressed size as the archive declares it (the reader enforces the
	// limits on the real size).
	DeclaredSize int64
	// contains filtered or unexported fields
}

type ArchiveLimits struct {
	// Most files in the archive (directories are not counted).
	MaxEntries int
	// Largest uncompressed file.
	MaxEntryBytes int64
	// Largest sum of the uncompressed files.
	MaxTotalBytes int64
	// Largest ratio of uncompressed to compressed size of one file, checked
	// as the file is read, once it is past 1 MiB.
	MaxRatio int64
}

type Coverage struct {
	Mapped  int
	Ignored int
}

type Field struct {
	Path    string
	Target  string
	Ignored string
}

type Format string

type Issue struct {
	// 1-based line and column of the place in the input, when known.
	Line   int `json:"line,omitempty"`
	Column int `json:"column,omitempty"`

	// The record the problem is in: an XML element path or a JSON pointer.
	Path string `json:"path,omitempty"`

	Message string `json:"message"`
}

type Limits struct {
	// Largest input, in bytes.
	MaxInputBytes int64

	// Deepest nesting of XML elements or JSON objects and arrays.
	MaxDepth int

	// Most XML elements in one document.
	MaxElements int

	// Most attributes on one XML element.
	MaxAttributes int

	// Largest text of one XML element or one JSON string, in bytes. Longer
	// values are refused, not truncated, so a file that needs them is seen
	// as what it is.
	MaxTextBytes int

	// Most findings, assets, dependencies and VEX statements in one result.
	MaxFindings   int
	MaxAssets     int
	MaxComponents int
	MaxStatements int

	// Most distinct source field paths recorded for the coverage check.
	MaxObservedPaths int

	// Most problems reported in Result.Issues.
	MaxIssues int
}

type Options struct {
	// Format of the input. Empty: Detect decides from the first bytes.
	Format Format

	// Limits on the input; zero fields take DefaultLimits.
	Limits Limits

	// Report timestamp. Zero: the time of the parse (UTC).
	Now time.Time

	// metadata.id of the report (an import or scan session id).
	ReportID string

	// metadata.source_type of the report. Empty: "manual" (a file someone
	// imports).
	SourceType string

	// tool.name of the report. Empty: the format's tool (nessus, qualys,
	// cyclonedx, ...).
	ToolName string

	// Findings below this severity are counted in Stats.Skipped and left
	// out. Empty keeps every finding.
	MinSeverity ctis.Severity

	// The asset of records that name none (a DefectDojo finding without an
	// endpoint). Nil: an unclassified asset named after the tool.
	DefaultAsset *ctis.Asset

	// The repository a code report (SARIF, semgrep, betterleaks, a trivy
	// file-system scan) is filed on, with its branch and commit. It wins
	// over what the file names (a SARIF versionControlProvenance, a trivy
	// artifact). A receiver that knows the repository from a verified
	// identity (a CI workload token) sets it from there and never from the
	// file; the importer only records the file's claim.
	Repository string
	Branch     string
	CommitSHA  string

	// SARIF only. ToolType is the kind of tool that wrote the log: "sast",
	// "sca", "secret", "iac" or "web3". It decides the type of every finding
	// and the tool's capabilities instead of the rule tags and the tool name
	// (a scanner runtime that knows what it ran sets it). Other values are
	// ignored. DefaultConfidence (1 to 100) is the confidence of a result
	// whose rule states no precision; zero or out of range: 90.
	ToolType          string
	DefaultConfidence int

	// The Qualys KnowledgeBase XML for a Qualys detection file. Optional:
	// without it, detections keep their QID and results but have no title
	// beyond the QID, CVEs or CVSS.
	QualysKnowledgeBase io.Reader
}

type ParseError struct {
	Format Format
	Line   int
	Column int
	Msg    string
	Err    error
}

type Product struct {
	// Package URL.
	PURL string `json:"purl,omitempty"`

	// CPE 2.3 name.
	CPE string `json:"cpe,omitempty"`

	// Name and version as the document states them, when it gives no
	// identifier.
	Name    string `json:"name,omitempty"`
	Version string `json:"version,omitempty"`

	// When set, the statement is about these components inside the
	// product only (an OpenVEX subcomponent, a CSAF relationship's
	// component), not about the product as a whole or about the components
	// anywhere else. A receiver matches a finding on a subcomponent's PURL
	// or CPE only when the finding's asset is the product.
	Subcomponents []Product `json:"subcomponents,omitempty"`
}

type Result struct {
	// Format of the file.
	Format Format `json:"format"`

	// The CTIS report: assets, findings and dependencies. Never nil; a VEX
	// document gives a report without findings.
	Report *ctis.Report `json:"report"`

	// The statements of a VEX document (CSAF VEX, OpenVEX, the analysis
	// members of a CycloneDX VEX). A receiver applies them to its own
	// findings that match a statement's vulnerability and product.
	VEX []VEXStatement `json:"vex,omitempty"`

	// Counts of what the file held and what was kept.
	Stats Stats `json:"stats"`

	// Problems that did not stop the import (an item without a required
	// field, a value out of range), at most Limits.MaxIssues.
	Issues []Issue `json:"issues,omitempty"`

	// Source field paths the file held that the format's mapping spec does
	// not list, sorted. Their values are not in the report; a receiver can
	// show them so the spec is extended.
	Unmapped []string `json:"unmapped,omitempty"`
}

type Spec struct {
	Format Format
	// Human name of the source format and the versions the spec was written
	// against.
	Title         string
	SourceVersion string
	// Notes on normalization rules that are not per field (severity tables,
	// status tables, asset identity, deduplication).
	Rules []string
	// The fields, in document order.
	Fields []Field
}

type Stats struct {
	// Records of the source: Nessus ReportItems, Qualys detections, CycloneDX
	// vulnerabilities, OSV affected packages, DefectDojo findings.
	Records int `json:"records"`

	Assets     int `json:"assets"`
	Findings   int `json:"findings"`
	Components int `json:"components"`
	Statements int `json:"statements"`

	// Records skipped (below the minimum severity, or unusable; the reason
	// of an unusable record is in Issues).
	Skipped int `json:"skipped"`

	// Findings per CTIS severity.
	BySeverity map[ctis.Severity]int `json:"by_severity,omitempty"`
}

type VEXStatement struct {
	// The vulnerability, under every id the document gives it.
	VulnerabilityIDs []ctis.VulnerabilityID `json:"vulnerability_ids"`

	// The products the statement is about. A receiver matches a finding
	// on a shared PURL (version-less when the statement's PURL has no
	// version) or CPE.
	Products []Product `json:"products"`

	// The statement.
	VEX ctis.VEX `json:"vex"`
}