> ## Documentation Index > Fetch the complete documentation index at: https://docs.corgea.app/llms.txt > Use this file to discover all available pages before exploring further. # Findings et détections > Quels endpoints décrivent une vulnérabilité en elle-même, et lesquels décrivent ce qu’un scan en a rapporté L’API décrit les vulnérabilités à deux niveaux. * Une **détection** est une occurrence d’une vulnérabilité dans un scan, telle que ce scan l’a rapportée : le fichier et la ligne, le package et la CVE, ou la règle IaC. Chaque scan produit de nouvelles détections avec de nouveaux identifiants. Les endpoints regroupés sous **Issues** renvoient des détections ; un *problème* (issue) et une *détection* désignent la même chose. * Un **finding** est la vulnérabilité elle-même, dans un projet, à travers tous les scans qui l’ont détectée. Son identifiant ne change pas d’un scan à l’autre, et c’est là que vit le triage : statut, commentaire, responsable, date d’expiration du risque accepté, date d’échéance et SLA. > [!NOTE] > > **`/detections` est la même API que `/issues`, sous un nouveau nom.** Chaque endpoint regroupé sous **Issues** est aussi servi sous `/detections`, avec le même code, les mêmes paramètres et la même réponse. Nous l’appelons `/detections` parce que « issue » se confondait facilement avec un finding : chaque résultat est la détection d’une vulnérabilité par un scan, pas la vulnérabilité elle-même. Utilisez `/detections` dans les nouvelles intégrations. `/issues` reste pris en charge : les intégrations existantes n’ont rien à changer. ![Trois scans, chacun avec sa propre détection, pointant tous vers un seul finding qui porte la décision de triage](https://mintcdn.com/corgea/iJfCXTeBC6cZmqD9/images/api/findings-detections-light.fr.svg?fit=max\&auto=format\&n=iJfCXTeBC6cZmqD9\&q=85\&s=341db113011d0496cea53b7bdef60f01) | | Finding | Détection (problème) | | - | - | - | | Ce que c’est | Une vulnérabilité dans un projet | Une occurrence de cette vulnérabilité dans un scan | | Identifiant | Même UUID d’un scan à l’autre, entre branches et après les migrations d’empreintes | Nouvel identifiant à chaque scan | | Triage | Porté ici | Reflète celui de son finding | | À utiliser pour | Synchronisation des tickets, triage en masse, métriques, « est-ce toujours ouvert ? » | Code, numéros de ligne, correctifs, rapports par scan | | Lien vers l’autre | `latest_detection.id` | `finding_id` | ## Passer de l’un à l’autre Chaque élément de détection porte le `finding_id` de son finding. Regroupez les détections sur ce champ, jamais sur `first_detection_date`, qui est une propriété du finding et non une clé. Le champ vaut `null` uniquement pour les détections ingérées avant l’apparition des findings. Chaque finding porte `latest_detection` : sa détection la plus récente, avec l’identifiant qu’acceptent les endpoints de détection et le localisateur propre à sa famille (`file_path` et `line_number` ; `path`, `package`, `version` et `cve` ; ou `path`, `rule_id`, `start_line` et `end_line`). Un changement de triage effectué à l’un ou l’autre niveau s’applique au finding, et donc à chacune de ses détections. ## Quel endpoint appeler | Vous voulez | Appelez | | - | - | | Tout ce qu’un scan a rapporté, avec l’emplacement dans le code | `GET /api/v1/scan/{scan_id}/detections` et ses variantes SCA, conteneurs et IaC | | L’explication et le correctif d’une occurrence | `GET /api/v1/detections/{issue_id}` | | Une ligne par vulnérabilité, filtrée par projet, statut ou urgence | `GET /api/v1/findings` | | Ce qui a changé depuis votre dernière synchronisation | `GET /api/v1/findings?status_changed_since=…` | | Les vulnérabilités dont les détections ont été supprimées avec un scan ou un projet | `GET /api/v1/findings?detection_state=retired` | | L’état de triage d’une vulnérabilité | `GET /api/v1/findings/{finding_id}` | | Changer le statut d’un ensemble de vulnérabilités | `PATCH /api/v1/triage/findings` avec `finding_ids` ou une `rule` | | Changer le statut via une seule détection ; le changement s’applique à son finding | `PATCH /api/v1/detections/{issue_id}` | ## Les endpoints de détections `/detections` est le nouveau nom des endpoints regroupés sous **Issues**, pas une API distincte. Chacun d’eux répond sous les deux chemins : | Chemin Issues | Chemin Detections | | - | - | | `/api/v1/issues` | `/api/v1/detections` | | `/api/v1/issue/{issue_id}` | `/api/v1/detections/{issue_id}` | | `/api/v1/issues/sca`, `/api/v1/issues/sca/{issue_id}` | `/api/v1/detections/sca`, `/api/v1/detections/sca/{issue_id}` | | `/api/v1/issues/container`, `/api/v1/issues/iac` | `/api/v1/detections/container`, `/api/v1/detections/iac` | | `/api/v1/scan/{scan_id}/issues` et ses variantes | `/api/v1/scan/{scan_id}/detections` et ses variantes | Les deux chemins exécutent le même code et renvoient la même réponse, y compris les clés `issues` et `total_issues`. Utilisez `/detections` dans vos nouvelles intégrations ; `/issues` reste pris en charge. ## Les endpoints de findings `GET /api/v1/findings` renvoie une ligne par finding, du plus récent au plus ancien selon la première détection, paginée avec `page` et `page_size` (jusqu’à 100) et accompagnée d’un total `total_findings`. Sauf mention contraire, les filtres acceptent des listes séparées par des virgules : | Paramètre | Valeurs | | - | - | | `issue_type` | `sast`, `secret`, `logic_auth`, `code_quality`, `dependency`, `container`, `iac`. Par défaut : toutes les familles de sécurité que le token peut consulter (toutes sauf `code_quality`) | | `status` | `open`, `fix_in_progress`, `accepted_risk`, `false_positive`, `fixed`, `duplicate` | | `urgency` | `CR`, `HI`, `ME`, `LO` | | `project_id` | Identifiants de projets | | `project` | Un nom de projet | | `repo` | Sous-chaîne de l’URL du dépôt | | `cwe` | `CWE-79` ou `79` | | `detection_state` | `active` (par défaut), `retired`, `all` | | `status_changed_since` | Date-heure ISO 8601, ou date interprétée comme minuit UTC : findings dont le triage a changé après cet instant | | `created_since` | Date-heure ISO 8601, ou date interprétée comme minuit UTC : findings détectés pour la première fois après cet instant | | `assigned_to` | Un identifiant d’utilisateur | | `sort_by` | `-created_at` (par défaut), `created_at`, `urgency`, `-urgency`, `status`, `-status`, `status_changed_at`, `-status_changed_at`. `created_at` est le moment où le finding a été détecté pour la première fois, l’instant que filtre `created_since`. Il ne figure pas dans la réponse et correspond à `first_detection_date`, sauf si les détections les plus anciennes du finding ont été supprimées avec leur scan | Il n’y a pas de filtre `branch` : un finding appartient à un projet, et la branche est une propriété de ses détections. Le token doit disposer de la même autorisation de consultation que pour la liste des détections de la famille ; demander une famille qu’il ne peut pas consulter renvoie un `403`. `GET /api/v1/findings/{finding_id}` renvoie un finding avec la même structure : ses champs de triage, `urgency`, `classification`, `project`, `detection_state`, `first_detection_date`, `last_detection_date`, `detections_count` et `latest_detection`. ### `detection_state` Un finding est `active` tant qu’il possède une détection dans son projet, et devient `retired` une fois sa dernière détection supprimée avec son scan ou son projet. Un finding qu’un nouveau scan ne rapporte plus n’est pas retiré : il reste `active` et son `status` passe à `fixed`. Un finding retiré conserve son triage, de sorte qu’une détection qui réapparaît est rattachée au même identifiant de finding et hérite de la même décision. > [!NOTE] > > `detection_state` vaut `null`, et `GET /api/v1/findings` répond `404`, tant que l’index des findings du compte n’est pas complet. Les endpoints de détections et `GET /api/v1/findings/{finding_id}` ne sont pas concernés. ## Triage par finding `PATCH /api/v1/triage/findings` accepte `finding_ids` : une liste d’identifiants de findings (issus de `GET /api/v1/findings` ou du `finding_id` des éléments de détection) ou d’identifiants de détections. Un identifiant de finding désigne la détection la plus récente du finding, et la décision s’applique à toutes ses détections. Les identifiants qui ne correspondent à rien sont renvoyés dans `unresolved_ids` et comptés comme non appariés : un lot contenant un identifiant obsolète applique donc quand même le reste. Le triage en masse couvre les familles SAST, secrets, logique, qualité du code et dépendances ; un identifiant de conteneur ou IaC est renvoyé dans `unresolved_ids`, et les lignes d’audit indiquent `finding_type` comme `sast` ou `sca`. Une `rule` peut porter une portée `statuses`, ce qui permet par exemple, en un seul appel, de passer en faux positif tous les findings actuellement en risque accepté. ## Une boucle de synchronisation Indexez le ticket sur l’identifiant du finding. Un identifiant de détection change à chaque scan ; un identifiant de finding, non. Chaque exécution lit trois listes et écrit un lot. Toutes les listes sont paginées : demandez `page=1, 2, …` avec `page_size=100` jusqu’à ce que `page` atteigne `total_pages`. Enregistrez l’heure de début de l’exécution sous forme de date-heure ISO 8601 complète en UTC, et passez-la comme `` la fois suivante. 1. `GET /api/v1/findings?created_since=` : ouvrez un ticket pour chaque nouveau finding. Un nouveau finding n’a pas encore de changement de triage, donc l’étape 2 ne le renvoie pas. 2. `GET /api/v1/findings?status_changed_since=&detection_state=all` : appliquez les changements de triage, y compris ceux des findings retirés. Un finding dont le `status` est passé à `fixed` ferme son ticket. 3. `GET /api/v1/findings?detection_state=retired` : rapprochez les findings retirés. Le retrait n’enregistre aucune heure et ne change aucun statut, donc aucun des deux curseurs ne le renvoie. Comparez cette liste complète avec vos tickets ouverts, et fermez ou signalez ceux qui y figurent. Si une détection réapparaît, le finding redevient `active` avec le même identifiant. 4. `PATCH /api/v1/triage/findings` avec `finding_ids` : renvoyez vers Corgea les décisions prises dans l’outil de tickets. Lisez `unresolved_ids` même avec un `200`. Ces identifiants, dont tous les findings de conteneurs et IaC, n’ont pas été mis à jour, alors que le reste du lot l’a été. Ajoutez `issue_type` à chaque appel de liste si vous synchronisez les findings de qualité du code, que la valeur par défaut exclut. Un `404` de `GET /api/v1/findings` signifie que l’index des findings du compte n’est pas encore complet, et non qu’il n’y a rien à synchroniser. Réessayez plus tard en conservant l’ancien curseur. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.