shellward 0.7.1 → 0.7.2

package/README.md

@@ -8,7 +8,7 @@
 
 [![npm](https://img.shields.io/npm/v/shellward?color=cb0000&label=npm)](https://www.npmjs.com/package/shellward)
 [![license](https://img.shields.io/badge/license-Apache--2.0-blue)](./LICENSE)
-[![tests](https://img.shields.io/badge/tests-273%20passing-brightgreen)](#performance)
+[![tests](https://img.shields.io/badge/tests-282%20passing-brightgreen)](#performance)
 [![deps](https://img.shields.io/badge/dependencies-0-brightgreen)](#performance)
 
 **🌐 官网: https://jnmetacode.github.io/shellward/**

package/dist/compliance/audit.d.ts

@@ -36,6 +36,10 @@ export interface ComplianceReport {
     generatedAt: string;
     /** 项目实测风险造成的扣分（仅项目体检路径）；0 表示纯控制项评分 */
     projectPenalty?: number;
+    /** 是否为静态扫描（未部署运行时）：此时多数控制项不可验证，得分不代表完整合规 */
+    staticScan?: boolean;
+    /** 项目扫描的文件总数（静态扫描路径） */
+    filesScanned?: number;
 }
 /** 采集真实环境事实（运行时调用；测试可绕过直接注入 EnvFacts） */
 export declare function gatherEnvFacts(): EnvFacts;

package/dist/compliance/audit.js

@@ -127,6 +127,8 @@ export function runProjectComplianceAudit(config, root) {
         report.grade = gradeOf(report.score);
         report.projectPenalty = penalty;
     }
+    report.staticScan = true;
+    report.filesScanned = scan.filesScanned;
     return { report, scan };
 }
 const FINDING_PENALTY = { critical: 8, high: 4, medium: 1 };

package/dist/compliance/html-report.js

@@ -40,23 +40,35 @@ export function renderHtmlReport(report, scan, locale, meta) {
     const when = report.generatedAt.slice(0, 19).replace('T', ' ');
     const S = [];
     // ===== 评分 Hero =====
+    // 诚实原则：静态扫描下多数控制项不可验证，不展示"优秀/A"式合规结论，
+    // 改以「风险发现数」为主指标，得分仅作"可观测项"的次要参考。
+    const findingsN = scan.findings.length;
+    const gradeLabel = report.staticScan ? t('可观测项', 'observable') : t(g.zh, g.en);
+    const verdict = report.staticScan
+        ? (findingsN === 0
+            ? { txt: t('未发现可观测风险', 'No observable risks'), c: '#16a34a', ic: '🟢' }
+            : { txt: t(`发现 ${findingsN} 项风险`, `${findingsN} risk(s) found`), c: '#dc2626', ic: '🔴' })
+        : { txt: t(g.zh, g.en), c: g.color, ic: '' };
     S.push(`
   <section class="hero">
     <div class="gauge" style="--p:${report.score};--c:${g.color}">
       <div class="gauge-in">
         <div class="gscore">${report.score}<small>/100</small></div>
-        <div class="ggrade" style="color:${g.color}">${esc(report.grade)} · ${t(g.zh, g.en)}</div>
+        <div class="ggrade" style="color:${g.color}">${esc(report.grade)} · ${esc(gradeLabel)}</div>
       </div>
     </div>
     <div class="hero-side">
+      <div class="verdict" style="--vc:${verdict.c}">${verdict.ic} ${esc(verdict.txt)}</div>
       <div class="stat-row">
         ${stat('pass', '🟢', t('合规', 'Pass'), report.passed)}
         ${stat('warn', '🟡', t('部分', 'Partial'), report.warned)}
         ${stat('fail', '🔴', t('不合规', 'Fail'), report.failed)}
-        ${stat('manual', '⚪', t('待确认', 'Review'), report.manual)}
+        ${stat('manual', '⚪', t('待核验', 'Review'), report.manual)}
       </div>
       ${report.projectPenalty ? `<div class="penalty">⚠ ${t('含项目实测风险扣分', 'Includes project-scan penalty')} <b>−${report.projectPenalty}</b></div>` : ''}
-      <p class="hero-note">${t('得分基于本次可静态观测的项目风险。⚪ 待确认项需把 ShellWard 部署为运行时防护或人工核验。', 'Score reflects statically-observable project risk. ⚪ items need runtime deployment or manual review.')}</p>
+      <p class="hero-note">${report.staticScan
+        ? t(`⚠ 本次为静态扫描：已检查 ${report.filesScanned ?? scan.filesScanned} 个文件，仅评估可观测风险。<b>${report.manual} 项合规控制项未验证</b>（需部署 ShellWard 运行时或人工核验）——本报告不构成完整合规结论，得分仅供参考。`, `⚠ Static scan: checked ${report.filesScanned ?? scan.filesScanned} files for observable risk only. <b>${report.manual} controls unverified</b> — not a complete compliance verdict.`)
+        : t('得分基于已部署运行时的合规评估。', 'Score based on deployed-runtime assessment.')}</p>
     </div>
   </section>`);
     // ===== 项目实测风险 =====
@@ -225,6 +237,7 @@ section,.reg{padding:0 36px}
 .gscore small{font-size:15px;font-weight:500;color:var(--faint)}
 .ggrade{font-size:14px;font-weight:700;margin-top:6px}
 .hero-side{flex:1;min-width:0}
+.verdict{font-size:17px;font-weight:800;color:var(--vc);margin:0 0 12px}
 .stat-row{display:grid;grid-template-columns:repeat(4,1fr);gap:10px}
 .stat{background:#fff;border:1px solid var(--line);border-radius:10px;padding:10px 12px;text-align:center}
 .stat .sn{font-size:22px;font-weight:800;line-height:1}

package/dist/compliance/report.js

@@ -31,21 +31,39 @@ export function renderComplianceReport(report, locale) {
     const bar = scoreBar(report.score);
     L.push(zh ? '## 总评' : '## Overall');
     L.push('');
-    L.push(`**${zh ? '合规得分' : 'Score'}: ${report.score}/100　${gradeBadge(report.grade)}**`);
-    L.push('');
-    L.push('```');
-    L.push(`${bar}  ${report.score}/100  [${report.grade}]`);
-    L.push('```');
+    // 诚实原则：静态扫描下不报"优秀/A"式合规结论，以风险发现数为主指标
+    if (report.staticScan) {
+        const fn = report.failed + (report.projectPenalty ? 1 : 0);
+        L.push(zh
+            ? `**项目实测风险: ${report.failed === 0 && !report.projectPenalty ? '🟢 未发现可观测风险' : '🔴 发现风险，详见下方'}**`
+            : `**Observable risk: ${report.failed === 0 && !report.projectPenalty ? '🟢 none found' : '🔴 see below'}**`);
+        L.push('');
+        L.push(`${bar}  ${report.score}/100 ${zh ? '（可观测合规项，仅供参考）' : '(observable controls only)'}`);
+        void fn;
+    }
+    else {
+        L.push(`**${zh ? '合规得分' : 'Score'}: ${report.score}/100　${gradeBadge(report.grade)}**`);
+        L.push('');
+        L.push('```');
+        L.push(`${bar}  ${report.score}/100  [${report.grade}]`);
+        L.push('```');
+    }
     L.push('');
     L.push(zh
-        ? `🟢 合规 ${report.passed} ｜ 🟡 部分 ${report.warned} ｜ 🔴 不合规 ${report.failed} ｜ ⚪ 待确认 ${report.manual}　(共 ${report.total} 项)`
-        : `🟢 Pass ${report.passed} ｜ 🟡 Partial ${report.warned} ｜ 🔴 Fail ${report.failed} ｜ ⚪ Manual ${report.manual}　(${report.total} controls)`);
+        ? `🟢 合规 ${report.passed} ｜ 🟡 部分 ${report.warned} ｜ 🔴 不合规 ${report.failed} ｜ ⚪ 待核验 ${report.manual}　(共 ${report.total} 项)`
+        : `🟢 Pass ${report.passed} ｜ 🟡 Partial ${report.warned} ｜ 🔴 Fail ${report.failed} ｜ ⚪ Review ${report.manual}　(${report.total} controls)`);
     if (report.projectPenalty && report.projectPenalty > 0) {
         L.push('');
         L.push(zh
             ? `> 含项目实测风险扣分 **-${report.projectPenalty}**（见下方「项目实测风险」）`
             : `> Includes **-${report.projectPenalty}** from project scan findings (see Project Scan Findings)`);
     }
+    if (report.staticScan) {
+        L.push('');
+        L.push(zh
+            ? `> ⚠ 本次为静态扫描：已检查 ${report.filesScanned ?? '?'} 个文件，仅评估可观测风险；**${report.manual} 项合规控制项未验证**（需部署 ShellWard 运行时或人工核验）。本报告不构成完整合规结论。`
+            : `> ⚠ Static scan: ${report.filesScanned ?? '?'} files checked; **${report.manual} controls unverified**. Not a complete compliance verdict.`);
+    }
     L.push('');
     // ===== 优先整改（fail 项，按严重度） =====
     const fails = report.results

package/dist/web/scan-server.js

@@ -21,8 +21,8 @@ import { runProjectComplianceAudit } from '../compliance/audit.js';
 import { renderHtmlReport } from '../compliance/html-report.js';
 import { DEFAULT_CONFIG, resolveLocale } from '../types.js';
 const REPO_RE = /^https:\/\/(github\.com|gitlab\.com|gitee\.com|bitbucket\.org)\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+?(?:\.git)?\/?$/;
-const CLONE_TIMEOUT_MS = 30_000;
-const MAX_CONCURRENT = 2;
+const CLONE_TIMEOUT_MS = 60_000;
+const MAX_CONCURRENT = 4;
 /** 校验仓库 URL：仅允许白名单代码托管域名，拒绝带凭据/异常字符 */
 export function validateRepoUrl(input) {
     const url = (input || '').trim();
@@ -101,7 +101,9 @@ async function handleRepo(res, repo, locale, inc, dec) {
         send(res, 200, 'text/html', renderHtmlReport(report, scan, locale, { root: v.url }));
     }
     catch (e) {
-        send(res, 502, 'text/html', errorPage('克隆/扫描失败：' + esc(e?.message || String(e)) + '。请确认是可公开访问的仓库。'));
+        const msg = esc(e?.message || String(e));
+        send(res, 502, 'text/html', errorPage(`克隆/扫描失败：${msg}。<br><br>可能原因：仓库过大（克隆超时 60s）、私有仓库、或地址有误。<br>` +
+            `<b>大仓库 / 私有代码请用本地客户端</b>（选文件夹、不上传）：<code>npx shellward web --local</code>，或命令行 <code>npx shellward scan</code>。`));
     }
     finally {
         dec();
@@ -214,11 +216,11 @@ function send(res, code, type, body) {
 }
 function formPage(local) {
     const urlForm = `
-      <form action="/scan" method="get">
+      <form action="/scan" method="get" onsubmit="var b=this.querySelector('button');b.disabled=true;b.textContent='扫描中…（大仓库需 10–60 秒，请勿重复点击）';">
         <label>${local ? '② ' : ''}公开仓库地址</label>
         <input name="repo" placeholder="https://github.com/owner/repo"${local ? '' : ' autofocus'}>
         <button type="submit">${local ? '体检该仓库 →' : '开始体检 →'}</button>
-        <p class="hint">仅支持公开仓库（GitHub / GitLab / Gitee / Bitbucket）。${local ? '' : '<b>私有/敏感代码请用本地客户端或 CLI</b>：<code>npx shellward web --local</code> / <code>npx shellward scan</code>（不上传）。'}</p>
+        <p class="hint">仅支持公开仓库（GitHub / GitLab / Gitee / Bitbucket）。大仓库可能超时——${local ? '此时改用上方「选择文件夹」更稳。' : '<b>大仓库 / 私有代码请用本地客户端或 CLI</b>：<code>npx shellward web --local</code> / <code>npx shellward scan</code>（不上传）。'}</p>
       </form>`;
     const uploadForm = local ? `
       <form id="dirform">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shellward",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "mcpName": "io.github.jnMetaCode/shellward",
   "description": "AI agent security & MCP security middleware — prompt injection detection, AI firewall, runtime guardrails & data-loss prevention for LLM tool calls. 8-layer defense against data exfiltration & dangerous commands. Zero dependencies. SDK + OpenClaw plugin. Supports LangChain, AutoGPT, Claude Code, Cursor, OpenAI Agents, Hermes Agent.",
   "keywords": [

package/src/compliance/audit.ts

@@ -57,6 +57,10 @@ export interface ComplianceReport {
   generatedAt: string
   /** 项目实测风险造成的扣分（仅项目体检路径）；0 表示纯控制项评分 */
   projectPenalty?: number
+  /** 是否为静态扫描（未部署运行时）：此时多数控制项不可验证，得分不代表完整合规 */
+  staticScan?: boolean
+  /** 项目扫描的文件总数（静态扫描路径） */
+  filesScanned?: number
 }
 
 /** 层能力映射：控制项 id → 必须启用的层（全部启用才 pass，部分启用 warn，全关 fail） */
@@ -191,6 +195,8 @@ export function runProjectComplianceAudit(config: ShellWardConfig, root: string)
     report.grade = gradeOf(report.score)
     report.projectPenalty = penalty
   }
+  report.staticScan = true
+  report.filesScanned = scan.filesScanned
 
   return { report, scan }
 }

package/src/compliance/html-report.ts

@@ -60,25 +60,37 @@ export function renderHtmlReport(
   const S: string[] = []
 
   // ===== 评分 Hero =====
+  // 诚实原则：静态扫描下多数控制项不可验证，不展示"优秀/A"式合规结论，
+  // 改以「风险发现数」为主指标，得分仅作"可观测项"的次要参考。
+  const findingsN = scan.findings.length
+  const gradeLabel = report.staticScan ? t('可观测项', 'observable') : t(g.zh, g.en)
+  const verdict = report.staticScan
+    ? (findingsN === 0
+        ? { txt: t('未发现可观测风险', 'No observable risks'), c: '#16a34a', ic: '🟢' }
+        : { txt: t(`发现 ${findingsN} 项风险`, `${findingsN} risk(s) found`), c: '#dc2626', ic: '🔴' })
+    : { txt: t(g.zh, g.en), c: g.color, ic: '' }
+
   S.push(`
   <section class="hero">
     <div class="gauge" style="--p:${report.score};--c:${g.color}">
       <div class="gauge-in">
         <div class="gscore">${report.score}<small>/100</small></div>
-        <div class="ggrade" style="color:${g.color}">${esc(report.grade)} · ${t(g.zh, g.en)}</div>
+        <div class="ggrade" style="color:${g.color}">${esc(report.grade)} · ${esc(gradeLabel)}</div>
       </div>
     </div>
     <div class="hero-side">
+      <div class="verdict" style="--vc:${verdict.c}">${verdict.ic} ${esc(verdict.txt)}</div>
       <div class="stat-row">
         ${stat('pass', '🟢', t('合规', 'Pass'), report.passed)}
         ${stat('warn', '🟡', t('部分', 'Partial'), report.warned)}
         ${stat('fail', '🔴', t('不合规', 'Fail'), report.failed)}
-        ${stat('manual', '⚪', t('待确认', 'Review'), report.manual)}
+        ${stat('manual', '⚪', t('待核验', 'Review'), report.manual)}
       </div>
       ${report.projectPenalty ? `<div class="penalty">⚠ ${t('含项目实测风险扣分', 'Includes project-scan penalty')} <b>−${report.projectPenalty}</b></div>` : ''}
-      <p class="hero-note">${t(
-        '得分基于本次可静态观测的项目风险。⚪ 待确认项需把 ShellWard 部署为运行时防护或人工核验。',
-        'Score reflects statically-observable project risk. ⚪ items need runtime deployment or manual review.')}</p>
+      <p class="hero-note">${report.staticScan
+        ? t(`⚠ 本次为静态扫描：已检查 ${report.filesScanned ?? scan.filesScanned} 个文件，仅评估可观测风险。<b>${report.manual} 项合规控制项未验证</b>（需部署 ShellWard 运行时或人工核验）——本报告不构成完整合规结论，得分仅供参考。`,
+            `⚠ Static scan: checked ${report.filesScanned ?? scan.filesScanned} files for observable risk only. <b>${report.manual} controls unverified</b> — not a complete compliance verdict.`)
+        : t('得分基于已部署运行时的合规评估。', 'Score based on deployed-runtime assessment.')}</p>
     </div>
   </section>`)
 
@@ -263,6 +275,7 @@ section,.reg{padding:0 36px}
 .gscore small{font-size:15px;font-weight:500;color:var(--faint)}
 .ggrade{font-size:14px;font-weight:700;margin-top:6px}
 .hero-side{flex:1;min-width:0}
+.verdict{font-size:17px;font-weight:800;color:var(--vc);margin:0 0 12px}
 .stat-row{display:grid;grid-template-columns:repeat(4,1fr);gap:10px}
 .stat{background:#fff;border:1px solid var(--line);border-radius:10px;padding:10px 12px;text-align:center}
 .stat .sn{font-size:22px;font-weight:800;line-height:1}

package/src/compliance/report.ts

@@ -41,21 +41,38 @@ export function renderComplianceReport(report: ComplianceReport, locale: 'zh' |
   const bar = scoreBar(report.score)
   L.push(zh ? '## 总评' : '## Overall')
   L.push('')
-  L.push(`**${zh ? '合规得分' : 'Score'}: ${report.score}/100　${gradeBadge(report.grade)}**`)
-  L.push('')
-  L.push('```')
-  L.push(`${bar}  ${report.score}/100  [${report.grade}]`)
-  L.push('```')
+  // 诚实原则：静态扫描下不报"优秀/A"式合规结论，以风险发现数为主指标
+  if (report.staticScan) {
+    const fn = report.failed + (report.projectPenalty ? 1 : 0)
+    L.push(zh
+      ? `**项目实测风险: ${report.failed === 0 && !report.projectPenalty ? '🟢 未发现可观测风险' : '🔴 发现风险，详见下方'}**`
+      : `**Observable risk: ${report.failed === 0 && !report.projectPenalty ? '🟢 none found' : '🔴 see below'}**`)
+    L.push('')
+    L.push(`${bar}  ${report.score}/100 ${zh ? '（可观测合规项，仅供参考）' : '(observable controls only)'}`)
+    void fn
+  } else {
+    L.push(`**${zh ? '合规得分' : 'Score'}: ${report.score}/100　${gradeBadge(report.grade)}**`)
+    L.push('')
+    L.push('```')
+    L.push(`${bar}  ${report.score}/100  [${report.grade}]`)
+    L.push('```')
+  }
   L.push('')
   L.push(zh
-    ? `🟢 合规 ${report.passed} ｜ 🟡 部分 ${report.warned} ｜ 🔴 不合规 ${report.failed} ｜ ⚪ 待确认 ${report.manual}　(共 ${report.total} 项)`
-    : `🟢 Pass ${report.passed} ｜ 🟡 Partial ${report.warned} ｜ 🔴 Fail ${report.failed} ｜ ⚪ Manual ${report.manual}　(${report.total} controls)`)
+    ? `🟢 合规 ${report.passed} ｜ 🟡 部分 ${report.warned} ｜ 🔴 不合规 ${report.failed} ｜ ⚪ 待核验 ${report.manual}　(共 ${report.total} 项)`
+    : `🟢 Pass ${report.passed} ｜ 🟡 Partial ${report.warned} ｜ 🔴 Fail ${report.failed} ｜ ⚪ Review ${report.manual}　(${report.total} controls)`)
   if (report.projectPenalty && report.projectPenalty > 0) {
     L.push('')
     L.push(zh
       ? `> 含项目实测风险扣分 **-${report.projectPenalty}**（见下方「项目实测风险」）`
       : `> Includes **-${report.projectPenalty}** from project scan findings (see Project Scan Findings)`)
   }
+  if (report.staticScan) {
+    L.push('')
+    L.push(zh
+      ? `> ⚠ 本次为静态扫描：已检查 ${report.filesScanned ?? '?'} 个文件，仅评估可观测风险；**${report.manual} 项合规控制项未验证**（需部署 ShellWard 运行时或人工核验）。本报告不构成完整合规结论。`
+      : `> ⚠ Static scan: ${report.filesScanned ?? '?'} files checked; **${report.manual} controls unverified**. Not a complete compliance verdict.`)
+  }
   L.push('')
 
   // ===== 优先整改（fail 项，按严重度） =====

package/src/web/scan-server.ts

@@ -23,8 +23,8 @@ import { renderHtmlReport } from '../compliance/html-report.js'
 import { DEFAULT_CONFIG, resolveLocale } from '../types.js'
 
 const REPO_RE = /^https:\/\/(github\.com|gitlab\.com|gitee\.com|bitbucket\.org)\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+?(?:\.git)?\/?$/
-const CLONE_TIMEOUT_MS = 30_000
-const MAX_CONCURRENT = 2
+const CLONE_TIMEOUT_MS = 60_000
+const MAX_CONCURRENT = 4
 
 export interface WebServerOptions {
   port: number
@@ -105,7 +105,10 @@ async function handleRepo(res: any, repo: string, locale: 'zh' | 'en', inc: () =
     const { report, scan } = runProjectComplianceAudit(DEFAULT_CONFIG, dir)
     send(res, 200, 'text/html', renderHtmlReport(report, scan, locale, { root: v.url }))
   } catch (e: any) {
-    send(res, 502, 'text/html', errorPage('克隆/扫描失败：' + esc(e?.message || String(e)) + '。请确认是可公开访问的仓库。'))
+    const msg = esc(e?.message || String(e))
+    send(res, 502, 'text/html', errorPage(
+      `克隆/扫描失败：${msg}。<br><br>可能原因：仓库过大（克隆超时 60s）、私有仓库、或地址有误。<br>` +
+      `<b>大仓库 / 私有代码请用本地客户端</b>（选文件夹、不上传）：<code>npx shellward web --local</code>，或命令行 <code>npx shellward scan</code>。`))
   } finally {
     dec()
     try { rmSync(dir, { recursive: true, force: true }) } catch { /* ignore */ }
@@ -197,11 +200,11 @@ function send(res: any, code: number, type: string, body: string) {
 
 function formPage(local: boolean): string {
   const urlForm = `
-      <form action="/scan" method="get">
+      <form action="/scan" method="get" onsubmit="var b=this.querySelector('button');b.disabled=true;b.textContent='扫描中…（大仓库需 10–60 秒，请勿重复点击）';">
         <label>${local ? '② ' : ''}公开仓库地址</label>
         <input name="repo" placeholder="https://github.com/owner/repo"${local ? '' : ' autofocus'}>
         <button type="submit">${local ? '体检该仓库 →' : '开始体检 →'}</button>
-        <p class="hint">仅支持公开仓库（GitHub / GitLab / Gitee / Bitbucket）。${local ? '' : '<b>私有/敏感代码请用本地客户端或 CLI</b>：<code>npx shellward web --local</code> / <code>npx shellward scan</code>（不上传）。'}</p>
+        <p class="hint">仅支持公开仓库（GitHub / GitLab / Gitee / Bitbucket）。大仓库可能超时——${local ? '此时改用上方「选择文件夹」更稳。' : '<b>大仓库 / 私有代码请用本地客户端或 CLI</b>：<code>npx shellward web --local</code> / <code>npx shellward scan</code>（不上传）。'}</p>
       </form>`
 
   const uploadForm = local ? `