イベントと SDK

JavaScript SDK

Node.js 18 以降、Deno、Bun 向けの軽量な型付きクライアントです。依存関係はなく、組み込みの fetch と Web Crypto を使います。

@scanverra/sdk はプレビュー版で、インターフェースは変更される可能性があります。すべての呼び出しは通常の HTTP リクエストなので、SDK なしでの方法は API ページで確認できます。

インストール

クライアントを1つ作成して再利用します。

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.audit() と scans.repo() は完成したレポートを返します。その他はすぐに ID を返し、wait() がレポートの完成までポーリングし、スキャンが失敗した場合はエラーを投げます。

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);

プロパティを読む

製品ごとのスコア、統合された問題、次のステップ。

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");

イベントを購読

任意のイベントの REST フックを作成し、各配信の署名を verifyWebhook で確認します。5分より古い配信は拒否されます。

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();

エラー

失敗するとすべて status、code、読みやすい message、レスポンスの body を持つ ScanverraError を投げます。応答がない場合、status は 0、code は network_error または 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)
}

リファレンス

フィールド	説明
`scans.audit(body)`Promise<report>任意	Webサイト監査を実行してレポートを返します。async: true を渡すとすぐに reportId を返します。
`scans.security(body)`Promise<{ scanId }>任意	セキュリティスキャンを開始します。
`scans.browser(body)`Promise<{ testId }>任意	ブラウザ監査を開始します。credentialId を渡すとログインが必要なページをテストできます。
`scans.seo(body)`Promise<{ scanId }>任意	SEO 分析を開始します。
`scans.repo(body)`Promise<{ scanId }>任意	接続済みのリポジトリをスキャンします。
`results.<tool>(id)`Promise<ScanResult>任意	ID でスキャンを読み取ります: audit、security、browser、seo、repo。
`wait(tool, id, options?)`Promise<ScanResult>任意	スキャンが完了するまで、そのツールの results メソッドをポーリングします。オプション: intervalMs (4000)、timeoutMs (600000)。
`properties.list() / get(id)`Promise<...>任意	プロパティの一覧、または問題と次のステップを含む1件を取得します。
`hooks.list() / create() / delete(id) / sample(event)`Promise<...>任意	REST フックを管理します。create() は署名用シークレットを1回だけ返します。
`verifyWebhook(input)`Promise<boolean>任意	X-Scanverra-Signature を生のボディとタイムスタンプで検証します。