GET /v1/organizations/{org_id}/projects/{id}/alerts

Les alertes sont créées automatiquement quand une vulnérabilité correspond à un item de la stack d’un projet : une CVE, ou un avis GHSA ou OSV sans identifiant CVE. Le champ cve_id porte l’identifiant principal. aliases liste les autres identifiants, fusion_de les avis devenus cette vulnérabilité (l’historique du dossier est conservé).

Lister les alertes d’un projet

GET /api/v1/organizations/{org_id}/projects/{project_id}/alerts
Authorization: Bearer twa_votre_cle_ici

Paramètres de chemin

Paramètre	Type	Description
org_id	UUID	Identifiant de l’organisation
project_id	UUID	Identifiant du projet

Paramètres de requête

Paramètre	Type	Défaut	Description
unread_only	boolean	false	Si true, retourne uniquement les alertes non lues
severity	string	—	Filtre par sévérité(s), séparées par virgule. Valeurs : CRITICAL, HIGH, MEDIUM, LOW
since	datetime (ISO 8601)	—	Retourne uniquement les alertes déclenchées après cette date
page	integer ≥ 1	1	Numéro de page
limit	integer 1–200	50	Nombre d’alertes par page

Réponse 200 OK

{
  "items": [
    {
      "id": "018e9999-0000-7000-8000-000000000030",
      "cve_id": "CVE-2024-11477",
      "triggered_at": "2024-11-05T14:32:00Z",
      "is_read": false,
      "severity": "CRITICAL",
      "description": "7-Zip contains a heap-based buffer overflow vulnerability...",
      "vendor": "7-zip",
      "product": "7-zip",
      "cvss_score": 7.8,
      "is_kev": false,
      "has_poc": true,
      "tags": [
        { "id": "018ec0de-0000-7000-8000-0000000000a1", "name": "production", "color": "#ef4444" },
        { "id": "018ec0de-0000-7000-8000-0000000000a2", "name": "à patcher", "color": "#f59e0b" }
      ]
    },
    {
      "id": "018e9999-0000-7000-8000-000000000031",
      "cve_id": "CVE-2024-38816",
      "triggered_at": "2024-09-13T08:00:00Z",
      "is_read": true,
      "severity": "HIGH",
      "description": "Applications serving static resources through the functional web...",
      "vendor": "vmware",
      "product": "spring_framework",
      "cvss_score": 7.5,
      "is_kev": false,
      "has_poc": false,
      "tags": []
    }
  ],
  "total": 42,
  "unread_count": 7
}

Champs — Enveloppe

Champ	Type	Description
items	array	Alertes de la page courante
total	integer	Nombre total d’alertes correspondant aux filtres actifs
unread_count	integer	Total des alertes non lues dans ce projet (indépendant des filtres)

Champs — Alerte

Champ	Type	Description
id	string (UUID)	Identifiant de l’alerte
cve_id	string	Identifiant CVE (ex : CVE-2024-11477)
triggered_at	string (ISO 8601)	Horodatage de déclenchement
is_read	boolean	true si au moins un membre a lu l’alerte. La clé n’est personne : la lecture reste celle de l’équipe
severity	string	Sévérité CVE : CRITICAL, HIGH, MEDIUM, LOW, NONE, UNKNOWN
description	string | null	Description anglaise de la CVE
vendor	string | null	Éditeur principal identifié
product	string | null	Produit principal identifié
cvss_score	float | null	Score CVSS (0.0 – 10.0)
is_kev	boolean	true si référencée dans le catalogue CISA KEV
has_poc	boolean	true si au moins un PoC ou exploit public est connu (GitHub via nomi-sec/PoC-in-GitHub, Exploit-DB, Metasploit, Nuclei)
tags	array<Tag>	Tags d’équipe assignés à cette CVE dans ce projet (voir objet Tag)

Objet Tag

Vocabulaire partagé au niveau de l’organisation, assigné par l’équipe à une CVE dans un projet. Tableau vide si aucun tag.

Champ	Type	Description
id	string (UUID)	Identifiant du tag
name	string	Libellé (ex : production, à patcher)
color	string	Couleur hexadécimale #rrggbb

---

Détail d’une alerte

GET /api/v1/organizations/{org_id}/projects/{project_id}/alerts/{alert_id}
Authorization: Bearer twa_votre_cle_ici

Paramètres de chemin

Paramètre	Type	Description
org_id	UUID	Identifiant de l’organisation
project_id	UUID	Identifiant du projet
alert_id	UUID	Identifiant de l’alerte

Réponse 200 OK

Même structure qu’un élément de la liste.

Erreurs

Code	Détail	Cause
404	Projet introuvable	Projet inexistant, d’une autre organisation, ou hors de la restriction de projets de la clé
403	Cette clé API n'a pas le droit d'accéder à cette ressource.	Le scope alerts manque à la clé
404	Alerte introuvable	alert_id inexistant ou n’appartient pas au projet

---

Exemples

Alertes critiques non lues depuis 30 jours

SINCE=$(date -u -d '30 days ago' +%Y-%m-%dT%H:%M:%SZ 2>/dev/null \
  || date -u -v-30d +%Y-%m-%dT%H:%M:%SZ)

curl -s \
  -H "Authorization: Bearer twa_votre_cle_ici" \
  "https://app.techwatchalert.com/api/v1/organizations/${ORG_ID}/projects/${PROJECT_ID}/alerts?severity=CRITICAL,HIGH&unread_only=true&since=${SINCE}&limit=100" \
  | jq '.items[] | {cve: .cve_id, score: .cvss_score, kev: .is_kev, poc: .has_poc}'

Script CI/CD — bloquer si CVE critique avec PoC

#!/bin/bash
set -euo pipefail

ORG_ID="${TWA_ORG_ID}"
PROJECT_ID="${TWA_PROJECT_ID}"
API_KEY="${TWA_API_KEY}"
BASE="https://app.techwatchalert.com/api/v1"

CRITICAL_POC=$(curl -sf \
  -H "Authorization: Bearer ${API_KEY}" \
  "${BASE}/organizations/${ORG_ID}/projects/${PROJECT_ID}/alerts?severity=CRITICAL&unread_only=true&limit=200" \
  | jq '[.items[] | select(.has_poc == true)] | length')

if [ "$CRITICAL_POC" -gt 0 ]; then
  echo "ERREUR : ${CRITICAL_POC} CVE(s) critiques avec PoC non traitées."
  exit 1
fi

echo "OK — aucune CVE critique avec PoC."

Python — export CSV des alertes

import csv, httpx
from datetime import datetime, timedelta, timezone

BASE = "https://app.techwatchalert.com/api/v1"
headers = {"Authorization": "Bearer twa_votre_cle_ici"}
org_id = "018e5678-abcd-7000-8000-000000000001"
project_id = "018e1234-abcd-7000-8000-000000000010"

since = (datetime.now(timezone.utc) - timedelta(days=7)).isoformat()
page, all_alerts = 1, []

while True:
    r = httpx.get(
        f"{BASE}/organizations/{org_id}/projects/{project_id}/alerts",
        headers=headers,
        params={"since": since, "limit": 200, "page": page},
    ).json()
    all_alerts.extend(r["items"])
    if len(all_alerts) >= r["total"]:
        break
    page += 1

with open("alertes.csv", "w", newline="") as f:
    w = csv.DictWriter(f, fieldnames=["cve_id", "severity", "cvss_score", "is_kev", "has_poc", "triggered_at"])
    w.writeheader()
    w.writerows(all_alerts)

print(f"{len(all_alerts)} alertes exportées.")

Avis GHSA et OSV du projet

Même portée que les alertes (alerts). Chaque avis s’affiche avec son identifiant principal, ses alias, son palier (a_patcher, haute ou absent) et les correspondances avec la stack.

GET /api/v1/organizations/{org_id}/projects/{project_id}/vulnerabilities
Authorization: Bearer twa_votre_cle_ici

Paramètre	Description
source	ghsa ou osv
palier	a_patcher, haute ou aucun