security

type Advisory struct {
	// ID identifies the entry. It is "OPENSSH-<date>-<n>", where <date> is
	// Date and <n> is the 1-based position of the entry among those sharing
	// that date, counted down the page — e.g. "OPENSSH-2025-02-18-1" and
	// "OPENSSH-2025-02-18-2" for the two entries of 2025-02-18. The trailing
	// entries that carry no date at all are "OPENSSH-UNDATED-<n>", numbered
	// the same way.
	//
	// The page states no identifier of its own, so this one is assigned. It is
	// derived rather than sequential so that an entry added upstream — always
	// at the top, under a new date — leaves the IDs of every existing entry
	// alone.
	ID string `json:"id"`

	// Date is the date the entry is filed under, as yyyy-mm-dd. Empty for the
	// undated entries at the foot of the page ("OpenSSH was never vulnerable
	// to ...").
	//
	// It is a publication date for the advisory, and not necessarily the date
	// the fix shipped: the two 2025-02-18 entries were published alongside the
	// 9.9p2 release, while the 2015-08-11 entry describes bugs fixed in 7.0,
	// released later that month.
	Date string `json:"date,omitempty"`

	// Title is the one-line statement of the issue, taken from the entry.
	// Where the entry has a sentence that serves as a summary, that sentence
	// is it ("VerifyHostKeyDNS server impersonation."); where it does not, it
	// is written from the entry's first clause. It is not translated,
	// re-worded for style, or given a severity it does not state.
	Title string `json:"title"`

	// Description is the entry's prose, as text: tags dropped, entities
	// decoded, runs of whitespace collapsed to single spaces, paragraphs
	// separated by a blank line. Nothing is added and nothing is summarized
	// away — the whole entry is here, including the sentences that also feed
	// Fixed, Mitigations and CVEs.
	Description string `json:"description"`

	// Status says which of the two kinds of entry this is. See Status.
	Status Status `json:"status"`

	// CVEs are the CVE IDs the entry itself names, in page order. Entries that
	// name none — the majority, since OpenSSH only began citing CVE IDs
	// inline in the 2010s — have none here. An ID is never supplied from
	// elsewhere, however well known the pairing is: that OpenSSH's page does
	// not name a CVE is itself the fact this field records.
	CVEs []string `json:"cves,omitempty"`

	// Affected are the version ranges the entry states are vulnerable, split
	// by the component or build they are stated against. Empty when
	// Status is StatusUnaffected, and empty when an affected entry gives no
	// version bound at all.
	Affected []Affected `json:"affected,omitempty"`

	// Fixed are the releases the entry names as carrying the fix, e.g.
	// ["9.9p2"] or ["7.2p2"]. Empty when the entry names none.
	//
	// A fixed release is not the complement of Affected: "corrected in OpenSSH
	// 9.6" against an affected range of "8.9 to 9.5 inclusive" states both
	// bounds, and neither is derived from the other here.
	Fixed []string `json:"fixed,omitempty"`

	// Mitigations are the workarounds the entry offers, one per measure, as
	// stated ("Mitigate by setting X11Forwarding=no in sshd_config, or on the
	// commandline."). A sentence that merely observes the feature is off by
	// default is not a mitigation and is left to Description.
	Mitigations []string `json:"mitigations,omitempty"`

	// References are the links in the entry, in page order, with relative
	// hrefs resolved against the page's URL.
	References []Reference `json:"references,omitempty"`

	// Annotations are claims about this entry that the page does not make and
	// the fields above therefore cannot carry: the CVE ID the release notes
	// name where the entry does not, the release a linked advisory says
	// carries the fix. Each one names the document it was read from and quotes
	// the sentence it was read off, so it is checkable the same way every other
	// field is.
	//
	// They are kept apart from CVEs and Fixed rather than merged into them,
	// and that separation is the point. Those fields answer "what does OpenSSH
	// say", which is a question with a fixed answer that this repository can
	// re-derive from Origin.HTML alone; Annotations answer "what can be found
	// out", which is a question whose answer grows as documents are read. Merged,
	// neither could be asked: a CVE ID in CVEs that is not in the entry breaks
	// the check that every field is readable off the stored <li>, and once
	// broken there is no way to tell a transcription error from an annotation.
	// Extraction merges them, because by then the distinction has been
	// recorded and what is wanted is the union.
	Annotations []Annotation `json:"annotations,omitempty"`

	// Origin records where the entry was read from.
	Origin Origin `json:"origin,omitzero"`
}

type Affected struct {
	// Product is which build the range is stated against: "OpenSSH" or
	// "Portable OpenSSH". The distinction is the entry's own and is kept —
	// e.g. the 2011-02-02 keysign entry is portable-only, and the 2024-07-01
	// race condition is stated against Portable because the RCE it leads to
	// is on non-OpenBSD systems. Where the entry does not say, this is
	// "OpenSSH".
	Product string `json:"product,omitempty"`

	// Component is the program the entry names, verbatim and with the manual
	// section the page gives it: "sshd(8)", "ssh(1)", "ssh-agent(1)",
	// "ssh-add(1)", "sftp-server". Empty when the entry speaks of OpenSSH as
	// a whole.
	Component string `json:"component,omitempty"`

	// Versions are the bounds, as stated. A range with several bounds is one
	// element ("7.4 to 9.9 (inclusive)" is one {ge, le}); alternatives are
	// several ("versions 3.2.2p1, 3.4p1 and 3.4" is three {eq}).
	Versions []Range `json:"versions,omitempty"`

	// Condition is the configuration the entry says the exposure requires,
	// as stated: "X11Forwarding enabled", "read-only mode (sftp-server -R)",
	// "VerifyHostKeyDNS enabled". Empty when the entry states none.
	//
	// It is recorded but not evaluated: extraction cannot test a remote
	// sshd_config, so a conditional entry still yields a detection on version
	// alone.
	Condition string `json:"condition,omitempty"`
}

type Annotation struct {
	// Field is the Advisory field this claim is about: "cves" or "fixed".
	//
	// It is the field name rather than a free-form label so that extraction can
	// dispatch on it, and it is checked there: an unrecognized name fails the
	// extract rather than being skipped, for the same reason a malformed
	// version does. These records are model-produced, and a claim filed under a
	// field nothing reads would be silently lost.
	Field string `json:"field"`

	// Value is what the source states, in the form the field takes: a CVE ID
	// for "cves", a release for "fixed". Always set -- an annotation exists to
	// record a value, including when Inapplicable says it is not this entry's,
	// where it is the whole point of the record.
	Value string `json:"value"`

	// Inapplicable records the second of the two outcomes worth writing down:
	// the source states Value for Field, and it is not this entry's.
	//
	// Omitting the value instead is not the same record. That is the "not
	// looked at yet" this type exists to rule out, and it costs the same
	// document being re-read and the same judgement being made again, with
	// nothing written down either time.
	//
	// It has two occasions on this source. A page entry recording that OpenSSH
	// was never vulnerable links notes about SSH at large, which do name CVE
	// IDs -- against the protocol, not against any release here. And one
	// release note covers several entries at once: three share 2023-02-02 and
	// all three are fixed in 9.2, so a CVE named there may well belong to a
	// sibling. Where it cannot be told which, that is not an Inapplicable
	// either but no annotation at all, since the reading was inconclusive
	// rather than negative.
	//
	// Extraction does not fold it in; it is for whoever reads raw/ next.
	//
	// There is deliberately no counterpart for "the source was read and states
	// nothing". On this page that outcome is a grep over origin/txt/ away --
	// five of the 35 stored documents name a CVE ID and the rest do not -- so
	// recording it caches an answer that is cheaper and more reliable to
	// recompute. It is also the one record that carries no quote, which makes
	// it the only kind nothing can check: were a document revised to name an ID,
	// the record would quietly become false with no verification to catch it.
	Inapplicable bool `json:"inapplicable,omitempty"`

	// Source is the document the claim was read from.
	Source AnnotationSource `json:"source"`
}

type AnnotationSource struct {
	// URL is the document, as the entry links to it.
	URL string `json:"url"`

	// Origin is the path of the stored copy under origin/, e.g.
	// "origin/txt/release-9.8". Set when the fetcher ingested the document,
	// which it does for the same-origin documents the page cites; empty when
	// the claim rests on something not stored here.
	//
	// The difference matters: with a stored copy the claim is offline-checkable
	// and an upstream edit to the evidence shows up as a diff, which is the
	// same guarantee Origin.HTML gives every other field. Without one, the
	// annotation is an assertion about a document that may since have changed
	// and nothing here would notice.
	Origin string `json:"origin,omitempty"`

	// Quote is the sentence the claim was read off, verbatim from the source.
	//
	// A quote rather than a line number or a byte offset: the documents are not
	// pinned, and an offset silently comes to point at the wrong line when one
	// is inserted above it, whereas a quote that no longer appears is a
	// detectable failure -- and a greppable one, when Origin is set.
	Quote string `json:"quote,omitempty"`

	// Retrieved is the date the source was read, as yyyy-mm-dd. It is what
	// dates the claim when the document behind it is revised.
	Retrieved string `json:"retrieved,omitempty"`
}

type Option interface {
	// contains filtered or unexported methods
}

type Origin struct {
	// URL is the page the entry was read from.
	URL string `json:"url,omitempty"`

	// HTML is the entry's <li> element, verbatim from origin/, including the
	// tag itself. It is what makes the rest of the record checkable — and
	// what lets a later run tell an entry upstream has revised from one it has
	// only re-read.
	HTML string `json:"html,omitempty"`
}

type Range struct {
	Equal        string `json:"eq,omitempty"`
	GreaterEqual string `json:"ge,omitempty"`
	GreaterThan  string `json:"gt,omitempty"`
	LessEqual    string `json:"le,omitempty"`
	LessThan     string `json:"lt,omitempty"`
}

type Reference struct {
	// URL is the href, made absolute.
	URL string `json:"url"`

	// Text is the link's anchor text ("release notes", "the advisory",
	// "Qualys Security Advisory Team").
	Text string `json:"text,omitempty"`
}

type Status string