# Projecten en lockfiles

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 {#contents}

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](#common) van het project, met het rapport.
- **CVE-monitor**: de [CVE-regels](https://ladon.hackindex.io/nl/docs/cve-rules.md) 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](https://ladon.hackindex.io/nl/docs/channels.md).
- **Sites**: de WordPress-sites die aan het project gekoppeld zijn, zie [WordPress-sites](#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](https://ladon.hackindex.io/nl/docs/watches.md#ecosystems) 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 {#lockfiles}

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](#github).
- WordPress-plugins, themes of core, en [gewone software](#common), 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](https://ladon.hackindex.io/nl/docs/plans-and-limits.md). 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 {#ci}

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](#github) leest, blijft vanzelf up-to-date. Anders gaat het het makkelijkst vanuit CI, met de [API](https://ladon.hackindex.io/nl/docs/api.md) en een token met de scope `projects:write`:

```bash
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:

```yaml
- 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`:

```bash
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 {#github}

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](https://ladon.hackindex.io/nl/docs/watches.md#github).

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 {#github-app}

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](https://ladon.hackindex.io/nl/docs/teams-and-security.md#github).

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-dependencies}

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](https://ladon.hackindex.io/nl/docs/channels.md) ervan, elk met eigen soorten events en een eigen ernstfilter. Een project bepaalt alleen of dev-afhankelijkheden meetellen, zie [Dev-afhankelijkheden](#dev-dependencies), 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](https://ladon.hackindex.io/nl/docs/channels.md#tags).

## Gewone software {#common}

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](https://ladon.hackindex.io/nl/docs/cve-rules.md) 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 {#sites}

Installeer de [HackIndex Ladon-plugin](https://wordpress.org/plugins/hackindex-ladon/) 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 {#default}

Elk team heeft een standaardproject. Dat staat geselecteerd als je een site koppelt, en de [API](https://ladon.hackindex.io/nl/docs/api.md) 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.
