@lateos/npm-scan 1.2.0 → 1.2.1

package/README.zh.md

@@ -9,8 +9,8 @@
 [![npm version](https://img.shields.io/npm/v/@lateos/npm-scan?style=flat-square)](https://www.npmjs.com/package/@lateos/npm-scan)
 [![License](https://img.shields.io/badge/license-Apache%202.0%20%2B%20Commons%20Clause-blue?style=flat-square)](LICENSING.md)
 [![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen?style=flat-square)](package.json)
-[![Tests](https://img.shields.io/badge/tests-459%20passing-brightgreen?style=flat-square)](https://github.com/lateos-ai/npm-scan)
-[![Coverage](https://img.shields.io/badge/coverage-85%25-yellowgreen?style=flat-square)](https://github.com/lateos-ai/npm-scan)
+[![Tests](https://img.shields.io/badge/tests-696%20passing-brightgreen?style=flat-square)](https://github.com/lateos-ai/npm-scan)
+[![Coverage](https://img.shields.io/badge/coverage-90%25-brightgreen?style=flat-square)](https://github.com/lateos-ai/npm-scan)
 [![Docker](https://img.shields.io/badge/docker-lateos%2Fnpm--scan-2496ED?style=flat-square&logo=docker)](https://hub.docker.com/r/lateos/npm-scan)
 [![Sigstore](https://img.shields.io/static/v1?label=Sigstore&message=Provenance&color=green&style=flat-square&logo=sigstore)](https://github.com/lateos-ai/npm-scan/actions/workflows/publish.yml)
 
@@ -485,102 +485,6 @@ npm-scan report --html > report.html
 
 ### Docker
 
-请参见上方的 [Docker 快速入门部分](#-在任何地方通过-docker-运行-lateosnpm-scan--零安装)，了解拉取命令、Compose 流水线和多架构镜像。
-
-在每个 PR 上扫描您项目的 `package-lock.json`——在它们进入生产环境之前检测域名抢注、混淆载荷、凭证窃取器和蠕虫传播：
-
-```yaml
-# .github/workflows/scan.yml
-name: npm-scan
-on:
-  pull_request:
-    paths:
-      - 'package-lock.json'
-      - '**/package.json'
-jobs:
-  scan:
-    runs-on: ubuntu-latest
-    steps:
-    - uses: actions/checkout@v4
-    - uses: actions/setup-node@v4
-      with:
-        node-version: 20
-    - name: Scan lockfile
-      uses: lateos/npm-scan@v1
-      with:
-        scan-type: lockfile
-        fail-on: high
-```
-
-#### Action 输入
-
-| 输入 | 默认值 | 描述 |
-|-------|---------|-------------|
-| `scan-type` | `lockfile` | `lockfile` 扫描 `package-lock.json` 或 `package` 扫描特定 npm 包 |
-| `package` | — | 包名（`scan-type=package` 时需要） |
-| `fail-on` | `high` | 在此严重性阈值处使工作流失败：`none`、`low`、`medium`、`high`、`critical` |
-| `policy-file` | — | YAML/JSON 策略文件路径，用于白名单、严重性覆盖和抑制 |
-| `license-key` | — | 用于 SIEM 导出和 PDF 报告的高级版许可证密钥 |
-| `siem-format` | — | SIEM 输出：`cef`、`ecs`、`sentinel`、`qradar`（高级版） |
-| `sbom-format` | — | SBOM 输出：`json`、`xml`、`spdx` |
-
-#### Action 输出
-
-| 输出 | 描述 |
-|--------|-------------|
-| `findings-count` | 检测到的发现项数量 |
-| `scan-id` | 扫描 ID，用于后续报告引用 |
-
-#### 示例：使用策略 + SBOM 扫描特定包
-
-```yaml
-- uses: lateos/npm-scan@v1
-  with:
-    scan-type: package
-    package: lodash
-    policy-file: .npm-scan.yml
-    sbom-format: spdx
-    fail-on: critical
-```
-
-#### 示例：使用 SIEM 导出扫描（高级版）
-
-```yaml
-- uses: lateos/npm-scan@v1
-  with:
-    scan-type: lockfile
-    siem-format: cef
-    license-key: ${{ secrets.NPM_SCAN_LICENSE_KEY }}
-```
-
-### CI/CD 流水线
-
-直接集成到您现有的流水线中，无需复合操作：
-
-```bash
-# 扫描锁定文件，在高严重性时使构建失败
-npm-scan scan-lockfile --policy .npm-scan.yml || exit 1
-
-# 扫描特定包，仅在严重时失败
-npm-scan scan lodash --policy .npm-scan.yml || exit 1
-
-# 生成 SBOM 作为构建产物
-npm-scan scan express --sbom spdx > express-sbom.spdx.json
-
-# 在 CI 中生成 HTML 合规报告
-npm-scan report --html > report.html
-
-# 上传报告作为产物
-# uses: actions/upload-artifact@v4
-#   with:
-#     name: npm-scan-report
-#     path: report.html
-```
-
-### Docker
-
-请参见上方的 [Docker 快速入门部分](#-在任何地方通过-docker-运行-lateosnpm-scan--零安装)，了解拉取命令、Compose 流水线和多架构镜像。
-
 ---
 
 ## 🗺️ 路线图与企业功能
@@ -706,4 +610,5 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 
 ```bash
 npx @lateos/npm-scan scan lodash
+```
 ```

package/backend/detectors/config/thresholds.js

@@ -108,4 +108,60 @@ export default {
     cross_package_burst_weight: 50,
     notes: 'D13: Version velocity anomaly and maintainer compromise detection',
   },
+  'D14-BUILD-CONFIG-ABUSE': {
+    flag_threshold: 70,
+    warn_threshold: 50,
+    pattern_weights: {
+      shell_exec: 50,
+      process_spawn: 45,
+      env_access: 35,
+      fs_access: 40,
+      http_request: 50,
+      path_traversal: 55,
+      hardcoded_key: 60,
+      getenv_call: 35,
+      curl_call: 45,
+      execve_call: 55,
+      credential_scan: 50,
+      socket_call: 40,
+      environ_access: 35,
+    },
+    legitimate_native_addons: [
+      'node-sass',
+      'sqlite3',
+      'bcrypt',
+      '@mapbox/node-pre-gyp',
+      'better-sqlite3',
+      'sharp',
+      'canvas',
+      'node-gyp',
+      'prebuild-install',
+    ],
+    pattern_confidence: {
+      hardcoded_key: 0.95,
+      execve_call: 0.9,
+      socket_call: 0.75,
+      env_access: 0.6,
+      getenv_call: 0.7,
+      curl_call: 0.85,
+    },
+    max_binary_size_bytes: 10 * 1024 * 1024,
+    binary_size_weight: 30,
+    binary_age_mismatch_days: 30,
+    undeclared_gyp_weight: 45,
+    known_reputable_packages: [
+      'electron',
+      'puppeteer',
+      'playwright',
+      'sharp',
+      'esbuild',
+      'node-gyp',
+      '@mapbox/node-pre-gyp',
+      'node-pre-gyp',
+      'webpack',
+      'vite',
+      'rollup',
+    ],
+    notes: 'D14: Build Configuration Abuse (Phantom Gyp / Miasma variant)',
+  },
 };

package/backend/detectors/index.js

@@ -33,6 +33,7 @@ import { scan as tier1SelfPropagationScan } from './tier1-self-propagation.js';
 import { scan as tier1EncryptedC2Scan } from './tier1-encrypted-c2.js';
 import { scan as tier1TransitiveDepsScan } from './tier1-transitive-deps.js';
 import { scan as tier1MaintainerCompromiseScan } from './tier1-maintainer-compromise.js';
+import { scan as tier1BuildConfigAbuseScan } from './tier1-build-config-abuse.js';
 
 function timeout(ms) {
   return new Promise((_, reject) =>
@@ -231,5 +232,15 @@ export async function runAll(pkgJson, files = [], registryMeta = null, allFiles
       allFiles || files
     ))
   );
+  findings.push(
+    ...(await runTier1(
+      'tier1-build-config-abuse',
+      tier1BuildConfigAbuseScan,
+      pkgJson,
+      files,
+      registryMeta,
+      allFiles || files
+    ))
+  );
   return findings.sort((a, b) => b.severity.localeCompare(a.severity));
 }

package/backend/detectors/tier1-build-config-abuse.js

@@ -0,0 +1,264 @@
+import thresholds from './config/thresholds.js';
+
+const cfg = thresholds['D14-BUILD-CONFIG-ABUSE'];
+const PATTERN_WEIGHTS = cfg.pattern_weights;
+const PATTERN_CONFIDENCE = cfg.pattern_confidence;
+const LEGITIMATE_ADDONS = new Set(cfg.legitimate_native_addons);
+
+function fileByName(files, name) {
+  if (!files) return null;
+  const target = name.replace(/\\/g, '/').toLowerCase();
+  return (
+    files.find((f) => {
+      const fp = (f.path || f.name || '').replace(/\\/g, '/').toLowerCase();
+      return fp === target || fp.endsWith('/' + target);
+    }) || null
+  );
+}
+
+function filesByExt(files, exts) {
+  if (!files) return [];
+  const lower = exts.map((e) => e.toLowerCase());
+  return files.filter((f) => {
+    const fp = (f.path || f.name || '').toLowerCase();
+    return lower.some((e) => fp.endsWith(e));
+  });
+}
+
+function extractLines(content, matchIndex) {
+  if (!content) return 1;
+  const before = content.slice(0, matchIndex);
+  return (before.match(/\n/g) || []).length + 1;
+}
+
+export const name = 'tier1-build-config-abuse';
+
+export async function scan(pkgJson, jsFiles, registryMeta, allFiles) {
+  const pkgName = pkgJson?.name;
+  if (
+    pkgName &&
+    cfg.known_reputable_packages?.some((r) => pkgName === r || pkgName.startsWith(r + '/'))
+  ) {
+    return [];
+  }
+
+  const files = allFiles || jsFiles || [];
+  if (files.length === 0) return [];
+
+  const findings = [];
+  let aggregatedRisk = 0;
+
+  const hasGypFile = !!fileByName(files, 'binding.gyp');
+  const isLegitimateAddon = pkgName && LEGITIMATE_ADDONS.has(pkgName);
+
+  // Step 1: binding.gyp presence on non-legitimate addon
+  const hasGypDeclared =
+    pkgJson &&
+    (pkgJson.gypfile === true ||
+      !!pkgJson.binary ||
+      (pkgJson.scripts &&
+        typeof pkgJson.scripts.install === 'string' &&
+        pkgJson.scripts.install.includes('node-gyp')) ||
+      (pkgJson.scripts &&
+        typeof pkgJson.scripts.install === 'string' &&
+        pkgJson.scripts.install.includes('node-pre-gyp')));
+
+  if (hasGypFile && !isLegitimateAddon && !hasGypDeclared) {
+    findings.push({
+      detector: 'tier1-build-config-abuse',
+      id: 'D14-BUILD-CONFIG-ABUSE',
+      severity: 'medium',
+      confidence: 'MEDIUM',
+      confidenceScore: 40,
+      message: `Unexpected binding.gyp in non-native-addon package${pkgName ? ': ' + pkgName : ''}`,
+      evidence: ['binding.gyp present but package is not a known native addon'],
+      locations: [{ file: 'binding.gyp', line: 1 }],
+    });
+    aggregatedRisk += 20;
+  }
+
+  // Step 2: Parse binding.gyp for suspicious patterns
+  if (hasGypFile) {
+    const gypFile = fileByName(files, 'binding.gyp');
+    const gypContent = gypFile?.content || '';
+
+    if (gypContent) {
+      const gypPatterns = {
+        shell_exec: /<!?\(.*\)/g,
+        process_spawn: /\b(spawn|exec|execSync|spawnSync|fork)\s*\(/g,
+        env_access: /process\.env\./g,
+        fs_access: /\bfs\.(read|write|readFile|writeFile|readdir|exists|stat|mkdir|rm|unlink)/g,
+        http_request: /\b(http|https|curl|wget|fetch)\b/gi,
+        path_traversal: /\.\.\//g,
+      };
+
+      for (const [patternName, regex] of Object.entries(gypPatterns)) {
+        regex.lastIndex = 0;
+        let match;
+        while ((match = regex.exec(gypContent)) !== null) {
+          const line = extractLines(gypContent, match.index);
+          findings.push({
+            detector: 'tier1-build-config-abuse',
+            id: 'D14-BUILD-CONFIG-ABUSE',
+            severity: PATTERN_WEIGHTS[patternName] >= 50 ? 'high' : 'medium',
+            confidence: 'HIGH',
+            confidenceScore: PATTERN_WEIGHTS[patternName],
+            message: `binding.gyp contains ${patternName.replace(/_/g, ' ')} pattern`,
+            evidence: [`pattern: ${patternName}`, `match: ${match[0].slice(0, 120)}`],
+            locations: [{ file: 'binding.gyp', line }],
+          });
+          aggregatedRisk += PATTERN_WEIGHTS[patternName] || 30;
+        }
+      }
+    }
+  }
+
+  // Step 3: Analyze C/C++ Source Code
+  const cppFiles = filesByExt(files, ['.cc', '.cpp', '.c', '.cxx', '.h', '.hpp']);
+  for (const cppFile of cppFiles) {
+    const content = cppFile.content || '';
+    if (!content) continue;
+
+    const cPatterns = {
+      hardcoded_key:
+        /(?:AWS|GITHUB|SLACK|STRIPE|TOKEN|SECRET|API_KEY|PASSWORD)\s*[:=]\s*['"][A-Za-z0-9_-]{20,}['"]|['"](?:sk_live_|sk_test_|ghp_|gho_|ghs_|ghu_)[A-Za-z0-9_-]{20,}['"]/g,
+      getenv_call: /\b(getenv|secure_getenv|getenv_s)\s*\(/g,
+      curl_call: /\b(curl_easy_perform|curl_slist_append|CURLOPT_URL|curl_easy_setopt)\s*\(/g,
+      execve_call: /\b(execve|execvp|execl|execlp|system|popen|pclose)\s*\(/g,
+      credential_scan: /(~\/\.aws|~\/\.ssh|\.env|credentials\.json|\/etc\/passwd)/g,
+      socket_call: /\b(socket\s*\(|listen\s*\(|accept\s*\(|connect\s*\(AF_)/g,
+      environ_access: /\b(environ|__environ)\s*\[/g,
+    };
+
+    for (const [patternName, regex] of Object.entries(cPatterns)) {
+      regex.lastIndex = 0;
+      let match;
+      while ((match = regex.exec(content)) !== null) {
+        const line = extractLines(content, match.index);
+        const confidence = PATTERN_CONFIDENCE[patternName] || 0.7;
+        const risk = PATTERN_WEIGHTS[patternName] || 30;
+
+        findings.push({
+          detector: 'tier1-build-config-abuse',
+          id: 'D14-BUILD-CONFIG-ABUSE',
+          severity: risk >= 50 ? 'high' : 'medium',
+          confidence: confidence >= 0.85 ? 'HIGH' : confidence >= 0.7 ? 'MEDIUM' : 'LOW',
+          confidenceScore: risk,
+          message: `C/C++ code contains ${patternName.replace(/_/g, ' ')} pattern`,
+          evidence: [
+            `pattern: ${patternName}`,
+            `match: ${match[0].slice(0, 120)}`,
+            `confidence: ${confidence}`,
+          ],
+          locations: [{ file: cppFile.path || cppFile.name || 'unknown.cc', line }],
+        });
+        aggregatedRisk += risk;
+      }
+    }
+  }
+
+  // Step 4: Check .node file legitimacy
+  const nodeFiles = filesByExt(files, ['.node']);
+  for (const nodeFile of nodeFiles) {
+    const content = nodeFile.content || '';
+    const fileSize = content.length;
+
+    if (fileSize > cfg.max_binary_size_bytes) {
+      findings.push({
+        detector: 'tier1-build-config-abuse',
+        id: 'D14-BUILD-CONFIG-ABUSE',
+        severity: 'medium',
+        confidence: 'MEDIUM',
+        confidenceScore: cfg.binary_size_weight,
+        message: 'Large prebuilt .node binary',
+        evidence: [
+          `file: ${nodeFile.path || nodeFile.name}`,
+          `size: ${(fileSize / (1024 * 1024)).toFixed(1)} MB`,
+          `max allowed: ${(cfg.max_binary_size_bytes / (1024 * 1024)).toFixed(1)} MB`,
+        ],
+        locations: [{ file: nodeFile.path || nodeFile.name || 'unknown.node' }],
+      });
+      aggregatedRisk += cfg.binary_size_weight;
+    }
+  }
+
+  // Step 5: Cross-reference — undeclared binding.gyp
+  if (hasGypFile && pkgJson && !hasGypDeclared) {
+    findings.push({
+      detector: 'tier1-build-config-abuse',
+      id: 'D14-BUILD-CONFIG-ABUSE',
+      severity: 'high',
+      confidence: 'HIGH',
+      confidenceScore: cfg.undeclared_gyp_weight,
+      message: 'Undeclared binding.gyp — package.json does not advertise native build',
+      evidence: ['binding.gyp exists but no gypfile/binary/install-script in package.json'],
+      locations: [{ file: 'binding.gyp', line: 1 }],
+    });
+    aggregatedRisk += cfg.undeclared_gyp_weight;
+  }
+
+  if (findings.length === 0) return [];
+
+  const overallScore = Math.min(100, Math.max(0, aggregatedRisk));
+  let severity;
+  if (overallScore >= cfg.flag_threshold) {
+    severity = 'critical';
+  } else if (overallScore >= cfg.warn_threshold) {
+    severity = 'high';
+  } else if (overallScore >= 30) {
+    severity = 'medium';
+  } else {
+    severity = 'low';
+  }
+
+  function confidenceLabel(sc) {
+    if (sc >= 80) return 'HIGH';
+    if (sc >= 50) return 'MEDIUM';
+    return 'LOW';
+  }
+
+  const hasShellExec = findings.some((f) => f.evidence?.some((e) => e.includes('shell_exec')));
+  const hasCreds = findings.some((f) => f.evidence?.some((e) => e.includes('hardcoded_key')));
+  const hasNetwork = findings.some((f) =>
+    f.evidence?.some((e) => e.includes('curl_call') || e.includes('http_request'))
+  );
+  const hasExec = findings.some((f) => f.evidence?.some((e) => e.includes('execve_call')));
+
+  let recommendation = 'PASS';
+  if (hasShellExec || hasCreds || hasExec) {
+    recommendation = 'BLOCK - Native addon build contains malicious patterns';
+  } else if (hasNetwork) {
+    recommendation = 'WARN - Native addon build makes network calls';
+  } else if (aggregatedRisk > cfg.warn_threshold) {
+    recommendation = 'REVIEW - Suspicious build configuration detected';
+  }
+
+  return [
+    {
+      detector: 'tier1-build-config-abuse',
+      id: 'D14-BUILD-CONFIG-ABUSE',
+      severity,
+      confidence: confidenceLabel(overallScore),
+      confidenceScore: overallScore,
+      message: `Build Configuration Abuse detected (aggregated risk: ${aggregatedRisk})`,
+      evidence: [
+        `total_findings: ${findings.length}`,
+        `aggregated_risk: ${aggregatedRisk}`,
+        ...findings.map((f) => {
+          const loc = f.locations?.[0];
+          return `${f.message}${loc ? ' @ ' + (loc.file || '') + (loc.line ? ':' + loc.line : '') : ''}`;
+        }),
+      ],
+      locations: findings.flatMap((f) => f.locations || []),
+      recommendation,
+      detail: findings.map((f) => ({
+        type:
+          f.evidence?.find((e) => e.startsWith('pattern:'))?.replace('pattern: ', '') || 'unknown',
+        pattern: f.evidence?.find((e) => e.startsWith('pattern:'))?.replace('pattern: ', ''),
+        confidence: f.confidenceScore,
+        risk: f.confidenceScore,
+        location: f.locations?.[0] || null,
+      })),
+    },
+  ];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lateos/npm-scan",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Production-grade npm supply chain vulnerability scanner. Detects 100% of 3 real May 2026 supply chain campaigns (dependency confusion, obfuscation, impersonation) with 0% false positive rate on top 1,000 npm packages.",
   "main": "backend/index.js",
   "bin": {