Broken Down Endpoint Design for Record Submission

[mattrbianchi]

Problem statement

A CNA is only responsible for data in the cna container of a CVE Record. The community wishes to reduce what is sent to the API for publishing and updating a record to only this object in order to avoid any problems trying to send a fully valid CVE Record to the API.

A literal resource oriented approach

Instead of making requests to the /cve/:id endpoint, the community would interact with sub-resource endpoints focused on the cna and adp container objects along with a rejected record:
POST /cve/:id/cna -> Publish the record, expecting a cna container in the JSON body.
PUT /cve/:id/cna -> Update the cna container for the record.
POST /cve/:id/reject -> Reject the CVE. Expects a descriptions array with at least one english description and an optional replacedBy array to build the new rejected CVE record.

When ADPs are added to the system post 2.1:

POST /cve/:id/adp -> Create a new adp container in a published record for the ADP. Must not already have an adp container for this organizaiton. If submitter is the CNA of the record they should not be able to make an ADP submission.
PUT /cve/:id/adp -> Update an existing adp container in a published record for the ADP. If submitter is the CNA of the record they should not be able to make an ADP submission.

This would require the QWG to provide an approved subset of the CVE Schema for the AWG to use to validate cna and adp container objects as well as a subset schema that validates the descriptions and replacedBy arrays submitted to the proposed rejected endpoint.

Questions

The cna and adp containers are very similar, why not combine them into one endpoint?

While the containers are similar, there are different requirements for either to be valid. A cna container has more required fields. Also, the action being done is different. When submitting an adp container, an organization is contributing data to a record that is not theirs. When submitting a cna container, an organization is publishing or updating their own record. By separating the two, not only can it be simpler to validate, but we allow clients to be clear in their intent.

[mattrbianchi]

@chandanbn @mprpic @david-waltermire-nist @kernelsmith @rbrittonMitre
Tagging interested parties.

[mprpic]

+1 for POST/PUT /cve/:id/cna.

Nitpick: POST /cve/:id/rejected -> /cve/:id/reject since it should match the action being performed.

Will it be possible to go from "rejected" to "published" by POSTing a CNA container to /cve/:id/cna on a previously rejected ID?

The cna and adp containers are very similar, why not combine them into one endpoint?

It's not impossible that in the future the CNA and ADP containers may differ in other ways apart from the set of required attributes. Splitting them now feels like a more future-proof solution, in my opinion.

[mattrbianchi]

Agreed on the tense of the action and for separate endpoints for the containers.

As for going from rejected to published for records: going off the story for documenting record state transitions #364, this will be possible per scenario 7.

[jwhitmore-mitre]

Rejected requires descriptions, but replacedBy is optional. The endpoint description given may imply both are required.

[mattrbianchi]

I agree, I've updated the rejected endpoint's wording to hopefully better convey this.

POST /cve/:id/rejected -> Reject the CVE. Expects a descriptions array with at least one english description and an optional replacedBy array to build the new rejected CVE record.

[david-waltermire]

I just posted an updated open API and an integration schema in #511 for discussion here. Figured something concrete would be useful.

[mattrbianchi]

Thank you @david-waltermire-nist ! I've added my comments to the yml file. But I agree it closely reflects the interface described above.

[Chris-Turner-NIST]

Possibly already discussed, but referencing the question response above there is an additional validation case that should be considered.

• If submitter is the CNA of the record they should not be able to make an ADP submission to that record

[mattrbianchi]

Thanks @Chris-Turner-NIST, I've added this text to both of the ADP endpoints for future implementation.

[chandanbn]

I can personally imagine a user getting a CVE ID incorrect in a form and accidentally submitting an adp container to a record that does not belong to them instead of updating a cna container on a record that does.

This would be a bug if it does not throw an error.
A CNA should get error if they try to post an ADP container to their reserved/allocated/assigned CVE ID.
A ADP should get error if they try to post a CNA container a CVE ID that is not reserved for their org.

[mattrbianchi]

That's a good point so as long as we do expect the input of the JSON body to name the object and those names be cnaContainer & adpContainer we would avoid that problem. So I'll remove this text from the proposal. But per @mprpic 's feedback, I think it wise to keep the container endpoints separate in case they diverge in structure in the future.

[david-waltermire]

Here are the state transitions we talked about today.

I think these cover how the specific IDR and RSUS endpoints interact. Please let me know if I have anything wrong.

[mprpic]

This looks good but one state that is missing is adding a record for the reserved state. If we add a state transition that allows submitting a reserved state record, it feels like there would be a lot of duplication though. Perhaps a completely different approach would be to ditch the PUT /cve-id endpoint, and only have:

• POST /cve-id: reserves one or more CVE IDs
• POST/PUT /cve/{id}/cna?state=(published|rejected|reserved): creates/updates CNA container in CVE record
• POST/PUT /cve/{id}/adp: creates/updates ADP container in CVE record

and move the CNA-required data for rejected/reserved into the CNA container. Right now the schema for a rejected CVE is (reserved schema is similar minus the replacedBy):

dataType
dataVersion
cveMetadata
descriptions
replacedBy

but maybe it should look just like a published record with the CNA container only allowing descriptions and replacedBy:

dataType
dataVersion
cveMetadata
containers
  cna
    descriptions
    replacedBy

Rejected and reserved CVEs would not allow ADP container updates of course.

[david-waltermire]

The following is a set of slides that break down each endpoint.
CVE ID-record-state-transitions.pptx

See slide 4. If we remove the `PUT /cve-id/{cve-id} endpoint, we lose the ability to reject/unreject CVE IDs without a record. I think a goal of this service approach was to reduce the number of noisy CVE records caused by CVE IDs that were never assigned.

Aside from the above, the changes you are suggesting to the reserved/rejected record are a bit larger than we had hoped to make at this point, but they would work. I think this questions is more about style, consistency, and noise reduction.

As for dropping the

[mprpic]

See slide 4. If we remove the `PUT /cve-id/{cve-id} endpoint, we lose the ability to reject/unreject CVE IDs without a record. I think a goal of this service approach was to reduce the number of noisy CVE records caused by CVE IDs that were never assigned.

True, but I think we need to move away from the design where a CVE ID is a separate entity than a CVE record. A CVE ID should just be a CVE record that has a different set of metadata in it depending on its state. I tried to reflect that in the schema update here:

CVEProject/cve-schema#125

Note that you can still submit a CVE record with an empty CNA container for reserved CVE IDs. But rejected ones require a description field even today in the schema, so I left that as a required field in the CNA container as well. We could relax that as well though if desired.

Aside from the above, the changes you are suggesting to the reserved/rejected record are a bit larger than we had hoped to make at this point, but they would work. I think this questions is more about style, consistency, and noise reduction.

I think it sets up the API design going forward, something which will be exceedingly hard to change the later we do it. If you add 6 endpoints for three related actions, you have so support all of them for a very long time.

As for dropping the

Did you mean to finish this and it got cut off somehow?