dsh-code-security 0.3.8 → 0.4.1

package/lib/engines.js

@@ -0,0 +1,255 @@
+/** Optional scanners run over bounded, owned snapshots; no project rules or install scripts. */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createHash } from 'node:crypto';
+import { homedir, tmpdir } from 'node:os';
+import { protectFinding, redactText } from './privacy.js';
+import { sanitizedHtmlLines } from './syntax.js';
+const rulePath = (file) => fileURLToPath(new URL('../rules/' + file, import.meta.url));
+const command = (id, cfg) => cfg.enginePaths[id] ?? (id === 'osv' ? 'osv-scanner' : id);
+const canonical = (file) => process.platform === 'win32' ? path.resolve(file).toLowerCase() : path.resolve(file);
+const missing = (error) => /ENOENT|not found|cannot find|找不到|不存在/i.test(String(error?.code ?? '') + ' ' + String(error?.message ?? error));
+/** File modification dates describe the cache, not the age of every advisory inside it. */
+export async function databaseHealth(cfg) {
+    const defaultRoot = process.platform === 'win32' ? process.env.LOCALAPPDATA : process.platform === 'darwin' ? path.join(homedir(), 'Library', 'Caches') : process.env.XDG_CACHE_HOME || path.join(homedir(), '.cache');
+    const root = cfg.osvDatabaseDir || process.env.OSV_SCALIBR_LOCAL_DB_CACHE_DIRECTORY || process.env.OSV_SCANNER_LOCAL_DB_CACHE_DIRECTORY || defaultRoot || tmpdir();
+    const directory = path.join(root, 'osv-scalibr'), databases = [];
+    try {
+        for (const entry of (await fs.readdir(directory, { withFileTypes: true })).slice(0, 200)) {
+            if (!entry.isDirectory() || entry.isSymbolicLink())
+                continue;
+            try {
+                const info = await fs.lstat(path.join(directory, entry.name, 'all.zip'));
+                if (info.isFile() && !info.isSymbolicLink())
+                    databases.push({ ecosystem: entry.name, fileModifiedAt: info.mtime.toISOString() });
+            }
+            catch { /* An ecosystem without an archive is unavailable. */ }
+        }
+    }
+    catch { /* A missing/unreadable cache is reported as unavailable, never an empty audit. */ }
+    return { directory, available: databases.length > 0, databases };
+}
+export async function probeEngine(engine, cfg, runner, signal) {
+    let owned;
+    try {
+        signal?.throwIfAborted();
+        if (engine === 'semgrep')
+            owned = await snapshot([], cfg);
+        const result = await runner.run([command(engine, cfg), engine === 'betterleaks' ? 'version' : '--version', ...(engine === 'semgrep' ? ['--metrics=off', '--disable-version-check'] : [])], { timeoutMs: Math.min(8000, cfg.engineTimeoutMs), signal,
+            ...(owned ? { env: { SEMGREP_APP_TOKEN: '', SEMGREP_SETTINGS_FILE: path.join(owned.dir, '.semgrep-settings.yml'), SEMGREP_SEND_METRICS: 'off', SEMGREP_ENABLE_VERSION_CHECK: '0' } } : {}) });
+        signal?.throwIfAborted();
+        if (result.signal || result.exitCode !== 0)
+            return { engine, status: missing(result.stderr) ? 'not-installed' : 'failed', reason: 'version-check-failed' };
+        const version = /\b\d+\.\d+\.\d+\b/.exec(result.stdout)?.[0];
+        if (!version || !version.startsWith(engine === 'osv' ? '2.' : '1.'))
+            return { engine, status: 'failed', reason: 'unsupported-version' };
+        return { engine, status: 'completed', version };
+    }
+    catch (error) {
+        signal?.throwIfAborted();
+        return { engine, status: missing(error) ? 'not-installed' : 'failed', reason: missing(error) ? 'executable-missing' : 'version-check-failed' };
+    }
+    finally {
+        await owned?.dispose();
+    }
+}
+async function snapshot(documents, cfg) {
+    const parent = path.resolve(cfg.stateDir, 'engine-tmp');
+    await fs.mkdir(parent, { recursive: true });
+    const dir = await fs.mkdtemp(path.join(parent, 'scan-')), files = new Map();
+    let bytes = 0, skipped = 0;
+    try {
+        for (const [i, doc] of documents.entries()) {
+            if (Buffer.byteLength(doc.text) > cfg.maxFileBytes || bytes + Buffer.byteLength(doc.text) > 64 * 1024 * 1024 || files.size >= cfg.maxFiles) {
+                skipped++;
+                continue;
+            }
+            const normalized = doc.file.replace(/\\/g, '/');
+            const relative = !path.isAbsolute(normalized) && !normalized.split('/').some(p => p === '..' || p.includes(':')) ? normalized : 'external/' + i + '/' + path.basename(normalized);
+            const file = path.resolve(dir, relative);
+            if (!file.startsWith(dir + path.sep))
+                throw new Error('Invalid snapshot path');
+            await fs.mkdir(path.dirname(file), { recursive: true });
+            await fs.writeFile(file, doc.text, { flag: 'wx', mode: 0o600 });
+            files.set(canonical(file), doc);
+            bytes += Buffer.byteLength(doc.text);
+        }
+        return { dir, files, skipped, async dispose() { if (path.dirname(dir) !== parent || !path.basename(dir).startsWith('scan-'))
+                throw new Error('Invalid owned snapshot'); await fs.rm(dir, { recursive: true, force: true }); } };
+    }
+    catch (error) {
+        if (path.dirname(dir) === parent && path.basename(dir).startsWith('scan-'))
+            await fs.rm(dir, { recursive: true, force: true });
+        throw error;
+    }
+}
+function documentFor(name, dir, files) {
+    if (typeof name !== 'string')
+        return undefined;
+    return files.get(canonical(path.isAbsolute(name) ? name : path.resolve(dir, name)));
+}
+function validLine(value) { return Number.isSafeInteger(value) && value >= 1; }
+function selected(doc, start, end) {
+    return !doc.selectedLines || [...doc.selectedLines].some(line => line >= start && line <= end);
+}
+function normalizeFindings(engine, report, dir, files) {
+    const rows = engine === 'betterleaks' ? report : report?.results;
+    if (!Array.isArray(rows))
+        throw new Error('invalid-json-schema');
+    const findings = [];
+    let incomplete = engine === 'semgrep' && (!Array.isArray(report.errors) || report.errors.length > 0);
+    const lines = new Map([...files.values()].map(doc => [doc, doc.text.split(/\r?\n/)]));
+    const sanitized = new Map();
+    if (rows.length > 5000)
+        incomplete = true;
+    for (const row of rows.slice(0, 5000)) {
+        const doc = documentFor(engine === 'betterleaks' ? row.File : row.path, dir, files);
+        const line = engine === 'betterleaks' ? row.StartLine : row.start?.line;
+        const endLine = engine === 'betterleaks' ? row.EndLine : row.end?.line;
+        const rule = engine === 'betterleaks' ? row.RuleID : row.check_id;
+        if (!doc || !validLine(line) || !validLine(endLine) || endLine < line || endLine > lines.get(doc).length || typeof rule !== 'string' || rule.length > 300) {
+            incomplete = true;
+            continue;
+        }
+        if (!selected(doc, line, endLine))
+            continue;
+        if (engine === 'semgrep' && rule === 'dsh-js-html-input') {
+            if (!sanitized.has(doc))
+                sanitized.set(doc, sanitizedHtmlLines(doc.text));
+            if (sanitized.get(doc).has(line))
+                continue;
+        }
+        const snippet = lines.get(doc).slice(line - 1, endLine).join('\n').slice(0, 200);
+        const message = engine === 'betterleaks' ? row.Description : row.extra?.message;
+        const title = engine === 'betterleaks' ? '检测到平台格式的密钥' : typeof message === 'string' ? message.slice(0, 200) : rule;
+        const cwe = engine === 'betterleaks' ? 'CWE-798' : String(row.extra?.metadata?.cwe?.[0] ?? row.extra?.metadata?.cwe ?? 'CWE-20').match(/CWE-\d+/)?.[0] ?? 'CWE-20';
+        const severity = engine === 'betterleaks' ? 'high' : row.extra?.severity === 'ERROR' ? 'high' : row.extra?.severity === 'INFO' ? 'low' : 'medium';
+        const finding = { id: 'EXT-' + createHash('sha256').update(engine + '|' + rule + '|' + doc.file + '|' + line).digest('hex').slice(0, 12), ruleId: engine + ':' + rule, engine,
+            title, cwe, severity, confidence: engine === 'betterleaks' ? row.Attributes?.confidence === 'low' ? 'low' : 'high' : row.extra?.metadata?.confidence === 'HIGH' ? 'high' : 'medium',
+            evidence: engine === 'semgrep' ? 'dataflow' : 'pattern', file: doc.file, line, endLine, snippet, message: typeof message === 'string' ? message.slice(0, 2000) : title };
+        findings.push(protectFinding(finding));
+    }
+    return { findings, incomplete };
+}
+async function execute(engine, args, cfg, runner, dir, signal) {
+    signal?.throwIfAborted();
+    const ctl = new AbortController(), timer = setTimeout(() => ctl.abort(new Error('engine timed out')), cfg.engineTimeoutMs);
+    const databaseRoot = cfg.osvDatabaseDir || process.env.OSV_SCALIBR_LOCAL_DB_CACHE_DIRECTORY || process.env.OSV_SCANNER_LOCAL_DB_CACHE_DIRECTORY;
+    try {
+        const result = await runner.run([command(engine, cfg), ...args], { cwd: dir, timeoutMs: cfg.engineTimeoutMs, signal: signal ? AbortSignal.any([signal, ctl.signal]) : ctl.signal,
+            ...(engine === 'osv' && databaseRoot ? { env: { OSV_SCANNER_LOCAL_DB_CACHE_DIRECTORY: databaseRoot, OSV_SCALIBR_LOCAL_DB_CACHE_DIRECTORY: databaseRoot } } : engine === 'semgrep' ? { env: { SEMGREP_APP_TOKEN: '', SEMGREP_SETTINGS_FILE: path.join(dir, '.semgrep-settings.yml'), SEMGREP_SEND_METRICS: 'off', SEMGREP_ENABLE_VERSION_CHECK: '0' } } : {}) });
+        signal?.throwIfAborted();
+        if (ctl.signal.aborted || result.signal)
+            return { coverage: { engine, status: 'timed-out', reason: 'execution-timeout' } };
+        if (result.exitCode !== 0 && result.exitCode !== 1)
+            return { coverage: { engine, status: 'failed', reason: engine === 'osv' && /database|cache|offline/i.test(result.stderr) ? 'database-unavailable' : 'execution-failed' } };
+        try {
+            return { report: JSON.parse(result.stdout.replace(/^\uFEFF/, '').trim()), exitCode: result.exitCode };
+        }
+        catch {
+            return { coverage: { engine, status: 'failed', reason: 'invalid-or-truncated-json' } };
+        }
+    }
+    catch (error) {
+        signal?.throwIfAborted();
+        return { coverage: { engine, status: missing(error) ? 'not-installed' : ctl.signal.aborted ? 'timed-out' : 'failed', reason: missing(error) ? 'executable-missing' : ctl.signal.aborted ? 'execution-timeout' : 'execution-failed' } };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export async function scanExternal(engine, documents, cfg, runner, signal) {
+    const started = Date.now(), health = await probeEngine(engine, cfg, runner, signal);
+    signal?.throwIfAborted();
+    if (health.status !== 'completed')
+        return { findings: [], coverage: health };
+    if (!documents.length)
+        return { findings: [], coverage: { ...health, status: 'not-run', reason: 'no-eligible-files' } };
+    const owned = await snapshot(documents, cfg);
+    try {
+        const args = engine === 'betterleaks' ? ['dir', owned.dir, '--config', rulePath('betterleaks.toml'), '--validation=false', '--redact=100', '--no-banner', '--no-color', '--ignore-gitleaks-allow', '--max-archive-depth=0', '--max-decode-depth=0', '--report-format=json', '--report-path=-', '--timeout', String(Math.ceil(cfg.engineTimeoutMs / 1000))]
+            : ['scan', '--config', rulePath('semgrep.yml'), '--metrics=off', '--disable-version-check', '--no-git-ignore', '--no-rewrite-rule-ids', '--json', '--quiet', '--max-target-bytes', String(cfg.maxFileBytes), '--timeout', '15', owned.dir];
+        const run = await execute(engine, args, cfg, runner, owned.dir, signal);
+        if (run.coverage)
+            return { findings: [], coverage: { ...run.coverage, version: health.version } };
+        try {
+            const normalized = normalizeFindings(engine, run.report, owned.dir, owned.files);
+            return { findings: normalized.findings, coverage: { ...health, status: normalized.incomplete || owned.skipped ? 'partial' : 'completed', ...(normalized.incomplete || owned.skipped ? { reason: 'incomplete-coverage' } : {}), findingsCount: normalized.findings.length, durationMs: Date.now() - started } };
+        }
+        catch {
+            return { findings: [], coverage: { ...health, status: 'failed', reason: 'invalid-json-schema' } };
+        }
+    }
+    finally {
+        await owned.dispose();
+    }
+}
+export function mergeFindings(findings) {
+    const grouped = new Map();
+    const rank = { critical: 4, high: 3, medium: 2, low: 1 };
+    const confidenceRank = { high: 3, medium: 2, low: 1 };
+    for (const finding of findings) {
+        const key = finding.file + '|' + finding.line + '|' + finding.cwe;
+        const previous = grouped.get(key);
+        if (!previous)
+            grouped.set(key, { ...finding, sources: [finding.engine ?? 'builtin'] });
+        else
+            grouped.set(key, { ...previous, severity: rank[finding.severity] > rank[previous.severity] ? finding.severity : previous.severity,
+                confidence: confidenceRank[finding.confidence] > confidenceRank[previous.confidence] ? finding.confidence : previous.confidence, evidence: finding.evidence === 'dataflow' ? 'dataflow' : previous.evidence,
+                sources: [...new Set([...(previous.sources ?? []), finding.engine ?? 'builtin'])] });
+    }
+    return [...grouped.values()].sort((a, b) => rank[b.severity] - rank[a.severity] || a.file.localeCompare(b.file) || a.line - b.line);
+}
+export async function auditDependencies(documents, mode, cfg, runner, signal) {
+    const health = await probeEngine('osv', cfg, runner, signal);
+    signal?.throwIfAborted();
+    if (health.status !== 'completed')
+        return { mode, coverage: health, packagesScanned: 0, vulnerabilities: [] };
+    if (!documents.length)
+        return { mode, coverage: { ...health, status: 'not-run', reason: 'no-lockfiles' }, packagesScanned: 0, vulnerabilities: [] };
+    const owned = await snapshot(documents, cfg);
+    try {
+        const args = ['scan', 'source', '--recursive', '--no-ignore', '--format=json', '--all-packages', '--no-resolve', '--no-call-analysis=go', '--no-call-analysis=rust', '--config', rulePath('osv.toml'), ...(mode === 'offline' ? ['--offline'] : []), owned.dir];
+        const run = await execute('osv', args, cfg, runner, owned.dir, signal);
+        if (run.coverage)
+            return { mode, coverage: { ...run.coverage, version: health.version }, packagesScanned: 0, vulnerabilities: [] };
+        if (!Array.isArray(run.report?.results))
+            return { mode, coverage: { ...health, status: 'failed', reason: 'invalid-json-schema' }, packagesScanned: 0, vulnerabilities: [] };
+        let packagesScanned = 0, incomplete = owned.skipped > 0;
+        const vulnerabilities = [];
+        for (const source of run.report.results) {
+            const doc = documentFor(source.source?.path, owned.dir, owned.files);
+            if (!doc || !Array.isArray(source.packages)) {
+                incomplete = true;
+                continue;
+            }
+            for (const item of source.packages) {
+                const pkg = item.package;
+                if (typeof pkg?.name !== 'string' || typeof pkg.version !== 'string') {
+                    incomplete = true;
+                    continue;
+                }
+                // OSV intentionally does not query public advisories for local packages.
+                if (typeof pkg.purl === 'string' && /[?&]source=LOCAL(?:&|$)/i.test(pkg.purl)) {
+                    incomplete = true;
+                    continue;
+                }
+                packagesScanned++;
+                for (const vuln of item.vulnerabilities ?? []) {
+                    if (typeof vuln.id !== 'string') {
+                        incomplete = true;
+                        continue;
+                    }
+                    const fixedVersions = (vuln.affected ?? []).filter((a) => a.package?.name === pkg.name && a.package?.ecosystem === pkg.ecosystem).flatMap((a) => (a.ranges ?? []).flatMap((r) => (r.events ?? []).flatMap((e) => typeof e.fixed === 'string' ? [e.fixed] : [])));
+                    vulnerabilities.push({ id: vuln.id, aliases: Array.isArray(vuln.aliases) ? vuln.aliases.filter((x) => typeof x === 'string') : [], package: redactText(pkg.name), version: redactText(pkg.version), ecosystem: pkg.ecosystem,
+                        file: doc.file, summary: redactText(String(vuln.summary ?? vuln.id).slice(0, 2000)), severity: vuln.database_specific?.severity ?? vuln.ecosystem_specific?.severity ?? 'unknown', fixedVersions: [...new Set(fixedVersions)].slice(0, 50), url: 'https://osv.dev/vulnerability/' + encodeURIComponent(vuln.id) });
+                }
+            }
+        }
+        return { mode, coverage: { ...health, status: incomplete ? 'partial' : packagesScanned ? 'completed' : 'not-run', ...(incomplete ? { reason: 'incomplete-coverage' } : !packagesScanned ? { reason: 'no-resolved-packages' } : {}), findingsCount: vulnerabilities.length }, packagesScanned, vulnerabilities };
+    }
+    finally {
+        await owned.dispose();
+    }
+}

package/lib/extra.d.ts

@@ -5,4 +5,5 @@
  */
 import { type ResolvedSecureConfig } from './config.js';
 import type { SecureToolDefinition } from './tools.js';
-export declare function buildExtraTools(cfg: ResolvedSecureConfig, cwd: string, signal?: AbortSignal): SecureToolDefinition[];
+import type { ProcessRunner } from './runner.js';
+export declare function buildExtraTools(cfg: ResolvedSecureConfig, cwd: string, signal?: AbortSignal, runner?: ProcessRunner): SecureToolDefinition[];

package/lib/extra.js

@@ -7,6 +7,10 @@ import path from 'node:path';
 import { optionalString, requiredString } from './config.js';
 import { scanDeps } from './deps.js';
 import { findingFingerprint, loadState, saveBaseline } from './state.js';
+import { scanArguments } from './tools.js';
+import { auditDependencies } from './engines.js';
+import { loadPolicy } from './policy.js';
+import fs from 'node:fs/promises';
 function compileParameters(spec) {
     const properties = {};
     const required = [];
@@ -18,11 +22,13 @@ function compileParameters(spec) {
             node.type = prop.type;
         if (typeof prop?.description === 'string')
             node.description = prop.description;
+        if (prop?.enum !== undefined)
+            node.enum = prop.enum;
         properties[key] = node;
     }
     return { type: 'object', properties, ...(required.length > 0 ? { required } : {}) };
 }
-export function buildExtraTools(cfg, cwd, signal) {
+export function buildExtraTools(cfg, cwd, signal, runner) {
     const stateDir = cfg.stateDir;
     const secureBaseline = {
         name: 'secure_baseline',
@@ -58,9 +64,10 @@ export function buildExtraTools(cfg, cwd, signal) {
     };
     const secureDeps = {
         name: 'secure_deps',
-        description: 'SBOM-lite：解析项目依赖清单（package.json / requirements.txt / pyproject.toml / go.mod / Cargo.toml / composer.json / Gemfile），列出依赖名称、版本约束与风险标记（wildcard/git/local/unpinned）。不联网。',
+        description: '解析依赖清单与锁文件。默认仅离线清单；audit=offline 使用本地 OSV 数据库，audit=online 明确允许向 OSV 查询包名/版本等依赖信息。不执行包管理器或安装脚本。清单检查不等于已知漏洞审计。',
         parameters: compileParameters({
             target: { type: 'string', description: '扫描根目录（可选，默认当前工作区）。' },
+            audit: { type: 'string', enum: ['none', 'offline', 'online'], description: '默认 none。offline 需要本地漏洞库；online 会向 OSV 查询依赖信息，不上传源码。' },
         }),
         output: {
             schema: {
@@ -85,10 +92,28 @@ export function buildExtraTools(cfg, cwd, signal) {
             },
         },
         async execute(rawArgs) {
-            const args = (rawArgs ?? {});
+            const args = scanArguments(rawArgs, ['target', 'audit']);
+            const mode = args.audit ?? 'none';
+            if (!['none', 'offline', 'online'].includes(String(mode)))
+                throw new Error('audit 只支持 none、offline、online');
             const target = optionalString(args, 'target');
             const root = path.resolve(cwd, target ?? '.');
-            return scanDeps(root);
+            const documents = [];
+            let bytes = 0, truncated = false;
+            const rootDir = (await fs.lstat(root)).isDirectory() ? root : path.dirname(root);
+            const inventory = await scanDeps(root, { maxFiles: cfg.maxFiles, maxFileBytes: cfg.maxFileBytes, signal, policy: await loadPolicy(cwd),
+                ...(mode === 'none' ? {} : { onDocument(doc) { if (bytes + Buffer.byteLength(doc.text) > 64 * 1024 * 1024) {
+                        truncated = true;
+                        return;
+                    } ; bytes += Buffer.byteLength(doc.text); documents.push({ file: path.relative(cwd, path.join(rootDir, doc.file)).split(path.sep).join('/'), text: doc.text }); } }) });
+            if (mode === 'none')
+                return { ...inventory, audited: false, audit: null };
+            if (!runner)
+                throw new Error('OSV 审计需要宿主 subprocess 服务');
+            const audit = await auditDependencies(documents, mode, cfg, runner, signal);
+            if (truncated && audit.coverage.status === 'completed')
+                audit.coverage = { ...audit.coverage, status: 'partial', reason: 'snapshot-size-limit' };
+            return { ...inventory, audited: audit.coverage.status === 'completed', audit, passed: inventory.complete && audit.coverage.status === 'completed' && audit.vulnerabilities.length === 0 };
         },
         timeoutMs: 30000,
     };

package/lib/index.d.ts

@@ -3,8 +3,8 @@
  *
  * 插件导出 apply(ctx, config)：注册 secure_scan / secure_diff / secure_fix_verify /
  * secure_report / secure_export / secure_baseline / secure_deps / secure_policy_show /
- * secure_policy_set / secure_health 十个工具。扫描为纯确定性规则，
- * git diff 通过官方 subprocess 服务执行，仅依赖文件锁库。
+ * secure_policy_set / secure_health 十个工具。内置规则与可选本地引擎共用
+ * 脱敏、覆盖状态与基线；子进程通过官方服务执行，设置面板与自动检查按需挂载。
  *
  * @module dsh-code-security
  */
@@ -23,6 +23,7 @@ export interface SecurePluginContext {
     on?(event: string, listener: (...args: any[]) => unknown, options?: {
         prepend?: boolean;
     }): (() => void) | void;
+    inject?(services: string[], callback: (ctx: any) => void): unknown;
 }
 export declare function apply(ctx: SecurePluginContext, config?: SecureConfig | null): void;
 export * from './config.js';
@@ -35,3 +36,8 @@ export * from './scanner.js';
 export * from './state.js';
 export * from './extra.js';
 export * from './tools.js';
+export * from './engines.js';
+export * from './audit.js';
+export * from './privacy.js';
+export * from './workbench.js';
+export * from './automatic.js';

package/lib/index.js

@@ -3,30 +3,65 @@
  *
  * 插件导出 apply(ctx, config)：注册 secure_scan / secure_diff / secure_fix_verify /
  * secure_report / secure_export / secure_baseline / secure_deps / secure_policy_show /
- * secure_policy_set / secure_health 十个工具。扫描为纯确定性规则，
- * git diff 通过官方 subprocess 服务执行，仅依赖文件锁库。
+ * secure_policy_set / secure_health 十个工具。内置规则与可选本地引擎共用
+ * 脱敏、覆盖状态与基线；子进程通过官方服务执行，设置面板与自动检查按需挂载。
  *
  * @module dsh-code-security
  */
 import { resolveConfig } from './config.js';
 import { createSubprocessRunner } from './runner.js';
 import { buildSecureTools } from './tools.js';
+import { SecurityWorkbench, installSecurityWorkbench } from './workbench.js';
+import { AutomaticSecurity } from './automatic.js';
 export const name = 'code-security';
 export const inject = ['tools', 'subprocess'];
 export function apply(ctx, config) {
     let cfg;
+    let configurationError;
     try {
         cfg = resolveConfig(config);
     }
     catch (error) {
-        console.warn('[dsh-code-security] ' + (error instanceof Error ? error.message : String(error)));
+        configurationError = error instanceof Error ? error.message : String(error);
+        console.warn('[dsh-code-security] ' + configurationError);
         cfg = resolveConfig(null);
     }
     const runner = createSubprocessRunner((spec) => ctx.subprocess.spawn(spec), 10000, 60000);
-    const tools = buildSecureTools(cfg, process.cwd(), runner);
+    const configuredTools = (config, root) => buildSecureTools(config, root, runner).map(definition => ({ ...definition, async execute(args, exec) {
+            if (configurationError && ['secure_scan', 'secure_diff', 'secure_fix_verify', 'secure_deps', 'secure_baseline'].includes(definition.name))
+                throw new Error('请先修复插件配置，检查未运行 / Fix the plugin configuration before scanning: ' + configurationError);
+            const value = await definition.execute(args, exec);
+            return configurationError && definition.name === 'secure_health' ? { ...value, ok: false, configurationError } : value;
+        } }));
+    const tools = configuredTools(cfg, process.cwd());
     const disposers = [];
+    const workbench = typeof ctx.inject === 'function' ? new SecurityWorkbench(cfg, { tools: configuredTools }) : undefined;
+    if (workbench) {
+        installSecurityWorkbench(ctx, workbench);
+        const automatic = new AutomaticSecurity(workbench);
+        ctx.inject?.(['sessions', 'systemPrompt'], host => {
+            const detach = automatic.attach(host);
+            if (typeof host.effect === 'function')
+                host.effect(() => detach);
+            else
+                host.on?.('dispose', detach);
+        });
+        ctx.on?.('dispose', async () => { automatic.dispose(); await automatic.whenIdle(); await workbench.dispose(); });
+    }
     for (const definition of tools) {
-        disposers.push(ctx.tools.register(definition));
+        disposers.push(ctx.tools.register({ ...definition, async execute(args, exec) {
+                if (!workbench)
+                    return definition.execute(args, exec);
+                const context = exec;
+                const root = context?.agent?.session?.header?.cwd || process.cwd();
+                const configured = configuredTools(await workbench.configFor(root), root).find(t => t.name === definition.name);
+                const value = await configured.execute(args, exec);
+                try {
+                    await workbench.remember(root, context?.agent?.session?.id);
+                }
+                catch { /* Indexing must not turn a successful check into an error. */ }
+                return value;
+            } }));
     }
     if (typeof ctx.on === 'function') {
         ctx.on('tools/pre-execute', async (exec, next) => {
@@ -56,3 +91,8 @@ export * from './scanner.js';
 export * from './state.js';
 export * from './extra.js';
 export * from './tools.js';
+export * from './engines.js';
+export * from './audit.js';
+export * from './privacy.js';
+export * from './workbench.js';
+export * from './automatic.js';

package/lib/privacy.d.ts

@@ -0,0 +1,7 @@
+import type { Finding } from './scanner.js';
+export declare function isHighEntropyToken(value: string): boolean;
+export declare function evidenceFingerprint(finding: Pick<Finding, 'ruleId' | 'file' | 'snippet'> & {
+    fingerprint?: string;
+}): string;
+export declare function redactText(text: string): string;
+export declare function protectFinding(finding: Finding): Finding;

package/lib/privacy.js

@@ -0,0 +1,54 @@
+/** Findings crossing the scanner boundary never contain complete credentials. */
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+export function isHighEntropyToken(value) {
+    if (value.length < 24 || !/\d/.test(value) || /^[0-9]+$/.test(value))
+        return false;
+    const counts = new Map();
+    for (const char of value)
+        counts.set(char, (counts.get(char) ?? 0) + 1);
+    let entropy = 0;
+    for (const count of counts.values()) {
+        const frequency = count / value.length;
+        entropy -= frequency * Math.log2(frequency);
+    }
+    return entropy >= 3.8;
+}
+export function evidenceFingerprint(finding) {
+    if (/^[a-f0-9]{64}$/.test(finding.fingerprint ?? ''))
+        return finding.fingerprint;
+    const file = finding.file.split(path.sep).join('/').replace(/^(?:\.\/)+/, '');
+    return createHash('sha256').update(finding.ruleId + '|' + file + '|' + finding.snippet.trim()).digest('hex');
+}
+export function redactText(text) {
+    return text
+        .replace(/-----BEGIN (?:[A-Z]+ )?PRIVATE KEY-----[\s\S]*?(?:-----END (?:[A-Z]+ )?PRIVATE KEY-----|$)/g, '[REDACTED PRIVATE KEY]')
+        .replace(/((?:[\w.-]*(?:password|passwd|pwd|secret|token|api[_-]?key|access[_-]?key|authorization)[\w.-]*)["']?\s*[:=]\s*)(["'`])([^\r\n]*?)(?:\2|$)/gim, '$1$2[REDACTED]$2')
+        .replace(/((?:[\w.-]*(?:password|passwd|pwd|secret|token|api[_-]?key|access[_-]?key|authorization)[\w.-]*)["']?\s*[:=]\s*)(?!["'`\s]|\[REDACTED\b)[^\s,;}\]]+/gi, '$1[REDACTED]')
+        .replace(/(^\s*[A-Z0-9_]*(?:KEY|TOKEN|SECRET|PASSWORD|PASS)[A-Z0-9_]*\s*=\s*)([^\r\n]+)/gm, '$1[REDACTED]')
+        .replace(/\b(?:gh[pousr]_[A-Za-z0-9_]{16,}|github_pat_[A-Za-z0-9_]{20,}|sk-(?:proj-)?[A-Za-z0-9_-]{16,}|AKIA[A-Z0-9]{16})\b/g, '[REDACTED]')
+        .replace(/(\bBearer\s+)[A-Za-z0-9._~+\/-]{12,}/gi, '$1[REDACTED]')
+        .replace(/(https?:\/\/)[^\s/@]+:[^\s/@]+@/g, '$1[REDACTED]@')
+        // A credential must stay redacted when another rule reports the same source line.
+        .replace(/(['"`])([A-Za-z0-9+/=_-]{24,})(?:\1|$)/g, (match, quote, value) => isHighEntropyToken(value) ? quote + '[REDACTED]' + quote : match);
+}
+export function protectFinding(finding) {
+    const fingerprint = evidenceFingerprint(finding);
+    let snippet = redactText(finding.snippet);
+    if (finding.ruleId === 'SEC-203')
+        snippet = snippet.replace(/(["'])([^\r\n]*?)\1/g, '$1[REDACTED]$1');
+    // Entropy/external secret rules can identify values without an assignment.
+    if (finding.ruleId === 'SEC-304' || finding.engine === 'betterleaks')
+        snippet = '[REDACTED SECRET]';
+    if (finding.ruleId === 'SEC-303')
+        snippet = '[REDACTED PRIVATE KEY]';
+    if (finding.ruleId === 'SEC-305')
+        snippet = snippet.replace(/(=)[\s\S]*/, '$1[REDACTED]');
+    return { id: finding.id, ruleId: finding.ruleId, file: finding.file, line: finding.line,
+        severity: finding.severity, confidence: finding.confidence, cwe: finding.cwe,
+        ...(finding.endLine === undefined ? {} : { endLine: finding.endLine }),
+        ...(finding.engine === undefined ? {} : { engine: finding.engine }),
+        ...(finding.evidence === undefined ? {} : { evidence: finding.evidence }),
+        ...(finding.sources === undefined ? {} : { sources: finding.sources }),
+        fingerprint, snippet, message: redactText(finding.message), title: redactText(finding.title) };
+}

package/lib/rules.js

@@ -19,7 +19,7 @@ export const RULES = Object.freeze([
     { id: 'SEC-006', title: 'Shell 管道下载执行', cwe: 'CWE-78', severity: 'critical', confidence: 'high', languages: SHELL, patterns: [/\bcurl\b[^|\n]*\|\s*(?:sudo\s+)?(?:ba|z|k|da)?sh\b/i, /\bwget\b[^|\n]*\|\s*(?:sudo\s+)?(?:ba|z|k|da)?sh\b/i], message: '下载内容直接通过管道交给 shell 执行。' },
     { id: 'SEC-007', title: 'JavaScript SQL 字符串拼接', cwe: 'CWE-89', severity: 'high', confidence: 'medium', languages: JS, patterns: [/['"](?:SELECT|INSERT|UPDATE|DELETE)\b[^'"]*['"]\s*\+/i, /\bquery\s*=\s*['"][^'"]*['"]\s*\+/i], message: 'SQL 语句与变量拼接，疑似可注入。' },
     { id: 'SEC-008', title: 'Python SQL 字符串格式化', cwe: 'CWE-89', severity: 'high', confidence: 'medium', languages: PY, patterns: [/\.execute\s*\([^)]*(?:%\s*\(|%\s*[a-z_]|\bf\s*['"]|\+\s*str\()/i], message: 'SQL 执行语句使用字符串格式化或拼接。' },
-    { id: 'SEC-009', title: 'JavaScript innerHTML / 危险 HTML 注入', cwe: 'CWE-79', severity: 'high', confidence: 'medium', languages: JS, patterns: [/\.innerHTML\s*=/, /\bdangerouslySetInnerHTML\b/], message: '将不可信内容写入 HTML 插值点。' },
+    { id: 'SEC-009', title: 'HTML 写入点需要核对输入来源', cwe: 'CWE-79', severity: 'medium', confidence: 'low', languages: JS, patterns: [/\.innerHTML\s*=/, /\bdangerouslySetInnerHTML\b/], message: '发现 HTML 写入接口。这是模式提示，尚未证明输入未经净化；已验证绑定的默认 DOMPurify.sanitize 调用不报告。' },
     { id: 'SEC-010', title: '开放重定向', cwe: 'CWE-601', severity: 'medium', confidence: 'medium', languages: JS, patterns: [/\bredirect\s*\(\s*(?:req|request)\.(?:query|params|body)/i, /\blocation\s*=\s*(?:req|request)\.(?:query|params|body)/i], message: '跳转目标直接取自请求参数。' },
     { id: 'SEC-101', title: 'Python pickle 反序列化', cwe: 'CWE-502', severity: 'critical', confidence: 'high', languages: PY, patterns: [/\bpickle\.(?:loads?)\s*\(/], message: 'pickle 反序列化不可信数据。' },
     { id: 'SEC-102', title: 'Python yaml.load 不安全解析', cwe: 'CWE-502', severity: 'high', confidence: 'medium', languages: PY, patterns: [/\byaml\.load\s*\(/], message: 'yaml.load 未使用 SafeLoader。' },

package/lib/runner.d.ts

@@ -14,6 +14,7 @@ export interface ProcessRunner {
         timeoutMs?: number;
         cwd?: string;
         signal?: AbortSignal;
+        env?: Record<string, string>;
     }): Promise<RunResult>;
 }
 export interface SubprocessHandleLike {
@@ -25,11 +26,13 @@ export interface SubprocessHandleLike {
         stdout?: {
             readFrom(offset: number): {
                 text: string;
+                lossy?: boolean;
             };
         };
         stderr?: {
             readFrom(offset: number): {
                 text: string;
+                lossy?: boolean;
             };
         };
     };
@@ -50,6 +53,7 @@ export interface SubprocessSpawnLike {
         };
         graceMs: number;
         signal?: AbortSignal;
+        env?: Record<string, string>;
     }): SubprocessHandleLike;
 }
 export declare function createSubprocessRunner(spawn: SubprocessSpawnLike, graceMs: number, defaultTimeoutMs: number): ProcessRunner;

package/lib/runner.js

@@ -11,7 +11,7 @@ export function createSubprocessRunner(spawn, graceMs, defaultTimeoutMs) {
             const controller = new AbortController();
             const signal = options?.signal ? AbortSignal.any([options.signal, controller.signal]) : controller.signal;
             signal.throwIfAborted();
-            const timer = setTimeout(() => controller.abort(new Error('git diff timed out')), timeoutMs);
+            const timer = setTimeout(() => controller.abort(new Error('scanner subprocess timed out')), timeoutMs);
             try {
                 const handle = spawn({
                     argv,
@@ -19,13 +19,18 @@ export function createSubprocessRunner(spawn, graceMs, defaultTimeoutMs) {
                     stdio: { stdin: 'ignore', stdout: { maxBytes: COLLECT_BYTES }, stderr: { maxBytes: COLLECT_BYTES } },
                     graceMs,
                     signal,
+                    ...(options?.env ? { env: options.env } : {}),
                 });
                 const outcome = await handle.done;
+                signal.throwIfAborted();
+                const stdout = handle.collected.stdout?.readFrom(0), stderr = handle.collected.stderr?.readFrom(0);
+                if (stdout?.lossy || stderr?.lossy)
+                    throw new Error('scanner subprocess output exceeded 8 MiB; this check is incomplete');
                 return {
                     exitCode: outcome.exitCode,
                     signal: outcome.signal,
-                    stdout: handle.collected.stdout?.readFrom(0).text ?? '',
-                    stderr: handle.collected.stderr?.readFrom(0).text ?? '',
+                    stdout: stdout?.text ?? '',
+                    stderr: stderr?.text ?? '',
                 };
             }
             finally {

package/lib/scanner.d.ts

@@ -6,6 +6,11 @@
 import { type Severity } from './config.js';
 import { type SecurePolicy } from './policy.js';
 export interface Finding {
+    endLine?: number;
+    fingerprint?: string;
+    engine?: 'builtin' | 'betterleaks' | 'semgrep';
+    evidence?: 'pattern' | 'dataflow';
+    sources?: string[];
     id: string;
     ruleId: string;
     title: string;
@@ -18,6 +23,8 @@ export interface Finding {
     message: string;
 }
 export interface ScanResult {
+    complete: boolean;
+    warnings: string[];
     root: string;
     filesScanned: number;
     filesSkipped: number;
@@ -25,6 +32,10 @@ export interface ScanResult {
     durationMs: number;
 }
 export interface ScanOptions {
+    onDocument?: (document: {
+        file: string;
+        text: string;
+    }) => void;
     cwd: string;
     target?: string;
     maxFiles: number;
@@ -37,7 +48,7 @@ export interface LineEntry {
     text: string;
 }
 /** 对带行号的文本行应用规则（全量扫描与 git diff 增量扫描共用）。 */
-export declare function scanLineSet(entries: LineEntry[], rel: string, policy: SecurePolicy, selectedLines?: ReadonlySet<number>): Finding[];
+export declare function scanLineSet(entries: LineEntry[], rel: string, policy: SecurePolicy, selectedLines?: ReadonlySet<number>, sanitized?: ReadonlySet<number>): Finding[];
 /** 扫描单个文件内容，按语言与行应用规则。 */
 export declare function scanText(content: string, file: string, rel: string, policy: SecurePolicy): Finding[];
 /** Apply the same exclusions to full scans, directly selected files and diffs. */