opena2a-cli 0.5.12 → 0.6.0

package/dist/commands/detect.js

@@ -2,8 +2,9 @@
 /**
  * opena2a detect -- Shadow AI Agent Audit
  *
- * Scans the local machine for running AI agents and MCP servers,
- * then reports their identity and governance status.
+ * Discovers AI agents running on this machine, MCP servers configured
+ * across all platforms, local LLM processes, and AI config files in the
+ * project. Reports identity, governance posture, and risk classification.
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -42,6 +43,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.scanProcesses = scanProcesses;
 exports.parseMcpConfig = parseMcpConfig;
 exports.scanMcpServers = scanMcpServers;
+exports.scanAiConfigs = scanAiConfigs;
 exports.scanIdentity = scanIdentity;
 exports.detect = detect;
 const node_child_process_1 = require("node:child_process");
@@ -49,26 +51,58 @@ const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const os = __importStar(require("node:os"));
 const colors_js_1 = require("../util/colors.js");
-/** Agent patterns to search for in the process list. */
+// ---------------------------------------------------------------------------
+// Agent patterns
+// ---------------------------------------------------------------------------
 const AGENT_PATTERNS = [
-    { name: 'Claude Code', patterns: [/\bclaude\b/i, /@anthropic-ai\/claude-code/i] },
-    { name: 'Cursor', patterns: [/\bcursor\b/i, /Cursor\.app/i] },
-    { name: 'GitHub Copilot', patterns: [/\bcopilot\b/i] },
-    { name: 'Windsurf', patterns: [/\bwindsurf\b/i, /Windsurf/] },
-    { name: 'Aider', patterns: [/\baider\b/i] },
-    { name: 'Continue', patterns: [/\bcontinue\b/i] },
-    { name: 'Cline', patterns: [/\bcline\b/i] },
+    // AI coding assistants
+    { name: 'Claude Code', category: 'ai-assistant', patterns: [/@anthropic-ai\/claude-code/i, /\bclaude\s*$/im, /\bclaude\s+/i] },
+    { name: 'Cursor', category: 'ai-assistant', patterns: [/Cursor\.app/i, /cursor-agent/i] },
+    { name: 'GitHub Copilot', category: 'ai-assistant', patterns: [/\bcopilot\b/i] },
+    { name: 'Windsurf', category: 'ai-assistant', patterns: [/Windsurf\.app/i, /windsurf-agent/i] },
+    { name: 'Aider', category: 'ai-assistant', patterns: [/\baider\b/] },
+    { name: 'Continue', category: 'ai-assistant', patterns: [/continue-server/i, /\bcontinue\.dev\b/i] },
+    { name: 'Cline', category: 'ai-assistant', patterns: [/\bcline\b/] },
+    { name: 'Amazon Q', category: 'ai-assistant', patterns: [/\bamazon-q\b/i, /\bq-developer\b/i] },
+    { name: 'Tabnine', category: 'ai-assistant', patterns: [/\btabnine\b/i] },
+    { name: 'Sourcegraph Cody', category: 'ai-assistant', patterns: [/\bcody\b/i, /sourcegraph.*cody/i] },
+    { name: 'Supermaven', category: 'ai-assistant', patterns: [/\bsupermaven\b/i] },
+    { name: 'Augment Code', category: 'ai-assistant', patterns: [/\baugment\b/i] },
+    // Local LLM runtimes
+    { name: 'Ollama', category: 'local-llm', patterns: [/\bollama\b/] },
+    { name: 'LM Studio', category: 'local-llm', patterns: [/lmstudio/i, /LM Studio/] },
+    { name: 'LocalAI', category: 'local-llm', patterns: [/\blocalai\b/i] },
+    { name: 'llama.cpp', category: 'local-llm', patterns: [/llama-server/i, /llama\.cpp/i, /\bllama-cli\b/i] },
+    { name: 'vLLM', category: 'local-llm', patterns: [/\bvllm\b/i] },
+    { name: 'Open WebUI', category: 'local-llm', patterns: [/open-webui/i] },
+    { name: 'GPT4All', category: 'local-llm', patterns: [/\bgpt4all\b/i] },
+    { name: 'Jan', category: 'local-llm', patterns: [/\bjan\.app\b/i, /Jan\.app/] },
 ];
 const MCP_CONFIG_LOCATIONS = [
-    { path: '.claude/mcp_servers.json', label: '~/.claude/mcp_servers.json' },
-    { path: '.cursor/mcp.json', label: '~/.cursor/mcp.json' },
-    { path: '.config/windsurf/mcp.json', label: '~/.config/windsurf/mcp.json' },
+    { path: '.claude/mcp_servers.json', label: 'Claude Code (global)' },
+    { path: '.cursor/mcp.json', label: 'Cursor (global)' },
+    { path: '.config/windsurf/mcp.json', label: 'Windsurf (global)' },
+    { path: '.vscode/globalStorage/saoudrizwan.claude-dev/mcp_servers.json', label: 'Cline (global)' },
 ];
 const PROJECT_MCP_FILES = ['mcp.json', '.mcp.json', '.mcp/config.json'];
-/**
- * Scan running processes for AI agents.
- * Runs a single `ps aux` and parses once.
- */
+// High-risk MCP capability keywords
+const HIGH_RISK_CAPABILITIES = ['execute', 'shell', 'bash', 'terminal', 'run', 'eval'];
+const MEDIUM_RISK_CAPABILITIES = ['filesystem', 'file', 'write', 'database', 'db', 'sql', 'network', 'http', 'fetch'];
+const AI_CONFIG_PATTERNS = [
+    { files: ['.cursorrules', '.cursor/config.json', '.cursor/rules'], tool: 'Cursor' },
+    { files: ['.claude/settings.json', '.claude/settings.local.json', 'CLAUDE.md'], tool: 'Claude Code' },
+    { files: ['.github/copilot-instructions.md', '.copilot'], tool: 'GitHub Copilot' },
+    { files: ['.windsurfrules', '.windsurf/config.json'], tool: 'Windsurf' },
+    { files: ['.aider.conf.yml', '.aiderignore'], tool: 'Aider' },
+    { files: ['.continue/config.json', '.continuerules'], tool: 'Continue' },
+    // SOUL.md is a governance file, not a risk config -- detected by scanIdentity() instead
+    { files: ['arp.config.yml', 'arp.config.yaml', '.opena2a/arp.config.yml'], tool: 'Agent Runtime Protection' },
+    { files: ['langchain.config.js', 'langchain.config.ts'], tool: 'LangChain' },
+    { files: ['.env.ai', 'ai.config.json', 'ai.config.yml'], tool: 'AI Framework' },
+];
+// ---------------------------------------------------------------------------
+// Process scanning
+// ---------------------------------------------------------------------------
 function scanProcesses(psOutput) {
     let output;
     if (psOutput !== undefined) {
@@ -89,10 +123,8 @@ function scanProcesses(psOutput) {
         for (const agent of AGENT_PATTERNS) {
             if (seen.has(agent.name))
                 continue;
-            const matches = agent.patterns.some((p) => p.test(line));
-            if (!matches)
+            if (!agent.patterns.some((p) => p.test(line)))
                 continue;
-            // Extract PID from ps aux output (second column)
             const parts = line.trim().split(/\s+/);
             const pid = parseInt(parts[1], 10);
             if (isNaN(pid))
@@ -100,25 +132,26 @@ function scanProcesses(psOutput) {
             agents.push({
                 name: agent.name,
                 pid,
+                category: agent.category,
                 identityStatus: 'no identity',
                 governanceStatus: 'no governance',
+                risk: agent.category === 'local-llm' ? 'medium' : 'high',
             });
             seen.add(agent.name);
         }
     }
     return agents;
 }
-/**
- * Parse an MCP config file and extract server entries.
- */
+// ---------------------------------------------------------------------------
+// MCP config parsing
+// ---------------------------------------------------------------------------
 function parseMcpConfig(filePath, label) {
     try {
         const content = fs.readFileSync(filePath, 'utf-8');
         const config = JSON.parse(content);
         const servers = [];
-        // MCP config can be { "mcpServers": { ... } } or { "servers": { ... } } or flat object
         const serversObj = config.mcpServers ?? config.servers ?? config;
-        if (typeof serversObj !== 'object' || serversObj === null)
+        if (typeof serversObj !== 'object' || serversObj === null || Array.isArray(serversObj))
             return [];
         for (const [name, entry] of Object.entries(serversObj)) {
             if (typeof entry !== 'object' || entry === null)
@@ -131,12 +164,10 @@ function parseMcpConfig(filePath, label) {
                 transport = 'sse';
             if (e.transport === 'stdio')
                 transport = 'stdio';
-            servers.push({
-                name,
-                transport,
-                source: label,
-                verified: false,
-            });
+            // Extract capabilities from server name and config
+            const capabilities = inferMcpCapabilities(name, e);
+            const risk = classifyMcpRisk(name, capabilities, transport);
+            servers.push({ name, transport, source: label, verified: false, capabilities, risk });
         }
         return servers;
     }
@@ -144,71 +175,197 @@ function parseMcpConfig(filePath, label) {
         return [];
     }
 }
-/**
- * Scan for MCP server config files.
- */
+/** Capability ID to plain-language description map. */
+const CAPABILITY_DESCRIPTIONS = {
+    'filesystem': 'Can read and write files on your machine',
+    'shell-access': 'Can run any command on your computer',
+    'database': 'Can read and modify your database',
+    'network': 'Can make requests to external services',
+    'browser': 'Can control a web browser and visit pages',
+    'source-control': 'Can read and push code to your repositories',
+    'messaging': 'Can send messages on your behalf',
+    'payments': 'Can access payment and billing systems',
+    'cloud-services': 'Can access your cloud infrastructure',
+    'unknown': 'Capabilities not determined',
+};
+function capabilityDescription(cap) {
+    return CAPABILITY_DESCRIPTIONS[cap] ?? cap;
+}
+function inferMcpCapabilities(name, config) {
+    const caps = [];
+    const nameLower = name.toLowerCase();
+    const args = Array.isArray(config.args) ? config.args.map(String) : [];
+    const command = typeof config.command === 'string' ? config.command : '';
+    const combined = `${nameLower} ${command} ${args.join(' ')}`.toLowerCase();
+    if (/filesys|file|fs\b/.test(combined))
+        caps.push('filesystem');
+    if (/shell|bash|terminal|exec/.test(combined))
+        caps.push('shell-access');
+    if (/database|db|sql|postgres|mysql|sqlite/.test(combined))
+        caps.push('database');
+    if (/network|http|fetch|curl|api/.test(combined))
+        caps.push('network');
+    if (/browser|playwright|puppeteer|selenium/.test(combined))
+        caps.push('browser');
+    if (/git\b|github|gitlab/.test(combined))
+        caps.push('source-control');
+    if (/slack|email|discord|teams/.test(combined))
+        caps.push('messaging');
+    if (/stripe|payment|billing/.test(combined))
+        caps.push('payments');
+    if (/supabase|firebase|cloud/.test(combined))
+        caps.push('cloud-services');
+    if (caps.length === 0)
+        caps.push('unknown');
+    return caps;
+}
+function classifyMcpRisk(name, capabilities, transport) {
+    const nameLower = name.toLowerCase();
+    // Shell/execute access is always critical
+    if (capabilities.includes('shell-access'))
+        return 'critical';
+    // Remote SSE servers with sensitive capabilities
+    if (transport === 'sse' && (capabilities.includes('database') || capabilities.includes('payments'))) {
+        return 'critical';
+    }
+    // Database or payment access
+    if (capabilities.includes('database') || capabilities.includes('payments'))
+        return 'high';
+    // Network or filesystem access
+    if (capabilities.includes('network') || capabilities.includes('filesystem'))
+        return 'medium';
+    // Known benign patterns
+    if (/\b(context7|greptile|serena)\b/.test(nameLower))
+        return 'low';
+    return 'medium';
+}
+// ---------------------------------------------------------------------------
+// Claude plugin MCP scanning
+// ---------------------------------------------------------------------------
+function scanClaudePluginMcpServers() {
+    const home = os.homedir();
+    const servers = [];
+    const pluginsBase = path.join(home, '.claude', 'plugins', 'marketplaces');
+    try {
+        const marketplaces = fs.readdirSync(pluginsBase, { withFileTypes: true });
+        for (const marketplace of marketplaces) {
+            if (!marketplace.isDirectory())
+                continue;
+            for (const subdir of ['external_plugins', 'plugins']) {
+                const dir = path.join(pluginsBase, marketplace.name, subdir);
+                try {
+                    const plugins = fs.readdirSync(dir, { withFileTypes: true });
+                    for (const plugin of plugins) {
+                        if (!plugin.isDirectory())
+                            continue;
+                        const mcpPath = path.join(dir, plugin.name, '.mcp.json');
+                        servers.push(...parseMcpConfig(mcpPath, `Claude plugin: ${plugin.name}`));
+                    }
+                }
+                catch { /* directory may not exist */ }
+            }
+        }
+    }
+    catch { /* plugins directory may not exist */ }
+    return servers;
+}
+// ---------------------------------------------------------------------------
+// MCP server scanning (all platforms)
+// ---------------------------------------------------------------------------
 function scanMcpServers(targetDir) {
     const home = os.homedir();
     const servers = [];
-    // Home-directory config locations
     for (const loc of MCP_CONFIG_LOCATIONS) {
-        const fullPath = path.join(home, loc.path);
-        servers.push(...parseMcpConfig(fullPath, loc.label));
+        servers.push(...parseMcpConfig(path.join(home, loc.path), loc.label));
     }
-    // VSCode MCP extensions -- scan ~/.vscode/extensions/*/mcp.json
+    servers.push(...scanClaudePluginMcpServers());
+    const claudeProjectMcp = path.join(home, '.claude', '.mcp.json');
+    servers.push(...parseMcpConfig(claudeProjectMcp, 'Claude Code (project)'));
     const vscodeExtDir = path.join(home, '.vscode', 'extensions');
     try {
         const entries = fs.readdirSync(vscodeExtDir, { withFileTypes: true });
         for (const entry of entries) {
             if (!entry.isDirectory())
                 continue;
-            const mcpPath = path.join(vscodeExtDir, entry.name, 'mcp.json');
-            servers.push(...parseMcpConfig(mcpPath, `~/.vscode/extensions/${entry.name}/mcp.json`));
+            servers.push(...parseMcpConfig(path.join(vscodeExtDir, entry.name, 'mcp.json'), `VS Code: ${entry.name}`));
         }
     }
-    catch {
-        // Directory may not exist
-    }
-    // Project-local MCP config files
+    catch { /* directory may not exist */ }
     for (const filename of PROJECT_MCP_FILES) {
-        const fullPath = path.join(targetDir, filename);
-        servers.push(...parseMcpConfig(fullPath, `${filename} (project)`));
+        servers.push(...parseMcpConfig(path.join(targetDir, filename), `${filename} (project)`));
     }
     return servers;
 }
-/**
- * Check for AIM identity and governance files.
- */
+// ---------------------------------------------------------------------------
+// AI config file discovery
+// ---------------------------------------------------------------------------
+function scanAiConfigs(targetDir) {
+    const configs = [];
+    for (const pattern of AI_CONFIG_PATTERNS) {
+        for (const file of pattern.files) {
+            const fullPath = path.join(targetDir, file);
+            if (!fs.existsSync(fullPath))
+                continue;
+            let details = `${pattern.tool} configuration`;
+            let risk = 'low';
+            // Check if it contains credential references
+            try {
+                const content = fs.readFileSync(fullPath, 'utf-8');
+                const hasApiKey = /(?:api[_-]?key|secret|token|password)\s*[:=]\s*["']?[a-zA-Z0-9_-]{20,}/i.test(content);
+                const hasPermissions = /(?:allow|permit|grant|unrestricted|all\s+bash)/i.test(content);
+                if (hasApiKey) {
+                    risk = 'critical';
+                    details = `${pattern.tool} config contains credential references`;
+                }
+                else if (hasPermissions) {
+                    risk = 'high';
+                    details = `${pattern.tool} config grants broad permissions`;
+                }
+                else {
+                    risk = 'low';
+                }
+            }
+            catch { /* file unreadable */ }
+            configs.push({ file, tool: pattern.tool, risk, details });
+        }
+    }
+    return configs;
+}
+// ---------------------------------------------------------------------------
+// Identity & governance scanning
+// ---------------------------------------------------------------------------
 function scanIdentity(targetDir) {
     let aimIdentities = 0;
     let mcpIdentities = 0;
     let soulFiles = 0;
     let capabilityPolicies = 0;
-    // Check for .opena2a/ directory in target dir only (project-scoped)
     const opena2aDir = path.join(targetDir, '.opena2a');
     if (fs.existsSync(opena2aDir)) {
+        // Check for actual AIM identity file in project
+        const identityFile = path.join(opena2aDir, 'aim', 'identity.json');
+        if (fs.existsSync(identityFile)) {
+            aimIdentities++;
+        }
+    }
+    // Also check global identity location (~/.opena2a/aim-core/identity.json)
+    // This is where `opena2a identity create` writes by default
+    const globalIdentity = path.join(os.homedir(), '.opena2a', 'aim-core', 'identity.json');
+    if (aimIdentities === 0 && fs.existsSync(globalIdentity)) {
         aimIdentities++;
-        // Count MCP server identities separately
+    }
+    if (fs.existsSync(opena2aDir)) {
         const mcpIdDir = path.join(opena2aDir, 'mcp-identities');
         if (fs.existsSync(mcpIdDir)) {
             try {
-                const files = fs.readdirSync(mcpIdDir).filter((f) => f.endsWith('.json'));
-                mcpIdentities = files.length;
+                mcpIdentities = fs.readdirSync(mcpIdDir).filter((f) => f.endsWith('.json')).length;
             }
             catch { /* ignore */ }
         }
     }
-    // Check for SOUL.md files
-    const soulPaths = [
-        path.join(targetDir, 'SOUL.md'),
-        path.join(targetDir, '.opena2a', 'SOUL.md'),
-    ];
-    for (const p of soulPaths) {
-        if (fs.existsSync(p)) {
+    for (const p of [path.join(targetDir, 'SOUL.md'), path.join(targetDir, '.opena2a', 'SOUL.md')]) {
+        if (fs.existsSync(p))
             soulFiles++;
-        }
     }
-    // Check for capability policy files
     const policyPaths = [
         path.join(targetDir, '.opena2a', 'policy.yml'),
         path.join(targetDir, '.opena2a', 'policy.yaml'),
@@ -217,85 +374,482 @@ function scanIdentity(targetDir) {
         path.join(targetDir, 'opena2a.policy.yaml'),
     ];
     for (const p of policyPaths) {
-        if (fs.existsSync(p)) {
+        if (fs.existsSync(p))
             capabilityPolicies++;
-        }
     }
     return { aimIdentities, mcpIdentities, totalAgents: 0, soulFiles, capabilityPolicies };
 }
+// ---------------------------------------------------------------------------
+// Risk scoring
+// ---------------------------------------------------------------------------
 /**
- * Format text output for the detect command.
+ * Calculate governance score (0-100, where 100 = fully governed).
+ *
+ * Internally computes deductions for gaps, then inverts:
+ *   governanceScore = 100 - deductions
+ *
+ * This way users see 100 as the goal and the score goes UP as they fix things.
  */
+function calculateGovernanceScore(result) {
+    let deductions = 0;
+    // Ungoverned agents: 15 points each
+    for (const agent of result.agents) {
+        if (agent.governanceStatus === 'no governance')
+            deductions += 15;
+        if (agent.identityStatus === 'no identity')
+            deductions += 10;
+    }
+    // Unverified MCP servers -- only project-local servers affect the score.
+    // Global/machine-wide servers (Claude plugins, ~/.cursor, etc.) are shown
+    // for awareness but don't penalize the project governance score because
+    // the user cannot verify them at the project level.
+    for (const server of result.mcpServers) {
+        if (server.verified)
+            continue;
+        const isProjectLocal = server.source.includes('(project)');
+        if (!isProjectLocal)
+            continue;
+        if (server.risk === 'critical')
+            deductions += 20;
+        else if (server.risk === 'high')
+            deductions += 12;
+        else if (server.risk === 'medium')
+            deductions += 5;
+        else
+            deductions += 2;
+    }
+    // AI config risk
+    for (const config of result.aiConfigs) {
+        if (config.risk === 'critical')
+            deductions += 25;
+        else if (config.risk === 'high')
+            deductions += 15;
+        else if (config.risk === 'medium')
+            deductions += 5;
+    }
+    // Governance gap: no AIM identity is a multiplier
+    if (result.identity.aimIdentities === 0 && result.agents.length > 0)
+        deductions += 20;
+    if (result.identity.soulFiles === 0 && result.agents.length > 0)
+        deductions += 10;
+    // Cap deductions at 100, round
+    deductions = Math.min(Math.round(deductions), 100);
+    return { governanceScore: 100 - deductions, deductions };
+}
+// ---------------------------------------------------------------------------
+// Finding generation
+// ---------------------------------------------------------------------------
+function generateFindings(result) {
+    const findings = [];
+    // No AIM identity -- recommend this first since identity is the foundation
+    const hasIdentity = result.identity.aimIdentities > 0;
+    if (!hasIdentity && result.agents.length > 0) {
+        findings.push({
+            severity: 'high',
+            category: 'identity',
+            title: 'No agent identity for this project',
+            detail: `${result.agents.length} AI tool${result.agents.length !== 1 ? 's' : ''} detected but no identity is registered`,
+            whyItMatters: 'An agent identity is a cryptographic key pair that lets you track which agent '
+                + 'did what in this project. Without one, agent actions cannot be attributed, verified, or '
+                + 'audited. This is the first step to managing AI tools in your project.',
+            remediation: 'opena2a identity create --name my-project',
+        });
+    }
+    // Ungoverned agents (consolidates governance + SOUL.md into one finding)
+    const ungoverned = result.agents.filter((a) => a.governanceStatus === 'no governance');
+    if (ungoverned.length > 0) {
+        const noSoul = result.identity.soulFiles === 0;
+        const detail = ungoverned.map((a) => a.name).join(', ')
+            + (noSoul ? ' -- no SOUL.md governance file found' : '');
+        findings.push({
+            severity: 'high',
+            category: 'governance',
+            title: `${ungoverned.length} AI agent${ungoverned.length !== 1 ? 's' : ''} running without governance`,
+            detail,
+            whyItMatters: 'These agents can take actions in your project but have no rules defining what they '
+                + 'should or should not do. A SOUL.md file sets behavioral boundaries — what agents can and '
+                + 'cannot do, and what requires human approval. Without one, agents rely entirely on their defaults.',
+            remediation: 'opena2a harden-soul',
+        });
+    }
+    // Project-local MCP servers with sensitive access (actionable -- affects score)
+    const projectCriticalMcp = result.mcpServers.filter((s) => s.risk === 'critical' && !s.verified && s.source.includes('(project)'));
+    if (projectCriticalMcp.length > 0) {
+        const details = projectCriticalMcp.map((s) => {
+            const caps = s.capabilities.filter((c) => c !== 'unknown');
+            const humanCaps = caps.map((c) => capabilityDescription(c).toLowerCase()).join(', ');
+            return `${s.name}: ${humanCaps}`;
+        });
+        findings.push({
+            severity: 'critical',
+            category: 'mcp',
+            title: `${projectCriticalMcp.length} project MCP server${projectCriticalMcp.length !== 1 ? 's' : ''} with sensitive access`,
+            detail: details.join('; '),
+            whyItMatters: 'These MCP servers are configured in your project and grant access to sensitive '
+                + 'operations like running commands, accessing databases, or processing payments. '
+                + 'Verifying them confirms they are the servers you intended to install.',
+            remediation: 'opena2a mcp audit',
+        });
+    }
+    // Project-local unverified MCP servers
+    const projectUnverified = result.mcpServers.filter((s) => !s.verified && s.source.includes('(project)'));
+    if (projectUnverified.length > 0 && projectCriticalMcp.length === 0) {
+        findings.push({
+            severity: 'medium',
+            category: 'mcp',
+            title: `${projectUnverified.length} project MCP server${projectUnverified.length !== 1 ? 's' : ''} without verified identity`,
+            detail: 'These servers are configured in your project but have not been signed.',
+            whyItMatters: 'Unverified servers could be modified or replaced without detection. '
+                + 'Signing creates a tamper-evident record of exactly which server version is in use.',
+            remediation: 'opena2a mcp audit',
+        });
+    }
+    // Config files with credential references
+    const criticalConfigs = result.aiConfigs.filter((c) => c.risk === 'critical');
+    if (criticalConfigs.length > 0) {
+        findings.push({
+            severity: 'critical',
+            category: 'config',
+            title: 'AI config files contain credential references',
+            detail: criticalConfigs.map((c) => c.file).join(', '),
+            whyItMatters: 'API keys or tokens appear to be stored directly in these configuration files. '
+                + 'Anyone with access to the file (or the repository) can see and use these credentials. '
+                + 'Moving them to environment variables limits exposure.',
+            remediation: 'opena2a protect',
+        });
+    }
+    // Broad permission grants
+    const highConfigs = result.aiConfigs.filter((c) => c.risk === 'high');
+    if (highConfigs.length > 0) {
+        findings.push({
+            severity: 'high',
+            category: 'config',
+            title: 'AI config files grant broad permissions',
+            detail: highConfigs.map((c) => c.file).join(', '),
+            whyItMatters: 'These configs allow AI agents to perform a wide range of actions without '
+                + 'restrictions. Broad permissions increase the surface area if an agent behaves '
+                + 'unexpectedly or if the config is modified by a third party.',
+            remediation: 'opena2a scan-soul',
+        });
+    }
+    // No SOUL governance (only if agents ARE governed but SOUL is missing --
+    // if ungoverned, the governance finding above already covers SOUL.md)
+    if (result.identity.soulFiles === 0 && result.agents.length > 0 && ungoverned.length === 0) {
+        findings.push({
+            severity: 'medium',
+            category: 'governance',
+            title: 'No SOUL.md governance file in this project',
+            detail: 'Agents are governed by capability policies but have no SOUL.md behavioral boundaries.',
+            whyItMatters: 'A SOUL.md file defines what an agent should and should not do beyond capability '
+                + 'restrictions — handling errors, sensitive data, and when to ask for human approval.',
+            remediation: 'opena2a harden-soul',
+        });
+    }
+    // Sort by severity
+    const order = { critical: 0, high: 1, medium: 2, low: 3 };
+    findings.sort((a, b) => order[a.severity] - order[b.severity]);
+    return findings;
+}
+// ---------------------------------------------------------------------------
+// CSV export -- asset inventory for enterprise tools (ServiceNow, CMDB, etc.)
+// ---------------------------------------------------------------------------
+function csvEscape(value) {
+    if (value.includes(',') || value.includes('"') || value.includes('\n')) {
+        return `"${value.replace(/"/g, '""')}"`;
+    }
+    return value;
+}
+function generateAssetCsv(result) {
+    const rows = [];
+    const hostname = os.hostname();
+    const username = os.userInfo().username;
+    const scanTime = result.scanTimestamp;
+    const scanDir = result.scanDirectory;
+    // Header -- columns designed for enterprise CMDB/ServiceNow import
+    rows.push('Hostname,Username,Scan Directory,Scan Timestamp,Asset Type,Name,Installed From,Transport,Capabilities,Risk');
+    const deviceCols = [csvEscape(hostname), csvEscape(username), csvEscape(scanDir), scanTime].join(',');
+    // AI Agents
+    for (const agent of result.agents) {
+        rows.push([
+            deviceCols,
+            'AI Agent',
+            csvEscape(agent.name),
+            'Running process',
+            '',
+            agent.category,
+            agent.risk,
+        ].join(','));
+    }
+    // MCP Servers
+    for (const server of result.mcpServers) {
+        const caps = server.capabilities.filter((c) => c !== 'unknown');
+        const isProjectLocal = server.source.includes('(project)');
+        const scope = isProjectLocal ? 'This project' : 'User machine';
+        rows.push([
+            deviceCols,
+            'MCP Server',
+            csvEscape(server.name),
+            scope,
+            server.transport,
+            csvEscape(caps.map((c) => capabilityDescription(c)).join('; ')),
+            server.risk,
+        ].join(','));
+    }
+    // AI Config Files
+    for (const config of result.aiConfigs) {
+        rows.push([
+            deviceCols,
+            'AI Config',
+            csvEscape(config.file),
+            csvEscape(config.tool),
+            '',
+            csvEscape(config.details),
+            config.risk,
+        ].join(','));
+    }
+    return rows.join('\n') + '\n';
+}
+// ---------------------------------------------------------------------------
+// Text formatting
+// ---------------------------------------------------------------------------
+function riskColor(level) {
+    switch (level) {
+        case 'critical': return colors_js_1.red;
+        case 'high': return (t) => `\x1b[38;5;208m${t}\x1b[39m`; // orange
+        case 'medium': return colors_js_1.yellow;
+        case 'low': return colors_js_1.green;
+    }
+}
+function riskLabel(level) {
+    return riskColor(level)(level.toUpperCase());
+}
+function buildSummaryLine(result) {
+    const { summary } = result;
+    const parts = [];
+    if (summary.totalAgents === 0 && summary.mcpServers === 0 && summary.aiConfigs === 0) {
+        return (0, colors_js_1.dim)('No AI agents, MCP servers, or AI configs detected.');
+    }
+    if (summary.totalAgents > 0) {
+        parts.push(`${(0, colors_js_1.bold)(String(summary.totalAgents))} AI agent${summary.totalAgents !== 1 ? 's' : ''}`);
+    }
+    if (summary.mcpServers > 0) {
+        parts.push(`${(0, colors_js_1.bold)(String(summary.mcpServers))} MCP server${summary.mcpServers !== 1 ? 's' : ''}`);
+    }
+    if (summary.aiConfigs > 0) {
+        parts.push(`${(0, colors_js_1.bold)(String(summary.aiConfigs))} AI config${summary.aiConfigs !== 1 ? 's' : ''}`);
+    }
+    if (summary.localLlms > 0) {
+        parts.push(`${(0, colors_js_1.bold)(String(summary.localLlms))} local LLM${summary.localLlms !== 1 ? 's' : ''}`);
+    }
+    return parts.join(' | ');
+}
+/**
+ * Build the governance score summary with recovery framing.
+ * 100 = fully governed (the goal), 0 = nothing in place.
+ *
+ *   "Governance: 35/100 -> 82/100 by addressing 3 findings"
+ */
+function buildGovernanceSummary(result) {
+    const { summary } = result;
+    const score = summary.governanceScore;
+    if (score === 100) {
+        return (0, colors_js_1.green)('Governance: 100/100 -- fully governed');
+    }
+    const scoreColor = score >= 70 ? colors_js_1.green : score >= 40 ? colors_js_1.yellow : colors_js_1.red;
+    const projected = Math.min(100, score + summary.recoverablePoints);
+    let line = `Governance: ${scoreColor((0, colors_js_1.bold)(String(score)))}/100`;
+    if (result.findings.length > 0 && projected > score) {
+        line += ` -> ${(0, colors_js_1.green)((0, colors_js_1.bold)(String(projected)))}/100 by addressing ${result.findings.length} finding${result.findings.length !== 1 ? 's' : ''}`;
+    }
+    return line;
+}
+/**
+ * Build a plain-language explanation of what was found, for people
+ * who do not think in security terminology.
+ */
+function buildWhatThisMeans(result) {
+    const lines = [];
+    const { summary } = result;
+    if (summary.totalAgents === 0 && summary.mcpServers === 0)
+        return lines;
+    lines.push((0, colors_js_1.bold)('What This Means'));
+    // Explain agent detection
+    if (summary.totalAgents > 0) {
+        const governed = summary.totalAgents - summary.ungoverned;
+        if (summary.ungoverned === 0) {
+            lines.push(`  Your ${summary.totalAgents === 1 ? 'AI agent has' : 'AI agents have'} `
+                + `governance in place. Actions are bounded by the rules you defined.`);
+        }
+        else if (governed > 0) {
+            lines.push(`  ${summary.totalAgents} AI tool${summary.totalAgents !== 1 ? 's are' : ' is'} running on this machine. `
+                + `${governed} ${governed === 1 ? 'has' : 'have'} governance rules, `
+                + `${summary.ungoverned} ${summary.ungoverned === 1 ? 'does' : 'do'} not.`);
+        }
+        else {
+            lines.push(`  ${summary.totalAgents} AI tool${summary.totalAgents !== 1 ? 's are' : ' is'} running `
+                + `without governance. This means there are no documented rules limiting what `
+                + `${summary.totalAgents === 1 ? 'it' : 'they'} can do in this project.`);
+        }
+    }
+    // Explain MCP servers
+    if (summary.mcpServers > 0) {
+        const verified = summary.mcpServers - summary.unverifiedServers;
+        lines.push(`  ${summary.mcpServers} MCP server${summary.mcpServers !== 1 ? 's give' : ' gives'} your AI agents `
+            + `additional capabilities (file access, database queries, API calls, etc.).`);
+        if (summary.unverifiedServers > 0 && verified > 0) {
+            lines.push(`  ${verified} ${verified === 1 ? 'has' : 'have'} verified identities, `
+                + `${summary.unverifiedServers} ${summary.unverifiedServers === 1 ? 'does' : 'do'} not.`);
+        }
+        else if (summary.unverifiedServers === summary.mcpServers) {
+            lines.push(`  None have verified identities, so there is no tamper-evident record of `
+                + `which server version is installed.`);
+        }
+    }
+    lines.push('');
+    return lines;
+}
 function formatText(result, verbose, targetDir) {
     const lines = [];
+    // Header with machine context
     lines.push((0, colors_js_1.bold)('Shadow AI Agent Audit'));
-    lines.push('=====================');
+    lines.push((0, colors_js_1.dim)(`${os.hostname()} | ${os.userInfo().username} | ${targetDir}`));
+    lines.push((0, colors_js_1.dim)(result.scanTimestamp.replace('T', ' ').replace(/\.\d+Z$/, ' UTC')));
+    lines.push('');
+    // Score and summary -- the only thing a Sr. Manager reads
+    lines.push(buildGovernanceSummary(result));
+    lines.push(buildSummaryLine(result));
     lines.push('');
-    // Running AI Agents
+    // What This Means (plain-language overview for non-security audience)
+    lines.push(...buildWhatThisMeans(result));
+    // Findings -- the actionable part, front and center
+    if (result.findings.length > 0) {
+        lines.push((0, colors_js_1.bold)(`Findings (${result.findings.length})`));
+        for (const finding of result.findings) {
+            lines.push('');
+            lines.push(`  ${riskLabel(finding.severity)}  ${finding.title}`);
+            if (finding.detail) {
+                lines.push(`  ${(0, colors_js_1.dim)(finding.detail)}`);
+            }
+            lines.push(`  ${finding.whyItMatters}`);
+            lines.push(`  ${(0, colors_js_1.dim)('Fix:')} ${(0, colors_js_1.cyan)(finding.remediation)}`);
+        }
+        lines.push('');
+    }
+    // All clear
+    if (result.findings.length === 0) {
+        lines.push((0, colors_js_1.green)('All detected AI tools have governance in place. No findings.'));
+        lines.push('');
+    }
+    // Running AI Agents -- compact, no PIDs unless verbose
+    const assistants = result.agents.filter((a) => a.category === 'ai-assistant');
+    const llms = result.agents.filter((a) => a.category === 'local-llm');
     lines.push((0, colors_js_1.bold)('Running AI Agents'));
-    if (result.agents.length === 0) {
-        lines.push((0, colors_js_1.dim)('  No AI agents detected in running processes'));
+    if (assistants.length === 0 && llms.length === 0) {
+        lines.push((0, colors_js_1.dim)('  No AI agents detected'));
     }
     else {
-        for (const agent of result.agents) {
-            const nameCol = agent.name.padEnd(20);
-            const pidCol = `PID ${agent.pid}`.padEnd(13);
-            const idStatus = agent.identityStatus === 'identified'
-                ? (0, colors_js_1.green)(agent.identityStatus)
-                : (0, colors_js_1.yellow)(agent.identityStatus);
-            const govStatus = agent.governanceStatus === 'governed'
-                ? (0, colors_js_1.green)(agent.governanceStatus)
-                : (0, colors_js_1.yellow)(agent.governanceStatus);
-            lines.push(`  ${nameCol}${pidCol}${idStatus}    ${govStatus}`);
+        for (const agent of [...assistants, ...llms]) {
+            const nameCol = agent.name.padEnd(22);
+            const idStatus = agent.identityStatus === 'identified' ? (0, colors_js_1.green)('identified') : (0, colors_js_1.yellow)('no identity');
+            const govStatus = agent.governanceStatus === 'governed' ? (0, colors_js_1.green)('governed') : (0, colors_js_1.yellow)('ungoverned');
+            const pidStr = verbose ? (0, colors_js_1.dim)(` (PID ${agent.pid})`) : '';
+            lines.push(`  ${nameCol}${idStatus}    ${govStatus}${pidStr}`);
         }
     }
     lines.push('');
-    // MCP Servers
+    // Identity & Governance details are omitted from default output.
+    // The governance score and findings already communicate everything actionable.
+    // Show only in verbose mode for debugging.
+    if (verbose) {
+        lines.push((0, colors_js_1.bold)('Identity & Governance'));
+        lines.push(`  Project identity:     ${result.identity.aimIdentities > 0 ? (0, colors_js_1.green)('initialized (.opena2a/)') : (0, colors_js_1.yellow)('not initialized')}`);
+        lines.push(`  Behavioral rules:     ${result.identity.soulFiles === 0 ? (0, colors_js_1.yellow)('none') : (0, colors_js_1.green)(`${result.identity.soulFiles} SOUL.md`)}`);
+        if (result.identity.mcpIdentities > 0) {
+            lines.push(`  MCP identities:       ${(0, colors_js_1.green)(`${result.identity.mcpIdentities} server(s) signed`)}`);
+        }
+        lines.push('');
+    }
+    // MCP Servers -- show summary in default mode, full list in verbose
     const mcpCount = result.mcpServers.length;
+    const projectMcp = result.mcpServers.filter((s) => s.source.includes('(project)'));
+    const globalMcp = result.mcpServers.filter((s) => !s.source.includes('(project)'));
     lines.push((0, colors_js_1.bold)(`MCP Servers (${mcpCount} found)`));
     if (mcpCount === 0) {
         lines.push((0, colors_js_1.dim)('  No MCP server configurations found'));
     }
     else {
-        for (const server of result.mcpServers) {
-            const nameCol = server.name.padEnd(20);
-            const transportCol = server.transport.padEnd(9);
-            const sourceCol = server.source.padEnd(40);
-            const verifiedLabel = server.verified
-                ? (0, colors_js_1.green)('verified')
-                : (0, colors_js_1.dim)('not verified');
-            lines.push(`  ${nameCol}${transportCol}${sourceCol}${verifiedLabel}`);
+        // Always show project-local MCP servers with capabilities (these are actionable)
+        if (projectMcp.length > 0) {
+            lines.push(`  ${(0, colors_js_1.bold)('Project-local')} (${projectMcp.length})`);
+            const riskOrder = { critical: 0, high: 1, medium: 2, low: 3 };
+            projectMcp.sort((a, b) => riskOrder[a.risk] - riskOrder[b.risk]);
+            for (const server of projectMcp) {
+                const nameCol = server.name.padEnd(20);
+                const verifiedStr = server.verified ? (0, colors_js_1.green)(' verified') : '';
+                const realCaps = server.capabilities.filter((c) => c !== 'unknown');
+                const capsStr = realCaps.length > 0
+                    ? (0, colors_js_1.dim)(` -- ${realCaps.map((c) => capabilityDescription(c).toLowerCase()).join(', ')}`)
+                    : '';
+                lines.push(`    ${nameCol}${verifiedStr}${capsStr}`);
+            }
+        }
+        // Show global MCP servers as a compact summary (not individually unless verbose)
+        if (globalMcp.length > 0) {
+            if (verbose) {
+                lines.push(`  ${(0, colors_js_1.bold)('Machine-wide')} (${globalMcp.length})`);
+                for (const server of globalMcp) {
+                    const nameCol = server.name.padEnd(20);
+                    const realCaps = server.capabilities.filter((c) => c !== 'unknown');
+                    const capsStr = realCaps.length > 0
+                        ? (0, colors_js_1.dim)(` -- ${realCaps.map((c) => capabilityDescription(c).toLowerCase()).join(', ')}`)
+                        : '';
+                    lines.push(`    ${nameCol}${capsStr}`);
+                }
+            }
+            else {
+                // Compact: just show the count and which ones have sensitive access
+                const sensitiveCaps = globalMcp.filter((s) => s.capabilities.some((c) => ['shell-access', 'database', 'payments', 'cloud-services'].includes(c)));
+                let globalLine = `  ${(0, colors_js_1.dim)(`Machine-wide (${globalMcp.length})`)}`;
+                if (sensitiveCaps.length > 0) {
+                    const names = sensitiveCaps.map((s) => s.name).join(', ');
+                    globalLine += (0, colors_js_1.dim)(` -- ${sensitiveCaps.length} with sensitive access: ${names}`);
+                }
+                lines.push(globalLine);
+                lines.push((0, colors_js_1.dim)(`    Run with --verbose to see full list`));
+            }
         }
     }
     lines.push('');
-    // Identity Status
-    lines.push((0, colors_js_1.bold)('Identity Status'));
-    const aimLabel = result.identity.aimIdentities > 0 ? (0, colors_js_1.green)('initialized') : (0, colors_js_1.yellow)('not initialized');
-    lines.push(`  AIM project:          ${aimLabel}`);
-    if (result.identity.mcpIdentities > 0) {
-        lines.push(`  MCP identities:       ${result.identity.mcpIdentities} server(s) signed`);
-    }
-    lines.push(`  Governance files:     ${result.identity.soulFiles === 0 ? 'none' : `${result.identity.soulFiles} SOUL.md found`}`);
-    lines.push(`  Capability policies:  ${result.identity.capabilityPolicies === 0 ? 'none' : String(result.identity.capabilityPolicies)}`);
-    lines.push('');
-    // Next Steps
-    lines.push((0, colors_js_1.bold)('Next Steps'));
-    lines.push(`  ${(0, colors_js_1.cyan)('opena2a identity create --name my-agent')}    Create an agent identity`);
-    lines.push(`  ${(0, colors_js_1.cyan)('opena2a init')}                               Initialize security posture`);
-    lines.push(`  ${(0, colors_js_1.cyan)('opena2a scan-soul')}                          Scan governance coverage`);
-    if (verbose) {
-        lines.push('');
-        lines.push((0, colors_js_1.dim)('Detection methods: process list (ps aux), MCP config files, AIM identity directories'));
-        lines.push((0, colors_js_1.dim)(`Target directory: ${targetDir}`));
+    // AI Config Files -- only show if there are noteworthy ones
+    const noteworthyConfigs = result.aiConfigs.filter((c) => c.risk !== 'low');
+    if (result.aiConfigs.length > 0) {
+        if (noteworthyConfigs.length > 0 || verbose) {
+            lines.push((0, colors_js_1.bold)(`AI Config Files (${result.aiConfigs.length} found)`));
+            const configsToShow = verbose ? result.aiConfigs : noteworthyConfigs;
+            for (const config of configsToShow) {
+                const fileCol = config.file.padEnd(35);
+                const toolCol = config.tool;
+                lines.push(`  ${fileCol}${toolCol}`);
+                if (config.risk === 'critical') {
+                    lines.push(`    ${(0, colors_js_1.yellow)('Contains credential references -- these should be in environment variables')}`);
+                }
+                else if (config.risk === 'high') {
+                    lines.push(`    ${(0, colors_js_1.yellow)('Grants broad permissions to AI agents in this project')}`);
+                }
+            }
+            if (!verbose && result.aiConfigs.length > noteworthyConfigs.length) {
+                lines.push((0, colors_js_1.dim)(`  + ${result.aiConfigs.length - noteworthyConfigs.length} low-risk config(s) -- run with --verbose to see all`));
+            }
+            lines.push('');
+        }
     }
     return lines.join('\n');
 }
-/**
- * Main detect command entry point.
- */
+// ---------------------------------------------------------------------------
+// Main entry point
+// ---------------------------------------------------------------------------
 async function detect(options) {
-    const dir = options.targetDir ?? process.cwd();
-    // Validate directory
+    const dir = path.resolve(options.targetDir ?? process.cwd());
     try {
         fs.accessSync(dir, fs.constants.R_OK);
     }
@@ -307,29 +861,84 @@ async function detect(options) {
     const agents = scanProcesses();
     const mcpServers = scanMcpServers(dir);
     const identity = scanIdentity(dir);
-    // Update totalAgents count
+    const aiConfigs = scanAiConfigs(dir);
     identity.totalAgents = agents.length;
-    // Enrich agents with identity info if .opena2a exists in target dir
+    // Enrich agents with identity/governance from project context
     if (identity.aimIdentities > 0) {
-        // Mark agents as identified if AIM identity exists in the project
-        // In a real implementation, this would match agent names to identities
+        for (const agent of agents) {
+            agent.identityStatus = 'identified';
+            agent.risk = agent.risk === 'high' ? 'medium' : agent.risk;
+        }
+    }
+    if (identity.soulFiles > 0 || identity.capabilityPolicies > 0) {
+        for (const agent of agents) {
+            agent.governanceStatus = 'governed';
+            agent.risk = 'low';
+        }
     }
-    // Enrich MCP servers with signing status from .opena2a/mcp-identities/
+    // Enrich MCP servers with signing status
     const mcpIdDir = path.join(dir, '.opena2a', 'mcp-identities');
     if (fs.existsSync(mcpIdDir)) {
         for (const server of mcpServers) {
             const idFile = path.join(mcpIdDir, `${server.name}.json`);
             if (fs.existsSync(idFile)) {
                 server.verified = true;
+                server.risk = 'low';
             }
         }
     }
-    const result = { agents, mcpServers, identity };
+    // Calculate governance score
+    const partialResult = { scanTimestamp: new Date().toISOString(), scanDirectory: dir, agents, mcpServers, aiConfigs, identity };
+    const { governanceScore, deductions } = calculateGovernanceScore(partialResult);
+    const ungoverned = agents.filter((a) => a.governanceStatus === 'no governance').length;
+    const unverifiedServers = mcpServers.filter((s) => !s.verified).length;
+    const localLlms = agents.filter((a) => a.category === 'local-llm').length;
+    const result = {
+        scanTimestamp: new Date().toISOString(),
+        scanDirectory: dir,
+        summary: {
+            totalAgents: agents.length,
+            ungoverned,
+            mcpServers: mcpServers.length,
+            unverifiedServers,
+            localLlms,
+            aiConfigs: aiConfigs.length,
+            governanceScore,
+            // All deductions are recoverable -- every deduction maps to a finding
+            // with an actionable fix. Addressing all findings reaches 100/100.
+            recoverablePoints: deductions,
+        },
+        agents,
+        mcpServers,
+        aiConfigs,
+        identity,
+        findings: [],
+    };
+    result.findings = generateFindings(result);
     if (options.format === 'json') {
         process.stdout.write(JSON.stringify(result, null, 2) + '\n');
-        return 0;
     }
-    process.stdout.write(formatText(result, options.verbose ?? false, dir) + '\n');
+    else {
+        process.stdout.write(formatText(result, options.verbose ?? false, dir) + '\n');
+    }
+    // Generate HTML report if requested
+    if (options.reportPath) {
+        const { generateDetectHtml } = await import('../report/detect-html.js');
+        const html = generateDetectHtml(result);
+        fs.writeFileSync(options.reportPath, html, 'utf-8');
+        if (!options.ci) {
+            const { exec } = await import('node:child_process');
+            const openCmd = os.platform() === 'darwin' ? 'open' : os.platform() === 'win32' ? 'start' : 'xdg-open';
+            exec(`${openCmd} "${options.reportPath}"`);
+        }
+        process.stdout.write(`Report: ${options.reportPath}\n`);
+    }
+    // Export CSV asset inventory if requested
+    if (options.exportCsv) {
+        const csv = generateAssetCsv(result);
+        fs.writeFileSync(options.exportCsv, csv, 'utf-8');
+        process.stdout.write(`Asset inventory: ${options.exportCsv}\n`);
+    }
     return 0;
 }
 //# sourceMappingURL=detect.js.map