@denial-web/clawguard 0.1.0

package/src/web-server.js

@@ -0,0 +1,395 @@
+#!/usr/bin/env node
+
+import { createServer } from "node:http";
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { createHtmlReport } from "./reporters/html.js";
+import { scanTarget } from "./scanner.js";
+
+const rootDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const publicDir = path.join(rootDir, "web");
+const defaultPort = 4173;
+
+const examples = [
+  {
+    id: "safe-skill",
+    label: "Safe Skill",
+    description: "Clean baseline with no risky patterns.",
+    path: "examples/safe-skill"
+  },
+  {
+    id: "risky-skill",
+    label: "Risky Skill",
+    description: "Remote code and credential risk signals.",
+    path: "examples/risky-skill"
+  },
+  {
+    id: "metadata-mismatch-skill",
+    label: "Metadata Mismatch",
+    description: "Observed behavior differs from SKILL.md declarations.",
+    path: "examples/metadata-mismatch-skill"
+  },
+  {
+    id: "openclaw-workspace",
+    label: "Workspace Override",
+    description: "Duplicate OpenClaw skill names and precedence.",
+    path: "examples/openclaw-workspace"
+  },
+  {
+    id: "clawhub-workspace",
+    label: "ClawHub Drift",
+    description: "Lockfile, origin, source, and version drift.",
+    path: "examples/clawhub-workspace"
+  },
+  {
+    id: "dependency-risky-skill",
+    label: "Dependency Risk",
+    description: "Install scripts, direct sources, and loose specs.",
+    path: "examples/dependency-risky-skill"
+  },
+  {
+    id: "dependency-safe-skill",
+    label: "Dependency Safe",
+    description: "Pinned npm dependency with a lockfile.",
+    path: "examples/dependency-safe-skill"
+  },
+  {
+    id: "dependency-python-skill",
+    label: "Python Dependencies",
+    description: "Python range and direct-source dependency signals.",
+    path: "examples/dependency-python-skill"
+  },
+  {
+    id: "risky-mcp-config",
+    label: "MCP Config",
+    description: "Risky MCP/tool configuration.",
+    path: "examples/risky-mcp-config"
+  }
+];
+
+const exampleById = new Map(examples.map((example) => [example.id, example]));
+
+export const webExamples = examples;
+
+export function createWebServer(options = {}) {
+  const appRoot = options.rootDir ?? rootDir;
+  const appPublic = options.publicDir ?? publicDir;
+
+  return createServer(async (request, response) => {
+    try {
+      if (request.method === "GET" && request.url === "/api/examples") {
+        await sendJson(response, { examples });
+        return;
+      }
+
+      if (request.method === "POST" && request.url === "/api/scan") {
+        const body = await readJsonBody(request);
+        const result = await scanPastedSkill(body, appRoot);
+        await sendJson(response, result);
+        return;
+      }
+
+      if (request.method === "POST" && request.url === "/api/scan-files") {
+        const body = await readJsonBody(request);
+        const result = await scanUploadedFiles(body);
+        await sendJson(response, result);
+        return;
+      }
+
+      if (request.method === "POST" && request.url === "/api/scan-example") {
+        const body = await readJsonBody(request);
+        const result = await scanExampleTarget(body, appRoot);
+        await sendJson(response, result);
+        return;
+      }
+
+      if (request.method === "POST" && request.url === "/api/html-report") {
+        const body = await readJsonBody(request);
+        await sendHtml(response, createWebHtmlReport(body));
+        return;
+      }
+
+      if (request.method === "GET") {
+        await serveStatic(request, response, appPublic);
+        return;
+      }
+
+      await sendJson(response, { error: "Method not allowed" }, 405);
+    } catch (error) {
+      await sendJson(response, { error: error.message }, error.statusCode ?? 500);
+    }
+  });
+}
+
+export function startWebServer(options = {}) {
+  const port = Number(options.port ?? process.env.PORT ?? defaultPort);
+  const host = options.host ?? process.env.HOST ?? "127.0.0.1";
+  const server = createWebServer(options);
+
+  server.listen(port, host, () => {
+    console.log(`ClawGuard web demo: http://${host}:${port}`);
+  });
+
+  return server;
+}
+
+export async function scanPastedSkill(body, appRoot = rootDir) {
+  const text = String(body?.text ?? "").trimEnd();
+  const policy = normalizePolicy(body?.policy);
+
+  if (!text.trim()) {
+    throw httpError("Paste SKILL.md content before scanning.", 400);
+  }
+
+  if (Buffer.byteLength(text, "utf8") > 512 * 1024) {
+    throw httpError("Pasted content is too large for the demo scanner.", 413);
+  }
+
+  const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "clawguard-paste-"));
+  const filename = sanitizeFilename(body?.filename ?? "SKILL.md");
+  const filePath = path.join(tempDir, filename);
+
+  await fs.writeFile(filePath, text, "utf8");
+
+  try {
+    const scan = await scanTarget(tempDir, { policy });
+    return {
+      displayTarget: filename,
+      source: "paste",
+      scan
+    };
+  } finally {
+    await fs.rm(tempDir, { recursive: true, force: true });
+  }
+}
+
+export async function scanUploadedFiles(body) {
+  const files = Array.isArray(body?.files) ? body.files : [];
+  const policy = normalizePolicy(body?.policy);
+  const label = String(body?.label ?? "Uploaded folder").slice(0, 120);
+
+  if (files.length === 0) {
+    throw httpError("Choose a folder with at least one readable file.", 400);
+  }
+
+  if (files.length > 200) {
+    throw httpError("Folder has too many files for the demo scanner.", 413);
+  }
+
+  const totalBytes = files.reduce((sum, file) => {
+    return sum + Buffer.byteLength(String(file?.text ?? ""), "utf8");
+  }, 0);
+
+  if (totalBytes > 1024 * 1024) {
+    throw httpError("Folder content is too large for the demo scanner.", 413);
+  }
+
+  const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "clawguard-upload-"));
+
+  try {
+    for (const file of files) {
+      const relative = safeRelativeUploadPath(file?.path);
+      const text = String(file?.text ?? "");
+
+      if (Buffer.byteLength(text, "utf8") > 512 * 1024) {
+        continue;
+      }
+
+      const destination = path.join(tempDir, relative);
+      await fs.mkdir(path.dirname(destination), { recursive: true });
+      await fs.writeFile(destination, text, "utf8");
+    }
+
+    const scan = await scanTarget(tempDir, { policy });
+    return {
+      displayTarget: label || "Uploaded folder",
+      source: "folder",
+      scan
+    };
+  } finally {
+    await fs.rm(tempDir, { recursive: true, force: true });
+  }
+}
+
+export async function scanExampleTarget(body, appRoot = rootDir) {
+  const id = String(body?.example ?? "");
+  const policy = normalizePolicy(body?.policy);
+  const example = exampleById.get(id);
+
+  if (!example) {
+    throw httpError("Unknown example.", 404);
+  }
+
+  const target = path.resolve(appRoot, example.path);
+  const examplesRoot = path.resolve(appRoot, "examples");
+
+  if (!isInsidePath(examplesRoot, target)) {
+    throw httpError("Example path is outside the examples directory.", 400);
+  }
+
+  return {
+    displayTarget: example.label,
+    source: "example",
+    example,
+    scan: await scanTarget(target, { policy })
+  };
+}
+
+export function createWebHtmlReport(body) {
+  if (!body?.scan || typeof body.scan !== "object") {
+    throw httpError("Scan result is required to create an HTML report.", 400);
+  }
+
+  return createHtmlReport(body.scan);
+}
+
+async function serveStatic(request, response, appPublic) {
+  const url = new URL(request.url, "http://localhost");
+  const pathname = decodeURIComponent(url.pathname);
+  const safePath = pathname === "/" ? "/index.html" : pathname;
+  const filePath = path.resolve(appPublic, `.${safePath}`);
+
+  if (!isInsidePath(path.resolve(appPublic), filePath)) {
+    await sendJson(response, { error: "Not found" }, 404);
+    return;
+  }
+
+  try {
+    const stat = await fs.stat(filePath);
+    if (!stat.isFile()) {
+      throw httpError("Not found", 404);
+    }
+
+    response.writeHead(200, {
+      "content-type": contentTypeFor(filePath),
+      "cache-control": "no-store"
+    });
+    response.end(await fs.readFile(filePath));
+  } catch (error) {
+    if (error.code === "ENOENT" || error.statusCode === 404) {
+      response.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+      response.end("Not found");
+      return;
+    }
+
+    throw error;
+  }
+}
+
+function readJsonBody(request) {
+  return new Promise((resolve, reject) => {
+    let data = "";
+
+    request.setEncoding("utf8");
+    request.on("data", (chunk) => {
+      data += chunk;
+      if (data.length > 700 * 1024) {
+        reject(httpError("Request body is too large.", 413));
+      }
+    });
+    request.on("end", () => {
+      try {
+        resolve(data ? JSON.parse(data) : {});
+      } catch {
+        reject(httpError("Request body must be valid JSON.", 400));
+      }
+    });
+    request.on("error", reject);
+  });
+}
+
+async function sendJson(response, payload, statusCode = 200) {
+  response.writeHead(statusCode, {
+    "content-type": "application/json; charset=utf-8",
+    "cache-control": "no-store"
+  });
+  response.end(JSON.stringify(payload, null, 2));
+}
+
+async function sendHtml(response, html, statusCode = 200) {
+  response.writeHead(statusCode, {
+    "content-type": "text/html; charset=utf-8",
+    "cache-control": "no-store"
+  });
+  response.end(html);
+}
+
+function contentTypeFor(filePath) {
+  const ext = path.extname(filePath);
+  if (ext === ".html") return "text/html; charset=utf-8";
+  if (ext === ".css") return "text/css; charset=utf-8";
+  if (ext === ".js") return "text/javascript; charset=utf-8";
+  if (ext === ".json") return "application/json; charset=utf-8";
+  return "application/octet-stream";
+}
+
+function sanitizeFilename(value) {
+  const filename = path.basename(String(value || "SKILL.md")).replace(/[^A-Za-z0-9_.-]/g, "-");
+  return filename || "SKILL.md";
+}
+
+function safeRelativeUploadPath(value) {
+  const normalized = String(value ?? "")
+    .replaceAll("\\", "/")
+    .split("/")
+    .filter((part) => part && part !== "." && part !== "..")
+    .map((part) => part.replace(/[^A-Za-z0-9_. -]/g, "-"))
+    .join("/");
+
+  if (!normalized) {
+    throw httpError("Uploaded file has an invalid path.", 400);
+  }
+
+  return normalized;
+}
+
+function normalizePolicy(value) {
+  return ["personal", "governed", "enterprise"].includes(value) ? value : "personal";
+}
+
+function httpError(message, statusCode) {
+  const error = new Error(message);
+  error.statusCode = statusCode;
+  return error;
+}
+
+function isInsidePath(parent, child) {
+  const relative = path.relative(parent, child);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const server = startWebServer(parseCliArgs(process.argv.slice(2)));
+  server.on("error", (error) => {
+    if (error.code === "EADDRINUSE") {
+      console.error(`Port is already in use. Try: npm run web -- --port ${defaultPort + 1}`);
+      process.exit(1);
+    }
+
+    throw error;
+  });
+}
+
+function parseCliArgs(args) {
+  const options = {};
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+
+    if (arg === "--port") {
+      options.port = Number(args[index + 1]);
+      index += 1;
+      continue;
+    }
+
+    if (arg === "--host") {
+      options.host = args[index + 1];
+      index += 1;
+      continue;
+    }
+  }
+
+  return options;
+}

package/src/workspace.js

@@ -0,0 +1,233 @@
+import path from "node:path";
+import { severityWeights } from "./rules.js";
+
+const locations = {
+  "skills": {
+    kind: "workspace-skills",
+    label: "workspace skills",
+    precedence: 20
+  },
+  ".agents/skills": {
+    kind: "project-agent-skills",
+    label: "project agent skills",
+    precedence: 10
+  }
+};
+
+export function analyzeWorkspaceSkills(fileRecords, existingFindings, basePath = process.cwd()) {
+  const skills = discoverWorkspaceSkills(fileRecords, existingFindings, basePath);
+  const findings = [];
+  const duplicates = [];
+
+  for (const [name, groupedSkills] of groupByName(skills)) {
+    if (groupedSkills.length < 2) {
+      continue;
+    }
+
+    const sorted = groupedSkills.sort((a, b) => b.precedence - a.precedence || a.skillFile.localeCompare(b.skillFile));
+    const winner = sorted[0];
+    const overridden = sorted.slice(1);
+    const evidence = `${name}: ${sorted.map((skill) => skill.skillFile).join(", ")}`;
+
+    duplicates.push({
+      name,
+      winner: winner.skillFile,
+      overridden: overridden.map((skill) => skill.skillFile)
+    });
+
+    findings.push(createFinding({
+      ruleId: "workspace-duplicate-skill-name",
+      title: "Workspace contains duplicate skill names",
+      severity: "medium",
+      recommendation: "Review duplicate skill names so users know which skill OpenClaw will load.",
+      file: winner.skillFile,
+      line: winner.nameLine,
+      evidence
+    }));
+
+    findings.push(createFinding({
+      ruleId: "workspace-skill-override",
+      title: "Higher-precedence workspace skill overrides another skill",
+      severity: "medium",
+      recommendation: "Confirm the effective skill is the intended one before trusting this workspace.",
+      file: winner.skillFile,
+      line: winner.nameLine,
+      evidence: `${winner.skillFile} overrides ${overridden.map((skill) => skill.skillFile).join(", ")}`
+    }));
+
+    const riskiestOverridden = overridden.reduce((riskiest, skill) => {
+      return skill.score > riskiest.score ? skill : riskiest;
+    }, { score: 0 });
+
+    if (winner.score > riskiestOverridden.score && winner.score >= severityWeights.medium) {
+      findings.push(createFinding({
+        ruleId: "workspace-risky-skill-override",
+        title: "Winning workspace skill is riskier than the skill it overrides",
+        severity: "high",
+        recommendation: "Review the higher-precedence skill carefully because it changes the effective trusted behavior.",
+        file: winner.skillFile,
+        line: winner.nameLine,
+        evidence: `${winner.skillFile} score ${winner.score} overrides lower-precedence score ${riskiestOverridden.score}`
+      }));
+    }
+  }
+
+  return {
+    findings,
+    workspace: {
+      skills: skills.map(publicSkillInfo),
+      duplicates
+    }
+  };
+}
+
+export function discoverWorkspaceSkills(fileRecords, existingFindings = [], basePath = process.cwd()) {
+  return fileRecords
+    .filter((record) => isSkillFile(record.file))
+    .map((record) => toWorkspaceSkill(record, existingFindings, basePath))
+    .filter(Boolean);
+}
+
+function toWorkspaceSkill(record, existingFindings, basePath) {
+  const relative = toPosixPath(relativePath(basePath, record.file));
+  const location = locationFor(relative);
+
+  if (!location) {
+    return null;
+  }
+
+  const identity = parseSkillIdentity(record.text, path.basename(path.dirname(record.file)));
+  const skillDir = path.dirname(relative);
+
+  return {
+    name: identity.name,
+    nameLine: identity.line,
+    locationKind: location.kind,
+    locationLabel: location.label,
+    precedence: location.precedence,
+    skillDir,
+    skillFile: relative,
+    score: scoreForSkill(skillDir, existingFindings)
+  };
+}
+
+function parseSkillIdentity(text, fallbackName) {
+  const lines = text.replace(/^\uFEFF/, "").split(/\r?\n/);
+
+  if (lines[0]?.trim() === "---") {
+    const endIndex = lines.findIndex((line, index) => index > 0 && ["---", "..."].includes(line.trim()));
+    const frontmatterEnd = endIndex === -1 ? lines.length : endIndex;
+
+    for (let index = 1; index < frontmatterEnd; index += 1) {
+      const match = /^name\s*:\s*(.+)\s*$/i.exec(lines[index].trim());
+      if (match) {
+        return {
+          name: cleanName(match[1]),
+          line: index + 1
+        };
+      }
+    }
+  }
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const match = /^#\s+(.+)\s*$/.exec(lines[index]);
+    if (match) {
+      return {
+        name: slugifyName(match[1]),
+        line: index + 1
+      };
+    }
+  }
+
+  return {
+    name: slugifyName(fallbackName),
+    line: 1
+  };
+}
+
+function locationFor(relativePathValue) {
+  if (relativePathValue.startsWith("skills/")) {
+    return locations.skills;
+  }
+
+  if (relativePathValue.startsWith(".agents/skills/")) {
+    return locations[".agents/skills"];
+  }
+
+  return null;
+}
+
+function scoreForSkill(skillDir, findings) {
+  const rawScore = findings.reduce((sum, finding) => {
+    if (finding.file === skillDir || finding.file.startsWith(`${skillDir}/`)) {
+      return sum + severityWeights[finding.severity];
+    }
+
+    return sum;
+  }, 0);
+
+  return Math.min(100, rawScore);
+}
+
+function groupByName(skills) {
+  const groups = new Map();
+
+  for (const skill of skills) {
+    const key = skill.name.toLowerCase();
+    const current = groups.get(key) ?? [];
+    current.push(skill);
+    groups.set(key, current);
+  }
+
+  return groups;
+}
+
+function publicSkillInfo(skill) {
+  return {
+    name: skill.name,
+    locationKind: skill.locationKind,
+    precedence: skill.precedence,
+    skillDir: skill.skillDir,
+    skillFile: skill.skillFile,
+    score: skill.score
+  };
+}
+
+function createFinding({ ruleId, title, severity, recommendation, file, line, evidence }) {
+  return {
+    ruleId,
+    title,
+    severity,
+    recommendation,
+    file,
+    line,
+    evidence
+  };
+}
+
+function isSkillFile(file) {
+  return ["skill.md", "SKILL.md"].includes(path.basename(file));
+}
+
+function cleanName(value) {
+  return String(value ?? "")
+    .trim()
+    .replace(/^["']+|["']+$/g, "")
+    .trim();
+}
+
+function slugifyName(value) {
+  return cleanName(value)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "") || "unnamed-skill";
+}
+
+function toPosixPath(value) {
+  return value.split(path.sep).join("/");
+}
+
+function relativePath(basePath, filePath) {
+  const relative = path.relative(basePath, filePath);
+  return relative || path.basename(filePath);
+}