hackmyagent 0.16.4 → 0.16.7

package/dist/cli.js

@@ -46,7 +46,9 @@ const program = new commander_1.Command();
 program.showHelpAfterError('(run with --help for usage)');
 // Total security check count across all scanner modules.
 // Update when adding new checks (verify with: grep -r "checkId:" src/hardening/ | grep -o "checkId: '[^']*'" | sort -u | wc -l)
-const CHECK_COUNT = 208;
+const CHECK_COUNT = 209;
+// How long registry-cached scan data is considered fresh before `check` re-scans.
+const STALE_SCAN_DAYS = 3;
 // Write a string to stdout synchronously with retry for pipe backpressure.
 // process.stdout.write() is async and gets truncated when process.exit()
 // runs before the stream flushes. fs.writeFileSync(1, ...) can fail with
@@ -171,17 +173,21 @@ program
     .description(`Check if a package, repo, or skill is safe
 
 Accepts npm packages, GitHub repos, local paths, or skill identifiers:
-  • npm package: downloads and runs full security analysis (${CHECK_COUNT} checks + NanoMind)
-  • GitHub repo: shallow clones and runs full security analysis
+  • npm package: queries the registry; downloads + scans (${CHECK_COUNT} checks + NanoMind) if data is missing or stale (>${STALE_SCAN_DAYS}d)
+  • PyPI package: downloads + scans (${CHECK_COUNT} checks + NanoMind)
+  • GitHub repo: queries the registry; shallow clones + scans if data is missing or stale (>${STALE_SCAN_DAYS}d)
   • Local path: runs NanoMind semantic analysis
   • Skill identifier: verifies publisher, permissions, revocation
 
+Use --rescan to skip the registry cache and force a fresh local scan.
+
 Risk levels: low, medium, high, critical
 Exit code 1 if high/critical risk detected.
 
 Examples:
   $ hackmyagent check express
   $ hackmyagent check @modelcontextprotocol/server-filesystem
+  $ hackmyagent check @sentry/mcp-server --rescan
   $ hackmyagent check modelcontextprotocol/servers
   $ hackmyagent check https://github.com/punkpeye/awesome-mcp-servers
   $ hackmyagent check ./my-agent/
@@ -195,6 +201,7 @@ Examples:
     .option('-v, --verbose', 'Show detailed verification info')
     .option('--json', 'Output as JSON (for scripting/CI)')
     .option('--offline', 'Skip DNS verification (offline mode)')
+    .option('--rescan', 'Force a fresh local scan, bypassing cached registry data')
     .action(async (skill, options) => {
     try {
         // Detect local file/directory paths - run NanoMind scan instead of registry lookup
@@ -245,6 +252,7 @@ Examples:
                     console.log(`\n  ... and ${issues.length - 10} more`);
                 console.log();
             }
+            printCheckNextSteps(resolved);
             if (risk === 'critical' || risk === 'high')
                 process.exit(1);
             return;
@@ -269,12 +277,17 @@ Examples:
             await checkNpmPackage(skill, options);
             return;
         }
+        // --rescan only applies to targets that otherwise hit the registry cache.
+        // For skill identifiers we fall through to the registry lookup below.
+        if (options.rescan && !options.json) {
+            console.error(`Note: --rescan has no effect on skill identifiers; it applies to npm/PyPI/GitHub targets.`);
+        }
         // Registry lookup path (non-local identifier) with 10s timeout
         const checkPromise = (0, index_1.checkSkill)(skill, {
             skipDnsVerification: options.offline,
         });
         const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error(`Timed out verifying "${skill}" (10s). The publisher may not exist or DNS is unreachable.\n` +
-            `Try: ${CLI_PREFIX.replace(' scan', '')} check ${skill} --offline`)), 10000));
+            `Try: ${getCheckCommand()} ${skill} --offline`)), 10000));
         const result = await Promise.race([checkPromise, timeoutPromise]);
         if (options.json) {
             writeJsonStdout(result);
@@ -2869,7 +2882,7 @@ Examples:
         const customPorts = options.ports
             ? options.ports.split(',').map((p) => parseInt(p.trim(), 10))
             : undefined;
-        const portCount = customPorts?.length ?? 11;
+        const portCount = customPorts?.length ?? 5;
         if (!options.json) {
             console.log(`\nScanning ${target} (${portCount} ports, ${timeoutMs}ms timeout)...\n`);
         }
@@ -5300,9 +5313,46 @@ program
         console.log(`${checkId}: ${explanation}`);
     }
     else {
-        console.log(`No explanation available for ${findingId}.`);
-        if (!available) {
-            console.log(`\nFor dynamic explanations, install NanoMind: npm install -g @nanomind/cli && nanomind-daemon start`);
+        // Fallback: generate explanation from taxonomy metadata
+        const { getAttackClass } = require('./hardening/taxonomy');
+        const attackClass = getAttackClass(checkId);
+        // Map check ID prefixes to human-readable category descriptions
+        const prefixDescriptions = {
+            'CRED': 'Credential exposure',
+            'MCP': 'MCP server configuration',
+            'SKILL': 'Skill package security',
+            'GOV': 'Governance policy',
+            'PERM': 'Permission scope',
+            'SOUL': 'Behavioral governance (SOUL.md)',
+            'PRIV': 'Privacy and data handling',
+            'DATA': 'Data protection',
+            'INJECT': 'Prompt injection defense',
+            'ATTEST': 'Agent attestation',
+            'SUPPLY': 'Supply chain security',
+            'NET': 'Network security',
+            'GIT': 'Git repository hygiene',
+            'PROMPT': 'Prompt security',
+            'NEMO': 'Static analysis pattern',
+            'LIFECYCLE': 'Prompt assembly lifecycle',
+            'AST': 'Deep code analysis',
+            'ENCRYPT': 'Encryption and hashing',
+            'LOG': 'Logging and audit',
+            'AUTH': 'Authentication',
+            'TOOL': 'Tool permission and safety',
+        };
+        const prefix = checkId.split('-')[0];
+        const categoryDesc = prefixDescriptions[prefix];
+        if (attackClass || categoryDesc) {
+            console.log(`${checkId}: ${categoryDesc || 'Security check'}.`);
+            if (attackClass) {
+                console.log(`  Attack class: ${attackClass}`);
+            }
+            console.log(`\n  Run 'hackmyagent secure --verbose' to see this check in context with fix guidance.`);
+            console.log(`  Run 'hackmyagent check-metadata --json' for full check details.`);
+        }
+        else {
+            console.log(`No explanation available for ${findingId}. This may not be a valid check ID.`);
+            console.log(`\nRun 'hackmyagent check-metadata --json' to see all ${CHECK_COUNT} valid check IDs.`);
         }
     }
 });
@@ -5765,7 +5815,6 @@ function parseGitHubTarget(target) {
     };
 }
 const REGISTRY_URL = 'https://api.oa2a.org';
-const STALE_SCAN_DAYS = 3;
 // ============================================================================
 // Scan counter + contribute preference (~/.hackmyagent/config.json)
 // ============================================================================
@@ -5938,6 +5987,57 @@ function displayRegistryResult(data) {
         const days = Math.floor((Date.now() - new Date(data.lastScannedAt).getTime()) / (1000 * 60 * 60 * 24));
         console.log(`  Scanned:    ${days === 0 ? 'today' : days + ' day(s) ago'}`);
     }
+    printCheckNextSteps(data.name);
+}
+/**
+ * Resolve the "run a check" command string for use in user-facing hints.
+ *
+ * Precedence:
+ *   1. HMA_CHECK_COMMAND env var (full command string, e.g. "opena2a check")
+ *   2. `${CLI_PREFIX} check` — sensible default derived from how HMA was
+ *      invoked.
+ *
+ * Parent CLIs should set HMA_CHECK_COMMAND when their verb layout differs
+ * from hackmyagent's, rather than trying to encode the full verb into
+ * HMA_CLI_PREFIX (which is treated as a binary-level prefix everywhere else).
+ */
+function getCheckCommand() {
+    const override = process.env.HMA_CHECK_COMMAND?.trim();
+    if (override)
+        return override;
+    return `${CLI_PREFIX} check`;
+}
+/**
+ * Resolve the "full project scan" hint command string.
+ *
+ * Precedence:
+ *   1. HMA_FULL_SCAN_HINT env var (full command string, e.g. "opena2a review")
+ *   2. `${CLI_PREFIX} secure <dir>` — default.
+ */
+function getFullScanHint() {
+    const override = process.env.HMA_FULL_SCAN_HINT?.trim();
+    if (override)
+        return override;
+    return `${CLI_PREFIX} secure <dir>`;
+}
+/**
+ * Print the standard 3-line next-steps footer shown after every `check`
+ * invocation. Lines:
+ *   1. How to force a fresh local scan of *this* target.
+ *   2. How to run the full project scan (respects HMA_FULL_SCAN_HINT so that
+ *      sibling CLIs like opena2a can redirect users to their own flagship
+ *      command instead of `hackmyagent secure <dir>`).
+ *   3. Discoverability: the other target syntaxes `check` accepts.
+ *
+ * Suppressed in --ci so machine-readable output stays clean.
+ */
+function printCheckNextSteps(target) {
+    if (globalCiMode)
+        return;
+    console.log();
+    console.log(`  ${colors.dim}Run a fresh local scan: ${getCheckCommand()} ${target} --rescan${RESET()}`);
+    console.log(`  ${colors.dim}Full project scan:      ${getFullScanHint()}${RESET()}`);
+    console.log(`  ${colors.dim}Also accepts: pip:<pkg> · <owner>/<repo> · ./<dir> · @publisher/skill${RESET()}`);
     console.log();
 }
 /**
@@ -5947,6 +6047,17 @@ function displayRegistryResult(data) {
 async function suggestSimilarPackages(name) {
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), 5000);
+    // Simple Levenshtein distance for filtering relevant suggestions
+    function levenshtein(a, b) {
+        const m = a.length, n = b.length;
+        const dp = Array.from({ length: m + 1 }, (_, i) => Array.from({ length: n + 1 }, (_, j) => i === 0 ? j : j === 0 ? i : 0));
+        for (let i = 1; i <= m; i++)
+            for (let j = 1; j <= n; j++)
+                dp[i][j] = a[i - 1] === b[j - 1]
+                    ? dp[i - 1][j - 1]
+                    : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+        return dp[m][n];
+    }
     try {
         // Build search queries: the name itself, plus the unscoped name for scoped packages
         const queries = [name];
@@ -5955,11 +6066,9 @@ async function suggestSimilarPackages(name) {
             queries.push(scopeMatch[1]);
         }
         const seen = new Set();
-        const suggestions = [];
+        const candidates = [];
         for (const query of queries) {
-            if (suggestions.length >= 3)
-                break;
-            const url = `https://registry.npmjs.org/-/v1/search?text=${encodeURIComponent(query)}&size=5`;
+            const url = `https://registry.npmjs.org/-/v1/search?text=${encodeURIComponent(query)}&size=10`;
             const res = await fetch(url, { signal: controller.signal });
             if (!res.ok)
                 continue;
@@ -5971,12 +6080,20 @@ async function suggestSimilarPackages(name) {
                 if (pkg === name || seen.has(pkg))
                     continue;
                 seen.add(pkg);
-                suggestions.push(pkg);
-                if (suggestions.length >= 3)
-                    break;
+                // Compare unscoped names for better matching
+                const unscopedInput = name.replace(/^@[^/]+\//, '');
+                const unscopedPkg = pkg.replace(/^@[^/]+\//, '');
+                const dist = levenshtein(unscopedInput.toLowerCase(), unscopedPkg.toLowerCase());
+                // Only suggest if reasonably similar (distance < half the input length + 3)
+                const maxDist = Math.floor(unscopedInput.length / 2) + 3;
+                if (dist <= maxDist) {
+                    candidates.push({ name: pkg, distance: dist });
+                }
             }
         }
-        return suggestions;
+        // Sort by edit distance and return top 3
+        candidates.sort((a, b) => a.distance - b.distance);
+        return candidates.slice(0, 3).map(c => c.name);
     }
     finally {
         clearTimeout(timeout);
@@ -5989,8 +6106,8 @@ async function suggestSimilarPackages(name) {
 async function checkGitHubRepo(target, options) {
     const { org, repo, cloneUrl } = parseGitHubTarget(target);
     const displayName = `${org}/${repo}`;
-    // Step 1: Check registry for existing trust data
-    if (!options.offline) {
+    // Step 1: Check registry for existing trust data (unless --rescan forces a fresh scan)
+    if (!options.offline && !options.rescan) {
         const registryData = await queryRegistry(displayName);
         if (registryData?.found && !isScanStale(registryData.lastScannedAt)) {
             if (options.json) {
@@ -6007,6 +6124,9 @@ async function checkGitHubRepo(target, options) {
             }
         }
     }
+    else if (options.rescan && !options.json && !globalCiMode) {
+        console.error(`Forcing fresh local scan (--rescan)...`);
+    }
     // Step 2: Clone and scan
     const { mkdtemp, rm } = await Promise.resolve().then(() => __importStar(require('node:fs/promises')));
     const { tmpdir } = await Promise.resolve().then(() => __importStar(require('node:os')));
@@ -6095,8 +6215,7 @@ async function checkGitHubRepo(target, options) {
                     queuePendingScan(displayName, result);
             }
         }
-        console.log(`\n  Full project scan: ${CLI_PREFIX} secure <dir>`);
-        console.log();
+        printCheckNextSteps(displayName);
         if (critical.length > 0 || high.length > 0)
             process.exit(1);
     }
@@ -6110,7 +6229,7 @@ async function checkGitHubRepo(target, options) {
             console.error(`Error: Cloning "${displayName}" timed out (120s). The repo may be too large.`);
             console.error(`\nTry cloning manually and scanning the local path:`);
             console.error(`  git clone --depth 1 ${cloneUrl}`);
-            console.error(`  ${CLI_PREFIX} check ./${repo}/`);
+            console.error(`  ${getCheckCommand()} ./${repo}/`);
         }
         else {
             console.error(`Error: ${message}`);
@@ -6239,8 +6358,9 @@ async function checkPyPiPackage(target, options) {
         else {
             console.log(`\n  ${colors.green}No security issues found.${RESET()}`);
         }
-        console.log(`\n  Full project scan: ${CLI_PREFIX} secure <dir>`);
-        console.log();
+        // Pass the original target (with pip: / pypi: prefix preserved) so the
+        // rescan hint stays runnable — `hackmyagent check requests` would try npm.
+        printCheckNextSteps(target);
         if (critical.length > 0 || high.length > 0)
             process.exit(1);
     }
@@ -6399,8 +6519,7 @@ async function checkRawUrl(url, options) {
                     queuePendingScan(displayName, result);
             }
         }
-        console.log(`\n  Full project scan: ${CLI_PREFIX} secure <dir>`);
-        console.log();
+        printCheckNextSteps(displayName);
         if (critical.length > 0 || high.length > 0)
             process.exit(1);
     }
@@ -6413,7 +6532,7 @@ async function checkRawUrl(url, options) {
         else if (message.includes('timeout') || message.includes('Timeout')) {
             console.error(`Error: Fetching "${url}" timed out. The target may be too large.`);
             console.error(`\nTry downloading manually and scanning the local path:`);
-            console.error(`  ${CLI_PREFIX} check ./downloaded-dir/`);
+            console.error(`  ${getCheckCommand()} ./downloaded-dir/`);
         }
         else {
             console.error(`Error scanning URL: ${message}`);
@@ -6425,8 +6544,8 @@ async function checkRawUrl(url, options) {
     }
 }
 async function checkNpmPackage(name, options) {
-    // Step 1: Check registry for existing trust data
-    if (!options.offline) {
+    // Step 1: Check registry for existing trust data (unless --rescan forces a fresh scan)
+    if (!options.offline && !options.rescan) {
         const registryData = await queryRegistry(name);
         if (registryData?.found && !isScanStale(registryData.lastScannedAt)) {
             // Fresh data in registry — show it
@@ -6445,6 +6564,9 @@ async function checkNpmPackage(name, options) {
             }
         }
     }
+    else if (options.rescan && !options.json && !globalCiMode) {
+        console.error(`Forcing fresh local scan (--rescan)...`);
+    }
     // Step 2: Download and scan
     const { mkdtemp, rm } = await Promise.resolve().then(() => __importStar(require('node:fs/promises')));
     const { tmpdir } = await Promise.resolve().then(() => __importStar(require('node:os')));
@@ -6537,8 +6659,7 @@ async function checkNpmPackage(name, options) {
                     queuePendingScan(name, result);
             }
         }
-        console.log(`\n  Full project scan: ${CLI_PREFIX} secure <dir>`);
-        console.log();
+        printCheckNextSteps(name);
         if (critical.length > 0 || high.length > 0)
             process.exit(1);
     }