toolmoat 0.0.0-stage → 0.1.0

package/dist/commands/pins.d.ts

@@ -0,0 +1,18 @@
+import type { Lockfile } from '../proxy/lockfile.js';
+export declare const help = "Usage: toolmoat pins [--lock <file>] [--json]\n\nLists the MCP servers pinned by toolmoat proxy, with their tool counts and\nany tool changes waiting for review.\n\nOptions:\n  --lock <file>   Lockfile (default: <toolmoat home>/lock.json)\n  --json          Machine-readable output";
+export interface ServerSummary {
+    name: string;
+    command: string;
+    tools: number;
+    pending: number;
+    pendingTools: Array<{
+        tool: string;
+        reason: string;
+        detectedAt: string;
+    }>;
+    firstSeen: string;
+    updated: string;
+}
+/** One summary per server, sorted by name. */
+export declare function summarizeServers(lock: Lockfile): ServerSummary[];
+export declare function run(argv: string[]): Promise<number>;

package/dist/commands/pins.js

@@ -0,0 +1,88 @@
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { defaultLockPath, readLockfile } from '../proxy/lockfile.js';
+import { safeText } from '../proxy/names.js';
+import { palette } from '../util/colors.js';
+export const help = `Usage: toolmoat pins [--lock <file>] [--json]
+
+Lists the MCP servers pinned by toolmoat proxy, with their tool counts and
+any tool changes waiting for review.
+
+Options:
+  --lock <file>   Lockfile (default: <toolmoat home>/lock.json)
+  --json          Machine-readable output`;
+/** One summary per server, sorted by name. */
+export function summarizeServers(lock) {
+    return Object.keys(lock.servers)
+        .sort()
+        .map((name) => {
+        const entry = lock.servers[name];
+        const pendingTools = Object.keys(entry.pending)
+            .sort()
+            .map((tool) => ({ tool, reason: entry.pending[tool].reason, detectedAt: entry.pending[tool].detectedAt }));
+        return {
+            name,
+            command: entry.command,
+            tools: Object.keys(entry.tools).length,
+            pending: pendingTools.length,
+            pendingTools,
+            firstSeen: entry.firstSeen,
+            updated: entry.updated,
+        };
+    });
+}
+export async function run(argv) {
+    let values;
+    try {
+        ({ values } = parseArgs({ args: argv, options: { lock: { type: 'string' }, json: { type: 'boolean' } }, allowPositionals: false }));
+    }
+    catch (error) {
+        process.stderr.write(`toolmoat pins: ${error instanceof Error ? error.message : String(error)}\n`);
+        return 2;
+    }
+    const lockPath = path.resolve(values.lock ?? defaultLockPath());
+    let lock;
+    try {
+        lock = readLockfile(lockPath);
+    }
+    catch (error) {
+        process.stderr.write(`toolmoat pins: ${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+    const servers = summarizeServers(lock);
+    if (values.json) {
+        process.stdout.write(`${JSON.stringify({ lockfile: lockPath, servers }, null, 2)}\n`);
+        return 0;
+    }
+    process.stdout.write(`${renderTable(servers, lockPath)}\n`);
+    return 0;
+}
+function renderTable(servers, lockPath) {
+    const c = palette(process.stdout);
+    if (servers.length === 0) {
+        return `No pinned MCP servers in ${lockPath}.\nServers are pinned the first time they run behind toolmoat proxy.`;
+    }
+    const rows = servers.map((s) => [safeText(s.name, 60), String(s.tools), String(s.pending), shortTime(s.updated)]);
+    const header = ['SERVER', 'TOOLS', 'PENDING', 'UPDATED (UTC)'];
+    const widths = header.map((h, i) => Math.max(h.length, ...rows.map((r) => r[i].length)));
+    const line = (cells) => cells.map((cell, i) => cell.padEnd(widths[i])).join('  ').trimEnd();
+    const out = [`Lockfile: ${lockPath}`, '', c.bold(line(header))];
+    rows.forEach((row, index) => {
+        const text = line(row);
+        out.push(servers[index].pending > 0 ? c.yellow(text) : text);
+    });
+    const waiting = servers.filter((s) => s.pending > 0);
+    if (waiting.length > 0) {
+        out.push('');
+        for (const s of waiting) {
+            const tools = s.pendingTools.map((p) => `${safeText(p.tool, 60)} (${p.reason})`).join(', ');
+            out.push(`${c.yellow('!')} ${safeText(s.name, 60)}: ${tools}`);
+        }
+        out.push('', `Review with ${c.cyan('toolmoat diff <server>')}, then ${c.cyan('toolmoat approve <server>')}.`);
+    }
+    return out.join('\n');
+}
+function shortTime(iso) {
+    const match = /^(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2})/.exec(iso);
+    return match ? `${match[1]} ${match[2]}` : iso || '-';
+}

package/dist/commands/proxy.d.ts

@@ -0,0 +1,24 @@
+import type { Mode, OnNew } from '../proxy/policy.js';
+export declare const help: string;
+export declare class UsageError extends Error {
+    name: string;
+}
+export interface ProxyArgs {
+    help: boolean;
+    name?: string;
+    lock?: string;
+    mode: Mode;
+    onNew: OnNew;
+    auditLog?: string;
+    noAudit: boolean;
+    logArgs: boolean;
+    allowSecrets: string[];
+    command?: string;
+    args: string[];
+}
+/**
+ * Parses proxy options up to `--` (or up to the first non-option word);
+ * everything after belongs to the server command and is never interpreted.
+ */
+export declare function parseProxyArgs(argv: readonly string[]): ProxyArgs;
+export declare function run(argv: string[]): Promise<number>;

package/dist/commands/proxy.js

@@ -0,0 +1,144 @@
+import path from 'node:path';
+import { SECRET_PATTERNS } from '../patterns/secrets.js';
+import { defaultLockPath } from '../proxy/lockfile.js';
+import { deriveServerName, fileSafeName, formatCommand } from '../proxy/names.js';
+import { runProxy } from '../proxy/proxy.js';
+import { toolmoatHome } from '../util/paths.js';
+export const help = `Usage: toolmoat proxy [options] -- <command> [args...]
+
+Runs an MCP stdio server behind toolmoat's runtime firewall. Use it in your
+MCP client config in place of the server command (toolmoat wrap does that).
+
+  - Pins every tool definition (sha256) on first run and hides tools whose
+    definition later changes (rug pulls) or that appear later, until you
+    approve them.
+  - Hides tools whose descriptions contain high or critical findings (tool
+    poisoning, hidden instructions) from the model.
+  - Blocks tool calls whose arguments contain credentials (egress guard).
+  - Warns when a tool's output looks like prompt injection.
+  - Keeps a JSONL audit log; argument values are not logged by default.
+
+Options:
+  --name <id>            Server id in the lockfile (default: derived from the command)
+  --lock <file>          Lockfile (default: <toolmoat home>/lock.json, ~/.toolmoat or TOOLMOAT_HOME)
+  --mode enforce|warn    enforce hides and blocks; warn only reports (default: enforce)
+  --on-new block|allow   Tools that appear on an already pinned server (default: block)
+  --audit-log <file>     Audit log (default: <toolmoat home>/audit/<name>.jsonl)
+  --no-audit             Do not write an audit log
+  --log-args             Also log tool-call arguments, with secrets redacted
+  --allow-secret <id>    Let one credential type through the egress guard (repeatable).
+                         Ids: ${SECRET_PATTERNS.map((p) => p.id).join(', ')}
+  -h, --help             Show this help (only before --)
+
+Examples:
+  toolmoat proxy -- npx -y @modelcontextprotocol/server-filesystem ~/projects
+  toolmoat proxy --name demo -- node examples/rugpull-server.mjs
+
+Held tools: toolmoat pins, toolmoat diff <name>, toolmoat approve <name>`;
+export class UsageError extends Error {
+    name = 'UsageError';
+}
+const VALUE_FLAGS = new Set(['--name', '--lock', '--mode', '--on-new', '--audit-log', '--allow-secret']);
+const BOOLEAN_FLAGS = new Set(['--no-audit', '--log-args', '--help', '-h']);
+/**
+ * Parses proxy options up to `--` (or up to the first non-option word);
+ * everything after belongs to the server command and is never interpreted.
+ */
+export function parseProxyArgs(argv) {
+    const out = { help: false, mode: 'enforce', onNew: 'block', noAudit: false, logArgs: false, allowSecrets: [], args: [] };
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === '--' || !token.startsWith('-') || token === '-') {
+            const start = token === '--' ? i + 1 : i;
+            out.command = argv[start];
+            out.args = argv.slice(start + 1);
+            break;
+        }
+        const eq = token.startsWith('--') ? token.indexOf('=') : -1;
+        const flag = eq === -1 ? token : token.slice(0, eq);
+        if (BOOLEAN_FLAGS.has(flag)) {
+            if (eq !== -1)
+                throw new UsageError(`${flag} does not take a value`);
+            if (flag === '--help' || flag === '-h')
+                out.help = true;
+            else if (flag === '--no-audit')
+                out.noAudit = true;
+            else
+                out.logArgs = true;
+            continue;
+        }
+        if (!VALUE_FLAGS.has(flag))
+            throw new UsageError(`unknown option ${flag}`);
+        const value = eq === -1 ? argv[++i] : token.slice(eq + 1);
+        if (value === undefined || value === '')
+            throw new UsageError(`${flag} needs a value`);
+        applyValue(out, flag, value);
+    }
+    return out;
+}
+function applyValue(out, flag, value) {
+    switch (flag) {
+        case '--name':
+            if (/[\u0000-\u001f\u007f]/.test(value) || value.length > 200)
+                throw new UsageError('--name must be at most 200 printable characters');
+            out.name = value;
+            break;
+        case '--lock':
+            out.lock = value;
+            break;
+        case '--mode':
+            if (value !== 'enforce' && value !== 'warn')
+                throw new UsageError(`--mode must be enforce or warn, not ${value}`);
+            out.mode = value;
+            break;
+        case '--on-new':
+            if (value !== 'block' && value !== 'allow')
+                throw new UsageError(`--on-new must be block or allow, not ${value}`);
+            out.onNew = value;
+            break;
+        case '--audit-log':
+            out.auditLog = value;
+            break;
+        case '--allow-secret':
+            if (!SECRET_PATTERNS.some((p) => p.id === value)) {
+                throw new UsageError(`unknown secret pattern '${value}' for --allow-secret; known ids: ${SECRET_PATTERNS.map((p) => p.id).join(', ')}`);
+            }
+            out.allowSecrets.push(value);
+            break;
+    }
+}
+export async function run(argv) {
+    let parsed;
+    try {
+        parsed = parseProxyArgs(argv);
+    }
+    catch (error) {
+        process.stderr.write(`toolmoat proxy: ${error instanceof Error ? error.message : String(error)}\nRun toolmoat proxy --help for usage.\n`);
+        return 2;
+    }
+    if (parsed.help) {
+        process.stdout.write(`${help}\n`);
+        return 0;
+    }
+    if (parsed.command === undefined || parsed.command === '') {
+        process.stderr.write('toolmoat proxy: missing the server command, e.g. toolmoat proxy -- npx -y some-mcp-server\n');
+        return 2;
+    }
+    const name = parsed.name ?? deriveServerName(parsed.command, parsed.args);
+    const auditPath = parsed.noAudit ? undefined : path.resolve(parsed.auditLog ?? path.join(toolmoatHome(), 'audit', `${fileSafeName(name)}.jsonl`));
+    const code = await runProxy({
+        server: name,
+        commandLine: formatCommand(parsed.command, parsed.args),
+        lockPath: path.resolve(parsed.lock ?? defaultLockPath()),
+        mode: parsed.mode,
+        onNew: parsed.onNew,
+        allowSecrets: parsed.allowSecrets,
+        logArgs: parsed.logArgs,
+        command: parsed.command,
+        args: parsed.args,
+        ...(auditPath ? { auditPath } : {}),
+    });
+    // A grandchild that inherited a handle must not keep the proxy alive after the server is gone.
+    setTimeout(() => process.exit(code), 500).unref();
+    return code;
+}

package/dist/commands/rules.d.ts

@@ -0,0 +1,15 @@
+import type { Rule } from '../types.js';
+export declare const help = "Usage: toolmoat rules [options]\n\nList every detection rule with its id, severity, category, the file kinds it\napplies to and what it detects.\n\nOptions:\n  -f, --format <format>    text (default), json or markdown (a README table)\n      --severity <sev>     Only list rules at or above this severity\n                           (critical, high, medium, low or info)\n      --color, --no-color  Force or disable colors (NO_COLOR is honoured)";
+export type RulesFormat = 'text' | 'json' | 'markdown';
+export interface RulesIo {
+    stdout(text: string): void;
+    stderr(text: string): void;
+    /** Whether stdout takes colors when neither --color nor --no-color is given. */
+    color: boolean;
+    rules: readonly Rule[];
+}
+export declare function run(argv: string[], io?: Partial<RulesIo>): Promise<number>;
+/** Renders a rule list sorted by id. The result ends with a newline. */
+export declare function renderRules(rules: readonly Rule[], format: RulesFormat, options?: {
+    color?: boolean;
+}): string;

package/dist/commands/rules.js

@@ -0,0 +1,173 @@
+import { parseArgs } from 'node:util';
+import { escapeCell } from '../report/markdown.js';
+import { allRules } from '../rules/index.js';
+import { atLeast, isSeverity, SEVERITIES } from '../types.js';
+import { palette } from '../util/colors.js';
+import { VERSION } from '../version.js';
+export const help = `Usage: toolmoat rules [options]
+
+List every detection rule with its id, severity, category, the file kinds it
+applies to and what it detects.
+
+Options:
+  -f, --format <format>    text (default), json or markdown (a README table)
+      --severity <sev>     Only list rules at or above this severity
+                           (critical, high, medium, low or info)
+      --color, --no-color  Force or disable colors (NO_COLOR is honoured)`;
+const RULES_FORMATS = ['text', 'json', 'markdown'];
+const WRAP_WIDTH = 100;
+export async function run(argv, io = {}) {
+    const env = {
+        stdout: (text) => process.stdout.write(text),
+        stderr: (text) => process.stderr.write(text),
+        color: palette(process.stdout).bold('x') !== 'x',
+        rules: allRules,
+        ...io,
+    };
+    let values;
+    try {
+        values = parseRulesArgs(argv);
+    }
+    catch (error) {
+        return usage(env, parseError(error));
+    }
+    if (values.help) {
+        env.stdout(`${help}\n`);
+        return 0;
+    }
+    const format = values.format ?? 'text';
+    if (!isRulesFormat(format))
+        return usage(env, `unknown format '${format}' (expected ${RULES_FORMATS.join(', ')})`);
+    const severity = values.severity;
+    if (severity !== undefined && !isSeverity(severity))
+        return usage(env, `invalid --severity '${severity}' (expected ${SEVERITIES.join(', ')})`);
+    const color = format === 'text' && (values['no-color'] ? false : values.color ? true : env.color);
+    const selected = env.rules.filter((rule) => severity === undefined || atLeast(rule.severity, severity));
+    env.stdout(renderRules(selected, format, { color }));
+    return 0;
+}
+function parseRulesArgs(argv) {
+    return parseArgs({
+        args: argv,
+        strict: true,
+        allowPositionals: false,
+        options: {
+            format: { type: 'string', short: 'f' },
+            severity: { type: 'string' },
+            color: { type: 'boolean' },
+            'no-color': { type: 'boolean' },
+            help: { type: 'boolean', short: 'h' },
+        },
+    }).values;
+}
+/** Renders a rule list sorted by id. The result ends with a newline. */
+export function renderRules(rules, format, options = {}) {
+    const sorted = [...rules].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    switch (format) {
+        case 'json':
+            return rulesJson(sorted);
+        case 'markdown':
+            return rulesMarkdown(sorted);
+        case 'text':
+            return rulesText(sorted, palette(process.stdout, options.color ?? false));
+    }
+}
+function rulesJson(rules) {
+    const out = {
+        tool: 'toolmoat',
+        version: VERSION,
+        rules: rules.map((rule) => {
+            const entry = {
+                id: rule.id,
+                title: rule.title,
+                severity: rule.severity,
+                category: rule.category,
+                kinds: [...rule.kinds],
+                description: rule.description,
+            };
+            if (rule.remediation)
+                entry.remediation = rule.remediation;
+            return entry;
+        }),
+    };
+    return `${JSON.stringify(out, null, 2)}\n`;
+}
+function rulesMarkdown(rules) {
+    const lines = ['| ID | Title | Severity | Category | Applies to | Description |', '| --- | --- | --- | --- | --- | --- |'];
+    for (const rule of rules) {
+        const cells = [`\`${rule.id}\``, escapeCell(rule.title), rule.severity, rule.category, escapeCell(rule.kinds.join(', ')), escapeCell(rule.description, 1000)];
+        lines.push(`| ${cells.join(' | ')} |`);
+    }
+    return `${lines.join('\n')}\n`;
+}
+function rulesText(rules, c) {
+    if (rules.length === 0)
+        return 'No rules match.\n';
+    const idWidth = Math.max(...rules.map((rule) => rule.id.length));
+    const lines = [];
+    for (const rule of rules) {
+        lines.push(`${c.cyan(rule.id.padEnd(idWidth))}  ${severityBadge(rule.severity, c)}  ${rule.category.padEnd(21)}  ${c.bold(rule.title)}`);
+        lines.push(...wrap(`Applies to: ${rule.kinds.join(', ')}`, '  ').map(c.gray));
+        lines.push(...wrap(rule.description, '  '));
+        lines.push('');
+    }
+    const counts = SEVERITIES.map((s) => [s, rules.filter((rule) => rule.severity === s).length])
+        .filter(([, n]) => n > 0)
+        .map(([s, n]) => `${n} ${s}`);
+    lines.push(`${rules.length} rule${rules.length === 1 ? '' : 's'}: ${counts.join(', ')}`);
+    return `${lines.join('\n')}\n`;
+}
+function severityBadge(severity, c) {
+    const text = severity.toUpperCase().padEnd('CRITICAL'.length);
+    switch (severity) {
+        case 'critical':
+            return c.bold(c.magenta(text));
+        case 'high':
+            return c.bold(c.red(text));
+        case 'medium':
+            return c.yellow(text);
+        case 'low':
+            return c.blue(text);
+        case 'info':
+            return c.gray(text);
+    }
+}
+function wrap(text, indent) {
+    const out = [];
+    let line = '';
+    for (const word of text.split(/\s+/)) {
+        if (!word)
+            continue;
+        if (line && indent.length + line.length + 1 + word.length > WRAP_WIDTH) {
+            out.push(indent + line);
+            line = word;
+        }
+        else {
+            line = line ? `${line} ${word}` : word;
+        }
+    }
+    if (line)
+        out.push(indent + line);
+    return out;
+}
+function isRulesFormat(value) {
+    return RULES_FORMATS.includes(value);
+}
+function usage(io, message) {
+    io.stderr(`toolmoat rules: ${message}\nRun 'toolmoat rules --help' for usage.\n`);
+    return 2;
+}
+function parseError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (error?.code === 'ERR_PARSE_ARGS_UNKNOWN_OPTION') {
+        const option = /'([^']{1,200})'/.exec(message)?.[1];
+        if (option)
+            return `unknown option '${option}'`;
+    }
+    if (error?.code === 'ERR_PARSE_ARGS_UNEXPECTED_POSITIONAL') {
+        const arg = /'([^']{1,200})'/.exec(message)?.[1];
+        if (arg)
+            return `unexpected argument '${arg}'`;
+    }
+    return message;
+}

package/dist/commands/scan.d.ts

@@ -0,0 +1,57 @@
+import type { ReportFormat } from '../report/index.js';
+import type { DiscoverOptions, DiscoverResult } from '../scan/discover.js';
+import type { IgnoreConfig } from '../scan/ignore.js';
+import type { Rule, ScanResult, Severity } from '../types.js';
+export declare const help = "Usage: toolmoat scan [paths...] [options]\n\nScan agent skills, plugins, hooks and MCP server configs for malicious or\nrisky content. Runs fully offline. With no paths, scans the default agent\nlocations (Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, Codex...).\n\nOptions:\n  -f, --format <format>      text (default), json, sarif or markdown\n  -o, --output <file>        Write the report to a file and print a one-line summary\n      --fail-on <severity>   Exit 1 when a finding is at or above this severity:\n                             critical, high (default), medium, low, info or none\n      --min-severity <sev>   Hide findings below this severity (default: low,\n                             or info with --verbose)\n      --ignore-file <file>   Suppressions to apply (default: ./.toolmoatignore\n                             if present; never read from scanned targets)\n      --no-ignore            Apply no ignore file at all, e.g. when the current\n                             directory is itself an untrusted download\n      --defaults             Also scan the default agent locations when paths are given\n      --deep                 Look further: deeper directory levels and bundled files\n      --max-file-size <MiB>  Skip files larger than this many MiB\n  -q, --quiet                Only print findings (nothing when clean); with\n                             --output, print nothing to stdout\n  -v, --verbose              Show info findings, skipped files and rule errors\n      --color, --no-color    Force or disable colors (NO_COLOR is honoured)\n\n--fail-on also counts findings hidden by --min-severity, but never findings\nsuppressed by the ignore file.\n\nExit codes:\n  0  no findings at or above --fail-on\n  1  findings at or above --fail-on\n  2  usage or runtime error, including a path that does not exist\n\nExamples:\n  toolmoat scan\n  toolmoat scan ./skills --format sarif --output toolmoat.sarif\n  toolmoat scan . --fail-on medium --format markdown >> \"$GITHUB_STEP_SUMMARY\"";
+export type FailOn = Severity | 'none';
+/** Input to the scan core. Paths are resolved by discovery against cwd. */
+export interface ScanOptions {
+    paths: string[];
+    useDefaults: boolean;
+    cwd: string;
+    deep?: boolean;
+    maxFileBytes?: number;
+    /** The user's suppressions. Never loaded from inside a scanned target. */
+    ignore?: IgnoreConfig;
+    /** Findings below this severity are left out of the result. Default low. */
+    minSeverity?: Severity;
+    /** Default high. */
+    failOn?: FailOn;
+}
+export interface ScanDeps {
+    discover(options: DiscoverOptions): Promise<DiscoverResult>;
+    /** Defaults to every built-in rule. */
+    rules?: readonly Rule[];
+}
+export interface RuleError {
+    ruleId: string;
+    file: string;
+    message: string;
+}
+export interface ScanOutcome {
+    /** Findings at or above minSeverity, not suppressed by the ignore config. */
+    result: ScanResult;
+    exitCode: 0 | 1;
+    roots: string[];
+    /** Findings below minSeverity that were left out of the result. */
+    hidden: number;
+    /** Findings dropped by the ignore config. */
+    suppressed: number;
+    ruleErrors: RuleError[];
+    /** Display path to absolute path of every scanned file. */
+    filePaths: Map<string, string>;
+}
+/** The scan pipeline without any I/O of its own: discover, run the rules, filter, decide the exit code. */
+export declare function runScan(options: ScanOptions, deps?: ScanDeps): Promise<ScanOutcome>;
+/** Process boundary for the command, injectable for tests. */
+export interface ScanIo {
+    cwd: string;
+    stdout(text: string): void;
+    stderr(text: string): void;
+    /** Whether stdout takes colors when neither --color nor --no-color is given. */
+    color: boolean;
+    deps: ScanDeps;
+}
+export declare function run(argv: string[], io?: Partial<ScanIo>): Promise<number>;
+/** One line for stdout when the report itself went to a file. */
+export declare function summaryLine(outcome: ScanOutcome, format: ReportFormat, written: string): string;