Referencia de la API

Versión v1. Cada cuerpo JSON incluye apiVersion. Envía Authorization: Bearer vsk_….

Autenticación y planes

Crea una clave en Ajustes → Claves API. El plan debe incluir api. Una clave ausente o desconocida devuelve 401. Un plan sin api devuelve 402. Más de 120 llamadas por hora devuelven 429. La cuota mensual de CI agotada devuelve 402. El mantenimiento devuelve 503. Estas reglas se aplican a las dos rutas siguientes.

POST /api/v1/check

Formulario multipart. Repite el campo files por cada manifiesto o lockfile. El nombre del archivo es la ruta dentro del proyecto (apps/web/package-lock.json). Como máximo 40 archivos y 15 MB. No se guarda nada.

  • fail_on — critical, high (predeterminado), moderate, low o none. El malware y los avisos explotados activamente fallan igualmente salvo con none.
  • repo — owner/name opcional. Se aplican las reglas de ignorar de ese repositorio.
  • include=all — devuelve también findings, todos los avisos activos, no solo failing.
  • explain=1 — añade explanation (riesgo, exposición, actualización). Desactivado si no lo envías.
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"

Los campos históricos no cambian:

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

Campos añadidos en v1

Cada aviso tiene también score (0–100), bucket (now, soon, later), label (“Fix now”, “Plan”, “Low”), reach (siempre unknown) y reachLabel (“Usage unknown”). El endpoint recibe lockfiles, no código fuente, así que la puntuación usa el peso de alcance desconocido. No afirma que el paquete se importe.

fix es un objeto o null. Es el plan que usaría planFixes: to, nature (direct o transitive), major, command, files, advisories. La API no escribe ese comando en ningún sitio.

explanation solo está presente con explain=1. Una explicación en caché se devuelve tal cual. Sin caché, se llama al modelo solo si la IA está activada en el servidor y el plan incluye ai. Si no, explanation es null. Como máximo 15 llamadas al modelo por petición; los demás avisos quedan en null. Los avisos con fallo se explican primero. include=all añade findings con la misma forma. Cada proyecto incluye también lockfile.

POST /api/v1/explain

JSON, un aviso, la misma clave y el mismo límite por hora. No cuenta como comprobación de CI. El alcance es unknown y no se puede cambiar. source es 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 es npm, PyPI, Go, crates.io, Packagist o RubyGems. Por defecto, npm.

Volver a la documentación del análisis