@atbash/cli 0.5.15 → 0.6.0-dev.1

package/dist/commands/scan.js

@@ -0,0 +1,301 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toRows = toRows;
+exports.toScanTools = toScanTools;
+exports.countNetworkRequests = countNetworkRequests;
+exports.registerScanCommand = registerScanCommand;
+const node_os_1 = __importDefault(require("node:os"));
+const chalk_1 = __importDefault(require("chalk"));
+const connect_1 = require("./connect");
+const introspect_mcp_1 = require("./introspect-mcp");
+const risk_1 = require("../lib/risk");
+const grade_llm_1 = require("../lib/grade-llm");
+const threats_llm_1 = require("../lib/threats-llm");
+const policy_1 = require("../lib/policy");
+const llm_1 = require("../lib/llm");
+/** One row per discovered runtime, with its tool names flattened for display. */
+function toRows(agents) {
+    return agents.map((a) => {
+        const tools = a.type === "declared" && Array.isArray(a.declaredTools)
+            ? a.declaredTools.map((t) => t.name)
+            : a.type === "config" && a.config?.mcpServers
+                ? Object.keys(a.config.mcpServers)
+                : [];
+        return { label: a.label, detail: a.detail, kind: a.type, tools };
+    });
+}
+/**
+ * The tool surface the risk engine grades.
+ *
+ * A config's SERVER names are deliberately not included: "gmail" is a server, not
+ * a capability, and grading it would invent a finding out of a filename. That is
+ * why a config-only machine needs --introspect before it gets a risk report — the
+ * scan says so rather than quietly reporting "Low".
+ */
+function toScanTools(agents, introspection) {
+    const out = [];
+    const seen = new Set();
+    const add = (name, description, source) => {
+        const key = (0, risk_1.toolKey)(source, name);
+        if (!name || seen.has(key))
+            return;
+        seen.add(key);
+        out.push({ name, description, source });
+    };
+    // Declared runtimes enumerated their own tools locally.
+    for (const a of agents) {
+        if (a.type === "declared")
+            for (const t of a.declaredTools ?? [])
+                add(t.name, t.description, a.label);
+    }
+    // Introspection is the authoritative surface for a config source: the names the
+    // server itself advertised, rather than what a config file claims.
+    for (const r of introspection) {
+        for (const s of r.servers) {
+            if (!s.ok)
+                continue;
+            for (const t of s.tools)
+                add(t.name, t.description, `${r.label}/${s.server}`);
+        }
+    }
+    return out;
+}
+/** Tool names each MCP server advertised, keyed by server name. */
+function introspectedByServer(results) {
+    const out = new Map();
+    for (const r of results) {
+        for (const s of r.servers) {
+            if (s.ok)
+                out.set(s.server, s.tools.map((t) => t.name));
+        }
+    }
+    return out;
+}
+/**
+ * Requests that actually left the machine. Only HTTP-transport servers are
+ * reached over the network — and then at the URL the user's own config names,
+ * never an Atbash host. stdio servers are spawned locally and spoken to over a
+ * pipe, so they are not counted here.
+ */
+function countNetworkRequests(results) {
+    return results.reduce((n, r) => n + r.servers.filter((s) => s.transport === "http").length, 0);
+}
+const LEVEL_RANK = { Low: 0, Elevated: 1, High: 2 };
+const FAIL_ON = { low: "Low", elevated: "Elevated", high: "High" };
+const SEV_COLOR = {
+    high: chalk_1.default.red,
+    medium: chalk_1.default.yellow,
+    low: chalk_1.default.green,
+};
+function renderThreats(threats) {
+    console.log("  " + chalk_1.default.bold("Threat paths") + "\n  " + "\u2500".repeat(28));
+    console.log(chalk_1.default.dim("  Combinations the per-tool rules cannot see. Model-generated.\n"));
+    for (const t of threats) {
+        console.log(`    ${SEV_COLOR[t.severity](t.severity.padEnd(6))} ${chalk_1.default.bold(t.title)} ${chalk_1.default.dim("\u2014 " + t.category)}`);
+        if (t.enabledBy)
+            console.log(chalk_1.default.dim(`           enabled by: ${t.enabledBy}`));
+        if (t.consequence)
+            console.log(chalk_1.default.dim(`           ${t.consequence}`));
+    }
+    console.log();
+}
+function renderPolicy(policy) {
+    console.log("  " + chalk_1.default.bold("Recommended boundary") + "\n  " + "\u2500".repeat(28));
+    console.log(`  ${chalk_1.default.dim("Mandate:")} ${policy.mandate}\n`);
+    console.log(`  ${chalk_1.default.bold("Red lines")} ${chalk_1.default.dim("(auto-deny)")}`);
+    for (const r of policy.redLines)
+        console.log(`    \u2022 ${r}`);
+    console.log(`\n  ${chalk_1.default.bold("Needs approval")}`);
+    if (policy.approvals.length === 0)
+        console.log(chalk_1.default.dim("    (none)"));
+    for (const a of policy.approvals)
+        console.log(`    \u2022 ${a}`);
+    console.log("\n" + chalk_1.default.dim(`  ${policy.notes}`) + "\n");
+}
+function renderRisk(report, hasKey, enrichError) {
+    const levelColor = report.level === "High" ? chalk_1.default.red : report.level === "Elevated" ? chalk_1.default.yellow : chalk_1.default.green;
+    console.log("  " + chalk_1.default.bold("Risk") + "\n  " + "─".repeat(28));
+    console.log(`  Level   : ${levelColor.bold(report.level)} ${chalk_1.default.dim(`(${report.score}/100)`)}`);
+    console.log(`  Method  : ${report.method === "llm" ? "deterministic + model-graded" : "deterministic"}`);
+    console.log(`  ${chalk_1.default.dim(report.summary)}\n`);
+    // Secondary paths are extra harms on a tool already listed; showing them inline
+    // would read as duplicate findings, so the primary carries the line.
+    const primary = report.paths.filter((p) => !p.secondary);
+    const shown = primary.slice(0, 12);
+    for (const p of shown) {
+        const sev = SEV_COLOR[p.severity](p.severity.padEnd(6));
+        console.log(`    ${sev} ${chalk_1.default.bold(p.tool)} ${chalk_1.default.dim("— " + p.category)}`);
+        console.log(`           ${chalk_1.default.dim(p.consequence)}`);
+    }
+    if (primary.length > shown.length) {
+        console.log(chalk_1.default.dim(`    … ${primary.length - shown.length} more`));
+    }
+    console.log();
+    if (enrichError) {
+        console.log(chalk_1.default.yellow(`  Model grading unavailable (${enrichError}) — deterministic result kept.\n`));
+    }
+    const unclassified = primary.filter(risk_1.isUnclassifiedPath).length;
+    if (unclassified > 0 && !hasKey) {
+        console.log(chalk_1.default.dim(`  ${unclassified} tool${unclassified === 1 ? "" : "s"} matched no rule. Pass --api-key <key> to grade\n` +
+            "  them with your own LLM provider (tool names and descriptions are sent there).\n"));
+    }
+}
+function render(rows, introspected, introspectRan, report, toolCount, hasKey, enrichError) {
+    console.log("\n" + chalk_1.default.bold("  Atbash local scan") + "\n  " + "─".repeat(28));
+    console.log(`  Machine : ${node_os_1.default.hostname()}`);
+    console.log(`  Found   : ${rows.length} runtime${rows.length === 1 ? "" : "s"}\n`);
+    if (rows.length === 0) {
+        console.log(chalk_1.default.dim("  No agents or MCP configs found in the usual locations.\n"));
+        return;
+    }
+    for (const r of rows) {
+        console.log(`  ${chalk_1.default.bold(r.label)} ${chalk_1.default.dim("— " + r.detail)}`);
+        for (const name of r.tools) {
+            // A name the server itself advertised is worth more than one read out of a
+            // config file, so say which this is rather than presenting them alike.
+            const confirmed = introspected.get(name);
+            if (confirmed) {
+                console.log(`    • ${name} ${chalk_1.default.dim(`(${confirmed.length} tool${confirmed.length === 1 ? "" : "s"} confirmed)`)}`);
+                for (const t of confirmed.slice(0, 8))
+                    console.log(chalk_1.default.dim(`        - ${t}`));
+                if (confirmed.length > 8)
+                    console.log(chalk_1.default.dim(`        … ${confirmed.length - 8} more`));
+            }
+            else {
+                console.log(`    • ${name}${introspectRan && r.kind === "config" ? chalk_1.default.dim("  (not reached)") : ""}`);
+            }
+        }
+        console.log();
+    }
+    if (toolCount === 0) {
+        console.log(chalk_1.default.dim("  No tool surface was resolved, so no risk could be derived. Config files name\n" +
+            "  servers, not capabilities — add --introspect to ask each server what it\n" +
+            "  actually advertises.\n"));
+    }
+    else {
+        renderRisk(report, hasKey, enrichError);
+    }
+    if (!introspectRan) {
+        console.log(chalk_1.default.dim("  Tool names above are what the configs declare. Add --introspect to ask\n  each MCP server what it actually advertises.\n"));
+    }
+}
+function registerScanCommand(program) {
+    program
+        .command("scan")
+        .description("Scan this machine for installed agents and MCP tools, grade the risk, and print the report here (the report is never sent anywhere)")
+        .option("--home <dir>", "Home directory to scan (for testing)")
+        .option("--introspect", "Also ask each configured MCP server which tools it advertises: stdio servers are started locally, HTTP servers are contacted at the URL their own config names. Never calls a tool")
+        .option("--api-key <key>", "YOUR LLM provider key (OpenRouter), used to grade tools the built-in rules could not classify. Sends those tool names and descriptions to that provider. Also read from ATBASH_SCAN_API_KEY or OPENROUTER_API_KEY")
+        .option("--model <id>", `Model for --api-key grading (default: ${llm_1.DEFAULT_MODEL})`)
+        .option("--threats", "Also enumerate CROSS-TOOL threat chains (e.g. read customer data + external send = exfiltration). Requires --api-key; never changes the risk score")
+        .option("--policy", "Also print a draft governance boundary derived from the findings: red lines and approval-required actions. Deterministic, no key needed")
+        .option("--fail-on <level>", "Exit 1 when the risk level reaches this: low, elevated or high (for CI)")
+        .option("--json", "Emit machine-readable JSON instead of formatted text")
+        .action(async (opts) => {
+        const home = opts.home || node_os_1.default.homedir();
+        let failOn;
+        if (opts.failOn) {
+            failOn = FAIL_ON[opts.failOn.toLowerCase()];
+            if (!failOn) {
+                console.error(chalk_1.default.red(`  Invalid --fail-on "${opts.failOn}". Choose: low, elevated, high.`));
+                process.exitCode = 2;
+                return;
+            }
+        }
+        const agents = (0, connect_1.discover)(home);
+        const rows = toRows(agents);
+        let introspection = [];
+        if (opts.introspect) {
+            if (!opts.json)
+                console.log(chalk_1.default.dim("\n  Asking configured MCP servers to list their tools…"));
+            try {
+                // The RAW specs, not the ones `discover` returns. Those are sanitized for
+                // relay — absolute command paths reduced to a basename, `env`/`headers`
+                // dropped — which is right for a payload and fatal for actually starting a
+                // server: a command installed outside PATH fails with ENOENT and the report
+                // blames the user's server for the scan's own omission. Nothing raw is
+                // printed; introspection returns only sanitized names and redacted errors.
+                const sources = (0, connect_1.readAllMcpServers)(home);
+                introspection = await (0, introspect_mcp_1.introspectServers)(sources);
+            }
+            catch (err) {
+                // Introspection is the optional half: a server that will not start must
+                // not cost the user the discovery result they already have.
+                if (!opts.json)
+                    console.error(chalk_1.default.yellow(`  Introspection failed: ${err.message}`));
+            }
+        }
+        const tools = toScanTools(agents, introspection);
+        let report = (0, risk_1.deriveRisk)(tools);
+        let networkRequests = countNetworkRequests(introspection);
+        // The user's own key, never a platform one. Env vars are accepted so a CI
+        // job never has to put a secret in argv, where it is visible in the process
+        // list to every other user on the box.
+        const apiKey = opts.apiKey || process.env.ATBASH_SCAN_API_KEY || process.env.OPENROUTER_API_KEY;
+        let enrichError;
+        if (apiKey && tools.length > 0) {
+            // Matched on source+name, not name alone: two different MCP servers can
+            // expose a same-named tool, and a name-only match would sweep an ALREADY
+            // classified tool's real description into the LLM batch just because some
+            // other server's same-named tool is unclassified.
+            const unclassified = tools.filter((t) => report.paths.some((p) => (0, risk_1.toolKey)(p.source, p.tool) === (0, risk_1.toolKey)(t.source, t.name) && !p.secondary && (0, risk_1.isUnclassifiedPath)(p)));
+            if (unclassified.length > 0) {
+                if (!opts.json) {
+                    console.log(chalk_1.default.dim(`\n  Grading ${unclassified.length} unclassified tool${unclassified.length === 1 ? "" : "s"} with your provider…`));
+                }
+                const outcome = await (0, grade_llm_1.gradeToolsWithLlm)(unclassified, { apiKey, model: opts.model });
+                networkRequests += outcome.requests;
+                enrichError = outcome.error;
+                report = (0, risk_1.gradeUnclassifiedPaths)(report, outcome.grades);
+            }
+        }
+        let threats = [];
+        let threatError;
+        if (opts.threats && tools.length > 0) {
+            if (!apiKey) {
+                threatError = "no API key — threat chains need one (--api-key, ATBASH_SCAN_API_KEY or OPENROUTER_API_KEY)";
+            }
+            else {
+                if (!opts.json)
+                    console.log(chalk_1.default.dim("\n  Looking for cross-tool threat chains\u2026"));
+                const outcome = await (0, threats_llm_1.deriveThreats)(tools, { apiKey, model: opts.model });
+                networkRequests += outcome.requests;
+                threatError = outcome.error;
+                threats = outcome.threats;
+            }
+        }
+        // Derived from the report, so it reflects any model grading that ran. The
+        // boundary is a SUGGESTION printed here; nothing is deployed anywhere.
+        const policy = opts.policy ? (0, policy_1.suggestPolicy)(report) : undefined;
+        if (failOn && LEVEL_RANK[report.level] >= LEVEL_RANK[failOn]) {
+            process.exitCode = 1;
+        }
+        if (opts.json) {
+            console.log(JSON.stringify({
+                ok: true,
+                machine: node_os_1.default.hostname(),
+                local: true,
+                networkRequests,
+                agents: rows,
+                introspection,
+                risk: report,
+                ...(threats.length > 0 ? { threats } : {}),
+                ...(policy ? { policy } : {}),
+                ...(enrichError ? { enrichmentError: enrichError } : {}),
+                ...(threatError ? { threatError } : {}),
+            }, null, 2));
+            return;
+        }
+        render(rows, introspectedByServer(introspection), !!opts.introspect, report, tools.length, !!apiKey, enrichError);
+        if (threatError)
+            console.log(chalk_1.default.yellow(`  Threat analysis unavailable (${threatError}).\n`));
+        if (threats.length > 0)
+            renderThreats(threats);
+        if (policy)
+            renderPolicy(policy);
+    });
+}
+//# sourceMappingURL=scan.js.map

package/dist/commands/scan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan.js","sourceRoot":"","sources":["../../src/commands/scan.ts"],"names":[],"mappings":"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"}

package/dist/commands/setup.d.ts

@@ -0,0 +1,151 @@
+import { Command } from "commander";
+interface KeyMaterial {
+    privkey: string;
+    /** Present when the source stated one; always re-derived and cross-checked. */
+    statedPubkey?: string;
+}
+/**
+ * Pull key material out of whatever the owner pointed us at.
+ *
+ * Accepts every shape Atbash itself produces or documents, so "the file I
+ * downloaded from the modal" always works:
+ *   - `privkey=…` / `pubkey=…` lines (what onboarding downloads, and what the
+ *     plugin parses)
+ *   - `{"privKey":…,"pubKey":…}` JSON (the alternate documented key-file form)
+ *   - a bare 64-hex private key on its own line (someone who copied just the key)
+ *
+ * Returns null rather than throwing: the caller tries several sources in turn and
+ * an unparseable one is a reason to move on, not to abort.
+ */
+export declare function parseKeyMaterial(raw: string): KeyMaterial | null;
+/** Normalize to the lowercase 64-hex the SDK validates, or "" if it is not one. */
+export declare function normalizePrivkey(raw: string): string;
+/** Files in a directory that plausibly hold an Atbash agent key, newest first. */
+export declare function keyCandidatesInDir(dir: string): string[];
+interface KeySource {
+    material: KeyMaterial;
+    /** Human description of WHERE it came from. Never contains the key. */
+    from: string;
+}
+/**
+ * Find the agent key, trying every way an owner could plausibly have it.
+ *
+ * Order is "most explicit first": a flag the owner typed beats a file we guessed
+ * at. The last resort is the interactive prompt, and if there is no TTY the
+ * caller gets a clear error listing the flags rather than a hang.
+ */
+export declare function resolveKeySource(opts: {
+    key?: string;
+    keyFile?: string;
+    keysDir?: string;
+    home: string;
+    /** Set for non-interactive runs (CI, an AI assistant with no TTY). */
+    allowPrompt: boolean;
+}): Promise<KeySource | {
+    error: string;
+}>;
+/**
+ * One thing setup will do. Building the whole plan BEFORE touching anything is
+ * what makes `--dry-run` truthful: the preview and the run are the same objects,
+ * so the preview cannot describe a merge the apply step then performs
+ * differently. Every `write` carries its exact final bytes.
+ */
+export type Step = {
+    kind: "write";
+    label: string;
+    file: string;
+    mode?: number;
+    before: string | null;
+    after: string;
+    secret?: boolean;
+} | {
+    kind: "exec";
+    label: string;
+    command: string;
+    args: string[];
+    optionalWhy?: string;
+} | {
+    kind: "manual";
+    label: string;
+    detail: string;
+    snippet?: string;
+};
+export interface Plan {
+    steps: Step[];
+    /** Things the owner must know, printed whether or not anything was written. */
+    notes: string[];
+    /** Runtimes found on this machine, for the summary line. */
+    found: string[];
+}
+/** The key file, in the `key=value` form the plugin and the SDK both parse. */
+export declare function keyFileContents(privkey: string, pubkey: string): string;
+/**
+ * True when a JSON file uses JSONC features (comments, trailing commas).
+ *
+ * We must not auto-merge into one: writing it back with JSON.stringify would
+ * silently delete the owner's comments. Detected by the disagreement between the
+ * strict and tolerant parsers — strict fails, tolerant succeeds.
+ */
+export declare function isJsonc(text: string): boolean;
+/**
+ * Merge the Atbash plugin block into an OpenClaw config object, in place.
+ *
+ * A MERGE, not a replacement — that distinction is the whole reason this command
+ * exists. Other plugins already in `allow`, `load.paths` and `entries` are
+ * preserved, and an entry from the legacy `@atbash/atbash-plugin` install is
+ * updated where it stands rather than being shadowed by a duplicate: the
+ * dashboard scan recognizes both keys, so two entries would mean two hooks.
+ *
+ * `load.paths` gets the real absolute extension path. The published docs show a
+ * `<your-username>` placeholder that people paste verbatim, producing a path that
+ * does not exist and a plugin that never loads.
+ */
+export declare function mergeOpenclawConfig(config: Record<string, unknown>, home: string): Record<string, unknown>;
+/**
+ * Work out everything that needs doing on this machine, without doing any of it.
+ *
+ * Detection drives the plan rather than a flag the owner picks, for the same
+ * reason the scan does: what is actually installed here is knowable, and asking
+ * someone to identify their own runtime from a list invites a wrong answer that
+ * writes a config for a plugin they do not have.
+ */
+export declare function buildPlan(args: {
+    home: string;
+    privkey: string;
+    pubkey: string;
+    /** Skip package installation; write config and the key file only. */
+    noInstall: boolean;
+    /** Restrict to these runtime ids; empty means "everything detected". */
+    only: string[];
+}): Plan;
+/**
+ * A minimal line diff, so the preview shows what CHANGES rather than dumping a
+ * whole config and leaving the owner to spot the difference. Standard LCS; these
+ * files are small enough that the quadratic table is irrelevant.
+ */
+export declare function lineDiff(before: string, after: string): string[];
+/**
+ * Print the plan. Used for `--dry-run` and for the confirmation prompt, so what
+ * the owner is shown and what they agree to cannot diverge.
+ *
+ * The key file's CONTENTS are never printed — the whole point of the file is that
+ * the private key stays put, and echoing it into a terminal scrollback undoes
+ * that. The path, mode and the public key are shown instead.
+ */
+export declare function renderPlan(plan: Plan, pubkey: string): void;
+/**
+ * Copy a file aside before overwriting it, without ever clobbering an existing
+ * backup — a second run must not overwrite the pristine copy from the first.
+ */
+export declare function backupFile(file: string): string | null;
+export interface ApplyResult {
+    written: string[];
+    backups: string[];
+    ran: string[];
+    failures: string[];
+}
+/** Execute the plan. Writes first, then commands, so a failed install still
+ *  leaves a correct config and key file behind for a manual retry. */
+export declare function applyPlan(plan: Plan): ApplyResult;
+export declare function registerSetupCommand(program: Command): void;
+export {};