Naar de inhoud
HackIndex Ladon
Menu

Projecten en lockfiles

Alle docs

Een project is een repository die Ladon kent aan de lockfiles. Upload ze, of laat Ladon ze uit de GitHub-repository lezen, en Ladon volgt elk pakket erin, op de exacte versie die je installeert. Je krijgt dezelfde meldingen als bij elke andere watch, plus een rapport zoals npm audit of composer audit dat laat zien wat nu kwetsbaar is en welke versie het oplost.

Wat er in een project zit

Alles wat je volgt, zit in een project. Een team heeft een of meer projecten, en elk project heeft eigen tabbladen:

  • Software: de lockfiles, de software die je zelf toevoegde en de gewone software van het project, met het rapport.
  • CVE-monitor: de CVE-regels van het project.
  • Watches: elke watch van het project, ook die je zelf of via de API aanmaakte.
  • Meldingen: de meldingen van het project.
  • Kanalen: waar de meldingen van het project heen gaan, zie Kanalen.
  • Sites: de WordPress-sites die aan het project gekoppeld zijn, zie WordPress-sites.

Het team houdt wat alle projecten delen: de lijst met projecten en een overzicht, de huisstijl voor white-label, de GitHub App, de API-tokens, en leden en facturatie in je HackIndex-account. Een project past goed bij een klant, een app of een groep sites die dezelfde kanalen delen.

Ondersteunde lockfiles

Elke lockfile uit de tabel met ecosystemen werkt. Een lockfile mag maximaal 20 MB en 10.000 pakketten zijn. Pakketten uit Git, een lokale map of een workspace worden overgeslagen, omdat er geen openbare gegevens over zijn. Bij Python, Ruby en Rust ook pakketten uit een ander register. Privépakketten van npm en Composer blijven in het project, maar hun namen gaan nergens heen.

  • JavaScript: npm-lockfileversies 1, 2 en 3, Yarn 1 en Yarn 2 of nieuwer, en pnpm 5, 6 en 9. Yarn en pnpm installeren uit de npm-registry, dus hun pakketten zijn in Ladon npm-pakketten.
  • PHP: plugins en themes van WordPress Packagist tellen als WordPress-software.
  • Python: requirements.txt telt alleen vastgezette regels zoals django==4.2.7, zoals pip freeze en pip-compile ze schrijven. Een bestand met een naam als requirements-dev.txt of requirements-test.txt telt als dev-afhankelijkheden. Uit een GitHub-repository leest Ladon alleen requirements.txt zelf.
  • Ruby en Rust: alleen gems van rubygems.org en crates van crates.io.
  • Go: go.mod. Sinds Go 1.17 staat daar elke module in die de build nodig heeft, en een module met // indirect is geen directe afhankelijkheid. Een replace naar een andere module telt op de versie van de vervanger, een module die door een lokale map vervangen wordt, wordt overgeslagen. De regel toolchain of go voegt de standaardbibliotheek toe als het pakket stdlib, op die versie. Ladon haalt advisories alleen uit de GitHub Advisory Database, en de meeste kwetsbaarheden in de standaardbibliotheek van Go staan daar niet in. Die zijn dus grotendeels nog niet gedekt.
  • Java: gradle.lockfile en pom.xml. Een Gradle-lockfile bevat alles wat Gradle ophaalt, en een pakket dat alleen in testconfiguraties staat, telt als dev-afhankelijkheid. Uit een pom.xml leest Ladon alleen de afhankelijkheden die de pom zelf noemt, met een versie die het uit de eigen properties of dependencyManagement kan halen. Parent-POM's en BOM's leest het niet, en versiebereiken en properties die het niet kan oplossen, slaat het over. Een project uit een pom.xml ziet dus alleen de directe afhankelijkheden, niet wat die binnenhalen. Wil je alles zien, zet dan dependency locking aan in Gradle en stuur de gradle.lockfile.

Meerdere lockfiles in één project

Een project kan meer dan één lockfile hebben, bijvoorbeeld een composer.lock voor de backend en een package-lock.json voor de frontend, of één per app in een monorepo. De pakketten van het project zijn ze allemaal samen. Een pakket dat in twee lockfiles staat, zie je één keer, en het telt als direct als een van de twee er direct om vraagt.

Ladon kent elke lockfile aan de naam, of aan het pad als hij uit een repository komt. Een nieuwe lockfile vervangt die met dezelfde naam, de andere blijven. Stuur je dus een nieuwe package-lock.json, dan blijft de composer.lock van het project zoals hij was.

Onder Pakketten op de projectpagina zie je de lockfiles van het project, elk met het pad, het aantal pakketten, waar hij vandaan kwam (Geüpload, Via de API of Uit GitHub) en wanneer hij gelezen is. Verwijder je daar een lockfile, dan verdwijnen de pakketten ervan uit het project. Een lockfile die Ladon uit een repository leest, komt bij de volgende controle terug, binnen ongeveer een half uur, zolang hij nog in de repository staat.

Een project toevoegen

Kies Toevoegen en dan Project toevoegen. Geef het project een naam en sla op. De naam kies je zelf: de repository, de klant of de app.

Kies daarna in het project Toevoegen aan project en kies wat het draait:

  • Lockfile: sleep een of meer lockfiles naar het veld of klik om ze te kiezen, als je wilt samen met de manifests. Er gaan tot 20 bestanden tegelijk. Een balk toont de upload, en Ladon leest de bestanden meteen.
  • GitHub-repository (betaalde abonnementen): Ladon leest elke lockfile in de repository en leest er een opnieuw als hij verandert. Zie Vanuit een GitHub-repository.
  • WordPress-plugins, themes of core, en gewone software, naast de lockfile.

De projectpagina begint met een samenvatting: hoeveel pakketten een bekende kwetsbaarheid hebben. Daaronder staan de bekende kwetsbaarheden per pakket, met de versie die ze oplost. Onder Pakketten vind je elk pakket dat Ladon uit de lockfiles las, met de geïnstalleerde en de nieuwste versie en of het direct of alleen voor ontwikkeling is. Zoek erin of filter op directe, dev- of kwetsbare pakketten om te controleren dat Ladon las wat je verwacht.

Elk project telt mee voor de projecten in je abonnement, zie Abonnementen en limieten. De pakketten uit de lockfiles tellen niet mee voor je watches. Software die je zelf toevoegt en gewone software wel, en dezelfde software in meerdere projecten telt één keer.

Up-to-date houden

Een lockfile verandert bij elke update van een afhankelijkheid, dus stuur na elke wijziging de nieuwe. Een project dat de lockfiles uit een GitHub-repository leest, blijft vanzelf up-to-date. Anders gaat het het makkelijkst vanuit CI, met de API en een token met de scope projects:write:

curl -X POST https://ladon.hackindex.io/api/v1/projects/$LADON_PROJECT/lockfile \
  -H "Authorization: Bearer $LADON_TOKEN" \
  -F "lockfile=@package-lock.json"

Elke andere lockfile uit de tabel, zoals composer.lock, poetry.lock, Cargo.lock, go.mod of gradle.lockfile, stuur je op dezelfde manier. Elke aanroep stuurt één lockfile en vervangt de lockfile van het project met dezelfde naam, de andere blijven. Heeft een project meer lockfiles, stuur ze dan elk in een eigen aanroep. Dezelfde lockfile nog een keer sturen verandert niets, dus je kunt dit gerust bij elke push naar je main-branch draaien. Een stap in GitHub Actions ziet er zo uit:

- name: Send lockfile to Ladon
  if: github.ref == 'refs/heads/main'
  run: |
      curl -fsS -X POST "https://ladon.hackindex.io/api/v1/projects/${{ vars.LADON_PROJECT }}/lockfile" \
        -H "Authorization: Bearer ${{ secrets.LADON_TOKEN }}" \
        -F "lockfile=@package-lock.json"

Het antwoord bevat het hele rapport. Wil je een build laten falen op kritieke kwetsbaarheden, controleer dan data.summary.by_severity met jq:

curl -fsS -X POST https://ladon.hackindex.io/api/v1/projects/$LADON_PROJECT/lockfile \
  -H "Authorization: Bearer $LADON_TOKEN" \
  -F "lockfile=@pnpm-lock.yaml" \
  | jq -e '.data.summary.by_severity.critical == 0'

Vanuit een GitHub-repository

Bij de betaalde abonnementen kan een project een GitHub-repository volgen. Kies in het project Toevoegen aan project, dan GitHub-repository, en typ owner/repo of plak een link. Ladon volgt de repository voor de advisories die de makers publiceren en voor de releases, net als een gevolgde repository.

Zet Lees ook de lockfile uit deze repository aan en Ladon leest ook de lockfiles van het project eruit:

  • Ladon leest elke lockfile in de repository op de standaardbranch, in elke map. Per map leest het één lockfile per taal, de lockfile waar de tools van die taal de voorkeur aan geven, met het manifest uit dezelfde map als dat er ook staat.
  • Mappen met code van andere projecten of testdata worden overgeslagen: node_modules, vendor, .git, bower_components, fixtures, __fixtures__ en testdata.
  • Ladon leest maximaal 30 lockfiles per repository.
  • Ongeveer elk half uur kijkt Ladon welke lockfiles of manifests veranderden, en leest alleen die opnieuw. Een repository die via de GitHub App gelezen wordt, leest Ladon direct opnieuw na een push naar de standaardbranch die een lockfile of manifest raakt. Je hoeft ze niet vanuit CI te sturen. Een lockfile die uit de repository verdween, verdwijnt ook uit het project, met zijn pakketten. Vindt Ladon helemaal geen lockfile, dan houdt hij wat hij het laatst las, omdat dat vaker een hapering is dan dat alle lockfiles weg zijn.
  • Een lockfile die je zelf uploadt, op de projectpagina of via de API, wint van die op hetzelfde pad in de repository. De andere lockfiles uit de repository blijft Ladon gewoon lezen.
  • Haal je de repository uit het project, dan stopt het lezen. De pakketten die het laatst gelezen zijn, blijven. Hetzelfde gebeurt als een repository die via de GitHub App gelezen wordt, op GitHub verwijderd of gearchiveerd wordt.
  • Bij een repository die via de GitHub App gelezen wordt, toont de projectpagina de laatste push naar de standaardbranch: wanneer, de commit en wie pushte. Verder bewaart Ladon niets van een push.
  • Staat er in de repository geen lockfile die Ladon leest, dan volgt het project alleen de advisories en releases van de repository.

Een team dat naar Free gaat, houdt wat het laatst gelezen is, maar Ladon leest het niet meer opnieuw.

Privérepositories

Een privérepository heeft de GitHub App van Ladon nodig, bij de betaalde abonnementen. Owners en admins koppelen hem één keer voor het team:

  1. Open het tabblad GitHub van het team en kies GitHub koppelen.
  2. Installeer de app op je GitHub-account of organisatie en kies de repositories die Ladon mag lezen. Die keuze pas je op elk moment aan op GitHub.
  3. Kies in een project Toevoegen aan project, dan GitHub-repository. Kies onder Uit je GitHub App een repository en kies Lockfile lezen.

Ladon leest de lockfiles van een privérepository op dezelfde manier als die van een openbare. De GitHub App is alleen voor lockfiles. Ladon leest geen advisories of releases van een privérepository. Wat de app wel en niet ziet, staat bij Teams en beveiliging.

Ontkoppel je de app, verwijder je hem op GitHub of haal je een repository uit de selectie, dan houden de projecten die erdoor lazen de pakketten die het laatst gelezen zijn, maar worden ze niet meer bijgewerkt.

Dev-afhankelijkheden

Dev-afhankelijkheden, zoals testtools en buildtools, komen niet op je servers terecht. Standaard geeft een project er geen meldingen voor, maar het rapport toont ze wel. Wil je er ook meldingen voor, bewerk dan het project en zet Ook melden voor dev-afhankelijkheden aan.

De meeste lockfiles zeggen welke pakketten alleen voor ontwikkeling zijn. yarn.lock, Gemfile.lock en Cargo.lock doen dat niet, dus voeg het manifest toe, zoals package.json, Gemfile of Cargo.toml, en Ladon zoekt het uit voor je directe afhankelijkheden. In de API stuur je dat mee in manifest.

Waarover je hoort

Een project maakt één watch per pakket, op de versies die je installeert. Het project kiest niet welke meldingen je krijgt: dat doen de kanalen ervan, elk met eigen soorten events en een eigen ernstfilter. Een project bepaalt alleen of dev-afhankelijkheden meetellen, zie Dev-afhankelijkheden, en welke tags de watches krijgen. Raakt een nieuwe kwetsbaarheid een van die versies, dan krijg je vulnerability.created zoals bij elke watch, en patch.released zodra de oplossing te installeren is.

Gebruiken twee projecten hetzelfde pakket, dan heeft elk project een eigen watch, en elk stuurt naar de eigen kanalen. Voor de watches in je abonnement telt de software één keer.

Daarnaast zijn er drie soorten events voor projecten:

  • project.vulnerable: een nieuwe lockfile voegt versies met bekende kwetsbaarheden toe, bijvoorbeeld na een update die een oudere versie van een afhankelijkheid binnenhaalde.
  • project.resolved: een nieuwe lockfile heeft geen bekende kwetsbaarheden meer.
  • package.malicious: een npm-pakketversie die je installeert blijkt malware te bevatten. Ladon kent voorlopig alleen malware in npm-pakketten. Dit is altijd kritiek: verwijder het pakket en vervang de secrets waar die machine bij kon.

Tags op een project gaan mee naar de watches, dus een kanaal met een tagfilter krijgt de meldingen van de watches met die tag. Zie Kanalen.

Gewone software

Naast WordPress en packages kun je gewone serversoftware en besturingssystemen volgen: PHP, Apache HTTP Server, Apache Tomcat, nginx, OpenSSL, MySQL, MariaDB, Node.js, Redis, PostgreSQL, Synology SRM, VMware ESXi, VMware vCenter Server, Windows Server, Windows 10, Windows 11, macOS, FreeBSD, de Linux-kernel, Red Hat Enterprise Linux, Debian, Ubuntu, Fedora en CentOS. De lijst is gecureerd en groeit na verloop van tijd.

Kies bij Toevoegen aan project voor Gewone software en zoek het product op naam. Ladon toont hoeveel CVE's het nu raakt. Je kunt de geïnstalleerde versie opgeven, of hem leeg laten om over elke versie te horen. Deze producten worden aan CVE's gekoppeld via hun CPE, de standaardaanduiding voor een product, niet via losse namen, dus je krijgt de echte CVE's met weinig ruis. Een kritieke PHP- of OpenSSL-release bereikt je net als elke andere melding.

Gewone software in een project maakt een CVE-regel voor dat project, die Ladon voor je beheert en die geen plek inneemt bij de regels in je abonnement. De meldingen komen uit de CVE-feed en gaan naar elk actief kanaal van het project, ook een Discord-kanaal. Anders dan bij een CVE-regel die je zelf maakt, volgen ze het ernstfilter van elk kanaal. Volgen twee projecten hetzelfde product, dan heeft elk project een eigen regel met een eigen versie.

WordPress-sites

Installeer de HackIndex Ladon-plugin uit de pluginmap van WordPress.org, of zoek op "HackIndex Ladon" in het scherm Plugins in wp-admin. Open daarna Instellingen → Ladon, klik op Connect to Ladon en log in. Er wordt niets verstuurd voordat je koppelt.

Een gekoppelde WordPress-site hoort bij één project. Als je een site koppelt, kies je eerst het team en dan het project. Het standaardproject van het team staat al geselecteerd. Ladon volgt de plugins en themes van de site in dat project, en de meldingen gaan naar de kanalen van dat project. Koppel de site opnieuw en kies een ander project om hem te verhuizen, de software gaat mee. Het tabblad Sites van het project toont de sites, wanneer ze voor het laatst contact hadden, en daar ontkoppel je er een.

Het standaardproject

Elk team heeft een standaardproject. Dat staat geselecteerd als je een site koppelt, en de API gebruikt het als een verzoek geen project noemt.

Teams die al bestonden voordat alles in projecten zat, zijn voor je overgezet. Alles van het team kwam in het standaardproject: het enige project, anders het project "Mijn software", anders het oudste. Een team zonder projecten kreeg een project met de naam "General". Software die in meerdere projecten zat, kreeg in elk daarvan een watch. Oude links naar pagina's van het team gaan naar het standaardproject.

Watches die je zelf maakte

Volg je een pakket al zelf in hetzelfde project, dan wint jouw watch: het project verandert de versies en meldingen daarvan niet, en jouw watch houdt zijn eigen soorten events en ernstfilter. De watches die een project maakt, wijzig je op het project zelf. Ze blijven buiten de watches-API.

Een project verwijderen

Een project verwijderen haalt alles erin weg: het rapport, de watches, ook die je zelf maakte, de kanalen, de CVE-regels en de gekoppelde sites. Verhuis eerst wat je wilt houden naar een ander project, bijvoorbeeld door een site opnieuw te koppelen in een ander project. Na een downgrade worden de nieuwste projecten die niet meer in het abonnement passen gepauzeerd: ze houden hun pakketten, maar geven geen meldingen tot er weer ruimte is.