Supply-chain scan — Clawvard course SOP

A one-command read-only check that says: does any package, extension, or MCP server on my disk match a known supply-chain compromise right now? Drives perplexityai/bumblebee v0.1.1 against the user-authorised target and turns the raw NDJSON inventory into a Clawvard-styled HTML dashboard. The playbook step is optional — without a Clawvard API key, the core dashboard still ships.

The course never runs npm install, pip install, go get, gem install, or anything similar. Bumblebee reads lockfiles and extension manifests only; it makes no network calls during the scan.

Pin

• Bumblebee v0.1.1 (commit c24089804ee66ece4bec6f14638cb98985389cdb, published 2026-05-22). Do not substitute a floating version reference.
• The reference dashboard renderer is the small Node script published at https://clawvard.school/skills/supply-chain-scan/examples/render_dashboard.mjs.

Prerequisites

• macOS, Linux, or Windows endpoint.
• Either:
  • Go 1.21+ to go install github.com/perplexityai/bumblebee/cmd/bumblebee@v0.1.1, or
  • A bumblebee_0.1.1_<os>_<arch>.tar.gz from the v0.1.1 release.
• Node ≥ 18 (the dashboard renderer is a single .mjs file).
• (Optional) A Clawvard API key from https://clawvard.school if you want the remediation playbook step. Without the key the dashboard still renders; the playbook is simply skipped with a single-line notice.

Step 1 — install Bumblebee (pinned)

# Path A: Go toolchain available
go install github.com/perplexityai/bumblebee/cmd/bumblebee@v0.1.1

# Path B: download the release tarball for your OS / arch
# (replace linux_amd64 with darwin_arm64, etc.)
curl -L -O https://github.com/perplexityai/bumblebee/releases/download/v0.1.1/bumblebee_0.1.1_linux_amd64.tar.gz
tar -xzf bumblebee_0.1.1_linux_amd64.tar.gz
./bumblebee version    # must print: bumblebee v0.1.1

Step 2 — grab the dashboard renderer + the demo exposure catalog

mkdir -p out
curl -L -o render_dashboard.mjs \
  https://clawvard.school/skills/supply-chain-scan/examples/render_dashboard.mjs

# The demo catalog is small and points at public advisory URLs.
# For production use, swap in your own exposure-catalog directory.
mkdir -p catalog
curl -L -o catalog/course-catalog.json \
  https://clawvard.school/skills/supply-chain-scan/fixtures/demo/catalog/course-catalog.json

Step 3 — scan a user-authorised target (read-only)

<target> is the directory you want scanned. Common choices:

• . — the current project
• ~/code — a known project root (use --profile project instead)
• A specific manifest folder you want triaged

Examples below use the --profile deep form because it scans an explicit --root and is the cleanest fit for on-demand exposure checks.

./bumblebee scan --profile deep \
  --root <target> \
  --exposure-catalog ./catalog \
  --output-file ./out/inventory.json --output file

The file is NDJSON internally even though it ends in .json — that's how Bumblebee writes inventory; the dashboard renderer handles it.

Step 4 — render the Clawvard dashboard

node render_dashboard.mjs \
  --inventory ./out/inventory.json \
  --catalog   ./catalog \
  --out       ./out/report.html \
  --scope     "scan: <target>" \
  --bumblebee-version v0.1.1

Open ./out/report.html in any browser. The page is self-contained — no CDNs, no fonts, no JS frameworks.

• Top bar: Critical / High / Medium / Low counts.
• Left: hit list grouped by ecosystem, severity-sorted, click to focus.
• Right: focused hit detail — installed version, compromised version range from the catalog, the advisory link, recommended fixes (pin / remove / replace / rotate-token / restart-agent as appropriate), and the source lockfile(s) the match came from.
• Bottom of the detail panel: download buttons for inventory.json, report.html, and (if produced) playbook.md.

Step 5 — (optional) Clawvard remediation playbook

Only run this step when you want a markdown remediation playbook on top of the dashboard. It calls the Clawvard SDK's cv.text.lectureNotes service (already shipped). Skipped silently when no Clawvard API key is set.

cv.text.lectureNotes takes an array of indexed segments (one per finding here) and returns a structured { title, summary, sections, keyTerms }. The snippet below maps each critical / high finding to one segment, then flattens the structured response into a ./out/playbook.md markdown file.

# Requires: pnpm add @clawvard/sdk (or npm / yarn / bun equivalent)
# Requires: export CLAW_API_KEY=<your Clawvard API key>
node - <<'NODE'
import { readFileSync, writeFileSync } from "node:fs";
import { Clawvard } from "@clawvard/sdk";

if (!process.env.CLAW_API_KEY) {
  console.log("CLAW_API_KEY not set — skipping playbook. Dashboard is complete.");
  process.exit(0);
}

const findings = readFileSync("./out/inventory.json", "utf8")
  .split("\n").filter(Boolean).map(JSON.parse)
  .filter((r) => r.record_type === "finding"
            && (r.severity === "critical" || r.severity === "high"));

if (findings.length === 0) {
  console.log("No critical/high findings — no playbook needed.");
  process.exit(0);
}

// Map each finding to a synthetic segment so cv.text.lectureNotes can
// chapterise the playbook. start/end are placeholder seconds (the
// service uses them only to order sections); index i preserves order.
const segments = findings.map((f, i) => ({
  i,
  start: i * 60,
  end:   (i + 1) * 60,
  text:
    "Finding " + (i + 1) + ": [" + f.severity.toUpperCase() + "] " +
    f.ecosystem + " " + f.package_name + "@" + f.version +
    " — " + (f.catalog_name || f.catalog_id) +
    ". Source file: " + (f.source_file || "(none)") +
    ". Recommended fix priority for this finding: pin to a safe version, " +
    "or remove the dependency, or replace it with the intended package, " +
    "then rotate any credentials the package could read and restart any " +
    "agent / IDE that loaded it.",
}));

const cv = new Clawvard({ apiKey: process.env.CLAW_API_KEY });
const out = await cv.text.lectureNotes({
  segments,
  language: "en",
  videoTitle: "Supply-chain remediation playbook",
  chapterTargetCount: Math.min(findings.length, 10),
});

// Flatten the structured TextLectureNotesOutput into a single markdown
// file. The service guarantees: title (H1), summary, sections[] with
// title + summary + bullets[], and an ordered keyTerms[] glossary.
const md = [];
md.push("# " + out.title);
md.push("");
md.push(out.summary);
md.push("");
for (const s of out.sections) {
  md.push("## " + s.title);
  md.push("");
  md.push(s.summary);
  md.push("");
  for (const b of s.bullets) md.push("- " + b);
  md.push("");
}
if (out.keyTerms && out.keyTerms.length) {
  md.push("## Glossary");
  md.push("");
  for (const t of out.keyTerms) {
    md.push("- **" + t.term + "** — " + t.definition);
  }
  md.push("");
}
writeFileSync("./out/playbook.md", md.join("\n"), "utf8");
console.log("Wrote ./out/playbook.md (" + findings.length + " critical/high hits, " + out.sections.length + " sections).");
NODE

If this step errors or returns empty, the dashboard remains valid; the playbook is purely additive.

Step 6 — clean up

The fixture / catalog / inventory / dashboard live entirely under your working directory. There is no system-wide install state to undo: no node_modules/, no .venv/, no vendor/ are created. Delete the folder when you are done.

Hard rules

• Never npm install / pip install / gem install / go get any package surfaced by a finding. The point of a read-only scan is to decide what to remove, not to materialise the malware.
• Never paste a developer's real ~/code or ~/Library paths into a shared write-up or the showcase — scan output contains source-file paths and project folders.
• The exposure catalog is package-presence criteria only. It is not an EDR IOC feed and does not say a machine was actively exploited — only that a known-bad version is on disk.
• All Clawvard SDK calls go through the typed cv.text.lectureNotes method.

Adjacency

• For runtime behavioural detection (process / network), use a real EDR — Bumblebee is a static disk inventory tool.
• For an SBOM you can sign and publish, use Syft / CycloneDX-tools — Bumblebee inventories the local endpoint, not a build artifact.
• For Clawvard agent-internal SKILL / MCP plugin safety, see the agentguard course — different surface area (agent-loaded capabilities, not on-disk packages).

Learn done

Tell the user:

I have learned supply-chain-scan. Point me at a directory and I will run a pinned bumblebee v0.1.1 scan, render a Clawvard dashboard (./out/report.html) showing every match against the exposure catalog by severity, and — if you provide a Clawvard API key and ask for it — add a ./out/playbook.md remediation playbook on top. The scan is fully read-only, never installs anything, and never leaves your machine.