Clarify how to find and select a provider-metadata.json

[bernhardreiter]

During implementation of https://github.com/csaf-poc/csaf_distribution/, especially the checker, aggregator and downloader part, our team at Intevation found that CSAF standard and tool implementors can profit from further clarifications in the section how to find a provider-metadata.json file. It is also helpful to give some rationale for the design decisions, even if just informational.

The current document reads: https://github.com/oasis-tcs/csaf/blob/1afbc08dfac6d4d860e91407fcf107117cfc6528/csaf_2.0/prose/csaf-v2-editor-draft.md?plain=1#L6236-L6249

"expected result"

Clarify the condition when a potentially found file is considered an "expected result" , in the sentence:

test whether the response provides an expected result as defined in the requirement in section 7.1

We suggest something along the lines:

Expected is contents which MUST be a valid JSON file which SHOULD have been tested by checking against the JSON schema for the provider-metadata.json.

Rationale: Webservers of organisations commonly give status 200, but with an error page in the contents. So checking that a valid JSON is returned is a good indicator for simple downloaders that cannot do a schema validation.

how to deal with several URLs

The order of the four steps can be more clear about what should happen in interactive and non-interactive cases.

Suggestions:

• Remove 4. Select one or moreprovider-metadata.jsonto use. in favor of a remark after step 2. Indicate that a non-interactive tool can take the first and log the other files found, an interactive tool may offer a selection.
• Use a pseudo algorithm style
• Say that each two found provider-metadata.json files are the same, if their contents is bitwise identical.

algorithm

Here is the algorithms for detect as far as we have understood how it was intended:

1. Download from .well-known URL, if "expected" -> R1; L=R1
2. Download security.txt, download from all CSAF entries, for all "expected" -> R2[]
3. If (the contents of the files) for R1 and R2[0] and are bitwise the same, (use L=R1 and) delete entry R2[0]
4. If there is no R1, but R2[0], use L=R2[0] and delete entry R2[0]
5. If len(R2>0) handle additional list of found locations
6. If no L, check DNS Path as last resort, download and if "expected" -> L
7. If L, retrieve further information as indicated by L

Instead of a domain, tools should also offer to work with a full URI to a provider-metadata.json.

Rationale: A tool should inform the user about additional potential sources for advisories, but be able to run as batch. It is expected that some providers will have to use several methods to advertise their locations, one example is when previously joined departments split up and thus later have three domains, where they originally had one with all advisories.

(In the long run, an aggregator use would make the algorithms simpler for downloaders.)

[tschmidtb51]

@sthagen: Maybe, we should address that in a committee note?

[sthagen]

@tschmidtb51 we can expand on that in the committee note (as it is a new feature compared to CSAF CVRf 1.2).

I do not share the perception that the description in the prose is unclear. The reference to section 7.1 seems clear enough to me.

Let us wait and see, if the one or more part is useful in practice or causes problems. If the latter the question will be, if the providers can manage to always provide a single file per „access point“. I remember no one could bring convincing simplifications while we were discussing and, well, exploring that automation mechanism and channel.

[bernhardreiter]

The reference to section 7.1 seems clear enough to me.

To further explain: Section 7.1 lists 23 requirements, with some having a direct connection to the provider-metadata.json and some do not. From our perspective it is unclear, how deep a downloader should check the requirements, until deciding that a specific provider-metadata.json is not "as expected" and then try the next. So some implementations may interpret this more deeply than others, potentiall leading to unwanted different behaviour in CSAF downloaders.

if the one or more part is useful in practice or causes problems.

From my perspective, the attempt to express the rules as algorithm (in this issue above) shows that the rules are significantly complex to implement.

[bernhardreiter]

(Edited the algorithm above for language, to be a bit more explicit.)