fullcourtdefense-cli 1.0.2 → 1.1.0

package/README.md

@@ -57,7 +57,7 @@ fullcourtdefense init
 Create a `.fullcourtdefense.yml` to avoid passing flags every time:
 
 ```yaml
-apiKey: ${BOTGUARD_API_KEY}
+apiKey: ${FULLCOURTDEFENSE_API_KEY}
 apiUrl: https://api.fullcourtdefense.ai
 shieldId: sh_your_shield_id
 # shieldKey: shsk_optional_if_locked
@@ -108,7 +108,7 @@ Local scans run from the customer machine or VPN and only send captured text out
 
 | Flag | Applies To | Description | Default |
 |---|---|---|---|
-| `--api-key <key>` | hosted scan/credits | Hosted scan API key. Can also use `BOTGUARD_API_KEY`. | config/env |
+| `--api-key <key>` | hosted scan/credits | Hosted scan API key. Can also use `FULLCOURTDEFENSE_API_KEY` or legacy `BOTGUARD_API_KEY`. | config/env |
 | `--shield-id <id>` | local scan | Shield ID from the Shield Integrate tab. Can also use `FULLCOURTDEFENSE_SHIELD_ID`, `FCD_SHIELD_ID`, or `AGENTGUARD_SHIELD_ID`. | config/env/prompt |
 | `--shield-key <key>` | local scan | Optional Shield key for locked Shields. Can also use `FULLCOURTDEFENSE_SHIELD_KEY`, `FCD_SHIELD_KEY`, or `AGENTGUARD_SHIELD_KEY`. | config/env/prompt |
 
@@ -206,7 +206,7 @@ Checked: https://api.fullcourtdefense.ai/api/health/ping
 Use hosted scans when the agent endpoint is reachable by FullCourtDefense and you have a CI/CD API key.
 
 ```powershell
-$env:BOTGUARD_API_KEY = "bg_live_..."
+$env:FULLCOURTDEFENSE_API_KEY = "bg_live_..."
 fullcourtdefense scan --endpoint "https://support-bot.example.com/chat" --description "Customer support chatbot" --mode sync --format summary --fail-threshold 80
 ```
 
@@ -345,7 +345,7 @@ fullcourtdefense scan --local --type endpoint --endpoint "https://agent.internal
 Fail the build if score is below 80:
 
 ```powershell
-fullcourtdefense scan --api-key "$env:BOTGUARD_API_KEY" --endpoint "https://agent.example.com/chat" --description "Production support agent" --mode sync --format summary --fail-threshold 80
+fullcourtdefense scan --api-key "$env:FULLCOURTDEFENSE_API_KEY" --endpoint "https://agent.example.com/chat" --description "Production support agent" --mode sync --format summary --fail-threshold 80
 ```
 
 Local CI against a service started earlier in the job:

package/dist/api.d.ts

@@ -69,6 +69,7 @@ export interface ScanResult {
     };
     agentDescription: string;
     createdAt: string;
+    reportUrl?: string;
 }
 export interface AsyncJobResponse {
     jobId: string;

package/dist/commands/credits.js

@@ -4,9 +4,9 @@ exports.creditsCommand = creditsCommand;
 const api_1 = require("../api");
 const output_1 = require("../output");
 async function creditsCommand(args, config) {
-    const apiKey = args.apiKey || config.apiKey || process.env.BOTGUARD_API_KEY;
+    const apiKey = args.apiKey || config.apiKey || process.env.FULLCOURTDEFENSE_API_KEY || process.env.BOTGUARD_API_KEY;
     if (!apiKey) {
-        console.error('Error: API key required. Use --api-key, BOTGUARD_API_KEY env var, or .botguard.yml');
+        console.error('Error: API key required. Use --api-key, FULLCOURTDEFENSE_API_KEY env var, or .fullcourtdefense.yml');
         process.exit(1);
     }
     const api = new api_1.BotGuardApi(apiKey, args.apiUrl || config.apiUrl);

package/dist/commands/discover.d.ts

@@ -0,0 +1,11 @@
+import { BotGuardConfig } from '../config';
+export interface DiscoverArgs {
+    type?: string;
+    apiKey?: string;
+    apiUrl?: string;
+    json?: string;
+    upload?: string;
+    connectorName?: string;
+    extraPath?: string;
+}
+export declare function discoverCommand(args: DiscoverArgs, config: BotGuardConfig): Promise<void>;

package/dist/commands/discover.js

@@ -0,0 +1,283 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.discoverCommand = discoverCommand;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const DEFAULT_API_URL = 'https://api.fullcourtdefense.ai';
+const SECRET_VALUE = /sk-[A-Za-z0-9_-]{12,}|ghp_[A-Za-z0-9_]{20,}|xox[baprs]-[A-Za-z0-9-]{20,}|AKIA[0-9A-Z]{16}|AIza[0-9A-Za-z_-]{20,}/;
+const SECRET_KEY = /key|token|secret|password|credential|api[_-]?key/i;
+/** Where MCP client configs live, by client + OS. */
+function candidateConfigPaths(cwd, extra) {
+    const home = os.homedir();
+    const appData = process.env.APPDATA || path.join(home, 'AppData', 'Roaming');
+    const xdg = process.env.XDG_CONFIG_HOME || path.join(home, '.config');
+    const list = [
+        // Cursor
+        { path: path.join(home, '.cursor', 'mcp.json'), source: 'Cursor (global)' },
+        { path: path.join(cwd, '.cursor', 'mcp.json'), source: 'Cursor (project)' },
+        // Claude Desktop
+        { path: path.join(appData, 'Claude', 'claude_desktop_config.json'), source: 'Claude Desktop (win)' },
+        { path: path.join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json'), source: 'Claude Desktop (mac)' },
+        { path: path.join(xdg, 'Claude', 'claude_desktop_config.json'), source: 'Claude Desktop (linux)' },
+        // VS Code (project + user settings)
+        { path: path.join(cwd, '.vscode', 'mcp.json'), source: 'VS Code (project)' },
+        { path: path.join(appData, 'Code', 'User', 'settings.json'), source: 'VS Code (user, win)' },
+        { path: path.join(home, 'Library', 'Application Support', 'Code', 'User', 'settings.json'), source: 'VS Code (user, mac)' },
+        { path: path.join(xdg, 'Code', 'User', 'settings.json'), source: 'VS Code (user, linux)' },
+        // Windsurf
+        { path: path.join(home, '.codeium', 'windsurf', 'mcp_config.json'), source: 'Windsurf' },
+        // Generic / repo-root
+        { path: path.join(cwd, '.mcp.json'), source: 'Repo (.mcp.json)' },
+        { path: path.join(cwd, 'mcp.json'), source: 'Repo (mcp.json)' },
+    ];
+    if (extra)
+        list.push({ path: path.resolve(extra), source: 'Custom path' });
+    return list;
+}
+/** MCP servers can be declared under several keys across clients. */
+function extractServerMap(parsed) {
+    if (!parsed || typeof parsed !== 'object')
+        return {};
+    if (parsed.mcpServers && typeof parsed.mcpServers === 'object')
+        return parsed.mcpServers;
+    if (parsed.servers && typeof parsed.servers === 'object')
+        return parsed.servers;
+    if (parsed.mcp?.servers && typeof parsed.mcp.servers === 'object')
+        return parsed.mcp.servers;
+    if (parsed['mcp.servers'] && typeof parsed['mcp.servers'] === 'object')
+        return parsed['mcp.servers'];
+    return {};
+}
+const RISK_RULES = [
+    { test: /shell|bash|\bexec\b|command[-_]?runner|terminal|subprocess|run[-_]?admin/i, level: 'critical', tag: 'shell/exec' },
+    { test: /postgres|mysql|mongo|sqlite|\bsql\b|database|\bdb\b|redis|snowflake|bigquery/i, level: 'critical', tag: 'database' },
+    { test: /stripe|payment|refund|payout|invoice|billing/i, level: 'critical', tag: 'payments' },
+    { test: /filesystem|file[-_]?system|\bfs\b|read[-_]?file|write[-_]?file/i, level: 'high', tag: 'filesystem' },
+    { test: /github|gitlab|bitbucket/i, level: 'high', tag: 'source-control' },
+    { test: /aws|gcp|azure|cloud|kubernetes|k8s|terraform/i, level: 'high', tag: 'cloud-infra' },
+    { test: /slack|email|gmail|smtp|sendgrid|twilio|notification/i, level: 'high', tag: 'messaging' },
+    { test: /browser|puppeteer|playwright|fetch|http[-_]?request|web[-_]?search/i, level: 'medium', tag: 'web/network' },
+    { test: /drive|gdrive|dropbox|s3|storage|notion|confluence/i, level: 'medium', tag: 'data-store' },
+];
+function scoreRisk(s) {
+    const hay = [s.serverName, s.command || '', ...(s.args || []), s.url || ''].join(' ');
+    const tags = [];
+    let level = 'low';
+    const order = { low: 0, medium: 1, high: 2, critical: 3 };
+    for (const rule of RISK_RULES) {
+        if (rule.test.test(hay)) {
+            tags.push(rule.tag);
+            if (order[rule.level] > order[level])
+                level = rule.level;
+        }
+    }
+    return { level, tags };
+}
+function parseConfigFile(filePath, source) {
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath, 'utf-8');
+    }
+    catch {
+        return [];
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return []; // settings.json with comments/JSONC — best-effort skip
+    }
+    const servers = extractServerMap(parsed);
+    const out = [];
+    for (const [name, cfgRaw] of Object.entries(servers)) {
+        const cfg = (cfgRaw || {});
+        const command = typeof cfg.command === 'string' ? cfg.command : undefined;
+        const args = Array.isArray(cfg.args) ? cfg.args.map(String) : undefined;
+        const url = typeof cfg.url === 'string' ? cfg.url : (typeof cfg.serverUrl === 'string' ? cfg.serverUrl : undefined);
+        const env = (cfg.env && typeof cfg.env === 'object') ? cfg.env : {};
+        const envKeys = Object.keys(env);
+        const transport = url
+            ? (/\/sse(\b|$)/.test(url) ? 'sse' : 'http')
+            : command ? 'stdio' : 'unknown';
+        const tools = Array.isArray(cfg.tools)
+            ? cfg.tools.map((t) => (typeof t === 'string' ? t : t?.name)).filter(Boolean).map(String)
+            : [];
+        const { level, tags } = scoreRisk({ serverName: name, command, args, url });
+        const warnings = [];
+        const blob = `${command || ''} ${(args || []).join(' ')} ${JSON.stringify(env)}`;
+        if (SECRET_VALUE.test(blob))
+            warnings.push('Hardcoded secret/API token detected in config (rotate + use env var).');
+        for (const [k, v] of Object.entries(env)) {
+            const val = String(v ?? '');
+            if (SECRET_KEY.test(k) && val && !/^\$\{?[A-Za-z0-9_]+\}?$/.test(val)) {
+                warnings.push(`Env "${k}" appears to contain a literal secret value.`);
+            }
+        }
+        out.push({
+            serverName: name,
+            command,
+            args,
+            url,
+            transport,
+            envKeys,
+            tools,
+            source,
+            configPath: filePath,
+            riskLevel: level,
+            riskTags: tags,
+            warnings,
+        });
+    }
+    return out;
+}
+/** Merge servers found in multiple files; keep richest record, union sources. */
+function dedupe(servers) {
+    const byName = new Map();
+    for (const s of servers) {
+        const existing = byName.get(s.serverName);
+        if (!existing) {
+            byName.set(s.serverName, { ...s, source: s.source });
+            continue;
+        }
+        if (!existing.source.includes(s.source))
+            existing.source += `, ${s.source}`;
+        existing.command = existing.command || s.command;
+        existing.url = existing.url || s.url;
+        existing.tools = Array.from(new Set([...existing.tools, ...s.tools]));
+        existing.warnings = Array.from(new Set([...existing.warnings, ...s.warnings]));
+    }
+    return [...byName.values()];
+}
+const COLOR = {
+    reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m',
+    red: '\x1b[31m', yellow: '\x1b[33m', green: '\x1b[32m', cyan: '\x1b[36m', gray: '\x1b[90m',
+};
+function riskColor(level) {
+    return level === 'critical' || level === 'high' ? COLOR.red : level === 'medium' ? COLOR.yellow : COLOR.green;
+}
+async function upload(servers, apiUrl, apiKey, connectorName) {
+    const payload = {
+        connectorName: connectorName || 'Local MCP discovery (CLI)',
+        servers: servers.map(s => ({
+            serverName: s.serverName,
+            command: s.command,
+            url: s.url,
+            tools: s.tools.map(name => ({ name })),
+        })),
+    };
+    const resp = await fetch(`${apiUrl.replace(/\/$/, '')}/api/cicd/discovery/mcp`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'X-API-Key': apiKey },
+        body: JSON.stringify(payload),
+    });
+    const data = await resp.json().catch(() => ({}));
+    if (!resp.ok || data.success === false) {
+        throw new Error(data.error || `Upload failed (${resp.status})`);
+    }
+    const ingested = data.data?.ingested ?? servers.length;
+    console.log(`${COLOR.green}Uploaded ${ingested} MCP server(s) to your AI Inventory.${COLOR.reset}`);
+}
+async function discoverCommand(args, config) {
+    const type = (args.type || 'mcp').toLowerCase();
+    if (type !== 'mcp') {
+        console.error(`Unsupported discover type "${type}". Supported: mcp`);
+        process.exit(1);
+    }
+    const cwd = process.cwd();
+    const candidates = candidateConfigPaths(cwd, args.extraPath);
+    const scanned = [];
+    let found = [];
+    for (const c of candidates) {
+        if (!fs.existsSync(c.path))
+            continue;
+        scanned.push(`${c.source} → ${c.path}`);
+        found.push(...parseConfigFile(c.path, c.source));
+    }
+    found = dedupe(found);
+    if (args.json === 'true') {
+        console.log(JSON.stringify({ scannedFiles: scanned, servers: found }, null, 2));
+        return;
+    }
+    console.log(`\n${COLOR.bold}${COLOR.cyan}MCP server discovery${COLOR.reset}`);
+    console.log(`${COLOR.gray}Scanned ${candidates.length} known config locations on this machine.${COLOR.reset}\n`);
+    if (scanned.length === 0) {
+        console.log(`${COLOR.yellow}No MCP config files found.${COLOR.reset}`);
+        console.log(`${COLOR.gray}Looked in Cursor, Claude Desktop, VS Code, Windsurf, and repo-root configs.${COLOR.reset}`);
+        return;
+    }
+    console.log(`${COLOR.bold}Config files found:${COLOR.reset}`);
+    for (const s of scanned)
+        console.log(`  ${COLOR.dim}•${COLOR.reset} ${s}`);
+    console.log('');
+    if (found.length === 0) {
+        console.log(`${COLOR.yellow}Config files exist but declare no MCP servers.${COLOR.reset}`);
+        return;
+    }
+    const order = { critical: 0, high: 1, medium: 2, low: 3 };
+    found.sort((a, b) => order[a.riskLevel] - order[b.riskLevel]);
+    console.log(`${COLOR.bold}${found.length} MCP server(s) discovered:${COLOR.reset}\n`);
+    for (const s of found) {
+        const col = riskColor(s.riskLevel);
+        const target = s.command ? `${s.command} ${(s.args || []).join(' ')}`.trim() : (s.url || 'unknown');
+        console.log(`  ${col}${COLOR.bold}[${s.riskLevel.toUpperCase()}]${COLOR.reset} ${COLOR.bold}${s.serverName}${COLOR.reset} ${COLOR.gray}(${s.transport})${COLOR.reset}`);
+        console.log(`        ${COLOR.gray}target:${COLOR.reset} ${target}`);
+        if (s.riskTags.length)
+            console.log(`        ${COLOR.gray}tags:${COLOR.reset} ${s.riskTags.join(', ')}`);
+        if (s.tools.length)
+            console.log(`        ${COLOR.gray}tools:${COLOR.reset} ${s.tools.slice(0, 12).join(', ')}${s.tools.length > 12 ? ' …' : ''}`);
+        console.log(`        ${COLOR.gray}from:${COLOR.reset} ${s.source}`);
+        for (const w of s.warnings)
+            console.log(`        ${COLOR.red}⚠ ${w}${COLOR.reset}`);
+        console.log('');
+    }
+    const counts = found.reduce((acc, s) => { acc[s.riskLevel] = (acc[s.riskLevel] || 0) + 1; return acc; }, {});
+    console.log(`${COLOR.bold}Summary:${COLOR.reset} ${counts.critical || 0} critical · ${counts.high || 0} high · ${counts.medium || 0} medium · ${counts.low || 0} low`);
+    if (args.upload === 'true') {
+        const apiKey = args.apiKey || config.apiKey || process.env.FULLCOURTDEFENSE_API_KEY;
+        const apiUrl = args.apiUrl || config.apiUrl || DEFAULT_API_URL;
+        if (!apiKey) {
+            console.error(`\n${COLOR.red}--upload requires an API key.${COLOR.reset} Set --api-key, FULLCOURTDEFENSE_API_KEY, or apiKey in config.`);
+            process.exit(1);
+        }
+        console.log('');
+        await upload(found, apiUrl, apiKey, args.connectorName);
+    }
+    else {
+        console.log(`${COLOR.gray}Run with --upload to push these into your AI Inventory.${COLOR.reset}`);
+    }
+}

package/dist/commands/hook.d.ts

@@ -0,0 +1,22 @@
+import { BotGuardConfig } from '../config';
+/**
+ * `fullcourtdefense hook` — Cursor hook bridge.
+ *
+ * Cursor invokes this command for agent lifecycle events (beforeSubmitPrompt,
+ * beforeShellExecution, beforeMCPExecution, afterFileEdit, ...). Cursor pipes a
+ * JSON payload on stdin and reads a JSON verdict on stdout. Exit code 2 also
+ * blocks the action, which we use as the cross-event, cross-version-safe block
+ * signal (not every event documents a `permission` output field).
+ *
+ * Verdict source of truth: POST {apiUrl}/api/shield/analyze/{shieldId}.
+ */
+export interface HookArgs {
+    event?: string;
+    apiUrl?: string;
+    shieldId?: string;
+    shieldKey?: string;
+    shadow?: string;
+    failClosed?: string;
+    timeout?: string;
+}
+export declare function hookCommand(args: HookArgs, config: BotGuardConfig): Promise<void>;