toolmoat 0.0.0-stage → 0.1.0

package/dist/scan/engine.js

@@ -0,0 +1,111 @@
+import { redactSecrets } from '../patterns/secrets.js';
+import { allRules } from '../rules/index.js';
+import { atLeast, SEVERITY_RANK } from '../types.js';
+import { lineAt, lineColAt, printable, truncate } from '../util/text.js';
+import { emptyIgnore, isFindingIgnored } from './ignore.js';
+const SNIPPET_MAX = 160;
+const LOWER = { critical: 'high', high: 'medium', medium: 'low', low: 'info', info: 'info' };
+/**
+ * Test code in plugins and MCP servers is full of deliberately hostile strings
+ * and is not what the agent runs, so its findings drop one level (critical
+ * still shows as high). Judged on the path inside the scanned root, so scanning
+ * a directory that itself lives under test/ is not affected.
+ */
+export function isTestPath(relPath) {
+    return (/(?:^|\/)(?:tests?|__tests__|spec|specs|testdata|__fixtures__)\//i.test(relPath) ||
+        /(?:^|\/)(?:test_[^/]*\.py|[^/]*_test\.(?:py|go)|[^/]*\.(?:test|spec)\.[cm]?[jt]sx?)$/i.test(relPath));
+}
+export function scanFile(file, options = {}) {
+    const rules = options.rules ?? allRules;
+    const ignore = options.ignore ?? emptyIgnore();
+    const findings = [];
+    const seen = new Set();
+    for (const rule of rules) {
+        if (!rule.kinds.includes(file.kind))
+            continue;
+        if (isFindingIgnored(rule.id, file.displayPath, ignore))
+            continue;
+        let matches;
+        try {
+            matches = rule.check(file);
+        }
+        catch (error) {
+            options.onRuleError?.(rule, file, error);
+            continue;
+        }
+        const inTests = file.kind === 'script' && isTestPath(file.rootRelPath ?? file.displayPath);
+        for (const match of matches) {
+            const finding = toFinding(rule, file, match);
+            if (inTests && finding.severity !== 'info') {
+                finding.severity = LOWER[finding.severity];
+                finding.message += ' (in a test file, so severity is lowered one level)';
+            }
+            if (options.minSeverity && !atLeast(finding.severity, options.minSeverity))
+                continue;
+            const key = `${finding.ruleId}|${finding.line ?? 0}|${finding.message}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            findings.push(finding);
+        }
+    }
+    return findings;
+}
+export function scanFiles(files, options = {}) {
+    return sortFindings(files.flatMap((file) => scanFile(file, options)));
+}
+export function toFinding(rule, file, match) {
+    let line = match.line;
+    let column;
+    if (match.index !== undefined) {
+        const pos = lineColAt(file.content, match.index);
+        line = pos.line;
+        column = pos.column;
+    }
+    const finding = {
+        ruleId: rule.id,
+        severity: match.severity ?? rule.severity,
+        category: rule.category,
+        title: rule.title,
+        message: match.message,
+        file: file.displayPath,
+    };
+    if (line !== undefined)
+        finding.line = line;
+    if (column !== undefined)
+        finding.column = column;
+    const snippet = makeSnippet(match.snippet ?? (line !== undefined ? lineAt(file.content, line) : undefined), column);
+    if (snippet)
+        finding.snippet = snippet;
+    if (file.target)
+        finding.target = file.target;
+    if (rule.remediation)
+        finding.remediation = rule.remediation;
+    return finding;
+}
+/** Redacts secrets, escapes invisible characters and trims long lines to a window around the column. */
+export function makeSnippet(raw, column) {
+    if (raw === undefined)
+        return undefined;
+    let text = redactSecrets(raw);
+    text = printable(text).trim();
+    if (!text)
+        return undefined;
+    if (text.length > SNIPPET_MAX && column !== undefined && column > 60) {
+        const start = Math.min(column - 40, text.length - SNIPPET_MAX + 1);
+        text = `…${text.slice(Math.max(0, start))}`;
+    }
+    return truncate(text, SNIPPET_MAX);
+}
+export function sortFindings(findings) {
+    return findings.sort((a, b) => SEVERITY_RANK[b.severity] - SEVERITY_RANK[a.severity] ||
+        a.file.localeCompare(b.file) ||
+        (a.line ?? 0) - (b.line ?? 0) ||
+        a.ruleId.localeCompare(b.ruleId));
+}
+export function countBySeverity(findings) {
+    const counts = { critical: 0, high: 0, medium: 0, low: 0, info: 0 };
+    for (const f of findings)
+        counts[f.severity]++;
+    return counts;
+}

package/dist/scan/ignore.d.ts

@@ -0,0 +1,28 @@
+/**
+ * User-controlled suppressions, read from .toolmoatignore in the directory
+ * toolmoat runs from (or --ignore-file). Ignore files and comments inside a
+ * scanned artifact are never honoured: the artifact is the thing under
+ * suspicion, so it must not be able to switch the scanner off.
+ */
+export interface IgnoreConfig {
+    /** Rule ids suppressed everywhere. */
+    rules: Set<string>;
+    /** Globs for files skipped entirely. */
+    paths: string[];
+    /** Rule ids suppressed only for files matching the glob. */
+    pathRules: {
+        pattern: string;
+        ruleId: string;
+    }[];
+}
+export declare function emptyIgnore(): IgnoreConfig;
+/**
+ * Format, one entry per line, # for comments:
+ *   TM-PI-001              suppress a rule everywhere
+ *   test/fixtures/**       skip matching files
+ *   docs/*.md:TM-PI-001    suppress a rule for matching files only
+ */
+export declare function parseIgnoreFile(text: string): IgnoreConfig;
+export declare function mergeIgnore(a: IgnoreConfig, b: IgnoreConfig): IgnoreConfig;
+export declare function isPathIgnored(displayPath: string, ignore: IgnoreConfig): boolean;
+export declare function isFindingIgnored(ruleId: string, displayPath: string, ignore: IgnoreConfig): boolean;

package/dist/scan/ignore.js

@@ -0,0 +1,46 @@
+import { matchesGlob } from '../util/glob.js';
+export function emptyIgnore() {
+    return { rules: new Set(), paths: [], pathRules: [] };
+}
+const RULE_ID = /^TM-[A-Z]+-\d{3}$/;
+/**
+ * Format, one entry per line, # for comments:
+ *   TM-PI-001              suppress a rule everywhere
+ *   test/fixtures/**       skip matching files
+ *   docs/*.md:TM-PI-001    suppress a rule for matching files only
+ */
+export function parseIgnoreFile(text) {
+    const config = emptyIgnore();
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (!line || line.startsWith('#'))
+            continue;
+        if (RULE_ID.test(line)) {
+            config.rules.add(line);
+            continue;
+        }
+        const scoped = /^(.+):(TM-[A-Z]+-\d{3})$/.exec(line);
+        if (scoped)
+            config.pathRules.push({ pattern: scoped[1], ruleId: scoped[2] });
+        else
+            config.paths.push(line);
+    }
+    return config;
+}
+export function mergeIgnore(a, b) {
+    return {
+        rules: new Set([...a.rules, ...b.rules]),
+        paths: [...a.paths, ...b.paths],
+        pathRules: [...a.pathRules, ...b.pathRules],
+    };
+}
+export function isPathIgnored(displayPath, ignore) {
+    return ignore.paths.some((pattern) => matchesGlob(displayPath, pattern));
+}
+export function isFindingIgnored(ruleId, displayPath, ignore) {
+    if (ignore.rules.has(ruleId))
+        return true;
+    if (isPathIgnored(displayPath, ignore))
+        return true;
+    return ignore.pathRules.some((entry) => entry.ruleId === ruleId && matchesGlob(displayPath, entry.pattern));
+}

package/dist/types.d.ts

@@ -0,0 +1,98 @@
+export type Severity = 'critical' | 'high' | 'medium' | 'low' | 'info';
+export declare const SEVERITIES: readonly Severity[];
+export declare const SEVERITY_RANK: Record<Severity, number>;
+export declare function isSeverity(value: string): value is Severity;
+export declare function atLeast(severity: Severity, threshold: Severity): boolean;
+export type Category = 'prompt-injection' | 'hidden-content' | 'exfiltration' | 'credential-access' | 'dangerous-execution' | 'obfuscation' | 'persistence' | 'destructive' | 'excessive-permissions' | 'supply-chain' | 'secrets' | 'insecure-transport';
+/**
+ * What a file is to the agent. Rules declare the kinds they apply to, and
+ * discovery assigns exactly one kind per file.
+ */
+export type FileKind = 
+/** SKILL.md: frontmatter plus instructions loaded straight into the agent's context. */
+'skill'
+/** Other markdown an agent reads: CLAUDE.md, AGENTS.md, commands/*.md, agents/*.md, reference files inside a skill. */
+ | 'instructions'
+/** Human-facing docs the agent normally does not load: README, CHANGELOG, CONTRIBUTING. */
+ | 'docs'
+/** Executable code shipped with a skill, plugin, hook or MCP server (.sh, .ps1, .py, .js, .ts, ...). */
+ | 'script'
+/** MCP client config: claude_desktop_config.json, .mcp.json, ~/.claude.json, Cursor, Windsurf, VS Code, Codex TOML. */
+ | 'mcp-config'
+/** Agent harness settings holding hooks and permissions: .claude/settings*.json, hooks/hooks.json. */
+ | 'agent-settings'
+/** Plugin and marketplace manifests: .claude-plugin/plugin.json, marketplace.json. */
+ | 'plugin-manifest'
+/** Dependency manifests: package.json, pyproject.toml, requirements.txt. */
+ | 'package-manifest'
+/** A live MCP tool definition (name, description, schema) observed by the runtime proxy. */
+ | 'tool-definition';
+export declare const FILE_KINDS: readonly FileKind[];
+export interface ScanFile {
+    /** Absolute path on disk, or a synthetic id such as "mcp://server/tool" for live tool definitions. */
+    path: string;
+    /** Path shown in reports: relative to the scan root when possible, always with forward slashes. */
+    displayPath: string;
+    kind: FileKind;
+    content: string;
+    /** Logical owner shown in reports: a skill name, plugin name or MCP server name. */
+    target?: string;
+    /** Path relative to the scan root the file was found under, with forward slashes. */
+    rootRelPath?: string;
+}
+/** What a rule returns for each problem it sees. The engine turns matches into findings. */
+export interface RuleMatch {
+    message: string;
+    /** Character offset into file.content where the problem starts. The engine derives line and column from it. */
+    index?: number;
+    /** Explicit 1-based line, used when there is no meaningful offset. Ignored when index is set. */
+    line?: number;
+    /** Override the computed snippet, for example to show decoded hidden text. Redacted by the engine. */
+    snippet?: string;
+    /** Override the rule's default severity for this match, for example to escalate inside a tool definition. */
+    severity?: Severity;
+}
+export interface Rule {
+    /** Stable id such as "TM-PI-001". Never reuse or renumber an id. */
+    id: string;
+    title: string;
+    /** One or two sentences explaining the threat, shown by `toolmoat rules` and in SARIF help. */
+    description: string;
+    category: Category;
+    severity: Severity;
+    kinds: readonly FileKind[];
+    remediation?: string;
+    /** Must be synchronous, side-effect free and linear-time on attacker-controlled input. */
+    check(file: ScanFile): RuleMatch[];
+}
+export interface Finding {
+    ruleId: string;
+    severity: Severity;
+    category: Category;
+    title: string;
+    message: string;
+    /** The file's displayPath. */
+    file: string;
+    /** 1-based. */
+    line?: number;
+    /** 1-based. */
+    column?: number;
+    /** Single-line excerpt with secrets redacted, at most ~160 characters. */
+    snippet?: string;
+    target?: string;
+    remediation?: string;
+}
+export interface SkippedFile {
+    path: string;
+    reason: string;
+}
+export interface ScanResult {
+    findings: Finding[];
+    filesScanned: number;
+    /** Distinct targets (skills, plugins, servers) that were scanned. */
+    targets: string[];
+    skipped: SkippedFile[];
+    /** The rules that were active, so reporters such as SARIF can describe them. */
+    rules: readonly Rule[];
+    durationMs: number;
+}

package/dist/types.js

@@ -0,0 +1,25 @@
+export const SEVERITIES = ['critical', 'high', 'medium', 'low', 'info'];
+export const SEVERITY_RANK = {
+    critical: 4,
+    high: 3,
+    medium: 2,
+    low: 1,
+    info: 0,
+};
+export function isSeverity(value) {
+    return SEVERITIES.includes(value);
+}
+export function atLeast(severity, threshold) {
+    return SEVERITY_RANK[severity] >= SEVERITY_RANK[threshold];
+}
+export const FILE_KINDS = [
+    'skill',
+    'instructions',
+    'docs',
+    'script',
+    'mcp-config',
+    'agent-settings',
+    'plugin-manifest',
+    'package-manifest',
+    'tool-definition',
+];

package/dist/util/colors.d.ts

@@ -0,0 +1,12 @@
+export interface Palette {
+    bold(s: string): string;
+    dim(s: string): string;
+    red(s: string): string;
+    yellow(s: string): string;
+    blue(s: string): string;
+    magenta(s: string): string;
+    cyan(s: string): string;
+    green(s: string): string;
+    gray(s: string): string;
+}
+export declare function palette(stream?: NodeJS.WriteStream, force?: boolean): Palette;

package/dist/util/colors.js

@@ -0,0 +1,24 @@
+function enabled(stream) {
+    if (process.env.NO_COLOR !== undefined && process.env.NO_COLOR !== '')
+        return false;
+    if (process.env.FORCE_COLOR !== undefined && process.env.FORCE_COLOR !== '0')
+        return true;
+    return Boolean(stream.isTTY);
+}
+function wrap(open, close, on) {
+    return (s) => (on ? `\u001b[${open}m${s}\u001b[${close}m` : s);
+}
+export function palette(stream = process.stdout, force) {
+    const on = force ?? enabled(stream);
+    return {
+        bold: wrap(1, 22, on),
+        dim: wrap(2, 22, on),
+        red: wrap(31, 39, on),
+        yellow: wrap(33, 39, on),
+        blue: wrap(34, 39, on),
+        magenta: wrap(35, 39, on),
+        cyan: wrap(36, 39, on),
+        green: wrap(32, 39, on),
+        gray: wrap(90, 39, on),
+    };
+}

package/dist/util/frontmatter.d.ts

@@ -0,0 +1,20 @@
+export type FrontmatterValue = string | string[];
+export interface Frontmatter {
+    /** Parsed top-level keys. Nested maps are kept as raw text under their key. */
+    data: Record<string, FrontmatterValue>;
+    /** 1-based line of each top-level key, for pointing findings at it. */
+    lines: Record<string, number>;
+    /** Markdown after the closing fence. */
+    body: string;
+    /** 1-based line where the body starts. */
+    bodyLine: number;
+}
+/**
+ * Parses the YAML frontmatter of a SKILL.md or command file. Handles the
+ * subset these files use in practice: scalars, quoted strings, inline [a, b]
+ * lists, "- item" lists and | or > block scalars. Returns null when the file
+ * has no frontmatter. Never throws.
+ */
+export declare function parseFrontmatter(content: string): Frontmatter | null;
+/** Reads a frontmatter value as a list: inline lists, "- item" lists and comma- or space-separated strings. */
+export declare function asList(value: FrontmatterValue | undefined): string[];

package/dist/util/frontmatter.js

@@ -0,0 +1,136 @@
+/**
+ * Parses the YAML frontmatter of a SKILL.md or command file. Handles the
+ * subset these files use in practice: scalars, quoted strings, inline [a, b]
+ * lists, "- item" lists and | or > block scalars. Returns null when the file
+ * has no frontmatter. Never throws.
+ */
+export function parseFrontmatter(content) {
+    const text = content.startsWith('') ? content.slice(1) : content;
+    const lines = text.split(/\r?\n/);
+    if (lines[0]?.trim() !== '---')
+        return null;
+    let end = -1;
+    for (let i = 1; i < lines.length; i++) {
+        if (lines[i].trim() === '---') {
+            end = i;
+            break;
+        }
+    }
+    if (end === -1)
+        return null;
+    const data = {};
+    const keyLines = {};
+    let i = 1;
+    while (i < end) {
+        const line = lines[i];
+        const m = /^([A-Za-z0-9_-]+)\s*:\s*(.*)$/.exec(line);
+        if (!m) {
+            i++;
+            continue;
+        }
+        const key = m[1];
+        const rest = m[2].trim();
+        keyLines[key] = i + 1;
+        i++;
+        if (rest === '|' || rest === '>' || rest === '|-' || rest === '>-' || rest === '|+' || rest === '>+') {
+            const block = [];
+            while (i < end && (lines[i].startsWith(' ') || lines[i].startsWith('\t') || lines[i].trim() === '')) {
+                block.push(lines[i].trim());
+                i++;
+            }
+            data[key] = rest.startsWith('>') ? block.join(' ').replace(/\s+/g, ' ').trim() : block.join('\n').trim();
+        }
+        else if (rest === '') {
+            const items = [];
+            const raw = [];
+            while (i < end && (lines[i].startsWith(' ') || lines[i].startsWith('\t') || lines[i].trim() === '')) {
+                const item = /^\s*-\s+(.*)$/.exec(lines[i]);
+                if (item)
+                    items.push(unquote(item[1].trim()));
+                raw.push(lines[i]);
+                i++;
+            }
+            data[key] = items.length > 0 ? items : raw.join('\n').trim();
+        }
+        else if (rest.startsWith('[') && rest.endsWith(']')) {
+            data[key] = splitInlineList(rest.slice(1, -1));
+        }
+        else {
+            data[key] = unquote(rest);
+        }
+    }
+    return { data, lines: keyLines, body: lines.slice(end + 1).join('\n'), bodyLine: end + 2 };
+}
+function unquote(value) {
+    if (value.length >= 2 && ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'")))) {
+        return value.slice(1, -1);
+    }
+    return value;
+}
+function splitInlineList(inner) {
+    const out = [];
+    let current = '';
+    let quote = null;
+    let depth = 0;
+    for (const ch of inner) {
+        if (quote) {
+            if (ch === quote)
+                quote = null;
+            current += ch;
+        }
+        else if (ch === '"' || ch === "'") {
+            quote = ch;
+            current += ch;
+        }
+        else if (ch === '(') {
+            depth++;
+            current += ch;
+        }
+        else if (ch === ')') {
+            depth = Math.max(0, depth - 1);
+            current += ch;
+        }
+        else if (ch === ',' && depth === 0) {
+            if (current.trim())
+                out.push(unquote(current.trim()));
+            current = '';
+        }
+        else {
+            current += ch;
+        }
+    }
+    if (current.trim())
+        out.push(unquote(current.trim()));
+    return out;
+}
+/** Reads a frontmatter value as a list: inline lists, "- item" lists and comma- or space-separated strings. */
+export function asList(value) {
+    if (value === undefined)
+        return [];
+    if (Array.isArray(value))
+        return value;
+    return splitInlineList(value).flatMap(splitOutsideParens).filter(Boolean);
+}
+/** Splits on whitespace that is not inside parentheses, so "Read Bash(git status:*)" gives two tools. */
+function splitOutsideParens(text) {
+    const out = [];
+    let current = '';
+    let depth = 0;
+    for (const ch of text) {
+        if (ch === '(')
+            depth++;
+        else if (ch === ')')
+            depth = Math.max(0, depth - 1);
+        if (/\s/.test(ch) && depth === 0) {
+            if (current)
+                out.push(current);
+            current = '';
+        }
+        else {
+            current += ch;
+        }
+    }
+    if (current)
+        out.push(current);
+    return out;
+}

package/dist/util/glob.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Minimal glob matcher for ignore files: `**` crosses directories, `*` and `?`
+ * stay within one path segment. A pattern without a slash matches a file or
+ * directory name at any depth, like .gitignore.
+ */
+export declare function globToRegExp(pattern: string): RegExp;
+export declare function matchesGlob(filePath: string, pattern: string): boolean;

package/dist/util/glob.js

@@ -0,0 +1,44 @@
+/**
+ * Minimal glob matcher for ignore files: `**` crosses directories, `*` and `?`
+ * stay within one path segment. A pattern without a slash matches a file or
+ * directory name at any depth, like .gitignore.
+ */
+export function globToRegExp(pattern) {
+    let p = pattern.trim().replace(/\\/g, '/');
+    const anchored = p.startsWith('/');
+    if (anchored)
+        p = p.slice(1);
+    if (p.endsWith('/'))
+        p = `${p}**`;
+    const floating = !anchored && !p.includes('/');
+    let re = '';
+    for (let i = 0; i < p.length; i++) {
+        const ch = p[i];
+        if (ch === '*') {
+            if (p[i + 1] === '*') {
+                i++;
+                if (p[i + 1] === '/') {
+                    i++;
+                    re += '(?:[^/]*/)*';
+                }
+                else {
+                    re += '.*';
+                }
+            }
+            else {
+                re += '[^/]*';
+            }
+        }
+        else if (ch === '?') {
+            re += '[^/]';
+        }
+        else {
+            re += ch.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+        }
+    }
+    const prefix = floating ? '(?:^|.*/)' : '^';
+    return new RegExp(`${prefix}${re}(?:/.*)?$`, process.platform === 'win32' ? 'i' : '');
+}
+export function matchesGlob(filePath, pattern) {
+    return globToRegExp(pattern).test(filePath.replace(/\\/g, '/'));
+}

package/dist/util/hash.d.ts

@@ -0,0 +1,3 @@
+/** JSON with object keys sorted at every level, so equal values always serialize identically. */
+export declare function canonicalJson(value: unknown): string;
+export declare function sha256(text: string): string;

package/dist/util/hash.js

@@ -0,0 +1,24 @@
+import { createHash } from 'node:crypto';
+/** JSON with object keys sorted at every level, so equal values always serialize identically. */
+export function canonicalJson(value) {
+    return JSON.stringify(sortKeys(value));
+}
+function sortKeys(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    if (value !== null && typeof value === 'object') {
+        // Null prototype, so a "__proto__" key from parsed JSON stays an ordinary own key
+        // instead of being swallowed by the prototype setter and dropped from the output.
+        const out = Object.create(null);
+        for (const key of Object.keys(value).sort()) {
+            const v = value[key];
+            if (v !== undefined)
+                out[key] = sortKeys(v);
+        }
+        return out;
+    }
+    return value;
+}
+export function sha256(text) {
+    return `sha256:${createHash('sha256').update(text, 'utf8').digest('hex')}`;
+}

package/dist/util/jsonc.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Parses JSON that may contain // and /* *\/ comments and trailing commas, as
+ * VS Code style config files do. Returns undefined instead of throwing.
+ */
+export declare function parseJsonc(text: string): unknown;
+/** Replaces comments with spaces so character offsets stay the same. */
+export declare function stripComments(text: string): string;
+/**
+ * Best-effort offset of a JSON string value (or key) in the raw text, used to
+ * point findings at the right line. Searches for the JSON-encoded form first,
+ * then the raw value. Returns -1 when not found.
+ */
+export declare function indexOfJsonString(text: string, value: string, from?: number): number;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;