bb1nfosec/bheeshma

## 为什么选择 BHEESHMA？ 在 2025-2026 年，npm 生态系统遭受了一波供应链攻击： | 攻击 | 时间 | 影响 | |--------|------|--------| | **Shai-Hulud 蠕虫** | 2025年9月 | 200+ 个软件包，自动化 CI/CD 劫持 | | **axios 妥协事件** | 2026年初 | 窃取 npm 凭据，影响 10K+ 系统，传播 RAT 恶意软件 | | **Mini Shai-Hulud** | 2026年5月 | 84 个 TanStack 软件包被攻陷 | | **CanisterWorm** | 2026年 | 自我传播，数据窃取 + 持久化 | **每一个主要工具 — Socket.dev, Snyk, Dependabot, npm audit — 都是安装前的静态分析。** 它们在代码*运行前*扫描。它们无法看到软件包在*运行时*实际做了什么。 BHEESHMA 不同。它**监控运行时行为** — 你的依赖项在执行时实际做了什么。它能捕捉： - 恶意的 `postinstall` 脚本窃取 CI 密钥 - 软件包向数据窃取端点建立出站连接 - 在运行时执行的混淆代码 - 凭据窃取、加密货币挖矿程序、数据窃取 - 假冒流行库的 typosquat 软件包 - 绕过 HTTP 级别监控的 DNS 隧道 **零依赖。零配置。零遥测。** ## 30 秒快速开始 ### GitHub Actions（推荐） 添加到你的 CI 管道 — 一行 YAML： ``` # .github/workflows/ci.yml - uses: bb1nfosec/bheeshma/.github/actions/bheeshma@main with: command: 'npm test' fail-level: 'critical' ``` 现在每个 PR 都会在 GitHub 差异视图中直接显示来自 bheeshma 的**运行时行为注释**。 ### npm install 监视器 观察软件包在安装期间做了什么： ``` npx bheeshma install ``` ### 基础监控 ``` npx bheeshma -- node app.js ``` ## GitHub Actions 集成 BHEESHMA 输出 **SARIF v2.1.0** — GitHub 代码扫描的标准格式。结果作为内联注释出现在每个 PR 上。 ### 基础设置 ``` name: CI on: [push, pull_request] jobs: security: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Install dependencies run: npm ci - uses: bb1nfosec/bheeshma/.github/actions/bheeshma@main with: command: 'npm test' fail-level: 'critical' # fail on CRITICAL (default) upload-sarif: 'true' # upload to Code Scanning ``` ### 所有选项 | 输入 | 默认值 | 描述 | |-------|---------|-------------| | `command` | _(必需)_ | 要在监控下运行的命令 | | `fail-level` | `critical` | 构建失败的最低风险等级 (`critical`, `high`, `medium`, `low`) | | `config` | `''` | `.bheeshmarc.json` 文件路径 | | `sarif-output` | `bheeshma-results.sarif` | SARIF 输出文件路径 | | `skip-low` | `true` | 在 SARIF 中跳过 LOW 风险信号（减少噪音） | | `upload-sarif` | `true` | 将 SARIF 上传到 GitHub 代码扫描 | ### 高级：多个命令 ``` - name: Monitor npm install uses: bb1nfosec/bheeshma/.github/actions/bheeshma@main with: command: 'npm ci' fail-level: 'high' - name: Monitor tests uses: bb1nfosec/bheeshma/.github/actions/bheeshma@main with: command: 'npm test' fail-level: 'critical' sarif-output: 'bheeshma-test-results.sarif' ``` ## npm install 监视器 2025-2026 年**首要攻击向量**是恶意软件包在 `npm install` 期间窃取 CI 密钥。BHEESHMA 监视每个软件包在安装时的行为： ``` # 监控 npm install npx bheeshma install # 监控 npm ci (lockfile-strict) npx bheeshma install ci # 监控安装特定包 npx bheeshma install -- --save-dev some-package # 为 CI 输出 SARIF npx bheeshma install -- --sarif --output install-results.sarif ``` 它能捕捉： - 运行 shell 命令的 `postinstall` 脚本 - 读取 `.npmrc`, `.env` 或凭据文件的软件包 - 安装期间的出站网络连接 - 在 `node_modules/` 之外的文件写入 ## CLI 用法 ### 监控任何命令 ``` # 监控 Node.js 应用 bheeshma -- node app.js # 监控测试套件 bheeshma -- npm test # 监控特定脚本 bheeshma -- node scripts/build.js ``` ### 输出格式 ``` # CLI (默认, 色彩编码终端输出) bheeshma -- node app.js # JSON (机器可读, 适用于流水线) bheeshma --format json --output report.json -- npm test # HTML (自包含深色主题报告) bheeshma --format html --output report.html -- node app.js # SARIF (GitHub Code Scanning 集成) bheeshma --format sarif --output results.sarif -- npm test ``` ### 强制模式 ``` # 若任何包为 CRITICAL 则退出码为 1 bheeshma --enforce -- npm test # 遇到 HIGH 或更高级别时失败 bheeshma-ci --fail-level high -- npm test # JSON 输出 + 策略强制执行 bheeshma --enforce --format json --output report.json -- npm test ``` ### CI 优化模式 ``` # bheeshma-ci 是针对 CI 流水线优化的轻量封装 # - 无 ANSI 颜色，无 HTML # - 默认输出 SARIF # - 支持策略执行的退出码 # - GitHub Actions ::error 标注 bheeshma-ci -- npm test bheeshma-ci --fail-level high --output results.sarif -- npm test ``` ### 子命令 ``` bheeshma install # Monitor npm install bheeshma ci -- # CI-optimized mode bheeshma -- # Standard monitoring ``` ### 编程式 API ``` const bheeshma = require('bheeshma'); // Initialize with default settings bheeshma.init(); // Your application code runs here require('./your-app'); // Generate report in any format console.log(bheeshma.generateReport('cli')); console.log(bheeshma.generateReport('json')); console.log(bheeshma.generateReport('sarif')); // Check enforcement policy const result = bheeshma.enforcePolicy(); if (!result.passed) { console.error('Policy violation:', result.message); process.exit(1); } ``` ## BHEESHMA 监控什么 | 行为 | 信号类型 | 风险 | 检测内容 | |----------|-------------|------|------------------| | 环境变量访问 | `ENV_ACCESS` | 中 | 凭据窃取，API 密钥泄露 | | 文件系统读取 | `FS_READ` | 低 | 侦察，凭据文件访问 | | 文件系统写入 | `FS_WRITE` | 高 | 持久化，后门安装 | | 原始 TCP 连接 | `NET_CONNECT` | 高 | 反向 Shell，C2 通信 | | HTTP 请求 | `HTTP_REQUEST` | 高 | 未加密数据泄露 | | HTTPS 请求 | `HTTPS_REQUEST` | 中高 | 加密数据泄露 | | DNS 查询 | `DNS_QUERY` | 中高 | DNS 隧道，编码子域数据泄露 | | Shell 执行 | `SHELL_EXEC` | 严重 | 任意代码执行 | | 混淆代码 | `OBFUSCATION_DETECTED` | 严重 | 隐藏负载，`eval`/`Function` | | 黑名单软件包 | `BLACKLISTED_PACKAGE` | 严重 | 已知恶意软件包 | ### 模式检测 BHEESHMA 关联信号以检测复杂的攻击模式： | 模式 | 信号 | 严重性 | |---------|---------|----------| | **加密货币挖矿** | `WALLET_ADDRESS` + `MINING_POOL` 环境变量 | 严重 | | **数据泄露** | 凭据文件读取 + 出站 HTTP | 严重 | | **后门** | Shell 执行 + 反向连接 | 严重 | | **凭据窃取** | `.env`/`.npmrc` 读取（上下文感知） | 高/低* | | **Typosquat** | 软件包名称与流行软件包相似 | 高 | *上下文感知：`dotenv` 读取 `.env` = 低（预期行为）。随机软件包读取 `.env` = 高（可疑）。 ### 信任评分 每个软件包获得一个**确定性的信任评分 [0-100]**： - **80-100（低风险）**：行为极少或良性 - **60-79（中风险）**：中等活动，建议审查 - **30-59（高风险）**：高活动性，需要调查 - **0-29（严重风险）**：高度可疑，需要立即行动 ## 配置 在你的项目根目录创建 `.bheeshmarc.json`（完全可选）： ``` { "thresholds": { "critical": 30, "high": 60, "medium": 80 }, "packageThresholds": { "axios": 40, "express": 50 }, "whitelist": ["express@*", "@types/*"], "blacklist": ["malicious-package"], "patterns": { "enabled": true, "detectCryptoMiners": true, "detectDataExfiltration": true, "detectBackdoors": true }, "performance": { "maxSignals": 10000, "deduplicateSignals": true } } ``` 或者使用 `bheeshma --config .bheeshmarc.json -- node app.js`。 ## 耻辱墙仪表板 [](https://bb1nfosec.github.io/bheeshma/) **bheeshma 耻辱墙**是一个实时威胁情报仪表板，跟踪每一个已知的 npm 供应链攻击，并展示 bheeshma 如何捕获它们。 **在线地址：** [bb1nfosec.github.io/bheeshma](https://bb1nfosec.github.io/bheeshma/) ### 它展示了什么 - **20+ 个精心策划的供应链威胁** — 从 axios 妥协事件到 Shai-Hulud 再到 AI 主题钓鱼软件包 - **实时 OSV 源** — 来自开源漏洞数据库的实时 npm 漏洞 - **100% bheeshma 覆盖率** — 每一个被跟踪的威胁都在运行时被 bheeshma 信号捕获 - **趋势图** — 供应链攻击频率随时间变化（2024-2025） - **攻击类型细分** — 恶意软件、typosquat、后门、凭据窃取、抗议软件、数据泄露 - **信号检测条形图** — 在所有已知攻击中，哪些 bheeshma 信号触发最多 ### 自动更新 仪表板通过 GitHub Actions **每天 UTC 06:00** 刷新： 1. `scripts/fetch-threats.js` 从 **OSV API** 获取最新的 npm 漏洞 2. 与策划的本地威胁数据库合并 3. 重新生成 `dashboard/data/threats.json` 4. 提交并推送更新的数据 5. GitHub Pages 自动部署更新的仪表板 ### 添加你自己的威胁 编辑 `scripts/fetch-threats.js` 并向 `CURATED_THREATS` 数组中添加条目。格式： ``` { id: 'T2025-021', package: 'package-name', version: '1.0.0', title: 'Short descriptive title', description: 'Full description of the attack', severity: 'critical', // critical | high | medium | low type: 'backdoor', // malware | typosquat | backdoor | data-exfil | etc. date: '2025-05-01', status: 'removed', // active | removed | patched | unpublished downloads: '50K+', bheeshma_signals: ['NETWORK_CONNECTION', 'SHELL_EXEC', 'DNS_QUERY'], references: ['https://source-url'], cve: 'CVE-YYYY-XXXXX' // optional } ``` ## 安全保证 - **零遥测** — 无出站通信（除非配置了 webhook 警报） - **仅本地** — 所有处理都在你的机器上进行 - **零依赖** — 纯 Node.js，不需要 npm 软件包 - **仅元数据** — 永不捕获密钥、文件内容或请求体 - **非侵入式** — 观察行为而不修改它 - **故障安全** — 钩子错误永远不会中断你的应用程序 - **信号不可变** — 所有信号在创建后被冻结 ## 安装 ``` # 全局安装 npm install -g bheeshma # 或使用 npx (无需安装) npx bheeshma -- node app.js ``` **要求：** Node.js >= 14.0.0。无其他依赖。 ## 架构 ``` ┌──────────────────────────────────────────────────────┐ │ CLI Layer │ │ bheeshma │ bheeshma-ci │ bheeshma-install │ └──────────────────┬───────────────────────────────────┘ │ ┌──────────────────▼───────────────────────────────────┐ │ Output Formatters │ │ CLI │ JSON │ HTML │ SARIF v2.1.0 │ └──────────────────┬───────────────────────────────────┘ │ ┌──────────────────▼───────────────────────────────────┐ │ Policy Engine + Trust Scoring │ │ Enforcement │ Thresholds │ Dedup │ Blacklist │ └──────────────────┬───────────────────────────────────┘ │ ┌──────────────────▼───────────────────────────────────┐ │ Pattern + Obfuscation Detection │ │ Crypto │ Exfil │ Backdoors │ Typosquat │ Static │ └──────────────────┬───────────────────────────────────┘ │ ┌──────────────────▼───────────────────────────────────┐ │ Attribution Engine │ │ Stack trace → outermost node_modules resolution │ └──────────────────┬───────────────────────────────────┘ │ ┌──────────────────▼───────────────────────────────────┐ │ Runtime Hooks (6 types) │ │ env │ fs │ net │ http │ dns │ child_process │ ├──────────────────────────────────────────────────────┤ │ Worker Thread Support │ ESM Loader │ └──────────────────────────────────────────────────────┘ ``` ## 测试 ``` npm test # 41/41 tests, no network required ``` 所有测试**离线**运行，结果**确定性**。 ## 为什么是运行时，而不是静态？ 每一个主要的 npm 安全工具 — Socket.dev, Snyk, Dependabot, npm audit — 都是**安装前的静态分析**。它们在代码*运行前*扫描。它们无法看到软件包在*运行时*实际做了什么。 | | 静态分析（Snyk, Dependabot） | **BHEESHMA（运行时）** | |---|---|---| | 在执行前扫描代码 | ✅ | ❌（监视它*实际做了什么*） | | 捕获混淆的运行时负载 | ❌ | ✅ | | 在运行时检测窃取的环境变量 | ❌ | ✅ | | 看到动态 DNS 隧道 | ❌ | ✅ | | 捕获 `eval`/`Function` 构造函数 | ❌ | ✅ | | 需要互联网/数据库 | ✅ | ❌（100% 离线） | | 零依赖 | ❌ | ✅ | | SARIF / 代码扫描 | ✅（部分） | ✅ | | 开源 | ❌（大部分） | ✅ | **BHEESHMA 能捕捉到每个静态工具错过的攻击。** 将它们结合使用 — 静态分析用于已知 CVE，bheeshma 用于其他一切。 ## 贡献 欢迎贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 获取指南。 **我们特别需要：** - 真实世界攻击重放脚本（例如我们的 [demos/](demos/)） - 附带重现步骤的误报报告 - 新的钩子类型（例如，`crypto`, `fs.watch`） - 大型代码库的性能优化 ## 许可证 **Apache License 2.0** ## 致谢 由安全工程师构建，他们相信 npm 生态系统应该拥有一个任何人都能使用、理解和信任的运行时监控工具。 **BHEESHMA**：信任，但要验证。在运行时。

标签：CI/CD管道保护, GitHub Action, JavaScript安全, LNA, MITM代理, Node.js安全, npm安全, SARIF输出, 供应链攻击防护, 依赖管理, 开源安全项目, 恶意包检测, 漏洞扫描工具, 自定义脚本, 运行时监控, 运行时行为分析, 零依赖工具, 静态分析对比