Dependency-Checks — Lizenzen, Security, Supply-Chain

Automatische Pruefungen fuer die npm-Dependencies. Teil von yarn kumiko check. Verhindert dass eine falsche Lizenz oder bekannte Schwachstelle unbemerkt ins Framework oder in Kumiko-basierte Apps wandert.

Prinzipien

Hart gegen problematische Lizenzen: Allowlist-basiert, nicht Denylist. Unbekannte Lizenz = Fehler (erzwingt Review).
Pro-Package-Exceptions mit Begruendung: wer eine Ausnahme will, muss sie eintragen + warum.
Teil von yarn kumiko check — laeuft in CI, nicht nur manuell.
Report auch als Artefakt: SBOM + Lizenz-Liste exportierbar (fuer Legal/Customer-Due-Diligence).

Check 1 — Lizenz-Compliance

Allowlist (diese Lizenzen sind ok)

Lizenz	Warum ok
MIT	Permissive, Standard
ISC	Permissive, aequivalent zu MIT
Apache-2.0	Permissive, mit Patent-Grant
BSD-2-Clause, BSD-3-Clause	Permissive
0BSD	Public-Domain-aehnlich
Unlicense	Public-Domain
CC0-1.0	Public-Domain
BlueOak-1.0.0	Permissive, Modern
Python-2.0	Permissive

Graue Zone (case-by-case, Exception noetig)

Lizenz	Problem	Wann ok
LGPL-2.1, LGPL-3.0	File-level Copyleft	Oft ok wenn nur als Dependency genutzt, nicht modifiziert. Pflicht-Attribution. Case-by-case.
MPL-2.0	File-level Copyleft	Aehnlich LGPL. Oft ok.
CDDL-1.0, CDDL-1.1	File-level Copyleft	Rare, Einzelfall
CC-BY-*	Attribution-Pflicht	Fuer Content-Assets ok, fuer Code problematisch

Denylist (blockt sofort)

Lizenz	Warum blockiert
GPL-1.0, GPL-2.0, GPL-3.0	Strong Copyleft — wuerde Kumiko zwingen GPL zu werden
AGPL-1.0, AGPL-3.0	Noch staerker — auch bei Netz-Service-Nutzung
SSPL-1.0 (MongoDB)	Service-Side-Public-License — effektiv SaaS-blockend
BUSL-1.1 (Business Source License)	Zeitverzoegerte Quellcode-Freigabe, kommerziell beschraenkt
Commons-Clause	Verbietet kommerzielle Nutzung
Custom / proprietary / UNLICENSED	Unklare Rechte, default-deny

Unbekannt / fehlend

Package ohne license-Feld in package.json → Fehler (darf nicht ins Projekt)
license-Feld hat Wert den wir nicht klassifizieren koennen → Fehler (manueller Review-Gate)

Exception-Mechanismus

Eine Datei dependency-license-exceptions.json im Repo-Root:

{
  "exceptions": [
    {
      "package":  "some-lgpl-lib",
      "version":  "^2.0.0",
      "license":  "LGPL-3.0",
      "reason":   "Nur als Dependency genutzt, nicht modifiziert. Attribution in NOTICES.md.",
      "reviewedBy": "Marc, 2026-03-14",
      "expires":  "2027-03-14"
    }
  ]
}

Laeuft ab → Re-Review noetig. Script warnt 30 Tage vor Ablauf.

Implementation

scripts/check-licenses.ts:

// Pseudocode
for each installed package (yarn list --production):
  readPkgJson(pkgPath)
  license = normalize(pkgJson.license)

  if license in ALLOWLIST:
    ok, collect for NOTICES
  else if license in DENYLIST:
    unless in exceptions[]: FAIL
  else if license in GRAY:
    unless in exceptions[]: WARN (CI blocks)
  else:
    # unbekannt
    unless in exceptions[]: FAIL

Tool-Basis: license-checker-rseidelsohn (npm) oder direkt yarn licenses list --json parsen. Letzteres ist weniger Dep und fuer Yarn 1 integriert.

Output-Beispiel

yarn kumiko check licenses

✅ 347 packages — Lizenzen ok
⚠️  2 packages — Lizenzen in grauer Zone (mit Exception):
    - some-lgpl-lib@2.1.3 (LGPL-3.0) — reviewed 2026-03-14, expires 2027-03-14
    - another-mpl@1.0.0 (MPL-2.0) — reviewed 2026-03-14, expires 2027-03-14

❌ 1 package — BLOCKIERT:
    - bad-gpl-dep@3.0.0 (GPL-3.0)
      No exception. Either remove this dep or add a signed-off exception.

❌ 2 packages — UNKNOWN LICENSE:
    - weird-package@0.1.0 (undefined)
    - another-one@1.0.0 ("SEE LICENSE IN LICENSE.md")
      Manual review required. Add to dependency-license-exceptions.json if ok.

Exit code: 1

NOTICES-File-Generierung

Als Nebenprodukt erzeugt das Script ein NOTICES.md:

# Third-Party Notices

Kumiko depends on the following open-source packages:

## MIT-licensed
- package-a@1.2.3 (MIT) — Copyright ...
- ...

## Apache-2.0-licensed
- package-b@4.5.6 (Apache-2.0) — Copyright ...
- ...

## LGPL (with exception)
- some-lgpl-lib@2.1.3 — Copyright ...
  Reason for use: ...

NOTICES.md wird in jedes Kumiko-Release mitgeliefert. Erleichtert Customer-Due-Diligence und deckt Attribution-Pflichten.

Check 2 — Security / Vulnerabilities

Mechanismus

yarn npm audit (Yarn 1) oder yarn audit — nutzt npm’s Advisory-DB
Alternativ: snyk (hat bessere DB, aber Kosten) oder osv-scanner (Google, open source)

Konfiguration

Severity	Verhalten
`critical`	FAIL sofort
`high`	FAIL ausser Exception vorhanden
`moderate`	WARN, CI greift nicht ein
`low`	Silent

Exception-Mechanismus (kurzlebig)

{
  "exceptions": [
    {
      "advisory": "GHSA-abcd-1234",
      "package":  "lodash",
      "reason":   "Nur transitive, unser Nutzungspfad nicht betroffen.",
      "reviewedBy": "Marc, 2026-04-15",
      "expires":  "2026-05-15"  // max 30 Tage default
    }
  ]
}

Security-Exceptions haben kurze Halbwertszeit (30d default). Zwingt regelmaessigen Review.

Check 3 — Outdated Dependencies

Schwellen

Age	Verhalten
> 12 Monate Major-Version hinten	WARN
> 6 Monate Security-Patch verfuegbar	WARN (schon durch Check 2 abgedeckt)
Deprecated-Flag im Registry	FAIL

Nicht alle “outdated” blocken — viele Libs sind stabil genug um Monate zurueck zu sein. Deprecated-Flag dagegen ist hart.

Check 4 — SBOM-Export

Software Bill of Materials — Liste aller Dependencies + Versionen + Lizenzen, maschinenlesbar.

Format: CycloneDX JSON (Industry-Standard, von CISA + NTIA empfohlen).

yarn kumiko sbom > sbom.json

Output enthaelt:

Package-Namen + Versionen
Lizenzen
Hashes (fuer Supply-Chain-Verifikation)
Autor/Repository-URLs

Wird bei jedem Release erzeugt + als Artefakt gespeichert. Kunden koennen das anfordern fuer ihr eigenes Vendor-Management.

Check 5 — Supply-Chain (optional, v2)

Nicht v1, aber auf dem Radar:

lockfile-lint: prueft yarn.lock auf nur-offizielle-Registry (https://registry.yarnpkg.com oder https://registry.npmjs.org), verhindert Injection via Fremd-Registry
socket.dev-Integration: scant neue Dependencies auf verdaechtige Muster (Install-Script-Hooks, Network-Calls beim Install etc.)
Package-Signing-Verifikation (sigstore): wenn Upstream-Pakete signiert sind, checken

Integration in `yarn kumiko check`

Bestehender check wird erweitert:

yarn kumiko check
  → biome lint
  → tsc --noEmit
  → tsx scripts/lint-cross-feature.ts
  → tsx scripts/lint-new-date.ts
  → tsx scripts/check-licenses.ts         ← NEU
  → tsx scripts/check-security.ts         ← NEU
  → tsx scripts/check-outdated.ts         ← NEU (WARN-only default)
  → vitest run
  → vitest run integration

Plus Einzel-Subcommands:

yarn kumiko licenses                      # Lizenz-Report anzeigen
yarn kumiko licenses --fix                # NOTICES.md regenerieren
yarn kumiko security                      # Security-Audit
yarn kumiko sbom                          # SBOM auf stdout

Config

dependencyChecks: {
  licenses: {
    allowlist: ["MIT", "ISC", "Apache-2.0", ...],
    denylist:  ["GPL-*", "AGPL-*", "SSPL-*", "BUSL-*", "Commons-Clause"],
    exceptionsFile: "dependency-license-exceptions.json",
    notices: {
      outputFile: "NOTICES.md",
      regenerateOnCheck: true,
    },
  },
  security: {
    failOn: ["critical", "high"],
    exceptionsFile: "dependency-security-exceptions.json",
    exceptionMaxDurationDays: 30,
  },
  outdated: {
    warnOnMajorBehindMonths: 12,
    failOnDeprecated: true,
  },
}

Sinnvolle Defaults — die meisten Apps brauchen nur diese.

Was NICHT im Scope ist

Automatische Lizenz-Text-Extraction in NOTICES.md (nur Hinweis, Attribution-Text ist Job des Maintainers)
Legal-Review-Automation — das Script weist auf, ein Mensch entscheidet
Cross-Repository-Compliance — jedes Kumiko-basierte Projekt macht seinen eigenen Check
Fix-Button: Script bietet Hinweise, aendert nichts automatisch (zu gefaehrlich)

Tests fuer die Checks selbst

scripts/__tests__/check-licenses.test.ts:

Mock-Package mit MIT → ok
Mock-Package mit GPL-3.0 ohne Exception → fail
Mock-Package mit GPL-3.0 mit Exception → ok (mit Warn)
Mock-Package mit abgelaufener Exception → fail mit Hinweis auf Ablauf
Mock-Package ohne license-Feld → fail
NOTICES.md-Generation korrekt

Build-Reihenfolge

scripts/check-licenses.ts — Grundversion mit Allowlist + Denylist + Exceptions
NOTICES.md-Generation
scripts/check-security.ts — ueber yarn npm audit
Integration in yarn kumiko check
dependency-*-exceptions.json Schemas + Templates
scripts/check-outdated.ts — WARN-only Start
yarn kumiko sbom — CycloneDX-Output
Post-Todos:
- Lockfile-lint (nur vertrauensvolle Registries)
- socket.dev-Integration
- Signatur-Verifikation via sigstore