Kontrollera npm-paketets ursprung – den gröna bocken räcker inte ensam

För att kontrollera ett npm-pakets ursprung behöver du granska provenance för den version projektet använder och sedan köra npm audit signatures på de installerade beroendena. Registervyn visar den angivna källan och byggningen; kommandot kontrollerar signaturer och attesteringar kryptografiskt. En markering på paketsidan besvarar därför inte ensam frågan om den hämtade paketversionen klarar verifieringen.

Enligt npm:s anvisning för provenance visar den gröna bocken att paketversionen publicerats med provenance, medan CLI-verifieringen kräver npm version 9.5.0 eller senare. Börja med versionsnumret i projektets låsfil eller installerade beroendeträd. Det är den versionens uppgifter och resultat du ska bedöma, även om paketets startsida först visar en annan utgåva.

Granska rätt version i registret

Öppna paketets sida i npm-registret och välj versionen som projektet använder. Bocken finns vid fältet Version till höger om README. Klicka på den och välj ”View more details” för att se byggmiljö, länk till byggkörningen, källcommit, arbetsflödesfil och post i den offentliga transparensloggen. Uppgifterna gör det möjligt att bedöma om den angivna källan och byggprocessen motsvarar den utgåva du väntar dig.

Jämför särskilt arkivets adress och commit med den källa som paketets utgivare uppger. En länk till en byggkörning ger mer konkretion än enbart ett projektnamn: den pekar på det arbetsflöde som förknippas med publiceringen. Provenance visar ett verifierbart samband med källa och byggning, men säger inte att koden är ofarlig eller att den valda källan är lämplig för projektet.

npm kontrollerar också om den länkade committen och kodbasen fortfarande går att hitta när provenanceuppgifterna öppnas. Om arkivet har tagits bort eller gjorts privat visas ett fel, och ursprunget kan då inte längre fastställas via registervyn. Behandla det som en relevant förändring i underlaget för just den paketversionen, även om bocken fortfarande syns.

Installera beroendena och kör kontrollen

Kör verifieringen i projektets rotkatalog efter att beroendena har installerats. Har projektet en låsfil är npm ci ett lämpligt val för en reproducerbar kontroll: kommandot använder låsta versioner och avbryter om låsfilen inte stämmer med package.json. Använd annars npm install enligt projektets ordinarie installationsflöde. Kontrollera först den lokala CLI-versionen med npm --version och uppdatera vid behov.

1. Installera projektets beroenden med npm ci eller npm install.
2. Kör npm audit signatures och notera både utskriften och kommandots avslutsstatus.
3. Behöver du undersöka attesteringsunderlaget, kör npm audit signatures --json --include-attestations.

npm:s kommandoreferens anger att npm audit signatures verifierar registersignaturer och provenanceattesteringar för nedladdade paket och att JSON-varianten kan inkludera kompletta Sigstore-attesteringspaket. Dessa finns i fältet verified och kan innehålla signerade DSSE-omslag, verifieringsmaterial och poster ur transparensloggen. Den vanliga utskriften räcker ofta för att se om kontrollen lyckades; JSON-resultatet behövs när en viss attestering ska granskas närmare.

Håll paketnamn och version samman genom hela flödet. Om låsfilen ändras mellan granskningen i registret och CLI-körningen gäller resultaten inte längre nödvändigtvis samma utgåva. Detsamma gäller om ett kommando körs i fel projekt eller mot ett annat beroendeträd. Kontrollera därför vad som faktiskt installerades innan du drar slutsatser om ett enskilt paket.

Läs signaturer och attesteringar var för sig

En verifierad registersignatur och en verifierad attestering svarar på olika frågor. Registersignaturen gäller paketnamn, version och integritetsuppgiften för paketarkivet, kontrollerade mot registrets publika nyckel. En provenanceattestering knyter publiceringen och artefakten till uppgifter om källa och byggprocess. Båda resultaten är användbara, men antalet giltiga registersignaturer säger inte hur många paket som har verifierad provenance.

I npm:s exempel på verifieringsutdata har 1 267 paket verifierade registersignaturer, medan 74 har verifierade attesteringar. Det är ett exempel på hur de separata raderna kan se ut, inte ett mått på vad ditt projekt bör uppnå. Läs därför en hög siffra för registersignaturer som ett resultat för just signaturkontrollen, inte som ett kvitto på spårbart byggursprung för hela beroendeträdet.

Om din policy kräver provenance för ett visst paket behöver du identifiera den installerade versionen, granska dess uppgifter i registret och kontrollera att en attestering för den versionen verifierades. Ett lyckat kommando kan fortfarande omfatta paket som saknar provenance; frånvaro av en sådan uppgift är därför en separat policyfråga. Även en giltig attestering lämnar kvar uppgiften att bedöma källkoden och det arbetsflöde som anges.

Skilj saknade uppgifter från misslyckad verifiering

Om npm audit signatures ger fel för en saknad eller ogiltig signatur eller attestering bör körningen stoppas medan orsaken utreds. Felet kan tyda på att ett paket eller dess metadata har ändrats, men det fastslår inte ensamt vad som hänt. Spara feltexten och notera paketnamn, version och register innan du installerar om eller ändrar beroendena.

Skilj också på två olika situationer: en version utan publicerad provenance och en version vars förväntade attesteringsuppgifter inte kan verifieras. Den första ger inget positivt ursprungsbesked och måste bedömas mot projektets krav. Den andra innebär att den tillgängliga verifieringen har misslyckats. Om registret saknar en signatur som kommandot förväntar sig är även det ett verifieringsfel, inte bara ett lägre antal i sammanfattningen.

Kontrollera därefter att låsfilen avser den tänkta versionen och att installationen använder rätt register, särskilt om projektet går via en proxy eller ett privat register. Byt inte version enbart för att få en godkänd körning: då prövas ett annat paketval. Om registervyn samtidigt visar att källarkivet eller committen inte längre kan nås behöver även den förlorade spårbarheten ingå i beslutet.

Placera kontrollen där den kan stoppa CI

Lägg npm audit signatures direkt efter installationen och före projektets byggning, tester eller publicering. Låt ett verifieringsfel ge en misslyckad CI-körning, och dokumentera separat vilka beroenden som enligt projektets policy måste ha provenance. Kommandots godkända resultat ersätter inte det kravet: ett paket kan ha en giltig registersignatur utan en provenanceattestering.

Kontrollen sker efter npm ci eller npm install och kan därför inte hindra sådant som redan inträffat under installationen, exempelvis körning av tillåtna installationsskript. Dess styrka i CI är att stoppa senare steg när signaturer eller attesteringar inte klarar verifieringen. För ett paket med krav på spårbart ursprung är beslutet komplett först när registeruppgifterna avser rätt version, dess attestering verifieras och ingen signaturkontroll har misslyckats.

Läs också:

• Signera Git-commits med SSH – den gröna markeringen räcker inte ensam
• Runway eller Firefly: filmisk kontroll möter svensk fast prislapp
• Kontrollera ett läckt lösenord – skriv inte in det på fel sida