Docs: Add triage guide

[terriko]

I've started adding some additional information on how to use triage and merged reports in #1746 but we could probably use a more complete guide about how to triage a cve-bin-tool report.

• related: test: Add triage to requirements test to address aiohttp disputed cve #1746

[terriko]

Possible topics:

• The intended purpose of each triage remark option and examples of when you might use them and why.
• How to re-use triage across projects
• How to re-use triage provided by CVE-bin-tool in test: Add triage to requirements test to address aiohttp disputed cve #1746 to duplicate the results we get in our cve scans of requirements
• Links to resources on triaging security issues in general
• Links to tools for editing/viewing json files

[raboof]

I think this would be great (especially "how to re-use triage") and I would be interested in helping out. I suspect we would like to make some code changes first, though.

Regarding #1746, I don't think that tests what it seems to test (anymore?): AFAICT -i and -m are currently mutually exclusive, and adding -m will cause any -i to be ignored. So what that test does is ignore the scan and only output the information from the triage report.

AFAICT the status of combining triage data with scan data is currently as follows:

• cve-bin-tool -i triage.json.vex thing/to/scan correctly applies the triage data to the report
• cve-bin-tool -i triage.json.vex --sbom cyclonedx --sbom-file scan.sbom.json correctly applies the triage data to the report
• cve-bin-tool -i triage.json.vex -i scanned.json will simply ignore the triage data
• cve-bin-tool -i scanned.json -i triage.json.vex will simply ignore the scan data
• cve-bin-tool -m triage.json,scanned.json will treat all intermediate objects as inputs for a new scan, so it will not take into account triage data

In other words: AFAICT currently only the variation cve-bin-tool -i triage.json.vex thing/to/scan does what we want - and that one can be pretty slow because of the scanning :).

cve-bin-tool -i triage.json.vex --sbom cyclonedx --sbom-file scan.sbom.json also does what we want, but we have no good way to produce the sbom that matches what we expect when we do the vulnerability matching.

I see two ways forward:

1. find a way to perform the equivalent of cve-bin-tool -i triage.json.vex thing/to/scan but with previously-scanned content. From my limited experience with the code it seems like everything to make this possible is mostly in place, and we mainly just need to come up with a sensible way to make this available from the CLI . Perhaps we should introduce a new flag explicitly meant for providing triage files as input? That'd also fix the slightly confusing behavior that providing a vex file with a '.json' extension doesn't work ;)
2. implement Export component list in SBOM format #1697 and recommend cve-bin-tool -i triage.json.vex --sbom cyclonedx --sbom-file scan.sbom.json. This is appealing for additional reasons mentioned in that issue, but probably a chunk more work.

Does this make sense at all? Perhaps we should first do '1' as a quick win, document it, and then leave '2' for later?

[terriko]

Yeah, let's at least get 1 working.

For 2 we already have the ability to use @anthonyharrison 's https://pypi.org/project/sbom4python and get an SBOM (and code showing how in the github actions files since we're generating them once per week to figure out how often things change) so maybe adding the vex triage wouldn't be that hard to get working from there? I admit, I haven't experimented with that at all.

[raboof]

Yeah, let's at least get 1 working.

👍 let me see if I can cook up an initial PR tomorrow! :)

[mastersans]

@terriko Although newer triage documention would be handled in Gsoc project, But this one in already been taken care of with #2335 : )

[terriko]

Closing this as per comment above.