# vuln-builder — modular (CVE / NVD / OSV)

**Ziel:** Bestehenden SQLite-Builder ohne Datenverlust modularisieren. Ein einzelner Gitea-Runner und ein einzelner Builder-Workflow reichen aus. Das SQL-Schema (v1), Delta-JSONL-Struktur und die Release-Dateinamen bleiben kompatibel zum bisherigen Builder. Die bereits vorhandenen 330-MB-Masterdateien werden **nicht** mitgeliefert.

## Dateien

```text
vuln-builder/
├── importers/
│   ├── __init__.py     # zentrale Registrierung
│   ├── common.py       # Datenbank- und ID-Helfer
│   ├── cve.py          # CVEProject V5
│   ├── nvd.py          # NVD-CVE direkt / Wrapper, einfache CPE-OR-Regeln
│   └── osv.py          # OSV-Aliasse und betroffene Pakete
├── scripts/
│   ├── sync_sources.py # bisheriger Gitea-Repo-Cache (übernommen)
│   ├── build.py        # Master + Delta + No-Change-Build
│   └── run.sh          # Synchronisierung und Build mit flock
├── sql/schema.sql      # bestehendes Tabellenlayout (v1)
├── tests/test_builder.py
└── .gitea/workflows/build.yml.example
```

## Produktiv übernehmen

1. Zuerst das bestehende `vuln-builder`-Repository **sichern**. `master.db`, `master.db.zst`, alle historischen Delta-Dateien und `manifest.json` an sicherer Stelle sichern.
2. Die vorhandenen Ordner `scripts/` und `sql/` nicht blind ersetzen: vorhandene eigene Workflow-/Script-Anpassungen vergleichen. Dieses Paket enthält die vollständigen drei vorhandenen Importer, den geposteten `sync_sources.py`, ein kompatibles SQL-Schema und ein Ausführungsskript.
3. Dateien nach `VULN/vuln-builder` kopieren, committen, nach `main` pushen.
4. Auf der Gitea-VM prüfen: `git`, `python3` (>= 3.9), `zstd`, `flock`, sowie Zugriff des Runner-Users auf `/opt/gitea-builder/cache/vuln-builder`.
5. Im **bereits vorhandenen** Builder-Workflow die eigentliche Build-Ausführung durch `bash scripts/run.sh` ersetzen; nicht gleichzeitig den Beispiel-Workflow aktivieren. Das Beispiel liegt absichtlich als `.example` vor.
6. Gitea Actions einmal manuell ausführen und `manifest.json` sowie `sources`-Tabelle prüfen.

## Lokaler Aufruf ohne Git-Synchronisierung

```bash
python3 scripts/build.py \
  --sources /opt/gitea-builder/cache/vuln-builder/sources \
  --output /opt/gitea-builder/cache/vuln-builder/releases
```

Mit Synchronisierung, bestehender `sources.json` aus `VULN/vuln-status` und Sperre:

```bash
CACHE_ROOT=/opt/gitea-builder/cache/vuln-builder bash scripts/run.sh
```

`SOURCE_READ_TOKEN` ist nur nötig, wenn die `sources.json` Authentifizierung verlangt. Das Originalskript setzt für private Git-Klone vorhandene Git-Credentials auf dem Host voraus; es übergibt `SOURCE_READ_TOKEN` **nicht** automatisch an Git. Bei bestehenden funktionierenden Checkouts brauchst du daran nichts zu ändern.

## No-Change und Delta

- Signatur über **alle Git-Quellrevisionen**, Python-Builder- und Importerdateien und Schema.
- Wenn Signatur gleich und Master-Zstd-SHA stimmt: `NO_CHANGES`, keine neue Version.
- Im ersten Lauf mit dieser modularen Version wird vollständig neu gebaut, weil die Signatur anders ist.
- Bei verändertem Input schreibt der Builder `master.db`, `master.db.zst`, `manifest.json` und `delta-<alt>-to-<neu>.jsonl.zst`.
- Historische Deltas werden nicht absichtlich gelöscht. Das Paket implementiert **keinen** automatischen Release-Uploader und **keinen** Delta-Client.

## Status anderer Quellen

Alle von `sync_sources.py` gelesenen Repositories werden weiterhin als Git-Checkouts synchronisiert. **Nur** `vuln-cve`, `vuln-nvd`, `vuln-osv` besitzen Importer. Die anderen erhalten in der Tabelle `sources` `indexed=0`, `documents=0`. Ein zusätzlicher Importer wird als `importers/<quelle>.py` angelegt und in `importers/__init__.py` registriert.

## Sicherheits- und Kompatibilitätshinweise

- Der NVD-Importer unterstützt direkt gespeicherte NVD-JSON-Datensätze und API-Wrapper `{ "cve": {...} }`.
- CVE-/OSV-Importer entsprechen dem konservativen v1-Ansatz und interpretieren keine komplexen Produkt-/Versionsbedingungen.
- **NVD AND/NOT-Konfigurationen werden nicht als unabhängige Matches abgelegt**. Der neue Parser lässt zusätzlich gesamte komplexe Konfigurationen weg, statt nur problematische Unterzweige herauszufiltern. Dadurch können CPE-Zahlen gegenüber früheren Builds sinken. Solche Fälle benötigen später eine eigene CPE-Bedingungsbaum-Tabelle.
- Die aktuelle v1-Speicherung ist **kein vollständig zuverlässiger Schwachstellenscanner**. Insbesondere fehlen präzise NVD-Bedingungsbäume und herstellerspezifische Importer.
- Ein fehlgeschlagener Parser unterbricht den Release-Build. Der letzte veröffentlichte Master bleibt erhalten, sofern die Fehler vor der finalen Veröffentlichung auftreten.
- Release-Manifest wird als Letztes ersetzt. Die eigentlichen Release-Dateien werden nacheinander ersetzt; für externe Downloader sind unveränderliche Release-Verzeichnisse sinnvoll.