Ereignisse und SDK

JavaScript-SDK

Ein kleiner typisierter Client für Node.js 18+, Deno und Bun. Ohne Abhängigkeiten: Er nutzt das eingebaute fetch und Web Crypto.

@scanverra/sdk ist in der Vorschau, die Schnittstelle kann sich noch ändern. Jeder Aufruf ist eine einfache HTTP-Anfrage, daher zeigen die API-Seiten, wie es ohne SDK geht.

Installieren

Erstellen Sie einen Client und verwenden Sie ihn wieder.

shell

npm install @scanverra/sdk

javascript

import { Scanverra } from "@scanverra/sdk";

const scanverra = new Scanverra({
  apiKey: process.env.SCANVERRA_API_KEY,
  // baseUrl: "https://www.scanverra.com",  // optional
  // timeoutMs: 300_000,                     // optional, per request
});

Scans ausführen

scans.audit() und scans.repo() antworten mit dem fertigen Bericht. Die anderen antworten sofort mit einer ID; wait() fragt ab, bis der Bericht fertig ist, und wirft einen Fehler, wenn der Scan fehlschlug.

javascript

// Answers with the finished report
const audit = await scanverra.scans.audit({ url: "https://example.com" });

// Answer with an id; wait() polls until the report is ready
const { scanId } = await scanverra.scans.security({ url: "https://example.com" });
const security = await scanverra.wait("security", scanId);

const { testId } = await scanverra.scans.browser({ url: "https://example.com" });
const browser = await scanverra.wait("browser", testId, { intervalMs: 5000 });

// Repo scans: owner and repo of a connected account
const repo = await scanverra.scans.repo({ owner: "acme", repo: "storefront", async: true });
const repoReport = await scanverra.wait("repo", repo.scanId);

Properties lesen

Scores, zusammengeführte Probleme und nächste Schritte für jedes Produkt.

javascript

const { properties } = await scanverra.properties.list();
for (const p of properties) console.log(p.name, p.score, p.openTasks);

const detail = await scanverra.properties.get(properties[0].id);
const critical = detail.issues.filter((i) => i.severity === "critical");

Ereignisse abonnieren

Erstellen Sie für ein beliebiges Ereignis einen REST-Hook und prüfen Sie die Signatur jeder Zustellung mit verifyWebhook. Zustellungen älter als fünf Minuten werden abgelehnt.

javascript

const hook = await scanverra.hooks.create({
  event: "remediation.task_created",
  url: "https://hooks.example.com/scanverra",
});
// Store hook.secret: it is shown only once.

// In your receiver, with the raw request body:
import { verifyWebhook } from "@scanverra/sdk";

const ok = await verifyWebhook({
  secret: process.env.SCANVERRA_HOOK_SECRET,
  body: rawBody,
  timestamp: req.headers["x-scanverra-timestamp"],
  signature: req.headers["x-scanverra-signature"],
});
if (!ok) return res.status(401).end();

Fehler

Jeder Fehler wirft ScanverraError mit status, code, einer lesbaren message und dem Antwort-body. Kommt keine Antwort, ist status 0 und code network_error oder timeout.

javascript

import { ScanverraError } from "@scanverra/sdk";

try {
  await scanverra.scans.audit({ url: "https://example.com" });
} catch (err) {
  if (!(err instanceof ScanverraError)) throw err;
  if (err.code === "SCAN_COOLDOWN") console.log("Try again later:", err.message);
  else if (err.status === 0 || err.status >= 500) console.log("Retry with backoff:", err.code ?? err.status);
  else throw err; // 4xx: fix the request (see /docs/errors)
}

Referenz

Feld	Beschreibung
`scans.audit(body)`Promise<report>Optional	Führt einen Website Audit aus und liefert den Bericht. Mit async: true erhalten Sie sofort reportId.
`scans.security(body)`Promise<{ scanId }>Optional	Startet einen Sicherheitsscan.
`scans.browser(body)`Promise<{ testId }>Optional	Startet einen Browser-Audit. Mit credentialId testen Sie Seiten hinter einem Login.
`scans.seo(body)`Promise<{ scanId }>Optional	Startet eine SEO-Analyse.
`scans.repo(body)`Promise<{ scanId }>Optional	Scannt ein verbundenes Repository.
`results.<tool>(id)`Promise<ScanResult>Optional	Liest einen Scan per ID: audit, security, browser, seo oder repo.
`wait(tool, id, options?)`Promise<ScanResult>Optional	Fragt die passende results-Methode ab, bis der Scan fertig ist. Optionen: intervalMs (4000), timeoutMs (600000).
`properties.list() / get(id)`Promise<...>Optional	Listet Properties oder liest eine mit Problemen und nächsten Schritten.
`hooks.list() / create() / delete(id) / sample(event)`Promise<...>Optional	Verwaltet REST-Hooks. create() gibt das Signatur-Secret einmal zurück.
`verifyWebhook(input)`Promise<boolean>Optional	Prüft X-Scanverra-Signature gegen den Roh-Body und den Zeitstempel.