API-Referenz

Authentifizierung und Pläne

Erstelle einen Schlüssel unter Einstellungen → API-Schlüssel. Der Plan muss api enthalten. Fehlende oder unbekannte Schlüssel liefern 401. Ein Plan ohne api liefert 402. Mehr als 120 Aufrufe pro Stunde liefern 429. Das aufgebrauchte monatliche CI-Kontingent liefert 402. Wartung liefert 503. Diese Regeln gelten für beide Routen unten.

POST /api/v1/check

Multipart-Formular. Wiederhole das Feld files für jedes Manifest und jede Lockfile. Der Dateiname ist der Pfad im Projekt (apps/web/package-lock.json). Höchstens 40 Dateien und 15 MB. Nichts wird gespeichert.

• fail_on — critical, high (Standard), moderate, low oder none. Malware und aktiv ausgenutzte Advisories schlagen trotzdem fehl, außer bei none.
• repo — optional owner/name. Es gelten die Ignorier-Regeln dieses Repositories.
• include=all — liefert auch findings, alle aktiven Advisories, nicht nur failing.
• explain=1 — fügt explanation hinzu (Risiko, Betroffenheit, Upgrade). Aus, solange du es nicht sendest.

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"

Die bisherigen Felder bleiben unverändert:

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

In v1 hinzugefügte Felder

Jede Advisory hat außerdem score (0–100), bucket (now, soon, later), label („Fix now“, „Plan“, „Low“), reach (immer unknown) und reachLabel („Usage unknown“). Der Endpunkt erhält Lockfiles, keinen Quellcode, daher nutzt der Wert das Gewicht für unbekannte Erreichbarkeit. Das ist keine Aussage, dass das Paket importiert wird.

fix ist ein Objekt oder null. Es ist der Plan, den planFixes nutzen würde: to, nature (direct oder transitive), major, command, files, advisories. Die API schreibt diesen Befehl nirgendwohin.

explanation ist nur mit explain=1 vorhanden. Eine gecachte Erklärung wird unverändert geliefert. Ohne Cache wird das Modell nur aufgerufen, wenn KI auf dem Server aktiv ist und der Plan ai enthält. Sonst ist explanation null. Höchstens 15 Modellaufrufe pro Anfrage; weitere Advisories bleiben null. Fehlgeschlagene Advisories werden zuerst erklärt. include=all fügt findings in derselben Form hinzu. Jedes Projekt enthält außerdem lockfile.

POST /api/v1/explain

JSON, eine Advisory, derselbe Schlüssel und dasselbe Stundenlimit. Zählt nicht als CI-Prüfung. Die Erreichbarkeit ist unknown und lässt sich nicht überschreiben. source ist cache, model oder 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 ist npm, PyPI, Go, crates.io, Packagist oder RubyGems. Standard ist npm.

Zurück zur Scan-Doku