# Vulnerability SQLite Builder – Schema v3

**Basis:** bereitgestellte `build.py` und bestehendes modulares Builder-Projekt. Das Paket enthält einen vollständigen Satz aus `scripts/build.py`, `scripts/sync_sources.py`, `scripts/run.sh`, `importers/`, `sql/schema.sql`, Tests und einem Workflow-Beispiel. Die vorhandene produktive `.gitea/workflows/build.yml` wird durch die Datei `.example` nicht ersetzt.

## Was Version 3 kann

- CVEProject, NVD, OSV und Red Hat CSAF indexieren; 12 weitere angebundene Repositories werden als `unsupported` in `sources` dokumentiert.
- NVD-CPE-Bedingungsbäume in `cpe_nodes` und `cpe_matches.node_id` **verlustfrei hinsichtlich AND/OR/negate-Baumstruktur** erfassen. Die CPE-Matches sind nicht als voneinander unabhängige Treffer zu interpretieren.
- Red Hat CSAF Advisory-IDs, CVE-Zuordnungen, Produktbäume, Produktstatus und Remediations erhalten (JSON).
- `sources` liefert `revision`, `indexed`, `documents`, `last_sync`, `last_import`, `import_status`, `import_errors`.
- `source-manifest.json` enthält nach erfolgreicher Synchronisierung pro Repo `synced_at`. `last_sync` enthält den Zeitstempel aus diesem Manifest, falls die Revision passt. Bei fehlendem oder altem Manifest bleibt das Feld `NULL`.
- `last_import` wird nur bei einem neu erzeugten Master für erfolgreich indexierte Quellen aktualisiert. Bei `NO_CHANGES` wird die Datenbank **absichtlich nicht neu geschrieben**; für die jüngste Synchronisierung siehe die JSON-Datei `source-manifest.json`.
- Die neue SQLite-Datenbank hat Schema-Version 3. Bei Umstellung von Version 1 oder 2 wird **kein inkompatibles Delta** angeboten; ein neuer Master ist notwendig.
- Schema-3-Deltas enthalten auch `sources`, `meta`, `cpe_nodes` und die beiden Red-Hat-Tabellen. Ein Delta muss **vollständig in einer Transaktion** mit `PRAGMA defer_foreign_keys=ON` angewandt werden. Das Update-Protokoll im Scanner muss diese Tabellen sowie das Schema kennen.

## Workflow / persistenter Cache

Die vorhandene Workflow-Datei soll den **im Job-Container** eingebundenen Pfad verwenden:

```yaml
env:
  CACHE_ROOT: /vuln-cache/vuln-builder
  SOURCE_READ_TOKEN: ${{ secrets.GITEA_TOKEN }}
```

Mit deinem Docker-Runner `-v /opt/gitea-builder/cache:/vuln-cache` bedeutet das auf dem Docker-Host:
`/opt/gitea-builder/cache/vuln-builder/releases/`.

Die Runner-Konfiguration selbst muss den Docker-Host-Pfad als Quellverzeichnis mounten (siehe bestehende Konfiguration).

Manueller Build im Job-Container:

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

Testlauf, wenn `zstd` und `git` verfügbar sind:

```bash
python3 -m unittest discover -s tests -v
```

Datenbank prüfen:

```bash
sqlite3 /opt/gitea-builder/cache/vuln-builder/releases/master.db \
  'SELECT name,indexed,documents,last_sync,last_import,import_status FROM sources ORDER BY name;'
```

## Sicherheits- und Funktionsgrenzen

- Nicht als vollständig implementierter Vulnerability-Matcher verwenden: OSV-GIT-Ranges, Produktbeziehungen und NVD-Baum-Auswertung müssen vom Scanner semantisch korrekt interpretiert werden.
- `import_status=unsupported` bedeutet **kein Importer vorhanden**, nicht „keine Schwachstellen“.
- Importfehler brechen die Veröffentlichung ab; deshalb erscheint `failed` nicht in einer erfolgreich veröffentlichten Master-DB. Das Fehlerprotokoll steht im Actions-Log.
- Der `schema.sql`-Satz ist für den **Neuaufbau** gedacht. Auf eine bereits vorhandene SQLite-Datei aufgerufen, führen `CREATE TABLE IF NOT EXISTS` keine Spaltenmigration durch. Vorhandene Master werden vom Builder separat aufgebaut und erst nach Erfolg ersetzt.
- Aufbewahrung alter `delta-*.zst` Dateien ist unverändert. Scanner müssen die aus `manifest.json` bestätigte Version verwenden.