@dzhechkov/harness-core 0.3.23 → 0.3.25

package/src/mcp-scan.ts

@@ -0,0 +1,489 @@
+/**
+ * `dz mcp-scan` — "npm audit for agent tools".
+ *
+ * A deterministic, static (no-execution) security scan of a project's agent
+ * permission surface. It reads Claude-Code-style `.claude/settings*.json`
+ * permission grants and MCP server declarations (`.mcp.json`, `.vscode/mcp.json`)
+ * and emits a three-tier verdict (`clean` / `medium` / `high`) with findings.
+ *
+ * The rule set is adapted from the MetaHarness `threat-model` skill
+ * (ruvnet/agent-harness-generator) and mapped onto the Claude Code permission
+ * grammar. See `docs/research/metaharness-analysis.md` §1.
+ *
+ * Semantics (verified against the MetaHarness rules + Claude Code merge model):
+ *  - settings.json and settings.local.json are evaluated as a MERGED surface
+ *    (union of allow, union of deny); deny wins over allow.
+ *  - findings are reported per CAPABILITY (one shell / network / write finding
+ *    with a count + examples), not per individual grant.
+ *  - secrets-reachability requires MCP to be active (per MetaHarness).
+ *  - `low`-severity findings are informational and do NOT change the verdict.
+ *
+ * Verdict (highest non-low severity wins):
+ *  - `high`   (exit 2): shell granted · default-deny off · secrets reachable ·
+ *                       hardcoded secret in MCP env · all-MCP-servers enabled ·
+ *                       MCP server runs an interpreter / package-runner
+ *  - `medium` (exit 1): network granted · file-write granted · remote MCP server
+ *  - `clean`  (exit 0): no high/medium findings (low/info may still be present)
+ *
+ * @packageDocumentation
+ */
+
+import { existsSync, lstatSync, readFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+
+import {
+  SHELL_TOOLS,
+  INTERPRETER_RE, PACKAGE_RUNNERS, INLINE_CODE_ARGS,
+  SHELL_NET_RE, SHELL_WRITE_RE, SECRET_FILE_RE, MAX_FILE_BYTES,
+  parseGrant, isWildcard, toolKind,
+  type CapabilityClass,
+} from './capability-vocab.js';
+
+/** Re-exported for back-compat (was historically exported from this module). */
+export { parseGrant } from './capability-vocab.js';
+
+/** Severity of a single finding. `low` is informational (verdict-neutral). */
+export type McpSeverity = 'high' | 'medium' | 'low';
+
+/** The capability class a finding concerns. */
+export type McpCapability = CapabilityClass;
+
+/** A single static-scan finding. */
+export interface McpFinding {
+  /** Stable rule id, e.g. `MS-SHELL-GRANT`. */
+  readonly id: string;
+  readonly severity: McpSeverity;
+  readonly capability: McpCapability;
+  /** Relative path / source the finding came from. */
+  readonly source: string;
+  /** Human-readable explanation. */
+  readonly detail: string;
+  /** The grant / value (or aggregated count + examples) that triggered the rule. */
+  readonly evidence: string;
+}
+
+/** The overall verdict. `clean` when there are zero high/medium findings. */
+export type McpVerdict = 'clean' | 'medium' | 'high';
+
+/** Result of {@link scanMcp}. */
+export interface McpScanReport {
+  readonly verdict: McpVerdict;
+  /** Process exit code: clean=0, medium=1, high=2. */
+  readonly exitCode: 0 | 1 | 2;
+  readonly findings: readonly McpFinding[];
+  /** Relative paths actually read during the scan. */
+  readonly scanned: readonly string[];
+  /** Derived capability flags (for badges / `--json`). */
+  readonly capabilities: {
+    readonly shell: boolean;
+    readonly network: boolean;
+    readonly fileWrite: boolean;
+    readonly secretsReachable: boolean;
+    /** Scoped to the `.claude/settings*.json` surface. */
+    readonly defaultDeny: boolean;
+  };
+}
+
+/** Compile a Claude arg glob (`*` wildcard) to a RegExp. */
+function globToRe(arg: string): RegExp {
+  const esc = arg.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*');
+  return new RegExp(`^${esc}$`);
+}
+
+/** True when a deny rule covers a grant (deny wins). Case-insensitive on tool. */
+function denyCovers(grant: string, denyList: string[]): boolean {
+  const g = parseGrant(grant);
+  return denyList.some((d) => {
+    const dd = parseGrant(d);
+    if (dd.tool === '*') return true;
+    if (dd.tool.toLowerCase() !== g.tool.toLowerCase()) return false;
+    if (dd.arg === null) return true; // bare-tool deny covers every arg
+    if (g.arg === null) return false;
+    try {
+      return globToRe(dd.arg).test(g.arg);
+    } catch {
+      return dd.arg === g.arg;
+    }
+  });
+}
+
+/** True when the deny list actually protects secret FILE locations. */
+function denyProtectsSecrets(denyList: string[]): boolean {
+  return denyList.some((d) => {
+    const { tool, arg } = parseGrant(d);
+    const t = tool.toLowerCase();
+    if (t !== 'read' && t !== 'glob' && t !== '*' && t !== 'bash') return false;
+    return arg !== null && SECRET_FILE_RE.test(arg);
+  });
+}
+
+/** Heuristic: does an MCP env value look like a hardcoded secret (not a `${VAR}` ref)? */
+function looksLikeHardcodedSecret(key: string, value: unknown): boolean {
+  if (typeof value !== 'string') return false;
+  if (!/key|token|secret|password|api|credential|auth/i.test(key)) return false;
+  const v = value.trim();
+  if (v === '') return false;
+  if (/^\$\{?\w+\}?$/.test(v)) return false; // pure ${VAR} / $VAR reference
+  if (/^(true|false|production|development|test|none|null|\d+)$/i.test(v)) return false;
+  return v.length >= 8;
+}
+
+// ---------------------------------------------------------------------------
+// accumulator
+// ---------------------------------------------------------------------------
+
+interface Accumulator {
+  findings: McpFinding[];
+  scanned: string[];
+  shellGrants: string[];
+  networkGrants: string[];
+  writeGrants: string[];
+  shellArgNetwork: string[];
+  shellArgWrite: string[];
+  mcpToolGrants: string[];
+  unknownTools: string[];
+  denyRules: string[];
+  hasReadGrant: boolean;
+  hasSettings: boolean;
+  hasDeny: boolean;
+  wildcardAll: boolean;
+  mcpActive: boolean;
+  enableAllMcp: boolean;
+  enableAllMcpSource: string;
+  serverShell: boolean;
+  serverNetwork: boolean;
+  serverSecret: boolean;
+}
+
+function readJson(path: string): unknown | null {
+  try {
+    const st = lstatSync(path);
+    if (st.isSymbolicLink() || !st.isFile() || st.size > MAX_FILE_BYTES) return null;
+    return JSON.parse(readFileSync(path, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+function asStringArray(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((x): x is string => typeof x === 'string') : [];
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+// ---------------------------------------------------------------------------
+// scanners
+// ---------------------------------------------------------------------------
+
+function scanSettings(root: string, rel: string, acc: Accumulator): void {
+  const abs = join(root, rel);
+  if (!existsSync(abs)) return;
+  const data = readJson(abs);
+  if (!isPlainObject(data)) return;
+  acc.scanned.push(rel);
+  acc.hasSettings = true;
+
+  const perms = isPlainObject(data['permissions']) ? data['permissions'] : {};
+  const allow = asStringArray(perms['allow']);
+  const deny = asStringArray(perms['deny']);
+  acc.denyRules.push(...deny);
+  if (deny.length > 0) acc.hasDeny = true;
+
+  for (const grant of allow) {
+    const { tool, arg } = parseGrant(grant);
+    if (grant.trim() === '*' || (SHELL_TOOLS.has(tool.toLowerCase()) && arg === null)) {
+      acc.wildcardAll = true;
+    }
+    const kind = toolKind(tool);
+    switch (kind) {
+      case 'shell':
+        acc.shellGrants.push(grant);
+        if (arg !== null && SHELL_NET_RE.test(arg)) acc.shellArgNetwork.push(grant);
+        if (arg !== null && SHELL_WRITE_RE.test(arg)) acc.shellArgWrite.push(grant);
+        break;
+      case 'network':
+        acc.networkGrants.push(grant);
+        break;
+      case 'file-write':
+        acc.writeGrants.push(grant);
+        break;
+      case 'read':
+        acc.hasReadGrant = true;
+        break;
+      case 'mcp':
+        acc.mcpToolGrants.push(grant);
+        acc.mcpActive = true;
+        break;
+      case 'safe':
+        break;
+      default:
+        acc.unknownTools.push(grant);
+    }
+  }
+
+  if (data['enableAllProjectMcpServers'] === true) {
+    acc.enableAllMcp = true;
+    acc.enableAllMcpSource = rel;
+    acc.mcpActive = true;
+  }
+  if (Array.isArray(data['enabledMcpjsonServers']) && data['enabledMcpjsonServers'].length > 0) {
+    acc.mcpActive = true;
+  }
+}
+
+function scanMcpServers(root: string, rel: string, acc: Accumulator): void {
+  const abs = join(root, rel);
+  if (!existsSync(abs)) return;
+  const data = readJson(abs);
+  if (!isPlainObject(data)) return;
+  acc.scanned.push(rel);
+
+  const merged: Record<string, unknown> = {};
+  if (isPlainObject(data['mcpServers'])) Object.assign(merged, data['mcpServers']);
+  if (isPlainObject(data['servers'])) Object.assign(merged, data['servers']);
+  if (Object.keys(merged).length > 0) acc.mcpActive = true;
+
+  for (const [name, raw] of Object.entries(merged)) {
+    if (!isPlainObject(raw)) continue;
+    const type = typeof raw['type'] === 'string' ? (raw['type'] as string) : '';
+    const url = typeof raw['url'] === 'string' ? (raw['url'] as string) : '';
+    const command = typeof raw['command'] === 'string' ? (raw['command'] as string) : '';
+    const args = asStringArray(raw['args']);
+    const env = isPlainObject(raw['env']) ? raw['env'] : {};
+
+    if (type === 'sse' || type === 'http' || url !== '') {
+      acc.serverNetwork = true;
+      acc.findings.push({
+        id: 'MS-MCP-REMOTE',
+        severity: 'medium',
+        capability: 'network',
+        source: rel,
+        detail: `MCP server "${name}" is remote (${type || 'url'}) — sends data to an external endpoint.`,
+        evidence: url || type,
+      });
+    }
+
+    const cmdBase = basename(command).toLowerCase();
+    const isInterpreter = INTERPRETER_RE.test(cmdBase);
+    const isRunner = PACKAGE_RUNNERS.has(cmdBase);
+    const hasInlineCode = args.some((a) => INLINE_CODE_ARGS.has(a));
+    if (command !== '' && (isInterpreter || isRunner || hasInlineCode)) {
+      acc.serverShell = true;
+      const why = isRunner
+        ? `package runner "${cmdBase}" fetches and executes remote code`
+        : hasInlineCode
+          ? `inline-code argument`
+          : `interpreter "${cmdBase}" can run arbitrary code`;
+      acc.findings.push({
+        id: 'MS-MCP-SHELL-CMD',
+        severity: 'high',
+        capability: 'shell',
+        source: rel,
+        detail: `MCP server "${name}" launches via ${why}.`,
+        evidence: [command, ...args].join(' ').slice(0, 120),
+      });
+    }
+
+    for (const [k, v] of Object.entries(env)) {
+      if (looksLikeHardcodedSecret(k, v)) {
+        acc.serverSecret = true;
+        acc.findings.push({
+          id: 'MS-SECRET-HARDCODED',
+          severity: 'high',
+          capability: 'secrets',
+          source: rel,
+          detail: `MCP server "${name}" env "${k}" appears to contain a hardcoded secret — use \${ENV_VAR} indirection instead.`,
+          evidence: `${k}=${String(v).slice(0, 4)}…`,
+        });
+      }
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// entry point
+// ---------------------------------------------------------------------------
+
+function aggregate(
+  grants: string[],
+  deny: string[],
+  id: string,
+  severity: McpSeverity,
+  capability: McpCapability,
+  label: string,
+): McpFinding | null {
+  const survivors = grants.filter((g) => !denyCovers(g, deny));
+  if (survivors.length === 0) return null;
+  const examples = survivors.slice(0, 3).join(', ');
+  return {
+    id,
+    severity,
+    capability,
+    source: '.claude/settings*.json',
+    detail: `${label} via ${survivors.length} allow rule(s) not covered by a deny rule.`,
+    evidence: survivors.length > 3 ? `e.g. ${examples}, … (+${survivors.length - 3} more)` : examples,
+  };
+}
+
+/**
+ * Statically scan a project/pack root for an unsafe agent permission surface.
+ * Deterministic and read-only — never executes anything it finds.
+ */
+export function scanMcp(rootDir: string): McpScanReport {
+  const acc: Accumulator = {
+    findings: [],
+    scanned: [],
+    shellGrants: [],
+    networkGrants: [],
+    writeGrants: [],
+    shellArgNetwork: [],
+    shellArgWrite: [],
+    mcpToolGrants: [],
+    unknownTools: [],
+    denyRules: [],
+    hasReadGrant: false,
+    hasSettings: false,
+    hasDeny: false,
+    wildcardAll: false,
+    mcpActive: false,
+    enableAllMcp: false,
+    enableAllMcpSource: '.claude/settings*.json',
+    serverShell: false,
+    serverNetwork: false,
+    serverSecret: false,
+  };
+
+  // order is irrelevant to the result: all signals are merged before evaluation.
+  scanSettings(rootDir, join('.claude', 'settings.json'), acc);
+  scanSettings(rootDir, join('.claude', 'settings.local.json'), acc);
+  scanMcpServers(rootDir, '.mcp.json', acc);
+  scanMcpServers(rootDir, join('.vscode', 'mcp.json'), acc);
+
+  const deny = acc.denyRules;
+
+  // --- aggregated capability findings (merged surface, deny-suppressed) ---
+  const shellSurvivors = acc.shellGrants.filter((g) => !denyCovers(g, deny));
+  if (shellSurvivors.length > 0) {
+    const anyWildcard = shellSurvivors.some((g) => isWildcard(parseGrant(g).arg));
+    const examples = shellSurvivors.slice(0, 3).join(', ');
+    acc.findings.push({
+      id: anyWildcard ? 'MS-SHELL-WILDCARD' : 'MS-SHELL-GRANT',
+      severity: 'high',
+      capability: 'shell',
+      source: '.claude/settings*.json',
+      detail: anyWildcard
+        ? `Wildcard shell grant — arbitrary command execution. ${shellSurvivors.length} shell allow rule(s).`
+        : `Shell execution granted via ${shellSurvivors.length} allow rule(s).`,
+      evidence: shellSurvivors.length > 3 ? `e.g. ${examples}, … (+${shellSurvivors.length - 3} more)` : examples,
+    });
+  }
+
+  const netFinding = aggregate(
+    [...acc.networkGrants, ...acc.shellArgNetwork],
+    deny,
+    'MS-NETWORK-GRANT',
+    'medium',
+    'network',
+    'Outbound network access granted',
+  );
+  if (netFinding) acc.findings.push(netFinding);
+
+  const writeFinding = aggregate(
+    [...acc.writeGrants, ...acc.shellArgWrite],
+    deny,
+    'MS-FILEWRITE-GRANT',
+    'medium',
+    'file-write',
+    'Filesystem write access granted',
+  );
+  if (writeFinding) acc.findings.push(writeFinding);
+
+  // --- enable-all-mcp ---
+  if (acc.enableAllMcp) {
+    acc.findings.push({
+      id: 'MS-MCP-ALL-ENABLED',
+      severity: 'high',
+      capability: 'mcp',
+      source: acc.enableAllMcpSource,
+      detail: `enableAllProjectMcpServers: true — every project MCP server is trusted unconditionally (no per-server gate).`,
+      evidence: 'enableAllProjectMcpServers: true',
+    });
+  }
+
+  // --- secrets reachability (MetaHarness: requires MCP active) ---
+  const secretsReachable = acc.mcpActive && acc.hasReadGrant && !denyProtectsSecrets(deny);
+  if (secretsReachable) {
+    acc.findings.push({
+      id: 'MS-SECRETS-REACHABLE',
+      severity: 'high',
+      capability: 'secrets',
+      source: '.claude/settings*.json',
+      detail: `MCP is active and a Read grant exists without a deny rule protecting secret files (.env, SSH keys, cloud creds) — secrets are reachable by tools.`,
+      evidence: 'allow contains Read(...) ∧ MCP active ∧ deny lacks a secret-file guard',
+    });
+  }
+
+  // --- default-deny posture (scoped to the settings surface) ---
+  const defaultDeny = acc.hasSettings ? acc.hasDeny && !acc.wildcardAll : true;
+  if (acc.hasSettings && !defaultDeny) {
+    acc.findings.push({
+      id: 'MS-DEFAULT-DENY-OFF',
+      severity: 'high',
+      capability: 'policy',
+      source: '.claude/settings*.json',
+      detail: acc.wildcardAll
+        ? `An allow rule grants a bare wildcard — everything is permitted (no default-deny).`
+        : `No deny rules declared — the permission surface has no guardrail (no default-deny baseline).`,
+      evidence: acc.wildcardAll ? 'allow contains "*" / "Bash(*)"' : 'permissions.deny is empty',
+    });
+  }
+
+  // --- informational (low) findings: verdict-neutral coverage signal ---
+  if (acc.mcpToolGrants.length > 0) {
+    acc.findings.push({
+      id: 'MS-MCP-TOOLS-ALLOWED',
+      severity: 'low',
+      capability: 'mcp',
+      source: '.claude/settings*.json',
+      detail: `${acc.mcpToolGrants.length} MCP tool(s) explicitly allowed (per-tool gate — the safe pattern).`,
+      evidence: acc.mcpToolGrants.slice(0, 3).join(', '),
+    });
+  }
+  if (acc.unknownTools.length > 0) {
+    acc.findings.push({
+      id: 'MS-UNKNOWN-TOOL',
+      severity: 'low',
+      capability: 'policy',
+      source: '.claude/settings*.json',
+      detail: `${acc.unknownTools.length} grant(s) for tools not in the recognised capability sets — coverage gap, review manually.`,
+      evidence: acc.unknownTools.slice(0, 3).join(', '),
+    });
+  }
+
+  // --- verdict (low is verdict-neutral) ---
+  const hasHigh = acc.findings.some((f) => f.severity === 'high');
+  const hasMedium = acc.findings.some((f) => f.severity === 'medium');
+  const verdict: McpVerdict = hasHigh ? 'high' : hasMedium ? 'medium' : 'clean';
+  const exitCode: 0 | 1 | 2 = verdict === 'high' ? 2 : verdict === 'medium' ? 1 : 0;
+
+  const order = { high: 0, medium: 1, low: 2 } as const;
+  const findings = [...acc.findings].sort(
+    (a, b) => order[a.severity] - order[b.severity] || a.id.localeCompare(b.id),
+  );
+
+  return {
+    verdict,
+    exitCode,
+    findings,
+    scanned: acc.scanned,
+    capabilities: {
+      shell: shellSurvivors.length > 0 || acc.serverShell,
+      network: Boolean(netFinding) || acc.serverNetwork,
+      fileWrite: Boolean(writeFinding),
+      secretsReachable: secretsReachable || acc.serverSecret,
+      defaultDeny,
+    },
+  };
+}

package/src/operations.ts

@@ -14,6 +14,7 @@ import { CODEX_SKILLS_ROOT } from '@dzhechkov/adapter-codex';
 import { HERMES_SKILLS_ROOT } from '@dzhechkov/adapter-hermes';
 import { OPENCODE_SKILLS_ROOT } from '@dzhechkov/adapter-opencode';
 import { OPENCLAUDE_SKILLS_ROOT } from '@dzhechkov/adapter-openclaude';
+import { COPILOT_INSTRUCTIONS_ROOT } from '@dzhechkov/adapter-copilot';
 import type { CanonicalSkill, EmitResult, SkillAsset } from '@dzhechkov/core';
 import { computeRiskScore } from './risk-scoring.js';
 
@@ -80,6 +81,9 @@ const SKILLS_ROOTS: Record<TargetName, string> = {
   opencode: OPENCODE_SKILLS_ROOT,
   hermes: HERMES_SKILLS_ROOT,
   openclaude: OPENCLAUDE_SKILLS_ROOT,
+  // copilot is a lossy instruction adapter (not a skills tree); enrichment never
+  // fires for it (no matching branch below), but the map must be total.
+  copilot: COPILOT_INSTRUCTIONS_ROOT,
 };
 
 /**
@@ -412,13 +416,13 @@ export async function runDoctor(options: { projectRoot: string }): Promise<Docto
     });
   }
 
-  // 3. Adapter resolvability
-  const adapters = ['adapter-claude', 'adapter-codex', 'adapter-hermes', 'adapter-opencode'];
+  // 3. Adapter resolvability (one per target platform)
+  const adapters = ['adapter-claude', 'adapter-codex', 'adapter-opencode', 'adapter-hermes', 'adapter-openclaude', 'adapter-copilot'];
   const foundAdapters = adapters.filter((a) => existsSync(join(root, 'packages/@dzhechkov', a)));
   checks.push({
     name: 'adapters present',
-    ok: foundAdapters.length === 4,
-    detail: `${foundAdapters.length}/4 adapters found`,
+    ok: foundAdapters.length === adapters.length,
+    detail: `${foundAdapters.length}/${adapters.length} adapters found`,
   });
 
   // 4. Package version consistency