Référence de l'API

Authentification et plans

Créez une clé dans Réglages → Clés API. Le plan doit inclure api. Une clé absente ou inconnue renvoie 401. Un plan sans api renvoie 402. Plus de 120 appels par heure renvoient 429. Le quota CI mensuel épuisé renvoie 402. La maintenance renvoie 503. Ces règles valent pour les deux routes ci-dessous.

POST /api/v1/check

Formulaire multipart. Répétez le champ files pour chaque manifeste ou lockfile. Le nom de fichier est le chemin dans le projet (apps/web/package-lock.json). 40 fichiers et 15 Mo au maximum. Rien n'est stocké.

• fail_on — critical, high (par défaut), moderate, low ou none. Les malwares et les alertes activement exploitées échouent quand même, sauf avec none.
• repo — owner/name facultatif. Les règles d'ignorance de ce dépôt s'appliquent.
• include=all — renvoie aussi findings, toutes les alertes actives, pas seulement failing.
• explain=1 — ajoute explanation (risque, exposition, mise à jour). Désactivé si vous ne l'envoyez pas.

curl -sS -H "Authorization: Bearer vsk_…" \
  -F [email protected] \
  -F [email protected] \
  -F fail_on=high \
  -F include=all \
  "$SCANDAR_API_URL/api/v1/check"

Les champs historiques ne changent pas :

{
  "passed": false,
  "failOn": "high",
  "report": "Scandar: 1 advisory fail the check …",
  "projects": [{
    "project": "/",
    "manager": "npm",
    "packages": 12,
    "counts": { "CRITICAL": 0, "HIGH": 1, "MODERATE": 0, "LOW": 0, "UNKNOWN": 0 },
    "ignored": 0,
    "exploited": 0,
    "failing": [{
      "id": "GHSA-…",
      "aliases": [],
      "package": "example",
      "version": "1.0.0",
      "severity": "HIGH",
      "fixedIn": "1.2.0",
      "exploited": false,
      "epss": null,
      "malicious": false,
      "summary": "…",
      "url": "https://osv.dev/vulnerability/GHSA-…"
    }]
  }]
}

Champs ajoutés en v1

Chaque alerte a aussi score (0–100), bucket (now, soon, later), label (« Fix now », « Plan », « Low »), reach (toujours unknown) et reachLabel (« Usage unknown »). Le point d'accès reçoit des lockfiles, pas le code source : le score utilise donc le poids d'une portée inconnue. Cela n'affirme pas que le paquet est importé.

fix est un objet ou null. C'est le plan qu'utiliserait planFixes : to, nature (direct ou transitive), major, command, files, advisories. L'API n'écrit cette commande nulle part.

explanation n'est présent qu'avec explain=1. Une explication en cache est renvoyée telle quelle. Sans cache, le modèle n'est appelé que si l'IA est activée sur le serveur et que le plan inclut ai. Sinon, explanation vaut null. 15 appels au modèle au maximum par requête ; les alertes suivantes restent à null. Les alertes en échec sont expliquées d'abord. include=all ajoute findings avec la même forme. Chaque projet inclut aussi lockfile.

POST /api/v1/explain

JSON, une alerte, même clé et même limite horaire. Cela ne compte pas comme une vérification CI. La portée vaut unknown et ne peut pas être remplacée. source vaut cache, model ou unavailable.

curl -sS -H "Authorization: Bearer vsk_…" \
  -H "Content-Type: application/json" \
  -d '{"id":"GHSA-…","package":"example","version":"1.0.0"}' \
  "$SCANDAR_API_URL/api/v1/explain"

ecosystem vaut npm, PyPI, Go, crates.io, Packagist ou RubyGems. Par défaut : npm.

Retour à la documentation du scan