@sayknow-cli/coding-agent 0.2.6 → 0.2.7

package/CHANGELOG.md

@@ -4,6 +4,18 @@ Sayknow-CLI is a rebranded fork of [gajae-code](https://github.com/Yeachan-Heo/g
 This file tracks the **fork's own releases**; upstream's full feature history lives
 in that project. Each release notes the upstream version it is built on.
 
+## [0.2.7] — 2026-06-23
+
+### Added
+
+- **Plugin install security scan (advisory).** Newly installed plugins/skills are now
+  statically scanned before activation for risky patterns — `curl|bash` download-and-exec,
+  `eval`/dynamic import, credential/secret access, obfuscation, cron persistence, and
+  package-install markers — with risk scoring. Findings surface as warnings in the install
+  output and in `plugin doctor`. Controlled by `plugins.security.scanMode`
+  (`warn` = default, `off`, `block`) and `plugins.security.riskThreshold`. Warn-only by
+  default — it never blocks an install unless you opt into `block` mode.
+
 ## [0.2.6] — 2026-06-22
 
 ### Fixed

package/dist/types/config/settings-schema.d.ts

@@ -3433,6 +3433,39 @@ export declare const SETTINGS_SCHEMA: {
         readonly type: "number";
         readonly default: 65536;
     };
+    readonly "plugins.security.scanMode": {
+        readonly type: "enum";
+        readonly values: readonly ["warn", "off", "block"];
+        readonly default: "warn";
+        readonly ui: {
+            readonly tab: "interaction";
+            readonly label: "Plugin Security Scan Mode";
+            readonly description: "warn: scan on install and log advisory findings (default); off: skip scan; block: deny install when score exceeds threshold";
+            readonly options: readonly [{
+                readonly value: "warn";
+                readonly label: "Warn";
+                readonly description: "Scan and log advisory findings (default)";
+            }, {
+                readonly value: "off";
+                readonly label: "Off";
+                readonly description: "Disable security scanning";
+            }, {
+                readonly value: "block";
+                readonly label: "Block";
+                readonly description: "Deny install when risk score exceeds threshold";
+            }];
+        };
+    };
+    readonly "plugins.security.riskThreshold": {
+        readonly type: "number";
+        readonly default: 60;
+        readonly validate: (value: number) => boolean;
+        readonly ui: {
+            readonly tab: "interaction";
+            readonly label: "Plugin Security Risk Threshold";
+            readonly description: "Score threshold (0\u2013100) above which block mode denies install. Default 60.";
+        };
+    };
 };
 type Schema = typeof SETTINGS_SCHEMA;
 /** All valid setting paths */

package/dist/types/extensibility/plugins/index.d.ts

@@ -4,4 +4,5 @@ export * from "./loader";
 export * from "./manager";
 export * from "./marketplace";
 export * from "./parser";
+export * from "./security-scanner";
 export type * from "./types";

package/dist/types/extensibility/plugins/security-scanner.d.ts

@@ -0,0 +1,31 @@
+import type { DoctorCheck } from "./types";
+export type RiskLevel = "none" | "low" | "medium" | "high";
+export type FindingCategory = "credential" | "execution" | "network" | "obfuscation" | "package_install" | "persistence";
+export interface SecurityFinding {
+    category: FindingCategory;
+    id: string;
+    label: string;
+    severity: "low" | "medium" | "high";
+    file: string;
+    line?: number;
+    snippet?: string;
+}
+export interface ScanReport {
+    findings: SecurityFinding[];
+    networkUrls: string[];
+    riskLevel: RiskLevel;
+    score: number;
+    reasoning: string;
+    recommendation: string;
+}
+/**
+ * Recursively scan `dir` for risky patterns.
+ * Never throws — on any top-level error returns an empty safe report.
+ */
+export declare function scanPluginDir(dir: string): Promise<ScanReport>;
+/**
+ * Convert a ScanReport into DoctorCheck entries for the plugin health check.
+ * Returns [] when riskLevel is "none".
+ * NEVER emits status:"error" — advisory only.
+ */
+export declare function toDoctorChecks(pluginName: string, report: ScanReport): DoctorCheck[];

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@sayknow-cli/coding-agent",
-	"version": "0.2.6",
+	"version": "0.2.7",
 	"description": "Sayknow-CLI CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/jaybeyond/Sayknow_CLI",
 	"author": "jaybeyond",
@@ -51,12 +51,12 @@
 		"@agentclientprotocol/sdk": "0.21.0",
 		"@babel/parser": "^7.29.3",
 		"@mozilla/readability": "^0.6.0",
-		"@sayknow-cli/stats": "0.2.6",
-		"@sayknow-cli/agent-core": "0.2.6",
-		"@sayknow-cli/ai": "0.2.6",
-		"@sayknow-cli/natives": "0.2.6",
-		"@sayknow-cli/tui": "0.2.6",
-		"@sayknow-cli/utils": "0.2.6",
+		"@sayknow-cli/stats": "0.2.7",
+		"@sayknow-cli/agent-core": "0.2.7",
+		"@sayknow-cli/ai": "0.2.7",
+		"@sayknow-cli/natives": "0.2.7",
+		"@sayknow-cli/tui": "0.2.7",
+		"@sayknow-cli/utils": "0.2.7",
 		"@puppeteer/browsers": "^2.13.0",
 		"@types/turndown": "5.0.6",
 		"@xterm/headless": "^6.0.0",

package/src/cli/plugin-cli.ts

@@ -6,6 +6,7 @@
 
 import { APP_NAME, getProjectDir } from "@sayknow-cli/utils";
 import chalk from "chalk";
+import { Settings } from "../config/settings";
 import { resolveOrDefaultProjectRegistryPath } from "../discovery/helpers";
 import { PluginManager, parseSettingValue, validateSetting } from "../extensibility/plugins";
 import {
@@ -15,6 +16,7 @@ import {
 	getPluginsCacheDir,
 	MarketplaceManager,
 } from "../extensibility/plugins/marketplace/index.js";
+import { type ScanReport, scanPluginDir } from "../extensibility/plugins/security-scanner";
 import { theme } from "../modes/theme/theme";
 
 // =============================================================================
@@ -147,6 +149,10 @@ export { classifyInstallTarget } from "./classify-install-target";
  * Run a plugin command.
  */
 export async function runPluginCommand(cmd: PluginCommandArgs): Promise<void> {
+	// Initialize settings so plugin commands can read config (e.g. the install-time
+	// security-scan mode/threshold); mirrors the other CLI command handlers. The scan
+	// itself also tolerates an uninitialized Settings, so this is best-effort.
+	await Settings.init().catch(() => {});
 	const manager = new PluginManager();
 
 	switch (cmd.action) {
@@ -342,6 +348,21 @@ async function handleUpgrade(args: string[], flags: PluginCommandArgs["flags"]):
 	}
 }
 
+function printSecurityAdvisory(report: ScanReport): void {
+	const riskColor = report.riskLevel === "high" ? chalk.red : report.riskLevel === "medium" ? chalk.yellow : chalk.dim;
+	console.log(
+		riskColor(`${theme.status.warning} Security advisory: ${report.riskLevel} risk (score ${report.score})`),
+	);
+	for (const f of report.findings.slice(0, 5)) {
+		const loc = f.line !== undefined ? `${f.file}:${f.line}` : f.file;
+		console.log(chalk.dim(`  ${f.id}: ${loc}`));
+	}
+	if (report.findings.length > 5) {
+		console.log(chalk.dim(`  ... and ${report.findings.length - 5} more finding(s)`));
+	}
+	console.log(chalk.dim("  Advisory only (regex-based, may have false positives)."));
+}
+
 async function handleInstall(
 	manager: PluginManager,
 	packages: string[],
@@ -368,11 +389,28 @@ async function handleInstall(
 					force: flags.force,
 					scope: flags.scope,
 				});
-				console.log(
-					chalk.green(
-						`${theme.status.success} Installed ${target.name} from ${target.marketplace} (${entry.version})`,
-					),
-				);
+				if (flags.json) {
+					// advisory is attached below via the scan path
+				} else {
+					console.log(
+						chalk.green(
+							`${theme.status.success} Installed ${target.name} from ${target.marketplace} (${entry.version})`,
+						),
+					);
+				}
+				// Post-install advisory scan (non-blocking)
+				try {
+					const report = await scanPluginDir(entry.installPath);
+					if (report.riskLevel !== "none") {
+						if (flags.json) {
+							console.log(JSON.stringify({ installed: target.name, securityAdvisory: report }, null, 2));
+						} else {
+							printSecurityAdvisory(report);
+						}
+					}
+				} catch {
+					// advisory — never fail install
+				}
 			} catch (err) {
 				console.error(chalk.red(`${theme.status.error} Failed to install ${spec}: ${err}`));
 				process.exit(1);
@@ -394,7 +432,17 @@ async function handleInstall(
 			const result = await manager.install(spec, { force: flags.force, dryRun: flags.dryRun });
 
 			if (flags.json) {
-				console.log(JSON.stringify(result, null, 2));
+				// Post-install advisory scan for JSON output
+				let securityAdvisory: ScanReport | undefined;
+				if (!flags.dryRun && result.path) {
+					try {
+						const report = await scanPluginDir(result.path);
+						if (report.riskLevel !== "none") securityAdvisory = report;
+					} catch {
+						// advisory
+					}
+				}
+				console.log(JSON.stringify(securityAdvisory ? { ...result, securityAdvisory } : result, null, 2));
 			} else {
 				if (flags.dryRun) {
 					console.log(chalk.dim(`[dry-run] Would install ${spec}`));
@@ -406,6 +454,15 @@ async function handleInstall(
 					if (result.manifest.description) {
 						console.log(chalk.dim(`  ${result.manifest.description}`));
 					}
+					// Post-install advisory scan
+					if (result.path) {
+						try {
+							const report = await scanPluginDir(result.path);
+							if (report.riskLevel !== "none") printSecurityAdvisory(report);
+						} catch {
+							// advisory
+						}
+					}
 				}
 			}
 		} catch (err) {

package/src/config/settings-schema.ts

@@ -2970,6 +2970,38 @@ export const SETTINGS_SCHEMA = {
 	"thinkingBudgets.xhigh": { type: "number", default: 32768 },
 
 	"thinkingBudgets.max": { type: "number", default: 65536 },
+
+	// ────────────────────────────────────────────────────────────────────────
+	// Plugins — security scanner
+	// ────────────────────────────────────────────────────────────────────────
+
+	"plugins.security.scanMode": {
+		type: "enum",
+		values: ["warn", "off", "block"] as const,
+		default: "warn",
+		ui: {
+			tab: "interaction",
+			label: "Plugin Security Scan Mode",
+			description:
+				"warn: scan on install and log advisory findings (default); off: skip scan; block: deny install when score exceeds threshold",
+			options: [
+				{ value: "warn", label: "Warn", description: "Scan and log advisory findings (default)" },
+				{ value: "off", label: "Off", description: "Disable security scanning" },
+				{ value: "block", label: "Block", description: "Deny install when risk score exceeds threshold" },
+			],
+		},
+	},
+
+	"plugins.security.riskThreshold": {
+		type: "number",
+		default: 60,
+		validate: (value: number) => Number.isFinite(value) && value >= 0 && value <= 100,
+		ui: {
+			tab: "interaction",
+			label: "Plugin Security Risk Threshold",
+			description: "Score threshold (0–100) above which block mode denies install. Default 60.",
+		},
+	},
 } as const;
 
 // ═══════════════════════════════════════════════════════════════════════════

package/src/extensibility/plugins/index.ts

@@ -6,4 +6,5 @@ export * from "./loader";
 export * from "./manager";
 export * from "./marketplace";
 export * from "./parser";
+export * from "./security-scanner";
 export type * from "./types";

package/src/extensibility/plugins/manager.ts

@@ -10,7 +10,9 @@ import {
 	isEnoent,
 	logger,
 } from "@sayknow-cli/utils";
+import { settings } from "../../config/settings";
 import { extractPackageName, parsePluginSpec } from "./parser";
+import { scanPluginDir, toDoctorChecks } from "./security-scanner";
 import type {
 	DoctorCheck,
 	DoctorOptions,
@@ -211,6 +213,9 @@ export class PluginManager {
 		}
 		// null = use defaults
 
+		// Security scan — advisory hook, runs after package is on disk but before config is saved.
+		await this.#runSecurityScan(pkg.name, path.join(getPluginsNodeModules(), actualName));
+
 		// Update runtime config
 		const config = await this.#ensureConfigLoaded();
 		config.plugins[pkg.name] = {
@@ -614,6 +619,14 @@ export class PluginManager {
 					}
 				}
 			}
+
+			// Security scan for installed plugin
+			try {
+				const secReport = await scanPluginDir(pluginPath);
+				checks.push(...toDoctorChecks(name, secReport));
+			} catch {
+				// advisory — never fail doctor
+			}
 		}
 
 		// Check for orphaned runtime config entries
@@ -632,6 +645,43 @@ export class PluginManager {
 		return checks;
 	}
 
+	async #runSecurityScan(pluginName: string, dir: string): Promise<void> {
+		// Resolve the scan mode defensively — this can run from CLI paths where Settings
+		// is not initialized, and an advisory scan must NEVER abort an install.
+		let mode = "warn";
+		try {
+			mode = settings.get("plugins.security.scanMode");
+		} catch {
+			mode = "warn";
+		}
+		if (mode === "off") return;
+		try {
+			const report = await scanPluginDir(dir);
+			if (report.riskLevel === "none") return;
+			logger.warn("Plugin security scan flagged risky patterns", {
+				plugin: pluginName,
+				riskLevel: report.riskLevel,
+				score: report.score,
+				findings: report.findings,
+			});
+			// score: 100 = safe, lower = riskier — block when it drops to/under the threshold.
+			let threshold = 60;
+			try {
+				threshold = settings.get("plugins.security.riskThreshold");
+			} catch {
+				threshold = 60;
+			}
+			if (mode === "block" && report.score <= threshold) {
+				throw new Error(
+					`Plugin "${pluginName}" blocked by security policy: ${report.riskLevel} risk (score ${report.score}). Set plugins.security.scanMode=warn to override.`,
+				);
+			}
+		} catch (err) {
+			if (mode === "block") throw err;
+			logger.debug("Security scan skipped due to error", { plugin: pluginName, error: err });
+		}
+	}
+
 	async #fixMissingPlugin(): Promise<boolean> {
 		try {
 			const proc = Bun.spawn(["bun", "install"], {

package/src/extensibility/plugins/marketplace/manager.ts

@@ -11,6 +11,8 @@ import * as os from "node:os";
 import * as path from "node:path";
 
 import { isEnoent, logger, pathIsWithin } from "@sayknow-cli/utils";
+import { settings } from "../../../config/settings";
+import { scanPluginDir } from "../security-scanner";
 
 import { cachePlugin } from "./cache";
 import { classifySource, fetchMarketplace, parseMarketplaceCatalog, promoteCloneToCache } from "./fetcher";
@@ -298,6 +300,9 @@ export class MarketplaceManager {
 			}
 		}
 
+		// Security scan — advisory hook, runs after plugin is on disk but before registry write.
+		await this.#runSecurityScan(pluginId, cachePath);
+
 		// Only now clean up old entries — new cache succeeded, so it is safe to remove old ones.
 		if (existing && existing.length > 0) {
 			// Remove from scope-appropriate registry first, then cross-check refs before disk deletion.
@@ -745,6 +750,43 @@ export class MarketplaceManager {
 		}
 	}
 
+	async #runSecurityScan(pluginName: string, dir: string): Promise<void> {
+		// Resolve the scan mode defensively — this can run from CLI paths where Settings
+		// is not initialized, and an advisory scan must NEVER abort an install.
+		let mode = "warn";
+		try {
+			mode = settings.get("plugins.security.scanMode");
+		} catch {
+			mode = "warn";
+		}
+		if (mode === "off") return;
+		try {
+			const report = await scanPluginDir(dir);
+			if (report.riskLevel === "none") return;
+			logger.warn("Plugin security scan flagged risky patterns", {
+				plugin: pluginName,
+				riskLevel: report.riskLevel,
+				score: report.score,
+				findings: report.findings,
+			});
+			// score: 100 = safe, lower = riskier — block when it drops to/under the threshold.
+			let threshold = 60;
+			try {
+				threshold = settings.get("plugins.security.riskThreshold");
+			} catch {
+				threshold = 60;
+			}
+			if (mode === "block" && report.score <= threshold) {
+				throw new Error(
+					`Plugin "${pluginName}" blocked by security policy: ${report.riskLevel} risk (score ${report.score}). Set plugins.security.scanMode=warn to override.`,
+				);
+			}
+		} catch (err) {
+			if (mode === "block") throw err;
+			logger.debug("Security scan skipped due to error", { plugin: pluginName, error: err });
+		}
+	}
+
 	/**
 	 * Compute the marketplace root directory for source resolution.
 	 *

package/src/extensibility/plugins/security-scanner.ts

@@ -0,0 +1,477 @@
+// Regex-based, false-positive-prone — ADVISORY ONLY. Never hard-block by default.
+
+import { readdir, readFile, stat } from "node:fs/promises";
+import { basename, extname, join, relative } from "node:path";
+
+import type { DoctorCheck } from "./types";
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export type RiskLevel = "none" | "low" | "medium" | "high";
+
+export type FindingCategory =
+	| "credential"
+	| "execution"
+	| "network"
+	| "obfuscation"
+	| "package_install"
+	| "persistence";
+
+export interface SecurityFinding {
+	category: FindingCategory;
+	id: string;
+	label: string;
+	severity: "low" | "medium" | "high";
+	file: string;
+	line?: number;
+	snippet?: string;
+}
+
+export interface ScanReport {
+	findings: SecurityFinding[];
+	networkUrls: string[];
+	riskLevel: RiskLevel;
+	score: number;
+	reasoning: string;
+	recommendation: string;
+}
+
+// ─── Rule definitions ─────────────────────────────────────────────────────────
+
+interface ScanRule {
+	id: string;
+	label: string;
+	pattern: RegExp;
+	category: FindingCategory;
+	severity: "low" | "medium" | "high";
+}
+
+const CREDENTIAL_RULES: ScanRule[] = [
+	{
+		id: "credential_keyword",
+		label: "Hardcoded credential keyword (API key/token/secret)",
+		pattern: /\b(api[_-]?key|secret|token|private[_-]?key|access[_-]?key|auth[_-]?token|bearer)\b/i,
+		category: "credential",
+		severity: "medium",
+	},
+	{
+		id: "credential_access",
+		label: "Environment variable access (process.env / os.environ)",
+		pattern: /\b(os\.environ|getenv|process\.env|dotenv|load_dotenv)\b/i,
+		category: "credential",
+		severity: "low",
+	},
+	{
+		id: "crypto_wallet",
+		label: "Cryptocurrency wallet reference (wallet/seed/mnemonic)",
+		pattern: /\b(wallet\.dat|keystore|mnemonic|seed phrase|private key|ledger|trezor|metamask)\b/i,
+		category: "credential",
+		severity: "high",
+	},
+	{
+		id: "ssh_access",
+		label: "SSH key / config access",
+		pattern: /(~\/.ssh|\\.ssh|id_rsa|id_ed25519|authorized_keys)/i,
+		category: "credential",
+		severity: "medium",
+	},
+	{
+		id: "cloud_credentials",
+		label: "Cloud credential file reference (AWS / GCloud / Azure)",
+		pattern: /(\.aws\/credentials|\.aws\/config|\.config\/gcloud|\.azure\/)/i,
+		category: "credential",
+		severity: "medium",
+	},
+	{
+		id: "browser_data",
+		label: "Browser sensitive data access (cookies/passwords)",
+		pattern: /(Login Data|Chrome\/User Data|Firefox\/Profiles|Brave\/User Data)/i,
+		category: "credential",
+		severity: "medium",
+	},
+];
+
+const EXEC_RULES: ScanRule[] = [
+	{
+		id: "download_exec",
+		label: "Download-then-execute pattern (curl|wget piped to shell)",
+		pattern: /(curl\s+.*\|\s*(bash|sh)|wget\s+.*\|\s*(bash|sh)|powershell\s+.*-c|Invoke-Expression)/i,
+		category: "execution",
+		severity: "high",
+	},
+	{
+		id: "shell_exec",
+		label: "Arbitrary system command execution (shell/subprocess)",
+		pattern: /\b(subprocess\.Popen|os\.system|popen|child_process\.exec|Runtime\.getRuntime\(\)\.exec)\b/i,
+		category: "execution",
+		severity: "medium",
+	},
+	{
+		id: "dynamic_exec",
+		label: "Dynamic code loading (eval / import)",
+		pattern: /\b(eval\(|__import__|importlib|dlopen)\b/i,
+		category: "execution",
+		severity: "medium",
+	},
+];
+
+const PERSISTENCE_RULES: ScanRule[] = [
+	{
+		id: "persistence",
+		label: "Background persistence / scheduled job (cron/systemd/launchd)",
+		pattern: /\b(cron|crontab|@reboot|systemd|launchd\.plist|schtasks)\b/i,
+		category: "persistence",
+		severity: "high",
+	},
+];
+
+const OBFUSCATION_RULES: ScanRule[] = [
+	{
+		id: "obfuscation_encoding",
+		label: "Obfuscation / encoding (base64 / hex / XOR)",
+		pattern: /\b(base64|atob|btoa|fromCharCode|rot13|xor|unescape|eval\(atob)\b/i,
+		category: "obfuscation",
+		severity: "medium",
+	},
+	{
+		id: "geo_evasion",
+		label: "Locale/timezone evasion pattern",
+		pattern: /(timezone|Intl\.DateTimeFormat|locale|LANG=)\b/i,
+		category: "obfuscation",
+		severity: "low",
+	},
+];
+
+const PACKAGE_INSTALL_RULES: ScanRule[] = [
+	{
+		id: "npm_install",
+		label: "npm install invocation",
+		pattern: /\b(npm\s+install|npm\s+i\s|npx\s)/i,
+		category: "package_install",
+		severity: "low",
+	},
+	{
+		id: "pip_install",
+		label: "pip install invocation",
+		pattern: /\b(pip\s+install|pip3\s+install|python\s+-m\s+pip)\b/i,
+		category: "package_install",
+		severity: "low",
+	},
+	{
+		id: "apt_install",
+		label: "apt-get install invocation",
+		pattern: /\b(apt-get\s+install|apt\s+install)\b/i,
+		category: "package_install",
+		severity: "low",
+	},
+	{
+		id: "brew_install",
+		label: "brew install invocation",
+		pattern: /\b(brew\s+install)\b/i,
+		category: "package_install",
+		severity: "low",
+	},
+];
+
+const ALL_RULES: ScanRule[] = [
+	...CREDENTIAL_RULES,
+	...EXEC_RULES,
+	...PERSISTENCE_RULES,
+	...OBFUSCATION_RULES,
+	...PACKAGE_INSTALL_RULES,
+];
+
+const URL_REGEX = /https?:\/\/[^\s)\]"'<>]+/gi;
+
+const TEXT_EXTS = new Set([
+	".md",
+	".py",
+	".js",
+	".ts",
+	".tsx",
+	".sh",
+	".json",
+	".yaml",
+	".yml",
+	".toml",
+	".txt",
+	".env",
+	".ini",
+	".conf",
+	".rb",
+	".go",
+	".java",
+	".html",
+	".css",
+	".xml",
+	".jsx",
+	".mjs",
+	".cjs",
+]);
+
+const SKIP_DIRS = new Set([
+	".git",
+	"node_modules",
+	"dist",
+	"build",
+	"__pycache__",
+	".venv",
+	"venv",
+	".idea",
+	".vscode",
+	"coverage",
+]);
+
+const ENV_FILENAMES = new Set([
+	".env",
+	".env.local",
+	".env.production",
+	".env.development",
+	".env.test",
+	".env.example",
+	"config.json",
+	"secrets.json",
+]);
+
+const MAX_FILE_SIZE = 2_000_000; // 2 MB
+
+const SNIPPET_MAX_LEN = 120;
+
+// ─── Score deduction per unique category ─────────────────────────────────────
+
+function deductionForCategory(category: FindingCategory): number {
+	switch (category) {
+		case "execution":
+			return 25;
+		case "persistence":
+			return 20;
+		case "credential":
+			return 15;
+		case "obfuscation":
+			return 10;
+		case "network":
+			return 5;
+		case "package_install":
+			return 5;
+	}
+}
+
+// ─── Risk thresholds ──────────────────────────────────────────────────────────
+//
+// Flags with inherently high risk elevate the level regardless of score.
+// Otherwise: score ≤ 50 → high, ≤ 75 → medium, ≤ 90 → low, 91-100 → none.
+
+const HIGH_FLAGS = new Set(["download_exec", "persistence", "crypto_wallet"]);
+const MEDIUM_FLAGS = new Set([
+	"shell_exec",
+	"dynamic_exec",
+	"ssh_access",
+	"cloud_credentials",
+	"browser_data",
+	"obfuscation_encoding",
+	"geo_evasion",
+]);
+
+function determineRiskLevel(flagIds: Set<string>, score: number, networkCount: number): RiskLevel {
+	for (const f of HIGH_FLAGS) {
+		if (flagIds.has(f)) return "high";
+	}
+	for (const f of MEDIUM_FLAGS) {
+		if (flagIds.has(f)) return "medium";
+	}
+	if (networkCount > 0) return "medium";
+	if (flagIds.size === 0) return "none";
+	if (score <= 50) return "high";
+	if (score <= 75) return "medium";
+	if (score <= 90) return "low";
+	// Findings are present here (the flagIds.size === 0 case returned "none" above), so a
+	// single low-weight pattern (e.g. a package-install / supply-chain marker scoring 95)
+	// still surfaces as an advisory instead of being silently suppressed.
+	return "low";
+}
+
+function buildReasoning(flagIds: Set<string>, networkCount: number): string {
+	const reasons: string[] = [];
+	if (flagIds.has("download_exec")) reasons.push("download-then-execute pattern detected");
+	if (flagIds.has("persistence")) reasons.push("background persistence / scheduled job");
+	if (flagIds.has("crypto_wallet")) reasons.push("cryptocurrency wallet / private key access");
+	if (flagIds.has("shell_exec")) reasons.push("arbitrary system command execution");
+	if (flagIds.has("dynamic_exec")) reasons.push("dynamic code execution (eval/import)");
+	if (flagIds.has("ssh_access") || flagIds.has("cloud_credentials"))
+		reasons.push("SSH key or cloud credential access");
+	if (flagIds.has("browser_data")) reasons.push("browser sensitive data access");
+	if (flagIds.has("obfuscation_encoding")) reasons.push("code obfuscation / encoding signs");
+	if (networkCount > 2) reasons.push(`multiple external connections (${networkCount})`);
+	else if (networkCount > 0) reasons.push("external network URLs present");
+	return reasons.length > 0 ? reasons.join("; ") : "";
+}
+
+function buildRecommendation(riskLevel: RiskLevel): string {
+	switch (riskLevel) {
+		case "high":
+			return "HIGH RISK: Do not install in environments with real credentials. Test only in an isolated sandbox.";
+		case "medium":
+			return "SUSPICIOUS: Test in an isolated environment and verify network traffic before activating.";
+		case "low":
+			return "LOW RISK: No clearly malicious patterns detected. Follow least-privilege principles.";
+		case "none":
+			return "No security concerns detected.";
+	}
+}
+
+// ─── Walker ───────────────────────────────────────────────────────────────────
+
+async function walkDir(
+	dir: string,
+	rootDir: string,
+	callback: (relPath: string, content: string, absPath: string) => void,
+): Promise<void> {
+	let entries: import("node:fs").Dirent[];
+	try {
+		entries = await readdir(dir, { withFileTypes: true });
+	} catch {
+		return;
+	}
+
+	for (const entry of entries) {
+		const fullPath = join(dir, entry.name);
+
+		if (entry.isDirectory()) {
+			if (SKIP_DIRS.has(entry.name)) continue;
+			await walkDir(fullPath, rootDir, callback);
+		} else if (entry.isFile()) {
+			const ext = extname(entry.name).toLowerCase();
+			const isText = TEXT_EXTS.has(ext) || ENV_FILENAMES.has(entry.name);
+			if (!isText) continue;
+
+			try {
+				const info = await stat(fullPath);
+				if (info.size > MAX_FILE_SIZE) continue;
+			} catch {
+				continue;
+			}
+
+			try {
+				const content = await readFile(fullPath, "utf-8");
+				const relPath = relative(rootDir, fullPath);
+				callback(relPath, content, fullPath);
+			} catch {
+				// ignore unreadable files
+			}
+		}
+	}
+}
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Recursively scan `dir` for risky patterns.
+ * Never throws — on any top-level error returns an empty safe report.
+ */
+export async function scanPluginDir(dir: string): Promise<ScanReport> {
+	try {
+		const findings: SecurityFinding[] = [];
+		const networkUrls: string[] = [];
+		const flagIds = new Set<string>();
+		const seenFlagFiles = new Map<string, Set<string>>(); // flagId -> set of relPaths already recorded
+
+		await walkDir(dir, dir, (relPath, content) => {
+			// Sensitive file detection
+			if (ENV_FILENAMES.has(basename(relPath))) {
+				findings.push({
+					category: "credential",
+					id: "sensitive_file",
+					label: `Sensitive config file present: ${relPath}`,
+					severity: "medium",
+					file: relPath,
+				});
+				flagIds.add("sensitive_file");
+			}
+
+			// Per-line rule matching
+			const lines = content.split("\n");
+			for (let lineIdx = 0; lineIdx < lines.length; lineIdx++) {
+				const line = lines[lineIdx];
+				for (const rule of ALL_RULES) {
+					if (!rule.pattern.test(line)) continue;
+					// Reset lastIndex for global regexes
+					rule.pattern.lastIndex = 0;
+
+					const fileSet = seenFlagFiles.get(rule.id) ?? new Set<string>();
+					seenFlagFiles.set(rule.id, fileSet);
+					// One finding per (rule.id, file) pair to avoid noise
+					if (fileSet.has(relPath)) continue;
+					fileSet.add(relPath);
+
+					flagIds.add(rule.id);
+					const snippet = line.trim().slice(0, SNIPPET_MAX_LEN);
+					findings.push({
+						category: rule.category,
+						id: rule.id,
+						label: rule.label,
+						severity: rule.severity,
+						file: relPath,
+						line: lineIdx + 1,
+						snippet,
+					});
+				}
+				// Reset all global regexes after each line
+				for (const rule of ALL_RULES) rule.pattern.lastIndex = 0;
+
+				// URL extraction (not per-rule deduplicated)
+				URL_REGEX.lastIndex = 0;
+				for (const urlMatch of line.matchAll(URL_REGEX)) {
+					if (!networkUrls.includes(urlMatch[0])) networkUrls.push(urlMatch[0]);
+				}
+			}
+		});
+
+		// Calculate score
+		const seenCategories = new Set<FindingCategory>();
+		let deduction = 0;
+		for (const f of findings) {
+			if (!seenCategories.has(f.category)) {
+				seenCategories.add(f.category);
+				deduction += deductionForCategory(f.category);
+			}
+		}
+		const score = Math.max(0, Math.min(100, 100 - deduction));
+		const riskLevel = determineRiskLevel(flagIds, score, networkUrls.length);
+
+		return {
+			findings,
+			networkUrls,
+			riskLevel,
+			score,
+			reasoning: buildReasoning(flagIds, networkUrls.length),
+			recommendation: buildRecommendation(riskLevel),
+		};
+	} catch {
+		return { findings: [], networkUrls: [], riskLevel: "none", score: 0, reasoning: "", recommendation: "" };
+	}
+}
+
+/**
+ * Convert a ScanReport into DoctorCheck entries for the plugin health check.
+ * Returns [] when riskLevel is "none".
+ * NEVER emits status:"error" — advisory only.
+ */
+export function toDoctorChecks(pluginName: string, report: ScanReport): DoctorCheck[] {
+	if (report.riskLevel === "none") return [];
+
+	const topFindings = report.findings.slice(0, 5);
+	const topLines = topFindings.map(f => `${f.id}: ${f.file}${f.line !== undefined ? `:${f.line}` : ""}`).join(", ");
+
+	const message =
+		`risk=${report.riskLevel} score=${report.score}` +
+		(topLines ? ` | ${topLines}` : "") +
+		(report.findings.length > 5 ? ` (+${report.findings.length - 5} more)` : "");
+
+	return [
+		{
+			name: `plugin:${pluginName}:security`,
+			status: "warning",
+			message,
+		},
+	];
+}