doc(adr): add ADR 00011 for CSAF remediation support#2179
Merged
Conversation
Contributor
Reviewer's GuideAdds a new architecture decision record (ADR 00011) defining how CSAF remediation guidance will be modeled, stored, ingested, and exposed via existing status APIs, including schema, ingestion flow, and query patterns. Sequence diagram for CSAF remediation ingestion flowsequenceDiagram
participant CsafIngestion as CsafIngestionService
participant StatusCreator as StatusCreator
participant ResolveCache as ResolveProductIdCache
participant RemediationCreator as RemediationCreator
participant DB as Database
CsafIngestion->>StatusCreator: create_status_records(csaf_document)
StatusCreator->>ResolveCache: resolve_product_ids(csaf_product_ids)
ResolveCache-->>StatusCreator: product_id_to_status_mapping
StatusCreator->>DB: insert_purl_status_records()
StatusCreator->>DB: insert_product_status_records()
StatusCreator-->>CsafIngestion: status_creation_result_with_mapping
CsafIngestion->>RemediationCreator: create_remediations(csaf_remediations, mapping)
RemediationCreator->>DB: insert_into_remediation(advisory_id, vulnerability_id, category, details, url, data)
RemediationCreator->>DB: insert_into_remediation_purl_status(remediation_id, purl_status_ids)
RemediationCreator->>DB: insert_into_remediation_product_status(remediation_id, product_status_ids)
RemediationCreator-->>CsafIngestion: remediation_creation_result
Sequence diagram for API status query with remediationssequenceDiagram
actor Client
participant Api as StatusApiService
participant DB as Database
Client->>Api: GET /v2/purl/{key}
Api->>DB: SELECT purl_status_with_remediations(purl_key)
DB-->>Api: purl_status_rows_with_joined_remediations
Api->>Api: map_rows_to_PurlStatus_and_RemediationSummary
Api-->>Client: PurlDetails_with_status_and_remediations
Client->>Api: POST /v3/vulnerability/analyze
Api->>DB: query_analysis_status_with_remediations(sbom_or_purls)
DB-->>Api: analysis_rows_with_remediations
Api->>Api: build_AnalysisResponse_with_PurlStatus_and_RemediationSummary
Api-->>Client: AnalysisResponse
ER diagram for CSAF remediation schema additionserDiagram
advisory_vulnerability {
UUID advisory_id
VARCHAR vulnerability_id
}
remediation {
UUID id
UUID advisory_id
VARCHAR vulnerability_id
VARCHAR category
TEXT details
VARCHAR url
JSONB data
}
purl_status {
UUID id
%% existing_columns
TEXT existing_columns
}
product_status {
UUID id
%% existing_columns
TEXT existing_columns
}
remediation_purl_status {
UUID remediation_id
UUID purl_status_id
}
remediation_product_status {
UUID remediation_id
UUID product_status_id
}
advisory_vulnerability ||--o{ remediation : has_remediation
remediation ||--o{ remediation_purl_status : links_purl_status
purl_status ||--o{ remediation_purl_status : is_target_of
remediation ||--o{ remediation_product_status : links_product_status
product_status ||--o{ remediation_product_status : is_target_of
Class diagram for remediation API models and status aggregationclassDiagram
class RemediationSummary {
Uuid id
String category
Option~String~ details
Option~String~ url
Option~JsonValue~ data
}
class PurlStatus {
/* existing_fields */
String status
String vulnerability_id
List~RemediationSummary~ remediations
}
class SbomStatus {
/* existing_fields */
String status
String vulnerability_id
List~RemediationSummary~ remediations
}
class PurlDetails {
/* existing_fields */
List~PurlStatus~ statuses
}
class SbomAdvisory {
/* existing_fields */
List~SbomStatus~ statuses
}
class AnalysisResponse {
/* existing_fields */
List~PurlStatus~ purl_statuses
}
PurlStatus "1" --> "*" RemediationSummary : has
SbomStatus "1" --> "*" RemediationSummary : has
PurlDetails "1" --> "*" PurlStatus : includes
SbomAdvisory "1" --> "*" SbomStatus : includes
AnalysisResponse "1" --> "*" PurlStatus : includes
File-Level Changes
Possibly linked issues
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Hey there - I've reviewed your changes - here's some feedback:
- In the 'Related ADRs' and 'References' sections the Markdown link syntax is inverted, e.g.
(ADR 00008)[00008-purls-recommendation.md]; update these to[ADR 00008](00008-purls-recommendation.md)and similarly for the CSAF test data path so the links render correctly. - Consider clarifying in the ADR how conflicting or overlapping remediations will be handled when multiple advisories reference the same vulnerability/package pair (e.g., prioritization or deduplication rules), since the schema allows multiple remediation records to attach to the same status.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- In the 'Related ADRs' and 'References' sections the Markdown link syntax is inverted, e.g. `(ADR 00008)[00008-purls-recommendation.md]`; update these to `[ADR 00008](00008-purls-recommendation.md)` and similarly for the CSAF test data path so the links render correctly.
- Consider clarifying in the ADR how conflicting or overlapping remediations will be handled when multiple advisories reference the same vulnerability/package pair (e.g., prioritization or deduplication rules), since the schema allows multiple remediation records to attach to the same status.
## Individual Comments
### Comment 1
<location> `docs/adrs/00011-csaf-remediation.md:93` </location>
<code_context>
+### Design Choices
+
+- Remediations link to **specific purl_status/product_status records**
+- Keep statuses (category) as VARCHAR. Having separate statuses table have added more complexity to queries than benefits.
+- Normalize only important remediation fields, while keeping the rest in JSON blob
+
</code_context>
<issue_to_address>
**suggestion (typo):** Fix subject–verb agreement in the explanation about a separate statuses table.
The sentence is grammatically off. Consider: "Having a separate statuses table would have added more complexity to queries than benefits" or "Having a separate statuses table has added more complexity to queries than benefits," depending on the tense you want.
```suggestion
- Remediations link to **specific purl_status/product_status records**
- Keep statuses (category) as VARCHAR. Having a separate statuses table has added more complexity to queries than benefits.
```
</issue_to_address>Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
dejanb
force-pushed
the
adr/remediations
branch
from
212e80e to
e3960a2
Compare
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #2179 +/- ##
==========================================
- Coverage 68.66% 68.65% -0.01%
==========================================
Files 379 379
Lines 21449 21449
Branches 21449 21449
==========================================
- Hits 14727 14726 -1
+ Misses 5855 5851 -4
- Partials 867 872 +5 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
ctron
reviewed
Dec 11, 2025
ctron
reviewed
Dec 11, 2025
ctron
reviewed
Dec 11, 2025
ctron
reviewed
Dec 11, 2025
docs/adrs/00011-csaf-remediation.md
Outdated
|
|
||
| **Modified Response Structures:** | ||
|
|
||
| Add `remediations: Vec<RemediationSummary>` to: |
Contributor
There was a problem hiding this comment.
I know we did simply add new information to all existing fields in the past. But is that the right idea? Why not start by adding it to the endpoints that require it today.
Contributor
Author
There was a problem hiding this comment.
I changed the ADR to consider adding the new information only to endpoints related to dependency analytics for now. We should consider other APIs later on.
Member
There was a problem hiding this comment.
Adding it to PurlStatus later will mean that /v3/vulnerability/analyze won't get it until "phase 2", I'm not sure how that will interact with @ruromero changing to v3 over v2
Contributor
There was a problem hiding this comment.
From DA perspective that is just a matter of adapting the endpoint and response.
Member
There was a problem hiding this comment.
I guess my only concern is: v2 analyze doesnt give any version range info (as v3 analyze returns purl statuses), so if we only add remediation support to v2 analyze for now, we'll be kinda split between all the new stuff being half in v2 and half in v3. But we can always start with v2 analyze for now and focus mainly on the actual implementation rather than what-endpoint-has-what
Contributor
Author
There was a problem hiding this comment.
I added some clarifications about this. The analyze API should contain remediations, there's a bit of description on how we can achieve this without modifying PurlStatus and example of the response.
ctron
reviewed
Dec 11, 2025
Strum355
reviewed
Jan 9, 2026
dejanb
force-pushed
the
adr/remediations
branch
from
e3960a2 to
c640f02
Compare
dejanb
force-pushed
the
adr/remediations
branch
from
3ec3307 to
0d7e109
Compare
ruromero
approved these changes
Jan 19, 2026
dejanb
force-pushed
the
adr/remediations
branch
from
0d7e109 to
823f741
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Propose ingesting CSAF remediation guidance and exposing it via APIs. Remediations provide actionable guidance (upgrade paths, workarounds) alongside vulnerability status information.
Assisted-by: Claude
Summary by Sourcery
Documentation: