toolstile 0.2.1 → 0.3.0

package/dist/report.d.ts

@@ -19,6 +19,8 @@ export declare function counts(findings: Finding[]): {
  * becomes `<project>`, and project paths inside pointers (Claude Code's `projects["/path"]`) are hidden.
  */
 export declare function redact(r: AuditResult, home: string, project: string | null): AuditResult;
-export declare function renderReport(r: AuditResult, home: string, s: Style, redacted?: boolean): string;
+/** Greedy word wrap; every line after the first starts with `indent`. Long words are kept whole. */
+export declare function wrap(text: string, width: number, indent?: string): string;
+export declare function renderReport(r: AuditResult, home: string, s: Style, redacted?: boolean, columns?: number): string;
 /** JSON output for scripts. Paths are included unless redacted; secret values never are. */
 export declare function renderJson(r: AuditResult): string;

package/dist/report.js

@@ -44,25 +44,85 @@ export function redact(r, home, project) {
         findings: r.findings.map((f) => ({
             ...f,
             title: scrub(f.title),
+            subject: scrub(f.subject),
+            note: scrub(f.note),
             detail: scrub(f.detail),
             fix: scrub(f.fix),
             locations: f.locations.map((l) => ({ file: scrub(l.file), pointer: scrub(l.pointer) })),
         })),
     };
 }
-export function renderReport(r, home, s, redacted = false) {
+/** How each kind of finding is explained once, above the places it was found. */
+const GROUPS = {
+    "plaintext-secret": {
+        heading: "Plaintext secrets",
+        why: "Anything that can read these files can use the credentials, including backups, dotfile syncs and other tools.",
+        fix: "Move them into environment variables, or use the server's OAuth sign-in. Rotate any secret in a file that was shared or synced.",
+    },
+    "insecure-transport": {
+        heading: "Unencrypted remote servers",
+        why: "Requests, tool results and any credentials travel over plain http://.",
+        fix: "Use the server's https:// endpoint.",
+    },
+    "privileged-container": {
+        heading: "Containers with host-level access",
+        why: "--privileged, the Docker socket and host networking give the server effective control of this machine.",
+        fix: "Remove them unless the server truly needs them.",
+    },
+    "copied-secret": {
+        heading: "Credentials copied into several files",
+        why: "Rotating or revoking one of these means finding every copy.",
+        fix: "Keep one copy in your environment or keychain and reference it from each client, or route the clients through one gateway.",
+    },
+    "readable-config": {
+        heading: "Files with secrets that other accounts can read",
+        why: "The file and every folder above it are open, so other accounts on this machine can read the secrets.",
+        fix: "Restrict each file to your user with chmod 600.",
+    },
+    "unpinned-package": {
+        heading: "Unpinned packages",
+        why: "Each start runs whatever version is newest, so a compromised or broken release runs with the server's access.",
+        fix: "Pin an exact version (an image digest or exact tag for Docker).",
+    },
+    "broad-filesystem": {
+        heading: "Filesystem servers with broad access",
+        why: "The allowed root includes SSH keys, cloud credentials and every other config file.",
+        fix: "Allow only the project folders the agent needs.",
+    },
+    "auto-approved-tools": {
+        heading: "Tools that run without asking",
+        why: "A prompt injection in a web page, issue or email the agent reads can call these, including write and delete tools.",
+        fix: "Approve specific read-only tools (mcp__server__tool) instead of whole servers.",
+    },
+};
+/** Greedy word wrap; every line after the first starts with `indent`. Long words are kept whole. */
+export function wrap(text, width, indent = "") {
+    const lines = [];
+    let line = "";
+    for (const word of text.split(/\s+/).filter(Boolean)) {
+        const room = width - (lines.length ? indent.length : 0);
+        if (line && line.length + 1 + word.length > room) {
+            lines.push(line);
+            line = word;
+        }
+        else
+            line = line ? `${line} ${word}` : word;
+    }
+    if (line)
+        lines.push(line);
+    return lines.join(`\n${indent}`);
+}
+const SEVERITIES = ["high", "medium", "low"];
+export function renderReport(r, home, s, redacted = false, columns = 80) {
+    // Wide terminals still get short lines: they are easier to read.
+    const width = Math.max(40, Math.min(columns, 100) - 1);
+    const para = (text, indent = "  ") => indent + wrap(text, width - indent.length, indent);
     const lines = [];
     lines.push("", `${s.bold("toolstile audit")} ${s.dim("· local MCP config check · nothing leaves this machine")}`, "");
     if (r.files.length === 0 && r.unreadable.length === 0) {
         lines.push("No MCP client configs found.", s.dim("Looked for Claude Code, Claude Desktop, Cursor, Codex, VS Code, Windsurf, Gemini CLI and Cline."), "");
         return lines.join("\n");
     }
-    const clientList = r.clients.map((c) => CLIENT_NAMES[c]).join(", ");
-    lines.push(`Scanned ${plural(r.files.length, "file")} from ${clientList}: ${plural(r.servers, "MCP server")}.`);
-    for (const u of r.unreadable) {
-        lines.push(s.dim(`Skipped ${tildify(u.path, home)} (${CLIENT_NAMES[u.client]}): ${u.error}.`));
-    }
-    lines.push("");
     if (r.grade !== null) {
         const c = counts(r.findings);
         const parts = [
@@ -71,33 +131,55 @@ export function renderReport(r, home, s, redacted = false) {
             c.low && s.sev("low", `${c.low} low`),
         ].filter(Boolean);
         const summary = parts.length ? parts.join(s.dim(" · ")) : "no issues found";
-        lines.push(`  ${s.bold(s.grade(r.grade, `Grade ${r.grade}`))}  ${s.dim(`${r.score}/100`)}   ${summary}`, "");
+        lines.push(`  ${s.bold(s.grade(r.grade, `Grade ${r.grade}`))}  ${s.dim(`${r.score}/100`)}   ${summary}`);
     }
-    const issues = r.findings.filter((f) => f.severity !== "info");
-    const info = r.findings.filter((f) => f.severity === "info");
-    for (const f of issues) {
-        const tag = s.sev(f.severity, f.severity.toUpperCase().padEnd(6));
-        lines.push(`${tag} ${s.bold(f.title)}`);
-        lines.push(`       ${f.detail}`);
-        const shown = f.locations.slice(0, 5);
-        for (const l of shown)
-            lines.push(s.dim(`       ${tildify(l.file, home)}  ${l.pointer}`));
-        if (f.locations.length > shown.length)
-            lines.push(s.dim(`       … and ${f.locations.length - shown.length} more`));
-        lines.push(`       ${s.dim("Fix:")} ${f.fix}`, "");
+    const clientList = r.clients.map((c) => CLIENT_NAMES[c]).join(", ");
+    lines.push(s.dim(para(`${plural(r.servers, "MCP server")} in ${plural(r.files.length, "file")} from ${clientList}`)));
+    for (const u of r.unreadable) {
+        lines.push(s.dim(para(`Skipped ${tildify(u.path, home)} (${CLIENT_NAMES[u.client]}): ${u.error}.`)));
     }
+    lines.push("");
+    // One block per kind of problem: what it is and how to fix it once, then each place it was found.
+    for (const severity of SEVERITIES) {
+        const byRule = new Map();
+        for (const f of r.findings)
+            if (f.severity === severity)
+                byRule.set(f.rule, [...(byRule.get(f.rule) ?? []), f]);
+        for (const [rule, list] of byRule) {
+            const group = GROUPS[rule];
+            const tag = s.sev(severity, severity.toUpperCase());
+            lines.push(`${tag}  ${s.bold(group?.heading ?? list[0].title)} ${s.dim(`(${list.length})`)}`);
+            lines.push(para(group?.why ?? list[0].detail), "");
+            for (const f of list) {
+                const note = f.note ? `  ${s.dim(f.note)}` : "";
+                lines.push(`  ${s.sev(severity, "•")} ${tildify(f.subject, home)}${note}`);
+                const shown = f.locations.filter((l) => l.file !== f.subject).slice(0, 4);
+                for (const l of shown) {
+                    const where = `${tildify(l.file, home)}  ${l.pointer}`;
+                    lines.push(s.dim(where.length <= width - 4 ? `    ${where}` : para(where, "    ")));
+                }
+                const hidden = f.locations.filter((l) => l.file !== f.subject).length - shown.length;
+                if (hidden > 0)
+                    lines.push(s.dim(`    … and ${hidden} more`));
+            }
+            lines.push("", `  ${s.bold("Fix")} ${wrap(group?.fix ?? list[0].fix, width - 6, "      ")}`, "");
+        }
+    }
+    const info = r.findings.filter((f) => f.severity === "info");
     if (info.length) {
         lines.push(s.dim("Also set up in more than one client (not scored):"));
         for (const f of info)
-            lines.push(s.dim(`  ${f.title.replace(/ is set up separately in (\d+) clients$/, "")}: ${f.detail.split(".")[0].replace(/^Configured in /, "")}`));
+            lines.push(s.dim(para(`${f.subject}: ${f.note}`)));
         lines.push("");
     }
+    if (r.findings.some((f) => f.severity !== "info"))
+        lines.push(`${s.bold("Fix them:")} npx toolstile audit --fix ${s.dim("(shows every change; you pick which to apply)")}`, "");
     lines.push(s.dim("Secret values are never printed."));
     if (!redacted)
-        lines.push(s.dim("Posting this? Run with --redact to hide your paths, or --card for an image with only the grade."));
+        lines.push(s.dim(wrap("Posting this? Run with --redact to hide your paths, or --card for an image with only the grade.", width)));
     else
         lines.push(s.dim("Share an image with only the grade: npx toolstile audit --card"));
-    lines.push(s.dim("Keep credentials off your machines and control each agent's tools: https://toolstile.com/?ref=cli"), "");
+    lines.push(s.dim(wrap("Keep credentials off your machines and control each agent's tools: https://toolstile.com/?ref=cli", width)), "");
     return lines.join("\n");
 }
 /** JSON output for scripts. Paths are included unless redacted; secret values never are. */

package/dist/sources.js

@@ -61,23 +61,29 @@ export function pointerJoin(base, key) {
         return part;
     return part.startsWith("[") ? `${base}${part}` : `${base}.${part}`;
 }
-function toServer(client, file, pointer, name, v) {
+function toServer(client, file, path, name, v) {
     if (!isObject(v))
         return null;
     const extraSecrets = {};
     const bearer = str(v.bearer_token);
     if (bearer)
         extraSecrets.bearer_token = bearer;
+    const headerKeys = {};
+    for (const key of ["headers", "http_headers"])
+        for (const name of Object.keys(stringRecord(v[key])))
+            headerKeys[name] = key;
     return {
         client,
         file,
-        pointer,
+        pointer: path.reduce(pointerJoin, ""),
+        path,
         name,
         command: str(v.command),
         args: strings(v.args),
         env: stringRecord(v.env),
         url: str(v.url) ?? str(v.serverUrl) ?? str(v.httpUrl),
         headers: { ...stringRecord(v.headers), ...stringRecord(v.http_headers) },
+        headerKeys,
         extraSecrets,
         autoApproved: [...strings(v.alwaysAllow), ...strings(v.autoApprove)],
     };
@@ -87,7 +93,7 @@ function serversAt(client, file, base, v) {
         return [];
     const out = [];
     for (const [name, def] of Object.entries(v)) {
-        const server = toServer(client, file, pointerJoin(base, name), name, def);
+        const server = toServer(client, file, [...base, name], name, def);
         if (server)
             out.push(server);
     }
@@ -194,16 +200,15 @@ export function discover(opts) {
             continue;
         switch (c.kind) {
             case "mcp":
-                result.servers.push(...serversAt(c.client, c.path, "mcpServers", data.mcpServers));
+                result.servers.push(...serversAt(c.client, c.path, ["mcpServers"], data.mcpServers));
                 break;
             case "claude-json":
-                result.servers.push(...serversAt(c.client, c.path, "mcpServers", data.mcpServers));
+                result.servers.push(...serversAt(c.client, c.path, ["mcpServers"], data.mcpServers));
                 if (isObject(data.projects)) {
                     for (const [project, conf] of Object.entries(data.projects)) {
                         if (!isObject(conf))
                             continue;
-                        const base = pointerJoin(pointerJoin("projects", project), "mcpServers");
-                        result.servers.push(...serversAt(c.client, c.path, base, conf.mcpServers));
+                        result.servers.push(...serversAt(c.client, c.path, ["projects", project, "mcpServers"], conf.mcpServers));
                     }
                 }
                 break;
@@ -211,14 +216,14 @@ export function discover(opts) {
                 result.approvals.push(...claudeApprovals(file));
                 break;
             case "codex":
-                result.servers.push(...serversAt(c.client, c.path, "mcp_servers", data.mcp_servers));
+                result.servers.push(...serversAt(c.client, c.path, ["mcp_servers"], data.mcp_servers));
                 break;
             case "vscode-settings":
                 if (isObject(data.mcp))
-                    result.servers.push(...serversAt(c.client, c.path, "mcp.servers", data.mcp.servers));
+                    result.servers.push(...serversAt(c.client, c.path, ["mcp", "servers"], data.mcp.servers));
                 break;
             case "vscode-mcp":
-                result.servers.push(...serversAt(c.client, c.path, "servers", data.servers));
+                result.servers.push(...serversAt(c.client, c.path, ["servers"], data.servers));
                 break;
         }
     }

package/dist/types.d.ts

@@ -22,12 +22,16 @@ export interface ServerEntry {
     file: string;
     /** Pointer to the server object, for example `mcpServers.github`. */
     pointer: string;
+    /** The same location as keys, for editing the file. */
+    path: string[];
     name: string;
     command?: string;
     args: string[];
     env: Record<string, string>;
     url?: string;
     headers: Record<string, string>;
+    /** The config key each header came from: `headers`, or Codex's `http_headers`. */
+    headerKeys: Record<string, string>;
     /** Other string fields that may carry credentials, such as Codex `bearer_token`. */
     extraSecrets: Record<string, string>;
     /** Tools listed under client auto-approval keys (`alwaysAllow`, `autoApprove`). */
@@ -44,6 +48,10 @@ export interface Finding {
     rule: string;
     severity: Severity;
     title: string;
+    /** What the finding is about, for example `github (Cursor)` or a file path. */
+    subject: string;
+    /** A short specific, for example the kind of secret or the package; may be empty. */
+    note: string;
     detail: string;
     fix: string;
     locations: Location[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolstile",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Audit the MCP server configs your AI agents use for plaintext secrets, unpinned packages, auto-approved tools and duplicated setups, and connect those agents to Toolstile without putting tokens in their configs.",
   "keywords": [
     "mcp",
@@ -43,6 +43,7 @@
     "prepublishOnly": "pnpm typecheck && pnpm test"
   },
   "dependencies": {
+    "jsonc-parser": "^3.3.1",
     "smol-toml": "^1.9.1"
   },
   "devDependencies": {