Findings et détections

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.

​

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

​

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 : 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 : 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.

​

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 <last run> la fois suivante.

1. GET /api/v1/findings?created_since=<last run> : 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=<last run>&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.