DependencyTrack / DependencyTrack/dependency-track
Include component occurrences in the Finding Packaging Format export
- Dominant language
- Java
- Stars
- 4.2k
- Forks
- 811
- Avg merge
- 8h 39m
- Merged PRs (30d)
- 237
Description
### Current Behavior
FPF says whether a component has occurrences, but not what they are. `Finding` sets `hasOccurrences` on the component as a boolean (`optValue(component, "hasOccurrences", findingRow.componentHasOccurrences(), false)`), and `FindingPackagingFormat` serializes the finding list as it is, so the boolean is all a consumer gets. The occurrences themselves are `ComponentOccurrence` (location, line, offset, symbol) and come from `GET /v1/component/{uuid}/occurrence`.
The DefectDojo integration has no way around that, since `DefectDojoUploader.process` builds the FPFdocument and posts it unchanged.
This is not a case of DT lacking the data. Our js BOMs carry `evidence.occurrences`, `ModelConverter` imports them into `ComponentOccurrence`, and the Components tab renders them. An entry looks like this:
```json
{ "location": "src/main.ts", "line": 14 }
```
So for those components DT holds the file and the line, and the export drops both.
### Proposed Behavior
Include the occurrences of the components that appear in the export, next to the `hasOccurrences` flag that already says they exist.
Occurrences are a list in CycloneDX and in DT's own model, so this wants to be a list rather than a single path. If payload size is the worry, a cap or a config property to opt in would work for us. FPF carries findings rather than the whole BOM, so the set is already limited to components with a vulnerability.
`FPF_VERSION` is 1.5 today and the class says the version needs a bump when the format changes. An added optional field is additive, so we will follow whatever you prefer there.
We are not asking DT to read vendor-specific component properties. #6643 settled that, and occurrences are the right place for this. cdxgen writes `SrcFile` properties instead of occurrences for our dotnet BOMs, so converting those is our job and we will do it before upload.
### Why this matters
DefectDojo is where our triage happens and DT is the ingestion engine, the same setup as #6169. A finding arrives naming the vulnerable package and nothing about where it is used. Whoever picks up the bug has to locate the package by hand, and in a portfolio where packages are built in one repository and consumed in another, they often look in the wrong one and close the finding as not applicable.
The occurrence paths answer that directly, and DT already has them.
### Related
- #6169 asks for `analysis.detail` in the same export. Same direction, different field.
- #6772 adds affected version ranges to FPF. Same direction again.
- #6643 established that locations belong in `evidence.occurrences` and not in component properties.
### Environment
- Dependency-Track 5.0.4
- BOM producer: cdxgen, CycloneDX 1.6
- Integration: the built-in DefectDojo publisher, driven by the project's
`integrations:defectdojo.engagementId` property
### Checklist
- [x] I have read and understand the [contributing guidelines](https://github.com/DependencyTrack/dependency-track/blob/main/CONTRIBUTING.md#filing-issues)
- [x] I have checked the [existing issues](https://github.com/DependencyTrack/dependency-track/issues) for whether this enhancement was already requested
Contributor guide
Research direction
Start by reading Finding and FindingPackagingFormat, then trace ComponentOccurrence data from GET /v1/component/{uuid}/occurrence through the FPF serialization. Review DefectDojoUploader.process and the FPF_VERSION handling before deciding the export shape. Done means findings include component occurrence lists alongside hasOccurrences, with the format version behavior addressed.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java
- Domain
- api, backend
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 55/100