Riferimento API

Versione v1. Ogni corpo JSON include apiVersion. Invia Authorization: Bearer vsk_….

Autenticazione e piani

Crea una chiave in Impostazioni → Chiavi API. Il piano deve includere api. Una chiave mancante o sconosciuta restituisce 401. Un piano senza api restituisce 402. Più di 120 chiamate all'ora restituiscono 429. La quota CI mensile esaurita restituisce 402. La manutenzione restituisce 503. Queste regole valgono per entrambe le route qui sotto.

POST /api/v1/check

Form multipart. Ripeti il campo files per ogni manifest o lockfile. Il nome del file è il percorso nel progetto (apps/web/package-lock.json). Al massimo 40 file e 15 MB. Non viene salvato nulla.

  • fail_on — critical, high (predefinito), moderate, low o none. Malware e avvisi sfruttati attivamente falliscono comunque, salvo con none.
  • repo — owner/name facoltativo. Si applicano le regole di esclusione di quel repository.
  • include=all — restituisce anche findings, tutti gli avvisi attivi, non solo failing.
  • explain=1 — aggiunge explanation (rischio, esposizione, aggiornamento). Disattivato se non lo invii.
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"

I campi storici non cambiano:

{
  "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-…"
    }]
  }]
}

Campi aggiunti in v1

Ogni avviso ha anche score (0–100), bucket (now, soon, later), label (“Fix now”, “Plan”, “Low”), reach (sempre unknown) e reachLabel (“Usage unknown”). L'endpoint riceve lockfile, non codice sorgente, quindi il punteggio usa il peso di portata sconosciuta. Non afferma che il pacchetto sia importato.

fix è un oggetto o null. È il piano che userebbe planFixes: to, nature (direct o transitive), major, command, files, advisories. L'API non scrive quel comando da nessuna parte.

explanation è presente solo con explain=1. Una spiegazione in cache viene restituita così com'è. Senza cache, il modello viene chiamato solo se l'IA è attiva sul server e il piano include ai. Altrimenti explanation è null. Al massimo 15 chiamate al modello per richiesta; gli avvisi successivi restano null. Gli avvisi falliti vengono spiegati per primi. include=all aggiunge findings con la stessa forma. Ogni progetto include anche lockfile.

POST /api/v1/explain

JSON, un avviso, stessa chiave e stesso limite orario. Non conta come controllo CI. La portata è unknown e non si può sostituire. source è cache, model o 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 è npm, PyPI, Go, crates.io, Packagist o RubyGems. Il valore predefinito è npm.

Torna alla documentazione della scansione