GET /v1/statistics/distribution

La répartition des CVE en paliers : combien à chaque score CVSS, à chaque niveau de probabilité d’exploitation, par vecteur d’attaque, par sévérité.

Là où /v1/statistics/top classe des valeurs ouvertes (des milliers de CWE ou d’éditeurs), cette route découpe la population en un petit nombre de paliers fermés et ordonnés.

Scope requis : stats-global

Requête

GET /api/v1/statistics/distribution
Authorization: Bearer twa_votre_cle_ici

Paramètres de requête

Paramètre	Type	Défaut	Description
metric	string	cvss	cvss, epss, attack_vector, severity
period	string	—	2026, 2026-Q1, 2026-03, 2026-W12, 2026-03-15
from / to	date	—	Bornes explicites, ignorées si period est fourni

Les quatre métriques

metric	Paliers	Usage
cvss	Tranches de 0,5, de 0.0 à 10.0	Histogramme de gravité technique
epss	<1%, 1–10%, 10–30%, 30–60%, >60%	Probabilité d’exploitation dans les 30 jours
attack_vector	Network, Adjacent, Local, Physical, Unknown	Lu dans le vecteur CVSS (AV:)
severity	CRITICAL … UNKNOWN	Répartition par niveau et couverture PoC

Réponse 200 OK

{
  "metric": "epss",
  "label": "Probabilité d'exploitation EPSS, en cinq paliers",
  "from": "2026-01-01",
  "to": "2026-12-31",
  "grand_total": 38104,
  "buckets": [
    { "bucket": "<1%",    "total": 30218, "with_poc": 2104, "kev": 3,  "share_pct": 79.30, "poc_pct": 7.0 },
    { "bucket": "1–10%",  "total": 5433,  "with_poc": 1187, "kev": 11, "share_pct": 14.26, "poc_pct": 21.8 },
    { "bucket": "10–30%", "total": 1502,  "with_poc": 611,  "kev": 14, "share_pct": 3.94,  "poc_pct": 40.7 },
    { "bucket": "30–60%", "total": 604,   "with_poc": 341,  "kev": 18, "share_pct": 1.59,  "poc_pct": 56.5 },
    { "bucket": ">60%",   "total": 347,   "with_poc": 264,  "kev": 29, "share_pct": 0.91,  "poc_pct": 76.1 }
  ]
}

Les paliers sont renvoyés dans l’ordre logique, pas alphabétique — sans quoi 10–30% se placerait avant 1–10%, et LOW avant MEDIUM.

Champs

Champ	Type	Description
grand_total	integer	Nombre de CVE couvertes par la métrique sur la fenêtre
bucket	string	Libellé du palier
total	integer	CVE dans ce palier
with_poc	integer	Dont au moins un PoC public connu
kev	integer	Dont présentes au catalogue KEV
share_pct	float	Part du palier dans grand_total
poc_pct	float	Taux de couverture PoC à l’intérieur du palier

Ces totaux comptent bien des CVE

Chaque CVE ne tombe que dans un seul palier : les share_pct se somment donc à 100 %, et grand_total est un nombre de CVE. C’est la différence avec /v1/statistics/top sur la dimension cwe, où une CVE portant deux CWE compte deux fois.

grand_total varie d’une métrique à l’autre sur la même fenêtre : seules les CVE disposant d’un score CVSS entrent dans cvss, d’un score EPSS dans epss, d’un vecteur dans attack_vector. La métrique severity couvre tout, la sévérité valant UNKNOWN par défaut.

Totaux de la base

GET /api/v1/statistics/totals

Sans paramètre : les compteurs globaux, tous états confondus.

{
  "total": 312044,
  "published": 297811,
  "rejected": 13402,
  "reserved": 831,
  "kev": 1284,
  "poc": 41209,
  "triple_threat": 218,
  "avg_cvss": 7.02,
  "avg_epss": 2.914
}

Champ	Description
rejected reserved	CVE retirées ou réservées sans publication
triple_threat	Critique et au catalogue KEV et avec PoC public — le croisement qui appelle une action immédiate
avg_epss	En pourcentage, pas en probabilité

La seule route qui voit les CVE non publiées

Toutes les autres statistiques ne portent que sur l’état PUBLISHED. rejected et reserved sont donc inaccessibles ailleurs, et les totaux de cette route ne se retrouvent pas en sommant les points de /v1/statistics/timeseries.

Exemple

La couverture PoC par sévérité sur l’année en cours :

curl -s \
  -H "Authorization: Bearer twa_votre_cle_ici" \
  "https://app.techwatchalert.com/api/v1/statistics/distribution?metric=severity&period=2026" \
  | jq '.buckets | map({severite: .bucket, cve: .total, avec_poc: .with_poc, taux: .poc_pct})'