@elmoxbt/agentskillguard 0.1.0

package/src/cli.ts

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import * as fs from 'fs';
+import * as path from 'path';
+import chalk from 'chalk';
+import { scanTarget } from './scanner';
+import { loadPolicy, DEFAULT_POLICY_YAML } from './policy/loader';
+import { printReport } from './report/formatter';
+import { saveScan, listScans } from './db/store';
+
+const program = new Command();
+
+program
+  .name('skillguard')
+  .description('AgentSkillGuard — static security scanner for AI agent tools that touch a Solana wallet.')
+  .version('0.1.0');
+
+program
+  .command('scan <target>')
+  .description('Scan a tool directory or file for dangerous capabilities')
+  .option('-p, --policy <file>', 'Path to a YAML capability manifest to enforce')
+  .option('--json', 'Print machine-readable JSON instead of the formatted report')
+  .option('--no-save', 'Do not persist this scan to the local history database')
+  .action((target: string, opts: { policy?: string; json?: boolean; save: boolean }) => {
+    const resolvedTarget = path.resolve(target);
+    if (!fs.existsSync(resolvedTarget)) {
+      console.error(chalk.red(`Target not found: ${resolvedTarget}`));
+      process.exitCode = 1;
+      return;
+    }
+
+    const policy = opts.policy ? loadPolicy(path.resolve(opts.policy)) : null;
+    const result = scanTarget(resolvedTarget, policy);
+
+    if (opts.save) {
+      try {
+        saveScan(result);
+      } catch (err) {
+        console.error(chalk.yellow(`Warning: could not save scan history (${(err as Error).message})`));
+      }
+    }
+
+    if (opts.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      printReport(result);
+    }
+
+    if (result.verdict === 'BLOCK') {
+      process.exitCode = 2;
+    } else if (result.verdict === 'WARN') {
+      process.exitCode = 1;
+    }
+  });
+
+program
+  .command('init-policy')
+  .description('Write a starter deny-by-default policy manifest')
+  .option('-o, --out <file>', 'Output path', 'skillguard.policy.yaml')
+  .action((opts: { out: string }) => {
+    const outPath = path.resolve(opts.out);
+    if (fs.existsSync(outPath)) {
+      console.error(chalk.red(`Refusing to overwrite existing file: ${outPath}`));
+      process.exitCode = 1;
+      return;
+    }
+    fs.writeFileSync(outPath, DEFAULT_POLICY_YAML, 'utf-8');
+    console.log(chalk.green(`Wrote starter policy to ${outPath}`));
+  });
+
+program
+  .command('history')
+  .description('Show recent scans from local history')
+  .option('-n, --limit <n>', 'Number of rows to show', '20')
+  .action((opts: { limit: string }) => {
+    const rows = listScans(parseInt(opts.limit, 10));
+    if (rows.length === 0) {
+      console.log(chalk.dim('No scans recorded yet. Run `skillguard scan <target>` first.'));
+      return;
+    }
+    for (const r of rows) {
+      const label = String(r.verdict).padEnd(6);
+      const colored = r.verdict === 'BLOCK' ? chalk.red(label) : r.verdict === 'WARN' ? chalk.yellow(label) : chalk.green(label);
+      console.log(
+        `#${r.id}  ${r.scanned_at}  ${colored}  ${r.tool_name ?? '(unnamed)'}  ${r.target}  ` +
+          chalk.dim(`(${r.findings_count} findings, ${r.violations_count} violations)`)
+      );
+    }
+  });
+
+program.parse(process.argv);

package/src/db/store.ts

@@ -0,0 +1,61 @@
+import Database from 'better-sqlite3';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { ScanResult } from '../types';
+
+const DB_DIR = path.join(os.homedir(), '.agentskillguard');
+const DB_PATH = path.join(DB_DIR, 'scans.db');
+
+function getDb(): Database.Database {
+  if (!fs.existsSync(DB_DIR)) fs.mkdirSync(DB_DIR, { recursive: true });
+  const db = new Database(DB_PATH);
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS scans (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      target TEXT NOT NULL,
+      tool_name TEXT,
+      verdict TEXT NOT NULL,
+      verdict_reason TEXT,
+      findings_count INTEGER,
+      violations_count INTEGER,
+      result_json TEXT NOT NULL,
+      scanned_at TEXT NOT NULL
+    );
+  `);
+  return db;
+}
+
+export function saveScan(result: ScanResult): number {
+  const db = getDb();
+  try {
+    const stmt = db.prepare(`
+      INSERT INTO scans (target, tool_name, verdict, verdict_reason, findings_count, violations_count, result_json, scanned_at)
+      VALUES (@target, @tool_name, @verdict, @verdict_reason, @findings_count, @violations_count, @result_json, @scanned_at)
+    `);
+    const info = stmt.run({
+      target: result.target,
+      tool_name: result.metadata?.name ?? null,
+      verdict: result.verdict,
+      verdict_reason: result.verdictReason,
+      findings_count: result.findings.length,
+      violations_count: result.violations.length,
+      result_json: JSON.stringify(result),
+      scanned_at: result.scannedAt,
+    });
+    return info.lastInsertRowid as number;
+  } finally {
+    db.close();
+  }
+}
+
+export function listScans(limit = 20): any[] {
+  const db = getDb();
+  try {
+    return db
+      .prepare(`SELECT id, target, tool_name, verdict, findings_count, violations_count, scanned_at FROM scans ORDER BY id DESC LIMIT ?`)
+      .all(limit);
+  } finally {
+    db.close();
+  }
+}

package/src/policy/enforcer.ts

@@ -0,0 +1,86 @@
+import * as fs from 'fs';
+import { Finding, Violation } from '../types';
+import { Policy } from './schema';
+import { extractDomains, extractLiteralUrls } from '../scanner/staticAnalyzer';
+
+/**
+ * Capabilities that are never acceptable for an agent tool, regardless of
+ * what a policy manifest grants. A policy can only narrow permissions
+ * below this floor — it can never widen past it.
+ */
+const ALWAYS_BLOCKED_CAPABILITIES = new Set([
+  'wallet.private_key_access',
+  'system.shell_exec',
+  'code.dynamic_load',
+  'code.obfuscation',
+  'solana.unlimited_approval',
+]);
+
+export function evaluatePolicy(findings: Finding[], policy: Policy | null, filesScanned: string[]): Violation[] {
+  const violations: Violation[] = [];
+  const capabilitiesSeen = new Set(findings.map((f) => f.capability));
+
+  // 1. Hard floor — applies even with no policy supplied at all.
+  for (const cap of capabilitiesSeen) {
+    if (ALWAYS_BLOCKED_CAPABILITIES.has(cap)) {
+      const f = findings.find((x) => x.capability === cap)!;
+      violations.push({
+        capability: cap,
+        severity: 'CRITICAL',
+        message: `${cap} is never permitted, regardless of policy (${f.description})`,
+      });
+    }
+  }
+
+  if (!policy) {
+    return violations;
+  }
+
+  // 2. Wallet signing must be explicitly granted.
+  if (capabilitiesSeen.has('wallet.signing') && !policy.permissions.wallet.signing) {
+    violations.push({
+      capability: 'wallet.signing',
+      severity: 'CRITICAL',
+      message: 'Tool signs transactions but policy.permissions.wallet.signing is false.',
+    });
+  }
+
+  // 3. Dynamic URLs can never be verified against an allowlist.
+  if (capabilitiesSeen.has('network.dynamic_url')) {
+    violations.push({
+      capability: 'network.dynamic_url',
+      severity: 'HIGH',
+      message: 'Tool builds request URLs dynamically — the target domain cannot be statically verified against the allowlist.',
+    });
+  }
+
+  // 4. Any literal domain contacted must be in the allowlist.
+  if (capabilitiesSeen.has('network.http')) {
+    const allowlist = new Set(policy.permissions.network.domains);
+    const seenDomains = new Set<string>();
+    for (const file of filesScanned) {
+      const content = fs.readFileSync(file, 'utf-8');
+      extractDomains(extractLiteralUrls(content)).forEach((d) => seenDomains.add(d));
+    }
+    for (const domain of seenDomains) {
+      if (!allowlist.has(domain)) {
+        violations.push({
+          capability: 'network.http',
+          severity: 'HIGH',
+          message: `Tool contacts domain "${domain}", which is not in the policy's network.domains allowlist.`,
+        });
+      }
+    }
+  }
+
+  // 5. Transaction manipulation requires at least one granted Solana program.
+  if (capabilitiesSeen.has('solana.tx_modification') && policy.permissions.solana.programs.length === 0) {
+    violations.push({
+      capability: 'solana.tx_modification',
+      severity: 'HIGH',
+      message: 'Tool modifies transaction instructions but the policy grants no Solana program permissions.',
+    });
+  }
+
+  return violations;
+}

package/src/policy/loader.ts

@@ -0,0 +1,31 @@
+import * as fs from 'fs';
+import * as yaml from 'js-yaml';
+import { Policy, PolicySchema } from './schema';
+
+export function loadPolicy(policyPath: string): Policy {
+  const raw = fs.readFileSync(policyPath, 'utf-8');
+  const parsed = yaml.load(raw);
+  const result = PolicySchema.safeParse(parsed);
+  if (!result.success) {
+    const issues = result.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; ');
+    throw new Error(`Invalid policy manifest (${policyPath}): ${issues}`);
+  }
+  return result.data;
+}
+
+export const DEFAULT_POLICY_YAML = `name: default-deny
+description: "Starter policy — deny everything until explicitly granted."
+
+permissions:
+  solana:
+    programs: []
+    max_sol: 0
+    tokens: []
+
+  network:
+    domains: []
+
+  wallet:
+    signing: false
+    max_transactions_per_hour: 0
+`;

package/src/policy/schema.ts

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+
+/**
+ * The Solana-specific capability manifest schema.
+ *
+ * This is intentionally narrow for the MVP: it describes the *ceiling* of
+ * what a tool is allowed to do. The static scanner's findings are checked
+ * against it in src/policy/enforcer.ts. Fields like max_sol and
+ * max_transactions_per_hour are captured here and are enforced at *runtime*
+ * by a wrapping guard (see README "Roadmap") — they cannot be verified by
+ * static analysis alone.
+ */
+export const PolicySchema = z.object({
+  name: z.string(),
+  description: z.string().optional(),
+  permissions: z.object({
+    solana: z
+      .object({
+        programs: z.array(z.string()).default([]),
+        max_sol: z.number().default(0),
+        tokens: z.array(z.string()).default([]),
+      })
+      .default({ programs: [], max_sol: 0, tokens: [] }),
+    network: z
+      .object({
+        domains: z.array(z.string()).default([]),
+      })
+      .default({ domains: [] }),
+    wallet: z
+      .object({
+        signing: z.boolean().default(false),
+        max_transactions_per_hour: z.number().default(0),
+      })
+      .default({ signing: false, max_transactions_per_hour: 0 }),
+  }),
+});
+
+export type Policy = z.infer<typeof PolicySchema>;

package/src/report/formatter.ts

@@ -0,0 +1,63 @@
+import chalk from 'chalk';
+import { ScanResult, Finding } from '../types';
+
+const SEVERITY_COLOR: Record<string, (s: string) => string> = {
+  CRITICAL: chalk.bgRed.white.bold,
+  HIGH: chalk.red.bold,
+  MEDIUM: chalk.yellow,
+  LOW: chalk.gray,
+};
+
+function verdictBadge(verdict: string): string {
+  const label = ` ${verdict} `;
+  if (verdict === 'BLOCK') return chalk.bgRed.white.bold(label);
+  if (verdict === 'WARN') return chalk.bgYellow.black.bold(label);
+  return chalk.bgGreen.black.bold(label);
+}
+
+export function printReport(result: ScanResult): void {
+  console.log('');
+  console.log(chalk.bold('AGENTSKILLGUARD'));
+  console.log(chalk.dim(`target: ${result.target}`));
+  if (result.metadata?.name) {
+    console.log(chalk.dim(`tool:   ${result.metadata.name}${result.metadata.version ? '@' + result.metadata.version : ''}`));
+  }
+  console.log(chalk.dim(`files scanned: ${result.filesScanned}`));
+  console.log('');
+
+  if (result.findings.length === 0) {
+    console.log(chalk.green('No suspicious capabilities detected.'));
+  } else {
+    console.log(chalk.bold('Capabilities detected:'));
+    const byCapability = new Map<string, Finding[]>();
+    for (const f of result.findings) {
+      if (!byCapability.has(f.capability)) byCapability.set(f.capability, []);
+      byCapability.get(f.capability)!.push(f);
+    }
+    for (const [capability, findings] of byCapability) {
+      const sev = findings[0].severity;
+      const color = SEVERITY_COLOR[sev] ?? ((s: string) => s);
+      console.log(`  [x] ${color(sev.padEnd(8))} ${capability} — ${findings[0].description}`);
+      for (const f of findings.slice(0, 3)) {
+        console.log(chalk.dim(`        ${f.file}:${f.line}  ${f.snippet}`));
+      }
+      if (findings.length > 3) {
+        console.log(chalk.dim(`        …and ${findings.length - 3} more occurrence(s)`));
+      }
+    }
+  }
+
+  console.log('');
+  if (result.violations.length > 0) {
+    console.log(chalk.bold('Policy violations:'));
+    for (const v of result.violations) {
+      const color = SEVERITY_COLOR[v.severity] ?? ((s: string) => s);
+      console.log(`  [!] ${color(v.severity.padEnd(8))} ${v.message}`);
+    }
+    console.log('');
+  }
+
+  console.log(`Recommended action: ${verdictBadge(result.verdict)}`);
+  console.log(chalk.dim(result.verdictReason));
+  console.log('');
+}

package/src/report/verdict.ts

@@ -0,0 +1,35 @@
+import { Violation } from '../types';
+
+/**
+ * Verdict is driven entirely by *violations* (findings checked against the
+ * policy + hard floor), not raw finding counts. A tool can have plenty of
+ * informational MEDIUM findings (e.g. "reads process.env") and still ALLOW,
+ * as long as nothing crosses a permission boundary.
+ */
+export function computeVerdict(violations: Violation[]): { verdict: 'ALLOW' | 'WARN' | 'BLOCK'; reason: string } {
+  const critical = violations.filter((v) => v.severity === 'CRITICAL');
+  const high = violations.filter((v) => v.severity === 'HIGH');
+
+  if (critical.length > 0) {
+    return {
+      verdict: 'BLOCK',
+      reason: `${critical.length} critical violation(s): ${critical.map((v) => v.capability).join(', ')}.`,
+    };
+  }
+
+  if (high.length > 0) {
+    return {
+      verdict: 'WARN',
+      reason: `${high.length} high-severity issue(s) require manual review: ${high.map((v) => v.capability).join(', ')}.`,
+    };
+  }
+
+  if (violations.length > 0) {
+    return {
+      verdict: 'WARN',
+      reason: `${violations.length} lower-severity policy issue(s) found. Review recommended before granting broader access.`,
+    };
+  }
+
+  return { verdict: 'ALLOW', reason: 'No policy violations detected. Review any informational findings below before deploying.' };
+}

package/src/rules/rules.ts

@@ -0,0 +1,110 @@
+import { Severity } from '../types';
+
+export interface Rule {
+  id: string;
+  capability: string;
+  severity: Severity;
+  description: string;
+  pattern: RegExp;
+  recommendation: string;
+}
+
+/**
+ * Static detection rules.
+ *
+ * Each rule is a single-line regex heuristic (MVP scope — see README for the
+ * tree-sitter/AST upgrade path). A match means "this line is CAPABLE of the
+ * behavior", not "this line is definitely malicious" — that judgment is made
+ * by the policy enforcer + verdict engine, which weighs findings against the
+ * capability manifest.
+ */
+export const RULES: Rule[] = [
+  {
+    id: 'wallet-signing-access',
+    capability: 'wallet.signing',
+    severity: 'CRITICAL',
+    description: 'Tool can invoke wallet transaction/message signing.',
+    pattern: /\b(signTransaction|signAllTransactions|signMessage|Keypair\.fromSecretKey)\b/,
+    recommendation: 'Only allow if the policy explicitly grants wallet.signing and the code path is audited.',
+  },
+  {
+    id: 'private-key-access',
+    capability: 'wallet.private_key_access',
+    severity: 'CRITICAL',
+    description: 'Tool references private key / secret / mnemonic material directly.',
+    pattern: /(PRIVATE_KEY|SECRET_KEY|secretKey\s*[:=]|mnemonic|seedPhrase|seed_phrase)/i,
+    recommendation: 'Tools should never need raw key material. Treat as an automatic block.',
+  },
+  {
+    id: 'network-call',
+    capability: 'network.http',
+    severity: 'MEDIUM',
+    description: 'Tool performs outbound HTTP(S) requests.',
+    pattern: /\b(fetch|axios\.(get|post|put|delete|patch|request)|http\.request|https\.request|XMLHttpRequest)\s*\(/,
+    recommendation: 'Cross-check target domains against the network allowlist in the policy manifest.',
+  },
+  {
+    id: 'dynamic-url-construction',
+    capability: 'network.dynamic_url',
+    severity: 'HIGH',
+    description: 'Request URL is built from a variable/expression rather than a static string literal.',
+    pattern: /\b(fetch|axios\.\w+)\s*\(\s*[^'"`\s)][^)]*\)/,
+    recommendation: 'Dynamic URLs cannot be statically allowlisted — treat as arbitrary network access.',
+  },
+  {
+    id: 'tx-destination-modification',
+    capability: 'solana.tx_modification',
+    severity: 'HIGH',
+    description: 'Tool manipulates transaction instructions or recipient/destination fields.',
+    pattern: /\b(transaction|tx)\.(instructions|add)\s*\(|\b(recipient|destination|toPubkey)\s*=/,
+    recommendation: 'Manually review: confirm destination addresses are user-supplied, not tool-controlled.',
+  },
+  {
+    id: 'shell-exec',
+    capability: 'system.shell_exec',
+    severity: 'CRITICAL',
+    description: 'Tool can execute OS shell commands via child_process.',
+    pattern: /require\(\s*['"]child_process['"]\s*\)|\b(execSync|spawnSync|exec|spawn|fork)\s*\(/,
+    recommendation: 'No legitimate Solana/agent tool needs shell access. Treat as an automatic block.',
+  },
+  {
+    id: 'dynamic-code-load',
+    capability: 'code.dynamic_load',
+    severity: 'CRITICAL',
+    description: 'Tool loads or executes code dynamically at runtime (eval, new Function, dynamic require, vm module).',
+    pattern: /\beval\s*\(|new\s+Function\s*\(|vm\.runInNewContext|vm\.runInThisContext|require\(\s*[a-zA-Z_$][\w$]*\s*\)/,
+    recommendation: 'Dynamic code loading defeats static review entirely. Treat as an automatic block.',
+  },
+  {
+    id: 'unlimited-token-approval',
+    capability: 'solana.unlimited_approval',
+    severity: 'HIGH',
+    description: 'Tool requests unlimited or maximum token approvals/authority delegation.',
+    pattern: /approve\([^)]*(MAX_UINT256|0xffffffff|Infinity)|setAuthority\([^)]*null/i,
+    recommendation: 'Unlimited approvals should never be requested by an automated agent tool.',
+  },
+  {
+    id: 'env-read',
+    capability: 'system.env_read',
+    severity: 'MEDIUM',
+    description: 'Tool reads process environment variables.',
+    pattern: /\bprocess\.env\b/,
+    recommendation: 'Confirm env vars read are not secrets being staged for exfiltration over a network call.',
+  },
+  {
+    id: 'obfuscated-execution',
+    capability: 'code.obfuscation',
+    severity: 'CRITICAL',
+    description: 'Tool decodes an obfuscated (base64/hex) payload and executes it.',
+    pattern: /(atob\(|Buffer\.from\([^)]*base64[^)]*\))[^;]*\b(eval|Function)\b/i,
+    recommendation: 'Obfuscated execution is a strong malware indicator. Treat as an automatic block.',
+  },
+  {
+    id: 'filesystem-write',
+    capability: 'system.filesystem_write',
+    severity: 'MEDIUM',
+    description: 'Tool writes to or deletes files on disk.',
+    pattern: /\bfs\.(writeFile(Sync)?|appendFile(Sync)?|unlink(Sync)?|rm(Sync)?|rmdir(Sync)?)\s*\(/,
+    recommendation: 'Confirm writes are scoped to an expected working directory, not arbitrary paths.',
+  },
+];

package/src/scanner/index.ts

@@ -0,0 +1,33 @@
+import { walk } from '../utils/fileWalker';
+import { analyzeFile } from './staticAnalyzer';
+import { readMetadata } from './mcpMetadata';
+import { evaluatePolicy } from '../policy/enforcer';
+import { computeVerdict } from '../report/verdict';
+import { Policy } from '../policy/schema';
+import { Finding, ScanResult } from '../types';
+
+export function scanTarget(target: string, policy: Policy | null): ScanResult {
+  const files = walk(target);
+  const metadata = readMetadata(target);
+
+  const findings: Finding[] = [];
+  for (const file of files) {
+    findings.push(...analyzeFile(file));
+  }
+
+  const violations = evaluatePolicy(findings, policy, files);
+  const { verdict, reason } = computeVerdict(violations);
+  const capabilities = Array.from(new Set(findings.map((f) => f.capability))).sort();
+
+  return {
+    target,
+    scannedAt: new Date().toISOString(),
+    filesScanned: files.length,
+    metadata,
+    findings,
+    capabilities,
+    violations,
+    verdict,
+    verdictReason: reason,
+  };
+}

package/src/scanner/mcpMetadata.ts

@@ -0,0 +1,56 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { ToolMetadata } from '../types';
+
+/**
+ * Best-effort read of a tool's declared identity: package.json plus an
+ * optional MCP manifest (mcp.json / mcp.manifest.json) if present. This is
+ * informational only — it is never trusted as a source of truth for
+ * capabilities, since a manifest can claim anything. Capabilities always
+ * come from the static analyzer, not from what the tool says about itself.
+ */
+export function readMetadata(root: string): ToolMetadata | null {
+  const stat = fs.existsSync(root) ? fs.statSync(root) : null;
+  const dir = stat && stat.isDirectory() ? root : path.dirname(root);
+
+  const pkgPath = path.join(dir, 'package.json');
+  const mcpPath1 = path.join(dir, 'mcp.json');
+  const mcpPath2 = path.join(dir, 'mcp.manifest.json');
+
+  let name: string | undefined;
+  let version: string | undefined;
+  let description: string | undefined;
+  let declaredTools: string[] | undefined;
+  let found = false;
+
+  if (fs.existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+      name = pkg.name;
+      version = pkg.version;
+      description = pkg.description;
+      found = true;
+    } catch {
+      // malformed package.json — ignore, not fatal to the scan
+    }
+  }
+
+  const mcpFile = fs.existsSync(mcpPath1) ? mcpPath1 : fs.existsSync(mcpPath2) ? mcpPath2 : null;
+  if (mcpFile) {
+    try {
+      const mcp = JSON.parse(fs.readFileSync(mcpFile, 'utf-8'));
+      if (Array.isArray(mcp.tools)) {
+        declaredTools = mcp.tools.map((t: any) => (t && t.name ? String(t.name) : String(t)));
+      }
+      name = name ?? mcp.name;
+      description = description ?? mcp.description;
+      found = true;
+    } catch {
+      // malformed MCP manifest — ignore, not fatal to the scan
+    }
+  }
+
+  if (!found) return null;
+
+  return { name, version, description, declaredTools, source: dir };
+}

package/src/scanner/staticAnalyzer.ts

@@ -0,0 +1,48 @@
+import * as fs from 'fs';
+import { RULES } from '../rules/rules';
+import { Finding } from '../types';
+
+/** Runs every rule against every line of a single file. */
+export function analyzeFile(filePath: string): Finding[] {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const lines = content.split(/\r?\n/);
+  const findings: Finding[] = [];
+
+  lines.forEach((line, idx) => {
+    for (const rule of RULES) {
+      if (rule.pattern.test(line)) {
+        findings.push({
+          ruleId: rule.id,
+          capability: rule.capability,
+          severity: rule.severity,
+          description: rule.description,
+          file: filePath,
+          line: idx + 1,
+          snippet: line.trim().slice(0, 160),
+        });
+      }
+    }
+  });
+
+  return findings;
+}
+
+/** Pulls literal http(s) URLs out of a file's raw text. */
+export function extractLiteralUrls(content: string): string[] {
+  const urlRegex = /https?:\/\/[^\s'"`)]+/g;
+  return Array.from(content.matchAll(urlRegex)).map((m) => m[0]);
+}
+
+/** Converts literal URLs into bare hostnames for allowlist comparison. */
+export function extractDomains(urls: string[]): string[] {
+  const domains = new Set<string>();
+  for (const url of urls) {
+    try {
+      domains.add(new URL(url).hostname);
+    } catch {
+      // malformed / template-interpolated URL — ignore, it will already
+      // have been flagged as a dynamic-url-construction finding instead.
+    }
+  }
+  return Array.from(domains);
+}