Gate CI CLI (BYOT)

Uploader lockfile/SBOM CI avec le CLI CodeCleared : scan parallèle des project units et verdict.

Objectif

Utiliser le CLI CodeCleared en CI lorsque le serveur ne peut pas résoudre des dépendances privées (ex. Maven avec credentials de build). Le runner collecte l’arbre localement et l’envoie ; le scan reste lié au dépôt connecté, au project unit existant et au commitHash.

Qui

Ingénieurs qui branchent la quality gate CI. Les owners fournissent un service token.

Prérequis

Dépôt connecté, project units de dépendances actifs, accès API et crédits. Cloner le package CLI (codecleared.io/cli) et npm link — pas encore publié sur npm.

Étapes

export CODECLEARED_API_TOKEN=...
# override optionnel ; défaut https://api.codecleared.io/api
# export CODECLEARED_API_URL=https://api.example/api

codecleared scan \
  --full-name owner/repo \
  --commit "$COMMIT_SHA" \
  --branch main \
  --wait

Sans --project-unit-id, tous les PU matchables sont scannés en parallèle (Promise.all).
Avec --project-unit-id, un seul PU.
--artifact lockfile|sbom force le type d’artifact.
--scan-types sca (liste séparée par des virgules) limite les activités. Préférer sca pour Maven BYOT / deps privées. Autorisés : sbom, sca, license, dependency-advisor, secrets, sast, all.
Avec --wait, le summary ne contient que les clés des types demandés (sca → vulnerabilities seul ; pas de secrets / licenses vides).
Le verdict wait utilise apiGateSeverityThreshold org (défaut critical ; Paramètres → Scan defaults). FAIL si ≥1 vuln / secret au-dessus ou égal à ce seuil, ou licence non-compliant. Pas les Quality Gates ; distinct de prCheckSeverityThreshold (PR). Reasons : critical_* si seuil critical, sinon vulnerabilities_above_threshold / secrets_above_threshold. summary.severityThreshold reprend le seuil utilisé. Voir API scans.
Les entrées CLI skipped ont un kind : project-unit (PU hors scope), scan-type (activité non demandée sur un PU triggeré), artifact (échec de collecte).
--commit invalide / inaccessible → wait avec errorCode: branch_or_commit_not_found (orchestrateur marqué failed dans Temporal — pas un timeout client).
Un job qui dépasse les limites Temporal se termine avec errorCode: workflow_timeout (côté serveur) ; distinct du délai client --wait / API wait, qui peut expirer alors que le scan tourne encore.
Codes de sortie avec --wait : 0 PASS, 1 FAIL, 2 ERROR (API / timeout / système).

Contrats d’artifact

Écosystème	Artifact	Notes
npm / yarn / pnpm / pip / gem / Cargo / composer / gomod	Upload lockfile	Contenu brut + chemin (`go.sum` préféré, sinon `go.mod`)
Gradle	`*.gradle.lockfile`	Activer le dependency locking en CI
Maven	SBOM CycloneDX	Plugin CycloneDX Maven, puis upload `sbom`
secrets / sast	Aucun	Trigger seul (`sourceTrigger=api`) ; pas BYOT

Ne pas installer/exécuter les scanners serveur sur le runner. L’analyse reste côté CodeCleared.

CLI vs curl Actions

Usage	Quand
CLI	Registries privés / creds Maven / arbre BYOT
curl `POST /v1/scans` sans artifact	Le serveur peut cloner et lire le lockfile (guide Actions)

Les deux chemins partagent le même credit gate (402). Un artifact force sourceTrigger=cli et désactive le dedup par commit (toujours un nouveau job).

Priorité snapshot & badge BYOT

Préférence « dernier scan » gouvernance : cli > api | push | manual-ui > scheduled (pr-event exclu). Dans l’UI, les résultats CLI affichent un badge BYOT : l’arbre vient du CI et peut différer d’un clone git serveur.

Limites

Corps ≤ 10 Mo par upload BYOT. Secrets/SAST peuvent être déclenchés depuis le CLI sans artifact (chemin API classique). Maven BYOT exige mvn dans le PATH ou un target/bom.json pré-généré ; un échec de collecte Maven n’annule pas les autres project units.