A CSAF Document Travels as a Report Attachment and Speaks for the Sender Only at the First Report
Context and Problem Statement
The Common Security Advisory Framework (CSAF) 2.1 draft adds a Vulnerability Report profile, csaf_vulnerability_report, made for private exchange during Coordinated Vulnerability Disclosure (CVD).
CVD tools will send such documents to Vultron participants, and the CSAF crosswalk expects them to travel inside a case.
Participants will also produce CSAF documents from their copies of a case and pass draft advisories around in CSAF, so CSAF documents will appear in a case for reasons other than reporting.
Five questions are open (Idea #5131, Idea #6197):
- Where in a Vultron message does a CSAF document go, and what tells a receiver that it is CSAF?
- When may a receiver read the content of a CSAF document as the sender's statement about the case?
- When a Vultron field and the CSAF document state a value for the same thing, which one counts?
- What does a receiver do with a CSAF document it cannot read, or one that fails the CSAF schema?
- When the report receiver and the CASE_MANAGER are separate actors, which of them turns the document into case inputs, and against which time are its dates judged?
Decision Drivers
- A report stays usable by a receiver that does not read CSAF, and a report can carry other files.
- The message keeps the ActivityStreams 2.0 (AS2) shapes, in which
contentis a string. - A document that describes a case must not change the case it describes.
- The case changes only through Vultron's own activities and fields.
- A broken attachment must not stop a real vulnerability report from being received.
- CSAF 2.1 is a draft that its Technical Committee can still change.
- The case owner states the starting content of its own case, and the Reporter's embargo proposal stays the Reporter's.
Considered Options
For the carriage:
- The CSAF document as the report's own
content, serialized to a string. - The CSAF document as a JSON object in the report's
content. - The CSAF document as an attached
Documentobject of the report, with the report'scontentkept as text.
For the identification:
- The media type
application/json, with the document identifying itself. application/jsonwith aprofileparameter that names the CSAF schema.- An unregistered media type, such as
application/csaf+json.
For the occasion of reading:
- Read any CSAF document that arrives in a case.
- Read only a CSAF Vulnerability Report attached to the first offer of a report, before a case exists for it.
For the reader of the document, when a proposal creates the case:
- The CASE_MANAGER reads the document on the Offer that the proposal carries, and the proposal states nothing.
- The report receiver reads the document and states the case inputs on its proposal, and the CASE_MANAGER never reads it.
- The report receiver reads the document and states the case inputs on its proposal, and the CASE_MANAGER reads the document only when a proposal states none.
Decision Outcome
Chosen options: the attached Document, application/json with self-identification, only at the first offer of a report, and the report receiver reads, with the CASE_MANAGER as the fallback, because together they keep AS2 shapes, keep the report readable without CSAF, keep every other CSAF document from rewriting a case, and let the case owner state its own case.
The decision has six parts:
- Carriage. A CSAF document travels as a
Documentin theattachmentof aVulnerabilityReport, with the JSON text of the document as thecontentof thatDocument. The report's owncontentis human-readable text, and the report can carry other attachments beside the CSAF document. - Identification. The
Documenthas the media typeapplication/json, which the distribution feeds of the CSAF draft also use. A receiver recognizes CSAF 2.1 from the document itself, by its$schemaanddocument.csaf_versionvalues, and reads the profile fromdocument.category. - One occasion for reading. A receiver may treat a CSAF document as the sender's statement only when the document has the category
csaf_vulnerability_reportand is attached to anOffer(VulnerabilityReport)whose report belongs to no case at the receiver. Then the document can fill the inputs of the case that the receiver creates. A CSAF document anywhere else, such as on a note, on a later report, or in a vulnerability record, is a result of the case and changes no case data. - Explicit fields win. A sender may fill the Vultron fields of the report and the offer as it chooses, and it should make them agree with the document it attaches. A receiver starts from those fields and may fill only what they leave unstated from the document. A field that the document omits states nothing, and neither does a default that the CSAF schema declares.
- Strict sender, lenient receiver. A sender should not attach a document that fails the CSAF 2.1 schema. A receiver never refuses a report because of its CSAF attachment, and it reads what it can.
- The report receiver states the case inputs. The report receiver turns the document into the case inputs of its case proposal, and the case owner may change every input except the CSAF disclosure date before it sends the proposal. When a proposal states case inputs, the CASE_MANAGER builds the case from them and reads no CSAF document. When a proposal states none, the CASE_MANAGER may fill the inputs from the document on the Offer that the proposal carries. The proposer passes the CSAF disclosure date along as the document states it. The CASE_MANAGER judges the date when it creates the case: a future date is the Reporter's proposed embargo end, and a past date makes the vulnerability public.
The mapping from CSAF fields to case inputs, the receiver's local record of what it read, and how the codebase follows the changing draft are current policy, and they live in the specification that cites this decision.
Consequences
- Good, because a report with no CSAF attachment, one with only a CSAF attachment, and one with several files all have the same shape.
- Good, because a receiver that does not read CSAF still has the report's text.
- Good, because the attachment sits inside the signed activity and inside the copy that the case ledger records.
- Good, because a projection or a draft advisory that circulates in a case cannot change the case.
- Good, because a Vultron field and a CSAF value never compete: the Vultron field always counts.
- Bad, because a sender that has only a CSAF document must still write at least a line of report text.
- Bad, because
application/jsonalone does not tell a receiver that an attachment is CSAF until it reads the document. - Bad, because a CSAF document that arrives after the case exists can only be read by a human, even when it carries news, such as a later exploitation report. Such news reaches the case through the Vultron activity that reports it.
- Good, because the receiver's record of what it read agrees with the proposal it sent.
- Good, because a disclosure date that passes while a proposal is delivered never becomes an embargo end.
- Bad, because the CASE_MANAGER keeps two ways to get the case inputs: from the proposal, or from the document.
Validation
A requirement for each part of the decision carries a test marker. Each marker is a strict expected failure until its behavior is built.
Pros and Cons of the Options
The CSAF document as the report's own content
- Good, because it needs no new object.
- Bad, because the report then has no text for a reader that does not read CSAF.
- Bad, because the report cannot carry other files in the same way.
The CSAF document as a JSON object in content
- Good, because the message is easier for a person to read.
- Bad, because AS2 defines
contentas a string, so the shape is not AS2.
The CSAF document as an attached Document
- Good, because it is the way ActivityPub servers attach files to a note: each attachment names its own format.
- Good, because the report keeps its text and can carry other files.
- Neutral, because a receiver must look in the attachments to find the document.
The CASE_MANAGER reads the document, and the proposal states nothing
- Good, because the mapping runs in one place.
- Bad, because the case owner cannot change the starting content of its own case before the case exists.
- Bad, because the receiver's record of what it read cannot say what the case took from it.
The report receiver reads the document, and the CASE_MANAGER never reads it
- Good, because only the actor that received the Offer reads the document.
- Bad, because a CSAF report from a receiver that does not convert it gives nothing to the case, and no error says so.
The report receiver reads the document, with the CASE_MANAGER as the fallback
- Good, because the case owner states its own case, as it states its case roles (ADR-0133).
- Good, because a receiver that does not convert the document still gets a case that takes what the document says.
- Neutral, because both paths use one mapping, so the fallback costs one check for the case inputs on the proposal.
A profile parameter or an unregistered media type
- Good, because the format is visible without reading the document.
- Bad, because
application/jsondefines no parameters, and no other tool knows an invented type. - Bad, because neither one helps a receiver that must read the document to identify it in any case.
Read any CSAF document that arrives in a case
- Good, because news in a later document could update the case automatically.
- Bad, because projections and draft advisories describe the case, so reading them back lets a description rewrite what it describes.
More Information
The crosswalk proposals include a request to the CSAF Technical Committee to register a media type for CSAF documents. If the committee registers one, the identification part of this decision can change without changing the others.
Producing a CSAF document from a case is planned separately (Idea #5134).
The requirements for the sixth part are planned in notes/csaf-case-inputs-on-proposal.md and land in case-proposal.yaml and embargo-policy.yaml with their code (#6722, #6723, #6725).
Generated spec requirements: csaf-report-content.yaml CSAF-01 through CSAF-03.