Aller au contenu
CodeCleared Docs
ApplicationEnglish
Publié

Dernière revue: 2026-09-08

Scans API

Créez des analyses CodeCleared avec UUID de dépôt et commitHash, attendez sans doublon et gérez unités de projet, crédits et délais.

Objectif

Utilisez cette API pour créer une analyse autorisée sur un dépôt connecté et en suivre la fin. Authentifiez chaque requête avec Authorization: Bearer <service-token>.

Prérequis

Il faut un jeton API / service token avec accès à l’organisation, un dépôt connecté, et un pool de crédits éligible. L’accès API est en général Team ou supérieur.

Étapes

  1. Résolvez le nom humain du dépôt : GET /v1/repositories/resolve?fullName=owner/repo.
  2. Lisez l’UUID de dépôt renvoyé.
  3. Créez l’analyse avec POST /v1/scans et repositoryId plus commitHash.
  4. Passez éventuellement branch, projectUnitId ou scanTypes.
  5. Attendez avec GET /v1/scans/:id/wait?timeout=300&interval=10.
{ "repositoryId": "repository-uuid", "commitHash": "full-commit-hash", "branch": "main", "scanTypes": ["sca"] }

Vous pouvez aussi uploader un artifact construit en CI (CLI / BYOT) : XOR lockfile { "path", "content" } ou sbom (objet CycloneDX). Présent → sourceTrigger=cli, pas de dedup par commit, projectUnitId obligatoire. Corps ≤ 10 Mo. Sans artifact, chemin API classique (sourceTrigger=api).

{ "repositoryId": "repository-uuid", "projectUnitId": "pu-uuid", "commitHash": "full-commit-hash", "lockfile": { "path": "package-lock.json", "content": "..." } }

Règles métier

La création d’analyse exige l’UUID repositoryId et commitHash ; n’envoyez pas fullName ni commitSha. L’endpoint d’attente vaut 300 secondes par défaut et accepte un timeout maximum de 600 secondes. Un 402 signifie que crédits, droit d’offre ou licence MAU (seat_license_required) sont indisponibles, pas que le JSON est mal formé. Les uploads d’artifact partagent le même credit gate.

Scénarios et cas limites

Resolve échoue : vérifiez le owner/repo exact et la connexion du dépôt. Wait expire : gardez l’ID d’analyse, interrogez plus tard, et ne créez pas de doublon parce que le client a arrêté d’attendre. Mauvaise unité de projet : vérifiez qu’elle appartient au dépôt avant soumission.
Périmètre partiel (scanTypes) : valeurs autorisées sbom, sca, license, dependency-advisor, secrets, sast, all. Ne précisez que ce dont votre workflow a besoin (ex. ["sca"] pour Maven BYOT). Types incompatibles avec l’unité → rejet ou skip.
summary du wait : clés limitées aux types demandés — ex. scanTypes: ["sca"] → seulement vulnerabilities (pas de secrets / licenses vides). Sans scanTypes / all → forme classique à trois clés. Inclut summary.severityThreshold — le apiGateSeverityThreshold org utilisé pour ce verdict.
Verdict wait (gate CI) : PASS / FAIL ne signifie pas « aucun finding ». Les échecs vulns / secrets utilisent apiGateSeverityThreshold org (défaut critical ; Paramètres → Scan defaults / Onboarding ; org uniquement — pas de surcharge dépôt). FAIL s’il y a au moins une vulnérabilité ou un secret ≥ ce seuil, ou une licence non-compliant (dans les dimensions scanTypes demandées). Ce n’est pas les Quality Gates et c’est distinct de prCheckSeverityThreshold (PR). Reasons : conserver critical_vulnerabilities_found / critical_secrets_found si le seuil est critical ; sinon vulnerabilities_above_threshold / secrets_above_threshold ; licences restent non_compliant_licenses_found. Les findings sous le seuil restent dans summary avec verdict: PASS et reason: no_issues_found (aucun issue de gate). Job failed / cancelled → ERROR. Même règle pour CLI --wait et MCP wait.
GET /v1/scans/:id (status) : statut + project units seulement — pas de verdict/summary (utiliser /wait pour la gate).
commitHash inaccessible : Temporal identifyCommit échoue avec errorCode: branch_or_commit_not_found ; le ScanJob orchestrateur passe en failed (workflow + updateScanJobActivity) pour que /wait renvoie ERROR au lieu d’un timeout.
BYOT lockfile.path : chemin relatif obligatoire (pas de .., pas de chemin absolu). Corps ≤ 10 Mo. XOR lockfile | sbom ; artifact ⇒ projectUnitId obligatoire.
Échec d’activité (crédits, entitlement, scanner) : même chemin — orchestrateur failed + errorCode stable ; lockfileContent BYOT restant est strippé sur update failed.

Limites

Ne placez jamais un service token dans une URL ou une sortie CI. Bornez l’attente à 600 secondes ; pour des workflows plus longs, utilisez un suivi asynchrone.

Erreurs courantes

  • Envoyer commitSha au lieu de commitHash.
  • Envoyer un nom de dépôt au lieu de repositoryId.
  • Traiter 401/403 comme 402 ; les premiers concernent l’auth ou le scope.

Statut d’échec (error / errorCode)

GET /v1/scans/:id (et wait) exposent par unité error et errorCode. Un errorCode top-level peut reprendre la première unité en échec. Codes stables : pat_required, repo_access, rate_limit, insufficient_credits, payment_failed, sast_addon_required, entitlement_denied, lockfile_not_found, branch_or_commit_not_found, workflow_timeout, system_error. Le reason wait reste scan_failed pour compatibilité. Voir Échecs de scan.

Liens