Integra CI e Dependency-Track¶

Questo documento spiega come abilitare e configurare le due funzionalità di qualità/sicurezza di gitrust:

1. La CI integrata (Dagger) che esegue build/test/lint a ogni push.
2. Il tracker delle dipendenze (Syft + Dependency-Track) che scansiona i componenti del codice ad ogni push e rileva le vulnerabilità conosciute.

Questi due sistemi sono indipendenti: è possibile attivarne uno senza l'altro.

1. Architettura generale¶

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

Tre componenti operano in parallelo:

• CiWorker: attività Tokio che utilizza CiTask da un canale mpsc, limitato da un Semaforo a pipeline simultanee CI_MAX_CONCURRENT.
• SbomService: eseguito in un tokio::spawn dopo ogni push, totalmente disaccoppiato dal CI.
• Build server: macchina remota (o localhost) che esegue Docker + Dagger. Gitrust invia lì lo spazio di lavoro tramite rsync e avvia Dagger tramite SSH.

2. Configurare l'elemento della configurazione¶

2.1 Creare i prerequisiti del server¶

Il server di compilazione può essere la stessa macchina di Gitrust (CI_REMOTE_HOST=localhost) o una macchina dedicata. Deve avere:

Installazione automatica consigliata:

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

Lo script esegue:

1. Controllo della connettività SSH
2. Installazione di Docker se assente
3. Installazione della CLI di Dagger se assente
4. Creazione della directory di lavoro remota
5. Sincronizzazione del motore ci
6. Prova del fumo (versioni)

2.2 Configurazione Gitrust (file .env)¶

Aggiungi a .env di Gitrust:

# 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

Riavvia Gitrust: systemctl restart gitrust (o cargo run --release).

2.3 Attivare la CI su un repository¶

Nell'interfaccia web: vai al repository → Impostazioni → CI.

• Seleziona CI abilitato (richiesto — predefinito false)
• Seleziona Trigger on push (attiva l'esecuzione a ogni push)
• Facoltativo: Annullamento automatico (annulla le pipeline correnti quando ne viene avviata una nuova)
• Facoltativo: Rami consentiti (ad esempio main,develop — vuoto = tutti)

2.4 Scegli la modalità: Facile o Potente¶

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

Modalità facile (consigliata per iniziare)¶

Crea .gitrust-ci.yml nella radice del repository:

# 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"

I profili disponibili si trovano in deployment/ci-engine/profiles/ (rust.yaml, python.yaml, node.yaml) nel repository dei sorgenti.

Modalità di alimentazione¶

Per gli utenti avanzati, crea un modulo Dagger completo in .dagger/:

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

La funzione ci del modulo viene chiamata direttamente:

dagger call -m .dagger/ ci

Vantaggio: accesso al Daggerverse, composizione, test della pipeline. Consulta la documentazione di Dagger.

2.5 Monitoraggio di una pipeline¶

Dopo un git push, viene visualizzata una voce nella scheda CI del repository:

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 --> [*]

I log stdout/stderr vengono trasmessi in streaming riga per riga nella tabella "ci_logs" e visibili in tempo reale nell'interfaccia utente. Se fallisce, viene inviata una notifica al proprietario del repository.

3. Configurare il monitoraggio delle dipendenze¶

Questa parte è completamente indipendente dal CI. Esegue la scansione del codice inviato e produce un SBOM CycloneDX, quindi (facoltativo) lo invia a Dependency-Track per la scansione delle vulnerabilità.

3.1 Installa Syft¶

Sulla macchina Gitrust (la scansione viene eseguita localmente, non sul 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 questa fase: con ogni push, viene generata e archiviata una SBOM CycloneDX (senza caricamento esterno). Visibile nella scheda Sicurezza del repository: numero di componenti, sha256 della distinta base.

3.2 Distribuire il tracciamento delle dipendenze¶

Dependency-Track è un'applicazione Java che memorizza SBOM ed è correlata ai database CVE/OSV/NVD. Distribuzione Docker consigliata:

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 Creare una chiave API¶

Nel tracciamento delle dipendenze → Amministrazione → Gestione degli accessi → Team:

1. Crea (o riutilizza) un team "gitrust".
2. Dategli i permessi:
3. "BOM_UPLOAD".
4. PROGETTO_CREAZIONE_CARICAMENTO
5. VISUALIZZA_PORTFOLIO
6. "VISUALIZZA_VULNERABILITÀ".
7. Genera una chiave API e copiala.

3.4 Configurare Gitrust¶

Aggiungi a .env:

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

Riavviare Gitrust. Ad ogni spinta:

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 Leggere i risultati¶

Scheda Sicurezza del repository → SBOM inserire:

• Numero di componenti rilevati
• Contatori per gravità: Critico / Alto / Medio / Basso
• Collegamento diretto al progetto in Dependency-Track (se l'UUID è risolto)
• Hash sha256 dalla distinta base (tracciabilità)

Se l'analisi di Dependency-Track impiega più di 30 secondi, lo stato rimane "in elaborazione" e uno spazzatore successivo cercherà i risultati.

4. Debug¶

Problemi comuni di CI¶

Problemi comuni della SBOM¶

Registri utili¶

# 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. Lista di controllo riepilogativa¶

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