Integrieren Sie CI und Dependency-Track¶

In diesem Dokument wird erläutert, wie Sie die beiden Qualitäts-/Sicherheitsfunktionen von Gitrust aktivieren und konfigurieren:

1. Das integrierte CI (Dagger), das die Builds/Tests/Lints bei jedem Push ausführt.
2. Der Abhängigkeits-Tracker (Syft + Dependency-Track), der Codekomponenten bei jedem Push scannt und bekannte Schwachstellen erkennt.

Diese beiden Systeme sind unabhängig: eines kann ohne das andere aktiviert werden.

1. Allgemeine Architektur¶

flowchart TB
  subgraph Client
    Dev[Développeur]
  end
  subgraph Gitrust[Instance Gitrust]
    HTTP[:4000 HTTP/Git]
    SSH[:2222 SSH/Git]
    Worker[CiWorker
tokio task]
    Sbom[SbomService
tokio spawn]
    DB[(PostgreSQL)]
  end
  subgraph Builder[Serveur de build]
    Docker[Docker/Podman]
    Dagger[Dagger CLI]
    CiEngine[/opt/gitrust-ci/ci-engine/]
  end
  subgraph Security[Stack sécurité optionnelle]
    Syft[syft]
    Dtrack[Dependency-Track]
  end

  Dev -->|git push| HTTP
  Dev -->|git push| SSH
  HTTP --> Worker
  SSH --> Worker
  HTTP --> Sbom
  SSH --> Sbom
  Worker -->|SSH + rsync| Builder
  Builder -->|logs streamés| Worker
  Worker --> DB
  Sbom -->|scan workspace| Syft
  Sbom -->|PUT BOM| Dtrack
  Dtrack -->|findings| Sbom
  Sbom --> DB

Drei Komponenten arbeiten parallel:

• CiWorker: Tokio-Task, die „CiTask“ von einem „mpsc“-Kanal verbraucht, begrenzt durch ein „Semaphore“ auf „CI_MAX_CONCURRENT“ gleichzeitige Pipelines.
• SbomService: wird nach jedem Push in einem „tokio::spawn“ ausgeführt, völlig entkoppelt vom CI.
• Build-Server: Remote-Maschine (oder „localhost“), auf der Docker + Dagger ausgeführt wird. Gitrust sendet den Arbeitsbereich per rsync dorthin und startet Dagger per SSH.

2. Richten Sie das CI ein¶

2.1 Servervoraussetzungen erstellen¶

Der Build-Server kann derselbe Computer wie Gitrust (CI_REMOTE_HOST=localhost) oder ein dedizierter Computer sein. Er muss haben:

Empfohlene automatische Installation:

# Depuis la machine Gitrust (l'utilisateur doit pouvoir SSH vers le builder)
./deployment/setup-remote-ci.sh .env

Das Skript führt Folgendes aus:

1. Überprüfung der SSH-Konnektivität
2. Docker installieren, falls nicht vorhanden
3. Installation der Dagger-CLI, falls nicht vorhanden
4. Erstellen des Remote-Arbeitsverzeichnisses
5. Synchronisation der „ci-engine“.
6. Rauchtest (Versionen)

2.2 Gitrust-Konfiguration (.env-Datei)¶

Zu Gitrusts „.env“ hinzufügen:

# Activer globalement le CI
CI_ENABLED=true

# Chemin du ci-engine sur le serveur de build
CI_ENGINE_PATH=/opt/gitrust-ci/ci-engine

# Limite de parallélisme
CI_MAX_CONCURRENT=4
CI_DEFAULT_TIMEOUT=3600
CI_WORKSPACE_PATH=/tmp/gitrust-ci

# Serveur de build (mettre localhost pour "même machine")
CI_REMOTE_HOST=builder.example.com
CI_REMOTE_USER=ci-runner
CI_REMOTE_PATH=/opt/gitrust-ci
CI_REMOTE_SSH_PORT=22
# CI_REMOTE_SSH_KEY=/home/gitrust/.ssh/id_ed25519   # si pas ssh-agent

Starten Sie Gitrust neu: „systemctl restart gitrust“ (oder „cargo run --release“).

2.3 CI in einem Repository aktivieren¶

Im Webinterface: Gehen Sie zum Repository → Einstellungen → CI.

• Überprüfen Sie CI aktiviert (erforderlich – Standardwert „false“)
• Aktivieren Sie Trigger on Push (aktiviert die Ausführung bei jedem Push)
• Optional: Automatisch abbrechen (bricht aktuelle Pipelines ab, wenn eine neue startet)
• Optional: Erlaubte Zweige (z. B. „main,develop“ – empty = alle)

2.4 Wählen Sie den Modus: Einfach oder Power¶

flowchart LR
  Push[Commit
poussé] --> Tree{Arbre du
commit contient ?}
  Tree -->|.dagger/| Power[Mode Power
dagger call -m .dagger/ ci]
  Tree -->|.gitrust-ci.yml| Easy[Mode Easy
dagger call -m ci-engine test-pr]
  Tree -->|rien| None[Pas de pipeline]
  Power --> Run[Exécution
distante SSH]
  Easy --> Run

Einfacher Modus (zum Starten empfohlen)¶

Erstellen Sie „.gitrust-ci.yml“ im Stammverzeichnis des Repositorys:

# Raccourci : charge un profil pré-configuré (rust | python | node)
language: rust

build:
  command: "cargo build --release"

checks:
  lint: "cargo clippy -- -D warnings"
  format: "cargo fmt -- --check"

tests:
  command: "cargo test --release"

Die verfügbaren Profile befinden sich unter „deployment/ci-engine/profiles/“ (rust.yaml, python.yaml, node.yaml) im Quell-Repository.

Power-Modus¶

Für fortgeschrittene Benutzer erstellen Sie ein vollständiges Dagger-Modul in „.dagger/“:

.dagger/
├── dagger.json
├── src/
│   └── main.py         # ou Go/TypeScript

Die „ci“-Funktion des Moduls wird direkt aufgerufen:

dagger call -m .dagger/ ci

Vorteil: Zugang zum Daggerverse, Zusammensetzung, Pipeline-Tests. Siehe die Dagger-Dokumentation.

2.5 Überwachung einer Pipeline¶

Nach einem „Git Push“ erscheint ein Eintrag im CI-Tab des Repositorys:

stateDiagram-v2
  [*] --> Pending: create_pipeline
  Pending --> Running: worker picks CiTask
  Running --> Success: exit 0
  Running --> Failure: exit != 0
  Running --> Cancelled: timeout / auto_cancel / manuel
  Success --> [*]
  Failure --> [*]
  Cancelled --> [*]

Die stdout/stderr-Protokolle werden Zeile für Zeile in der Tabelle „ci_logs“ gestreamt und sind live in der Benutzeroberfläche sichtbar. Wenn dies fehlschlägt, wird eine Benachrichtigung an den Repository-Eigentümer gesendet.

3. Richten Sie den Dependency Tracker ein¶

Dieser Teil ist völlig unabhängig vom CI. Es scannt den gepushten Code, erstellt ein CycloneDX-SBOM und sendet es dann (optional) zur Schwachstellenprüfung an Dependency-Track.

3.1 Syft installieren¶

Auf der Gitrust-Maschine (der Scan erfolgt lokal, nicht auf dem Builder):

# Installation officielle
curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh \
  | sh -s -- -b /usr/local/bin

# Vérification
syft --version

In „.env“:

CI_SBOM_ENABLED=true
CI_SYFT_BIN=/usr/local/bin/syft   # optionnel, défaut: syft dans PATH

In dieser Phase: Bei jedem Push wird eine CycloneDX-SBOM generiert und gespeichert (ohne externen Upload). Sichtbar auf der Registerkarte Sicherheit des Repositorys: Anzahl der Komponenten, SHA256 der Stückliste.

3.2 Dependency-Track bereitstellen¶

Dependency-Track ist eine Java-Anwendung, die SBOM speichert und mit CVE/OSV/NVD-Datenbanken korreliert. Empfohlene Docker-Bereitstellung:

mkdir -p /opt/dtrack && cd /opt/dtrack
curl -L -o docker-compose.yml \
  https://dependencytrack.org/docker-compose.yml
docker compose up -d

L'API est disponible sur http://localhost:8081 et l'UI sur http://localhost:8080. Login initial : admin / admin (à changer immédiatement).

3.3 Erstellen Sie einen API-Schlüssel¶

In Dependency-Track → Administration → Zugriffsverwaltung → Teams:

1. Erstellen Sie ein „Gitrust“-Team (oder verwenden Sie es wieder).
2. Erteilen Sie ihm Berechtigungen:
3. „BOM_UPLOAD“.
4. „PROJECT_CREATION_UPLOAD“.
5. „VIEW_PORTFOLIO“.
6. „VIEW_VULNERABILITY“.
7. Generieren Sie einen API-Schlüssel und kopieren Sie ihn.

3.4 Gitrust konfigurieren¶

Zu „.env“ hinzufügen:

CI_DTRACK_ENABLED=true
CI_DTRACK_URL=http://localhost:8081
CI_DTRACK_API_KEY=odt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Starten Sie Gitrust neu. Bei jedem Druck:

sequenceDiagram
  participant Push as post-receive
  participant Sbom as SbomService
  participant Git as git archive
  participant Syft
  participant Dtrack as Dependency-Track
  participant DB as sbom_reports

  Push->>Sbom: process_push(sha, ref)
  Sbom->>DB: upsert status=pending
  Sbom->>Git: archive sha | tar -x tmpdir
  Sbom->>Syft: scan dir:tmpdir -o cyclonedx-json
  Syft-->>Sbom: BOM bytes
  Sbom->>DB: update sha256
  Sbom->>Dtrack: PUT /api/v1/bom (base64)
  Dtrack-->>Sbom: token
  loop max 30s
    Sbom->>Dtrack: GET /api/v1/bom/token/{token}
    Dtrack-->>Sbom: processing ?
  end
  Sbom->>Dtrack: GET /api/v1/finding/project/{uuid}
  Dtrack-->>Sbom: findings[]
  Sbom->>DB: update status=success
+ critical/high/medium/low

3.5 Lesen Sie die Ergebnisse¶

Registerkarte Sicherheit des Repositorys → SBOM-Einfügung:

• Anzahl der erkannten Komponenten
• Zähler nach Schweregrad: Kritisch / Hoch / Mittel / Niedrig
• Direkter Link zum Projekt in Dependency-Track (wenn UUID aufgelöst ist)
• Hash sha256 aus der Stückliste (Rückverfolgbarkeit)

Wenn die Analyse von Dependency-Track mehr als 30 Sekunden dauert, bleibt der Status „in Bearbeitung“ – ein nachfolgender Sweeper wird nach den Ergebnissen suchen.

4. Debuggen¶

Häufige CI-Probleme¶

Häufige SBOM-Probleme¶

Nützliche Protokolle¶

# Logs Gitrust (systemd)
journalctl -u gitrust -f | grep -E "CI|SBOM|sbom|pipeline"

# Vérifier un pipeline en DB
psql $DATABASE_URL -c "SELECT id, status, commit_sha, created_at FROM ci_pipelines ORDER BY created_at DESC LIMIT 10;"

# Vérifier un SBOM
psql $DATABASE_URL -c "SELECT commit_sha, status, components_count, critical_count, high_count FROM sbom_reports ORDER BY created_at DESC LIMIT 10;"

5. Zusammenfassende Checkliste¶

CI : - [ ] Docker + Dagger installés sur le serveur de build (setup-remote-ci.sh) - [ ] CI_ENABLED=true et CI_REMOTE_* dans .env - [ ] Gitrust redémarré - [ ] CI activée dans Settings → CI pour chaque dépôt - [ ] Fichier .gitrust-ci.yml (Easy) ou .dagger/ (Power) commité - [ ] Push → pipeline visible dans l'onglet CI

Dependency Tracker : - [ ] Syft installé sur la machine Gitrust - [ ] CI_SBOM_ENABLED=true dans .env - [ ] (Optionnel) Dependency-Track déployé + API key créée avec les 4 permissions - [ ] (Optionnel) CI_DTRACK_ENABLED=true, CI_DTRACK_URL, CI_DTRACK_API_KEY dans .env - [ ] Gitrust redémarré - [ ] Push → SBOM visible dans l'onglet Security