dsh-code-security 0.2.2

package/lib/index.js

@@ -0,0 +1,51 @@
+/**
+ * dsh-code-security —— AI 代码安全审查插件（node 半身，配置走 cordis.patch.yml）。
+ *
+ * 插件导出 apply(ctx, config)：注册 secure_scan / secure_diff / secure_fix_verify /
+ * secure_report / secure_export / secure_policy_show / secure_policy_set 七个工具。扫描为纯确定性规则，
+ * git diff 通过官方 subprocess 服务执行，零运行时依赖。
+ *
+ * @module dsh-code-security
+ */
+import { resolveConfig } from './config.js';
+import { createSubprocessRunner } from './runner.js';
+import { buildSecureTools } from './tools.js';
+export const inject = ['tools', 'subprocess'];
+export function apply(ctx, config) {
+    let cfg;
+    try {
+        cfg = resolveConfig(config);
+    }
+    catch (error) {
+        console.warn('[dsh-code-security] ' + (error instanceof Error ? error.message : String(error)));
+        cfg = resolveConfig(null);
+    }
+    const runner = createSubprocessRunner(ctx.subprocess.spawn, 10000, 60000);
+    const tools = buildSecureTools(cfg, process.cwd(), runner);
+    const disposers = [];
+    for (const definition of tools) {
+        const wrapped = { ...definition };
+        if (wrapped.gate !== undefined) {
+            const original = wrapped.gate.bind(wrapped);
+            wrapped.gate = async (exec, next) => {
+                const record = (typeof exec === 'object' && exec !== null ? exec : {});
+                return original({ ...record, approval: ctx.get?.('approval') }, next);
+            };
+        }
+        disposers.push(ctx.tools.register(wrapped, { prepend: true }));
+    }
+    if (typeof ctx.on === 'function') {
+        ctx.on('dispose', () => { for (const dispose of disposers)
+            dispose(); });
+    }
+}
+export * from './config.js';
+export * from './deps.js';
+export * from './diff.js';
+export * from './policy.js';
+export * from './rules.js';
+export * from './runner.js';
+export * from './scanner.js';
+export * from './state.js';
+export * from './extra.js';
+export * from './tools.js';

package/lib/policy.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 项目策略文件 .code-security.json：排除目录、忽略规则与门禁阈值。
+ *
+ * @module dsh-code-security/policy
+ */
+export interface PolicyIgnore {
+    ruleId?: string;
+    file?: string;
+    reason?: string;
+}
+export interface SecurePolicy {
+    version: 1;
+    exclude: string[];
+    ignore: PolicyIgnore[];
+    failOn?: 'critical' | 'high' | 'medium' | 'low';
+}
+export declare const DEFAULT_POLICY: SecurePolicy;
+export declare const POLICY_FILE = ".code-security.json";
+export declare function policyPath(cwd: string): string;
+export declare function loadPolicy(cwd: string): Promise<SecurePolicy>;
+export declare function normalizePolicy(obj: Record<string, unknown>): SecurePolicy;
+export declare function savePolicy(cwd: string, policy: SecurePolicy): Promise<string>;
+export declare function policyExcludesDir(policy: SecurePolicy, rel: string): boolean;
+export declare function policyIgnores(policy: SecurePolicy, ruleId: string, file: string): boolean;

package/lib/policy.js

@@ -0,0 +1,67 @@
+/**
+ * 项目策略文件 .code-security.json：排除目录、忽略规则与门禁阈值。
+ *
+ * @module dsh-code-security/policy
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+export const DEFAULT_POLICY = Object.freeze({
+    version: 1,
+    exclude: [],
+    ignore: [],
+});
+export const POLICY_FILE = '.code-security.json';
+export function policyPath(cwd) {
+    return path.join(cwd, POLICY_FILE);
+}
+export async function loadPolicy(cwd) {
+    try {
+        const text = await fs.readFile(policyPath(cwd), 'utf8');
+        const parsed = JSON.parse(text);
+        const obj = (parsed ?? {});
+        return normalizePolicy(obj);
+    }
+    catch {
+        return { ...DEFAULT_POLICY, exclude: [...DEFAULT_POLICY.exclude], ignore: [] };
+    }
+}
+export function normalizePolicy(obj) {
+    const exclude = Array.isArray(obj.exclude) ? obj.exclude.filter((x) => typeof x === 'string') : [];
+    const ignoreRaw = Array.isArray(obj.ignore) ? obj.ignore : [];
+    const ignore = [];
+    for (const item of ignoreRaw) {
+        if (typeof item !== 'object' || item === null)
+            continue;
+        const rec = item;
+        ignore.push({
+            ruleId: typeof rec.ruleId === 'string' && rec.ruleId !== '' ? rec.ruleId : undefined,
+            file: typeof rec.file === 'string' && rec.file !== '' ? rec.file : undefined,
+            reason: typeof rec.reason === 'string' ? rec.reason : '',
+        });
+    }
+    const failOn = obj.failOn === 'critical' || obj.failOn === 'high' || obj.failOn === 'medium' || obj.failOn === 'low' ? obj.failOn : undefined;
+    return { version: 1, exclude, ignore, failOn };
+}
+export async function savePolicy(cwd, policy) {
+    const file = policyPath(cwd);
+    const tmp = file + '.tmp-' + process.pid;
+    await fs.writeFile(tmp, JSON.stringify(policy, null, 2) + '\n', 'utf8');
+    await fs.rename(tmp, file);
+    return file;
+}
+function globToRegex(glob) {
+    const escaped = glob.replace(/[.+^$()|{}]/g, '\\$&').replace(/\*\*/g, '§§').replace(/\*/g, '[^/]*').replace(/§§/g, '.*');
+    return new RegExp('(^|/)' + escaped + '($|/)');
+}
+export function policyExcludesDir(policy, rel) {
+    return policy.exclude.some((pattern) => globToRegex(pattern).test(rel));
+}
+export function policyIgnores(policy, ruleId, file) {
+    return policy.ignore.some((item) => {
+        if (item.ruleId !== undefined && item.ruleId !== ruleId)
+            return false;
+        if (item.file !== undefined && !globToRegex(item.file).test(file))
+            return false;
+        return true;
+    });
+}

package/lib/rules.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 确定性安全规则库。每条规则只报告事实模式，不包含修复建议。
+ *
+ * @module dsh-code-security/rules
+ */
+import type { Severity } from './config.js';
+export type Language = 'javascript' | 'python' | 'go' | 'java' | 'ruby' | 'php' | 'shell' | 'yaml' | 'dockerfile' | 'json' | 'env' | 'any';
+export interface SecurityRule {
+    id: string;
+    title: string;
+    cwe: string;
+    severity: Severity;
+    confidence: 'high' | 'medium' | 'low';
+    languages: Language[];
+    patterns: RegExp[];
+    message: string;
+    fileLevel?: boolean;
+}
+export declare const RULES: readonly SecurityRule[];
+/** 规则类别：供报告聚合与排序使用。 */
+export declare function ruleCategory(ruleId: string): string;
+export declare function languageForFile(file: string): Language;

package/lib/rules.js

@@ -0,0 +1,101 @@
+/**
+ * 确定性安全规则库。每条规则只报告事实模式，不包含修复建议。
+ *
+ * @module dsh-code-security/rules
+ */
+const JS = ['javascript'];
+const PY = ['python'];
+const JAVA = ['java'];
+const SHELL = ['shell'];
+const YAML = ['yaml'];
+const DOCKER = ['dockerfile'];
+const ALL = ['any'];
+export const RULES = Object.freeze([
+    { id: 'SEC-001', title: 'JavaScript eval / Function 动态执行', cwe: 'CWE-95', severity: 'critical', confidence: 'high', languages: JS, patterns: [/\beval\s*\(/, /\bnew\s+Function\s*\(/], message: '发现 eval 或 new Function 动态代码执行。' },
+    { id: 'SEC-002', title: 'Node.js exec 使用 shell 执行命令', cwe: 'CWE-78', severity: 'high', confidence: 'high', languages: JS, patterns: [/\bexecSync\s*\(/, /child_process\s*\.\s*exec(?:Sync)?\s*\(/], message: 'child_process exec/execSync 经 shell 解释命令字符串。' },
+    { id: 'SEC-003', title: 'Node.js spawn shell: true', cwe: 'CWE-78', severity: 'high', confidence: 'high', languages: JS, patterns: [/\bspawn(?:Sync)?\s*\([^)]*\{\s*shell\s*:\s*true/], message: 'spawn 显式启用了 shell 解释。' },
+    { id: 'SEC-004', title: 'Python subprocess shell=True', cwe: 'CWE-78', severity: 'critical', confidence: 'high', languages: PY, patterns: [/\bsubprocess\.(?:run|call|Popen|check_output|check_call)\s*\([^)]*shell\s*=\s*True/], message: 'subprocess 调用启用 shell=True。' },
+    { id: 'SEC-005', title: 'Python os.system / popen', cwe: 'CWE-78', severity: 'high', confidence: 'high', languages: PY, patterns: [/\bos\.(?:system|popen)\s*\(/], message: '使用 os.system/os.popen 执行 shell 命令。' },
+    { 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-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。' },
+    { id: 'SEC-103', title: 'Java 原生反序列化', cwe: 'CWE-502', severity: 'high', confidence: 'medium', languages: JAVA, patterns: [/\bObjectInputStream\b/, /\.readObject\s*\(/], message: '使用 Java 原生对象反序列化。' },
+    { id: 'SEC-104', title: 'Ruby 危险反序列化', cwe: 'CWE-502', severity: 'high', confidence: 'medium', languages: ['ruby'], patterns: [/\bMarshal\.load\s*\(/, /\bYAML\.load\s*\(/], message: 'Ruby 反序列化不可信对象。' },
+    { id: 'SEC-105', title: 'PHP 反序列化', cwe: 'CWE-502', severity: 'high', confidence: 'medium', languages: ['php'], patterns: [/\bunserialize\s*\(/], message: 'unserialize 处理不可信输入。' },
+    { id: 'SEC-201', title: '弱哈希用于安全场景', cwe: 'CWE-328', severity: 'high', confidence: 'medium', languages: ALL, patterns: [/\bcreateHash\s*\(\s*['"]?(?:md5|sha1)['"]?/i, /\bhashlib\.(?:md5|sha1)\s*\(/i, /\b(?:md5|sha1)(?:sum)?\s+/i], message: '使用 MD5 / SHA1 弱哈希。' },
+    { id: 'SEC-202', title: 'ECB 分组加密模式', cwe: 'CWE-327', severity: 'high', confidence: 'medium', languages: ALL, patterns: [/aes[-_/]?\d*[-_/]?ecb/i, /['"]AES\/ECB/i], message: '使用 ECB 加密模式。' },
+    { id: 'SEC-203', title: '硬编码 IV / 密钥', cwe: 'CWE-321', severity: 'high', confidence: 'medium', languages: ALL, patterns: [/\.createCipheriv?\s*\([^)]*['"][A-Za-z0-9+/=]{12,}['"]/, /\b(?:iv|key|secret)\s*[:=]\s*['"][A-Za-z0-9+/=]{16,}['"]/i], message: '加密密钥或 IV 以字面量硬编码。' },
+    { id: 'SEC-204', title: 'JWT alg none / 不校验签名', cwe: 'CWE-347', severity: 'critical', confidence: 'high', languages: JS, patterns: [/['"]?alg['"]?\s*[:=]\s*['"]?none['"]?/i, /\bjwt\.verify\s*\([^)]*\{\s*algorithms\s*:\s*\[\s*['"]none/i], message: 'JWT 允许 none 算法或未校验签名。' },
+    { id: 'SEC-205', title: 'TLS 校验被禁用', cwe: 'CWE-295', severity: 'high', confidence: 'high', languages: ALL, patterns: [/rejectUnauthorized\s*:\s*false/, /\bverify\s*=\s*False/, /InsecureSkipVerify\s*:\s*true/], message: 'TLS 证书校验被显式关闭。' },
+    { id: 'SEC-206', title: 'Math.random 用于安全敏感逻辑', cwe: 'CWE-330', severity: 'low', confidence: 'low', languages: JS, patterns: [/\bMath\.random\s*\(/], message: '使用非密码学安全的 Math.random。' },
+    { id: 'SEC-301', title: '硬编码密码', cwe: 'CWE-798', severity: 'critical', confidence: 'high', languages: ALL, patterns: [/(?:password|passwd|pwd)\s*[:=]\s*['"][^'"]{4,}['"]/i], message: '密码以明文硬编码在源码中。' },
+    { id: 'SEC-302', title: '硬编码令牌 / API 密钥', cwe: 'CWE-798', severity: 'high', confidence: 'medium', languages: ALL, patterns: [/(?:api[_-]?key|secret[_-]?key|access[_-]?key|auth[_-]?token)\s*[:=]\s*['"][A-Za-z0-9_\-]{16,}['"]/i], message: '访问令牌或 API 密钥以字面量硬编码。' },
+    { id: 'SEC-303', title: '私钥材料', cwe: 'CWE-798', severity: 'critical', confidence: 'high', languages: ALL, patterns: [/-----BEGIN (?:RSA |EC |OPENSSH |DSA )?PRIVATE KEY-----/], message: '检测到私钥文件内容。', fileLevel: true },
+    { id: 'SEC-304', title: '疑似高熵密钥', cwe: 'CWE-798', severity: 'medium', confidence: 'medium', languages: ALL, patterns: [], message: '检测到高熵字符串，疑似密钥或令牌。' },
+    { id: 'SEC-401', title: 'chmod 777', cwe: 'CWE-732', severity: 'high', confidence: 'high', languages: ALL, patterns: [/(?:chmod|os\.chmod|fs\.chmod)\b[^\n;]*(?:777|0o777|0o?0777)/, /chmod\s+(?:-R\s+)?777/], message: '文件权限设置为 777。' },
+    { id: 'SEC-402', title: 'Docker privileged 模式', cwe: 'CWE-250', severity: 'high', confidence: 'high', languages: DOCKER, patterns: [/--privileged/], message: '容器以 privileged 特权模式运行。' },
+    { id: 'SEC-403', title: 'CORS 通配符', cwe: 'CWE-942', severity: 'medium', confidence: 'medium', languages: JS, patterns: [/(?:origin|allowedOrigins?)\s*[:=]\s*['"]?\*['"]?/i], message: 'CORS 允许任意来源。' },
+    { id: 'SEC-404', title: 'npm 禁用安全审计', cwe: 'CWE-693', severity: 'medium', confidence: 'high', languages: ['json', 'any'], patterns: [/"audit"\s*:\s*false/i, /^audit\s*=\s*false\b/im], message: '依赖审计被显式关闭。', fileLevel: true },
+    { id: 'SEC-405', title: '依赖安装使用 force / legacy-peer-deps', cwe: 'CWE-693', severity: 'medium', confidence: 'high', languages: SHELL, patterns: [/--force\b/, /--legacy-peer-deps\b/], message: '包安装使用了会绕过安全/兼容门禁的标志。' },
+    { id: 'SEC-406', title: 'Docker 使用 latest 标签', cwe: 'CWE-1104', severity: 'low', confidence: 'high', languages: DOCKER, patterns: [/\bFROM\s+\S+:latest\b/i], message: '基础镜像使用 latest 浮动标签。' },
+    { id: 'SEC-501', title: '日志打印敏感变量', cwe: 'CWE-532', severity: 'medium', confidence: 'medium', languages: ALL, patterns: [/(?:console\.log|log\.(?:info|debug)|print|printf|log\b)\s*\([^)]*(?:password|secret|token|api[_-]?key)/i], message: '日志输出包含疑似敏感变量。' },
+    { id: 'SEC-502', title: '错误信息包含内部细节', cwe: 'CWE-209', severity: 'low', confidence: 'medium', languages: JS, patterns: [/\.send\s*\(\s*(?:err|error)\.stack/i, /\bres\.(?:json|send)\s*\(\s*(?:err|error)\.message/i], message: '错误响应直接返回堆栈或内部错误消息。' },
+    { id: 'SEC-601', title: '路径拼接来自请求参数', cwe: 'CWE-22', severity: 'high', confidence: 'medium', languages: JS, patterns: [/(?:path\.join|readFile(?:Sync)?|writeFile(?:Sync)?|open(?:Sync)?)\s*\([^)]*(?:req|request)\.(?:query|params|body)/i], message: '文件路径由请求参数参与拼接。' },
+    { id: 'SEC-602', title: 'SSRF：请求目标来自用户输入', cwe: 'CWE-918', severity: 'high', confidence: 'medium', languages: JS, patterns: [/(?:fetch|axios\.get|axios\(|request\()\s*\(\s*(?:req|request)\.(?:query|params|body)/i], message: '请求 URL 直接取自用户输入。' },
+    { id: 'SEC-011', title: 'PHP 命令执行函数', cwe: 'CWE-78', severity: 'critical', confidence: 'high', languages: ['php'], patterns: [/\b(?:system|exec|shell_exec|passthru|proc_open)\s*\(/], message: '使用 PHP 命令执行函数。' },
+    { id: 'SEC-012', title: 'Ruby 命令执行函数', cwe: 'CWE-78', severity: 'high', confidence: 'high', languages: ['ruby'], patterns: [/\bsystem\s*\(/, /\bexec\s*\(/, /\bIO\.popen\s*\(/], message: '使用 Ruby 命令执行接口。' },
+    { id: 'SEC-013', title: 'Java Runtime.exec / ProcessBuilder', cwe: 'CWE-78', severity: 'high', confidence: 'medium', languages: JAVA, patterns: [/Runtime\.getRuntime\(\)\.exec\s*\(/, /\bnew\s+ProcessBuilder\s*\(/], message: '使用 Java 进程执行接口。' },
+    { id: 'SEC-014', title: 'Python eval / exec', cwe: 'CWE-95', severity: 'critical', confidence: 'high', languages: PY, patterns: [/\beval\s*\(/, /\bexec\s*\(/], message: '使用 Python 动态代码执行。' },
+    { id: 'SEC-015', title: 'tarfile.extractall 路径穿越', cwe: 'CWE-22', severity: 'high', confidence: 'medium', languages: PY, patterns: [/\.extractall\s*\(/], message: '压缩包提取未做成员路径校验。' },
+    { id: 'SEC-016', title: 'JavaScript document.write', cwe: 'CWE-79', severity: 'high', confidence: 'medium', languages: JS, patterns: [/\bdocument\.write\s*\(/], message: '使用 document.write 写入动态内容。' },
+    { id: 'SEC-017', title: 'Python 请求目标来自用户输入', cwe: 'CWE-918', severity: 'high', confidence: 'medium', languages: PY, patterns: [/\brequests\.(?:get|post|request)\s*\([^)]*(?:request|params|form|data|input)/i], message: 'HTTP 请求目标可能来自用户输入。' },
+    { id: 'SEC-305', title: '.env 包含敏感项', cwe: 'CWE-312', severity: 'high', confidence: 'medium', languages: ['env'], patterns: [/^(?:[A-Z0-9_]*(?:KEY|TOKEN|SECRET|PASSWORD|PASS)[A-Z0-9_]*)\s*=\s*.+/im], message: '.env 文件中包含敏感配置项。', fileLevel: true },
+    { id: 'SEC-306', title: 'Node crypto.createCipher 已废弃', cwe: 'CWE-327', severity: 'high', confidence: 'high', languages: JS, patterns: [/\bcrypto\.createCipher\s*\(/], message: '使用已废弃的非认证加密接口。' },
+    { id: 'SEC-407', title: 'GitHub Actions 使用浮动分支', cwe: 'CWE-1104', severity: 'low', confidence: 'high', languages: YAML, patterns: [/\buses\s*:\s*\S+@(?:main|master)\b/i], message: 'Action 未锁定到提交 SHA 或版本标签。' },
+    { id: 'SEC-408', title: 'Docker USER root', cwe: 'CWE-250', severity: 'low', confidence: 'high', languages: DOCKER, patterns: [/^\s*USER\s+root\b/im], message: '容器默认以 root 用户运行。' },
+    { id: 'SEC-603', title: 'Python 文件路径来自用户输入', cwe: 'CWE-22', severity: 'high', confidence: 'medium', languages: PY, patterns: [/\bopen\s*\([^)]*(?:request|params|form|input|filename)/i, /\bos\.path\.join\s*\([^)]*(?:request|params|form|input)/i], message: '文件路径可能由用户输入参与。' },
+]);
+/** 规则类别：供报告聚合与排序使用。 */
+export function ruleCategory(ruleId) {
+    const group = ruleId.slice(4, 6);
+    const map = {
+        '00': '注入',
+        '01': '反序列化',
+        '02': '加密与密钥',
+        '03': '凭据泄露',
+        '04': '配置与权限',
+        '05': '日志与信息泄露',
+        '06': '路径与网络',
+    };
+    return map[group] ?? '其他';
+}
+export function languageForFile(file) {
+    const name = file.toLowerCase();
+    if (/\.(?:js|mjs|cjs|jsx|ts|tsx)$/.test(name))
+        return 'javascript';
+    if (/\.py$/.test(name))
+        return 'python';
+    if (/\.go$/.test(name))
+        return 'go';
+    if (/\.java$/.test(name))
+        return 'java';
+    if (/\.rb$/.test(name))
+        return 'ruby';
+    if (/\.php$/.test(name))
+        return 'php';
+    if (/\.(?:sh|bash|zsh)$/.test(name) || name.endsWith('.bashrc') || name.endsWith('.zshrc'))
+        return 'shell';
+    if (/\.(?:ya?ml)$/.test(name))
+        return 'yaml';
+    if (name.endsWith('dockerfile'))
+        return 'dockerfile';
+    if (/\.json$/.test(name))
+        return 'json';
+    if (/\.env(?:\..*)?$/.test(name))
+        return 'env';
+    return 'any';
+}

package/lib/runner.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 子进程执行层：通过 DSH 官方 subprocess 服务运行 git diff。
+ *
+ * @module dsh-code-security/runner
+ */
+export interface RunResult {
+    exitCode: number | null;
+    signal: string | null;
+    stdout: string;
+    stderr: string;
+}
+export interface ProcessRunner {
+    run(argv: readonly string[], options?: {
+        timeoutMs?: number;
+    }): Promise<RunResult>;
+}
+export interface SubprocessHandleLike {
+    done: Promise<{
+        exitCode: number | null;
+        signal: string | null;
+    }>;
+    collected: {
+        stdout?: {
+            readFrom(offset: number): {
+                text: string;
+            };
+        };
+        stderr?: {
+            readFrom(offset: number): {
+                text: string;
+            };
+        };
+    };
+    terminate(): void;
+}
+export interface SubprocessSpawnLike {
+    (spec: {
+        argv: readonly string[];
+        cwd: string;
+        stdio: {
+            stdin: 'ignore';
+            stdout: {
+                maxBytes: number;
+            };
+            stderr: {
+                maxBytes: number;
+            };
+        };
+        graceMs: number;
+        signal?: AbortSignal;
+    }): SubprocessHandleLike;
+}
+export declare function createSubprocessRunner(spawn: SubprocessSpawnLike, graceMs: number, defaultTimeoutMs: number): ProcessRunner;

package/lib/runner.js

@@ -0,0 +1,35 @@
+/**
+ * 子进程执行层：通过 DSH 官方 subprocess 服务运行 git diff。
+ *
+ * @module dsh-code-security/runner
+ */
+const COLLECT_BYTES = 8 * 1024 * 1024;
+export function createSubprocessRunner(spawn, graceMs, defaultTimeoutMs) {
+    return {
+        async run(argv, options) {
+            const timeoutMs = options?.timeoutMs ?? defaultTimeoutMs;
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(new Error('git diff timed out')), timeoutMs);
+            let handle;
+            try {
+                handle = spawn({
+                    argv,
+                    cwd: process.cwd(),
+                    stdio: { stdin: 'ignore', stdout: { maxBytes: COLLECT_BYTES }, stderr: { maxBytes: COLLECT_BYTES } },
+                    graceMs,
+                    signal: controller.signal,
+                });
+            }
+            finally {
+                clearTimeout(timer);
+            }
+            const outcome = await handle.done;
+            return {
+                exitCode: outcome.exitCode,
+                signal: outcome.signal,
+                stdout: handle.collected.stdout?.readFrom(0).text ?? '',
+                stderr: handle.collected.stderr?.readFrom(0).text ?? '',
+            };
+        },
+    };
+}

package/lib/scanner.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 确定性安全扫描器：遍历文件、按语言应用规则、密钥熵检测、内联豁免。
+ *
+ * @module dsh-code-security/scanner
+ */
+import { type Severity } from './config.js';
+import { type SecurePolicy } from './policy.js';
+export interface Finding {
+    id: string;
+    ruleId: string;
+    title: string;
+    cwe: string;
+    severity: Severity;
+    confidence: 'high' | 'medium' | 'low';
+    file: string;
+    line: number;
+    snippet: string;
+    message: string;
+}
+export interface ScanResult {
+    root: string;
+    filesScanned: number;
+    filesSkipped: number;
+    findings: Finding[];
+    durationMs: number;
+}
+export interface ScanOptions {
+    cwd: string;
+    target?: string;
+    maxFiles: number;
+    maxFileBytes: number;
+    policy: SecurePolicy;
+}
+export interface LineEntry {
+    line: number;
+    text: string;
+}
+/** 对带行号的文本行应用规则（全量扫描与 git diff 增量扫描共用）。 */
+export declare function scanLineSet(entries: LineEntry[], rel: string, policy: SecurePolicy): Finding[];
+/** 扫描单个文件内容，按语言与行应用规则。 */
+export declare function scanText(content: string, file: string, rel: string, policy: SecurePolicy): Finding[];
+/** 扫描目录或单个文件。 */
+export declare function scanPath(options: ScanOptions): Promise<ScanResult>;

package/lib/scanner.js

@@ -0,0 +1,235 @@
+/**
+ * 确定性安全扫描器：遍历文件、按语言应用规则、密钥熵检测、内联豁免。
+ *
+ * @module dsh-code-security/scanner
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { DEFAULT_EXCLUDE_DIRS } from './config.js';
+import { languageForFile, RULES } from './rules.js';
+import { policyExcludesDir, policyIgnores } from './policy.js';
+const DISABLE_NEXT = /secure-review-disable-next-line(?:\s+([\w,-]+))?/;
+const DISABLE_LINE = /secure-review-disable-line(?:\s+([\w,-]+))?/;
+function isComment(line) {
+    const t = line.trim();
+    return t.startsWith('//') || t.startsWith('#') || t.startsWith('/*') || t.startsWith('*');
+}
+function disabledRules(line, pattern) {
+    const m = pattern.exec(line);
+    if (m === null)
+        return null;
+    if (m[1] === undefined)
+        return [];
+    return m[1].split(',').map((x) => x.trim()).filter((x) => x !== '');
+}
+function shouldSkipLine(rule, disabled) {
+    if (disabled === null || disabled === undefined)
+        return false;
+    if (disabled.length === 0)
+        return true;
+    return disabled.includes(rule.id);
+}
+function fileHasBinary(buffer) {
+    const sample = buffer.subarray(0, Math.min(buffer.length, 8000));
+    for (const byte of sample)
+        if (byte === 0)
+            return true;
+    return false;
+}
+const TEXT_EXTENSIONS = /\.(?:js|mjs|cjs|jsx|ts|tsx|py|go|java|rb|php|sh|bash|zsh|ya?ml|json|env|dockerfile|txt|md|html|css|vue|svelte)$/i;
+function shouldScanFile(file) {
+    const base = path.basename(file).toLowerCase();
+    if (base === 'dockerfile')
+        return true;
+    if (/\.env(?:\..*)?$/.test(base))
+        return true;
+    if (base === '.npmrc')
+        return true;
+    return TEXT_EXTENSIONS.test(file);
+}
+/** Shannon 熵；只对 24 位以上且以字母数字为主的 token 判分。 */
+function shannon(text) {
+    if (text.length < 16)
+        return 0;
+    const counts = new Map();
+    for (const char of text)
+        counts.set(char, (counts.get(char) ?? 0) + 1);
+    let entropy = 0;
+    for (const count of counts.values()) {
+        const p = count / text.length;
+        entropy -= p * Math.log2(p);
+    }
+    return entropy;
+}
+const TOKEN_PATTERN = /['"]([A-Za-z0-9+/=_-]{24,})['"]/g;
+const HIGH_ENTROPY_THRESHOLD = 3.8;
+function detectHighEntropy(line, lineNumber, file, rel, rule) {
+    const findings = [];
+    for (const match of line.matchAll(TOKEN_PATTERN)) {
+        const token = match[1];
+        if (/^[0-9]+$/.test(token))
+            continue;
+        if (!/\d/.test(token))
+            continue;
+        if (shannon(token) < HIGH_ENTROPY_THRESHOLD)
+            continue;
+        const id = makeId(rule.id, rel, lineNumber, token.slice(0, 32));
+        findings.push({
+            id,
+            ruleId: rule.id,
+            title: rule.title,
+            cwe: rule.cwe,
+            severity: rule.severity,
+            confidence: rule.confidence,
+            file: rel,
+            line: lineNumber,
+            snippet: line.trim().slice(0, 200),
+            message: rule.message,
+        });
+    }
+    return findings;
+}
+function makeId(ruleId, file, line, snippet) {
+    const hash = createHash('sha256').update(ruleId + '|' + file + '|' + line + '|' + snippet.slice(0, 80)).digest('hex').slice(0, 10);
+    return 'SR-' + hash;
+}
+/** 对带行号的文本行应用规则（全量扫描与 git diff 增量扫描共用）。 */
+export function scanLineSet(entries, rel, policy) {
+    const language = languageForFile(rel);
+    const findings = [];
+    const applied = RULES.filter((rule) => rule.languages.includes(language) || rule.languages.includes('any'));
+    const prevDisable = new Map();
+    for (const entry of entries) {
+        if (isComment(entry.text))
+            prevDisable.set(entry.line + 1, disabledRules(entry.text, DISABLE_NEXT));
+    }
+    for (const entry of entries) {
+        const currentDisable = isComment(entry.text) ? disabledRules(entry.text, DISABLE_LINE) : null;
+        for (const rule of applied) {
+            if (rule.id === 'SEC-304')
+                continue;
+            if (policyIgnores(policy, rule.id, rel))
+                continue;
+            if (shouldSkipLine(rule, currentDisable) || shouldSkipLine(rule, prevDisable.get(entry.line)))
+                continue;
+            if (rule.fileLevel === true)
+                continue;
+            if (!rule.patterns.some((pattern) => pattern.test(entry.text)))
+                continue;
+            findings.push({
+                id: makeId(rule.id, rel, entry.line, entry.text),
+                ruleId: rule.id,
+                title: rule.title,
+                cwe: rule.cwe,
+                severity: rule.severity,
+                confidence: rule.confidence,
+                file: rel,
+                line: entry.line,
+                snippet: entry.text.trim().slice(0, 200),
+                message: rule.message,
+            });
+        }
+        const entropyRule = RULES.find((rule) => rule.id === 'SEC-304');
+        if (entropyRule !== undefined && !policyIgnores(policy, entropyRule.id, rel)) {
+            findings.push(...detectHighEntropy(entry.text, entry.line, rel, rel, entropyRule));
+        }
+    }
+    return findings;
+}
+/** 扫描单个文件内容，按语言与行应用规则。 */
+export function scanText(content, file, rel, policy) {
+    const lines = content.split(/\r?\n/);
+    const entries = lines.map((text, index) => ({ line: index + 1, text }));
+    const findings = scanLineSet(entries, rel, policy);
+    const language = languageForFile(rel);
+    const applied = RULES.filter((rule) => rule.languages.includes(language) || rule.languages.includes('any'));
+    for (const rule of applied) {
+        if (rule.fileLevel !== true)
+            continue;
+        if (policyIgnores(policy, rule.id, rel))
+            continue;
+        if (rule.patterns.some((pattern) => pattern.test(content))) {
+            findings.push({
+                id: makeId(rule.id, rel, 1, content.slice(0, 80)),
+                ruleId: rule.id,
+                title: rule.title,
+                cwe: rule.cwe,
+                severity: rule.severity,
+                confidence: rule.confidence,
+                file: rel,
+                line: 1,
+                snippet: content.slice(0, 200),
+                message: rule.message,
+            });
+        }
+    }
+    return findings;
+}
+/** 扫描目录或单个文件。 */
+export async function scanPath(options) {
+    const started = Date.now();
+    const { cwd, maxFiles, maxFileBytes, policy } = options;
+    const root = options.target !== undefined && options.target.trim() !== '' ? path.resolve(cwd, options.target.trim()) : cwd;
+    let filesScanned = 0;
+    let filesSkipped = 0;
+    const findings = [];
+    const relRoot = path.relative(cwd, root) || '.';
+    const visit = async (absolute, rel) => {
+        let stat;
+        try {
+            stat = await fs.stat(absolute);
+        }
+        catch {
+            filesSkipped += 1;
+            return;
+        }
+        if (stat.isDirectory()) {
+            if (DEFAULT_EXCLUDE_DIRS.includes(path.basename(absolute)) || policyExcludesDir(policy, rel))
+                return;
+            let entries;
+            try {
+                entries = await fs.readdir(absolute, { withFileTypes: true });
+            }
+            catch {
+                filesSkipped += 1;
+                return;
+            }
+            for (const entry of entries) {
+                if (filesScanned >= maxFiles)
+                    return;
+                await visit(path.join(absolute, entry.name), rel === '' ? entry.name : rel + '/' + entry.name);
+            }
+            return;
+        }
+        if (!stat.isFile() || !shouldScanFile(absolute)) {
+            filesSkipped += 1;
+            return;
+        }
+        if (stat.size > maxFileBytes) {
+            filesSkipped += 1;
+            return;
+        }
+        let buffer;
+        try {
+            buffer = new Uint8Array(await fs.readFile(absolute));
+        }
+        catch {
+            filesSkipped += 1;
+            return;
+        }
+        if (fileHasBinary(buffer)) {
+            filesSkipped += 1;
+            return;
+        }
+        filesScanned += 1;
+        const text = new TextDecoder('utf-8', { fatal: false }).decode(buffer);
+        findings.push(...scanText(text, absolute, rel, policy));
+    };
+    await visit(root, relRoot);
+    findings.sort((a, b) => severityRank(b.severity) - severityRank(a.severity) || a.file.localeCompare(b.file) || a.line - b.line);
+    return { root, filesScanned, filesSkipped, findings, durationMs: Date.now() - started };
+}
+function severityRank(severity) {
+    return severity === 'critical' ? 4 : severity === 'high' ? 3 : severity === 'medium' ? 2 : 1;
+}