OSV-aanbevelingen

Dependency-scans tonen afzonderlijke CVE’s. Het tabblad Aanbevelingen onder Beveiliging › Bevindingen › Afhankelijkheden (/<org>/_admin/security/findings/dependencies?view=recommendations) maakt van die lijst een fixlijst: elke openstaande bevinding met een gepubliceerde fix wordt één kaart, met repo + package + current → fix + welke CVE’s die ene upgrade oplost.

Hoe aanbevelingen worden berekend

De groeperingssleutel is (repo_full_name, ecosystem, package_name, current_version, fixed_version). Bevindingen die alle vijf delen, vallen samen tot één kaart.

De sortering gebeurt in drie stappen:

1. Bereikbaarheid: een kaart krijgt het meest bereikbare bereikbaarheidsoordeel van de bevindingen die ze oplost: eerst bereikbaar, dan onbekend (inclusief niet geanalyseerd), dan niet bereikbaar.
2. Ernst (binnen een oordeel): kritiek → hoog → gemiddeld → laag.
3. EPSS-score (binnen een ernst): de hoogste EPSS-score van de gebundelde kwetsbaarheden wint.

Een advisory met lage ernst die je code bereikt, staat dus boven een kritieke die niet bereikbaar is, en binnen één oordeel en ernst staat een advisory die actief wordt misbruikt boven een theoretische. Een kaart die niet bereikbaar is, blijft in de lijst staan; ze zakt alleen. De belangrijkste aanbevelingen op het overzicht en de wekelijkse digest gebruiken dezelfde volgorde.

Wat de kaart toont

acme/api                                              critical
  npm:lodash 4.17.20 → 4.17.21
  3 vulns fixed · EPSS 23.4% · CVE-2021-23337, CVE-2020-8203 +1

Een kaart met het oordeel bereikbaar of niet bereikbaar toont ook Bereikbaar of Niet bereikbaar naast de ernst.

• Manifestpaden: is hetzelfde pakket vastgepind in package-lock.json en pnpm-lock.yaml, dan worden beide getoond.
• EPSS: de hoogste kans op misbruik van de gebundelde CVE’s (0–100%). De dagelijkse verversingsjob haalt EPSS-gegevens op bij FIRST.org.
• Kwetsbaarheids-id’s: de eerste drie staan in de regel; de rest in een samenvatting +N.

De upgrade-PR krijgen

Elke kaart heeft een knop Fix-PR openen voor pakketten in de ecosystemen die beveiligingsfixes krijgen (zie Ondersteunde ecosystemen). Die opent één pull request die dat pakket in die repository ophoogt, als de dependency-bot van je organisatie, en die op een review wacht of samenvoegt zodra de checks slagen, zoals je organisatie heeft gekozen; zie Samenvoegen. Na de aanvraag toont de kaart Herstel voorgesteld: #N met de status van de pull request.

Andere manieren om de upgrade te krijgen:

• Laat Updates van afhankelijkheden de PR’s openen. Met Updates van afhankelijkheden ingeschakeld opent Renovate een beveiligingsupdate-PR in zijn eerstvolgende nachtelijke run nadat er een advisory (OSV) voor een afhankelijkheid is gepubliceerd, ongeacht je schedule en de wachttijd voor de leeftijd van een release. Hoogt een openstaande Renovate-PR een pakket al op, dan linkt de bevinding op het tabblad Bevindingen ernaar (Renovate-PR #n).
• Start nu een run. Het tabblad Aanbevelingen heeft een knop Een afhankelijkheidsupdate-run starten die buiten het schema een Renovate-run voor de hele organisatie start, maximaal één keer per uur. Is Updates van afhankelijkheden niet ingeschakeld, dan linkt het tabblad naar de pagina waar je het inschakelt.
• Hoog het zelf op. Elke kaart noemt het pakket, de geïnstalleerde versie en de voorgestelde gefixte versie, zodat je de wijziging op je eigen branch kunt maken en de PR-scan laat bevestigen dat de bevindingen weg zijn.

Het oude endpoint Upgrade-PR openen blijft buiten gebruik en antwoordt 410 Gone; de knop Fix-PR openen vervangt het.

Migratie nodig: de fix zit in een ander pakket

Voor sommige advisory’s is er geen fix voor het pakket dat je gebruikt, maar wel in een opvolger die de advisory zelf noemt: een nieuw modulepad of nieuwe majorversie, of een hernoemd pakket. Voorbeelden uit echte advisory’s:

Zo’n bevinding toont Migratie nodig naar <package> (opgelost in <version>) in plaats van “nog geen fix”, op de tabbladen Bevindingen en Per pakket, in de API (needs_migration, zie Findings-API) en in de wekelijkse digest. Ze verschijnt niet onder Aanbevelingen en krijgt geen knop Fix-PR openen: overstappen naar een andere module of ander pakket verandert imports en vaak ook de API, dus het is een codewijziging die je zelf maakt, geen versie-upgrade.

Hoe de opvolger wordt gekozen:

• De advisory moet je geïnstalleerde versie raken, en geen gefixte versie van je pakket daarboven noemen. Heeft je eigen pakket een fix, dan krijgt de bevinding die fix zoals gewoonlijk.
• De opvolger is een ander pakket in hetzelfde ecosysteem dat de advisory met een gefixte versie noemt. De getoonde versie is de laagste die de advisory niet raakt. De aliassen van een advisory (bijvoorbeeld een Go-record GO-… en zijn tweeling GHSA-…) worden samen gelezen.
• Worden er meerdere genoemd, dan kiest Go bij voorkeur dezelfde majorversie als de jouwe (go-jose.v2 naar go-jose/go-jose.v2, niet go-jose/v4), daarna de laagste hogere major, en stelt het nooit een lagere major van dezelfde module voor. Andere ecosystemen kiezen bij voorkeur een naam die op die van jou eindigt (request naar @cypress/request).
• Kunnen de versies niet worden geordend, of is geen ander pakket gefixt, dan houdt de bevinding “nog geen fix”. Een advisory die nergens is opgelost, zoals golang.org/x/crypto/openpgp (niet meer onderhouden), wordt nooit als migratie getoond.

Waarom dit niet hetzelfde is als het tabblad Bevindingen

Het tabblad Bevindingen is de canonieke bron: één rij per (CVE × manifest). Aanbevelingen zijn de samenvatting waar je mee aan de slag kunt:

• Een pakket zonder gepubliceerde fix verschijnt nooit onder Aanbevelingen (er valt nog niets mee te doen).
• Een pakket dat met één upgrade te fixen is, verschijnt één keer onder Aanbevelingen en N keer onder Bevindingen (één keer per CVE).
• Een genegeerde bevinding verschijnt in geen van beide.

Gebruik Bevindingen om afzonderlijke CVE’s te beoordelen en te negeren; gebruik Aanbevelingen om het fixwerk van de dag te sturen.

Via de REST API

GET /_app/api/v1/orgs/:slug/security/recommendations (findings:read) geeft de aanbevelingen zelf terug, in de volgorde van het tabblad: één item per repository, pakket en huidige versie, met fixed_version, highest_severity, vulnerability_count, vulnerability_ids, manifest_paths, max_epss, reachability, known_exploited en finding_id, de bevinding op de standaardbranch die een aanvraag voor een beveiligingsfix noemt (null als elke bevinding van de groep op een pull request staat).

De onderliggende CVE-bevindingen, de ruwe gegevens die Aanbevelingen samenvat, zijn beschikbaar via de publieke API. Gebruik die als je een eigen dashboard bouwt, naar een ticketsysteem exporteert of de prioritering vanuit een AI-agent stuurt.

• Dependency-bevindingen opvragen GET /_app/api/v1/orgs/:slug/code-security/deps/findings: één rij per (CVE × manifest), met package_name, current_version, fixed_version, severity, vulnerability_id, manifest_path. Groepeer aan de clientkant op (repo_full_name, ecosystem, package_name, current_version, fixed_version) om de samenvatting van Aanbevelingen na te bootsen.
• Een bevinding negeren POST /_app/api/v1/orgs/:slug/code-security/deps/findings/:id/dismiss body: { "reason": "..." }

Het endpoint voor de lijst vereist een Personal Access Token (PAT) met de scope findings:read; negeren vereist findings:write:

curl -H "Authorization: Bearer ${FREMFORGE_PAT}" \
  "https://frem.sh/_app/api/v1/orgs/acme/code-security/deps/findings?include_dismissed=false"

Zie de referentie van de publieke REST API voor de volledige OpenAPI-specificatie.

Zie ook

• Hersteltermijn (SLA): hoe het SLA-label op het tabblad Bevindingen wordt berekend.
• Beveiligingsdigest: mailt elke maandag de 5 belangrijkste te fixen bevindingen, bereikbare eerst.
• Push-bescherming: secrets die al bij de push worden tegengehouden, de bovenstroomse helft van dezelfde supply-chain-drieslag.