vuln-builder/README.md

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:

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:

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

Testlauf, wenn zstd und git verfügbar sind:

python3 -m unittest discover -s tests -v

Datenbank prüfen:

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.