Rushabh5000/dep-warden

# DepWarden — 免费软件成分分析 (SCA) 与供应链扫描器 [](https://depwarden.in) [](https://www.npmjs.com/package/depwarden) [](https://www.npmjs.com/package/depwarden) [](LICENSE) [](https://depwarden.in) **DepWarden 是一款免费、匿名的软件成分分析 (SCA) 工具及供应链扫描器。** 粘贴清单或 lockfile —— 或者指向一个公开仓库 —— 它就会将每一个开源依赖项与 **实时漏洞情报** (OSV.dev, CISA KEV, FIRST EPSS) 进行比对扫描，捕获**域名仿冒 (typosquat) 和依赖混淆**攻击，标记**高风险许可证、已弃用和已停止维护 (EOL)** 的包， 根据**真实世界的可利用性**对所有内容进行排名，并为您提供**一键修复**方案。无需账户， 且您的源代码永远不会被上传。 **用例：** [软件成分分析](https://depwarden.in/software-composition-analysis) · [免费漏洞扫描器](https://depwarden.in/free-vulnerability-scanner) · [SBOM 扫描器 (CycloneDX/SPDX)](https://depwarden.in/sbom-scanner) · [免费 Snyk 替代品](https://depwarden.in/vs/snyk) 作为 Snyk、Black Duck、Mend 和 JFrog Xray 在依赖项扫描方面的免费替代品 —— 专为希望 在几秒钟内获得结果，而无需账户或上传源代码的开发者打造。位于 [depwarden.in](https://depwarden.in) 的托管应用运行在私有、会话隔离的工作区中；此仓库是其背后的完整平台（多租户、基于角色的、 实时的、通过所有上游源的**每日本地镜像**支持离线能力 —— 没有任何模拟数据）。 ### 快速开始 (CLI —— 免安装，免账户) ``` # Node >= 18 — 仅扫描 manifest 文本，绝不扫描您的源代码 npx depwarden scan package-lock.json --fail-on high npx depwarden diff base/package-lock.json package-lock.json --fail-on-new high ``` 或使用 GitHub Action： ``` - uses: Rushabh5000/dep-warden/cli@v1 with: file: package-lock.json fail-on: high ``` ## 功能 ### 扫描 (8 大生态系统) - 粘贴清单/lockfile **或** 上传文件（包括二进制 `.jar`/`.war`/`.ear`）。 - 自动格式检测，在 lockfile 提供的情况下进行完整的传递依赖树解析。 - 每次扫描提供**风险评分 (0–100)**、严重程度统计、直接与传递依赖深度对比，以及依赖项边。 | 生态系统 | 接受的输入 | OSV 源 | |-----------|-----------------|------------| | npm | `package-lock.json` (v1/v2/v3), `package.json` | npm | | PyPI | `requirements.txt` | PyPI | | Go | `go.mod` | Go | | Cargo | `Cargo.lock` | crates.io | | RubyGems | `Gemfile.lock` | RubyGems | | Maven / Java | `pom.xml`, `build.gradle`, `.jar` / `.war` / `.ear` | Maven | | NuGet | `.csproj`, `packages.config`, `packages.lock.json` | NuGet | | Composer | `composer.json`, `composer.lock` | Packagist | ### 漏洞与风险情报 - **OSV.dev 关联**，针对每个生态系统进行准确的 semver/范围匹配。 - **CISA KEV** 扩充 —— 标记已知被利用的漏洞。 - **FIRST EPSS** 扩充 —— 为每个 CVE 提供漏洞利用概率评分。 - 通过 OSV `MAL-` 公告进行**恶意软件检测**。 - 通过 deps.dev 进行**许可证解析**，包含 SPDX 标识符、类别和义务。 - **CycloneDX SBOM** 生成与下载（包含真实的 `urn:uuid` 序列号）。 ### 离线弹性 —— 每日本地镜像 - **OSV.dev（所有 8 个生态系统）**、**CISA KEV** 和 **FIRST EPSS** 的本地 SQLite 镜像。 - **镜像优先读取**：扫描和公告查询使用本地快照；实时网络作为后备方案。 - 在启动时（如果数据过期）、每小时以及从**数据源**管理页面按需刷新。 - 持久化的 deps.dev 许可证缓存，确保已解析的许可证在重启或中断后依然可用。 ### 分流与探索 - 跨所有扫描的**发现结果浏览器** —— 按严重程度、类型、仅直接依赖、可提供修复和自由文本进行筛选。 - **公告数据库** —— 按 ID（CVE/GHSA/…）或按包 + 生态系统进行查询。 - 每次扫描的**依赖图**和**爆炸半径**（即某个公告会影响哪些项目）。 - **升级指导**（类似 BlackDuck）—— 对于每个易受攻击的组件，提供**无已知漏洞**的最近发布版本以及最新发布版本，可下载为 CSV 表格。发布版本信息来自 deps.dev / Packagist；每个候选版本都会根据 OSV 镜像重新核对。 - 跨组件、发现结果、项目和公告的**全局搜索**。 ### 治理 - **策略门禁** —— 根据严重程度、最高 CVSS、可提供修复、恶意软件、KEV 或被阻止的许可证来判定扫描失败。 - **例外 / 豁免** —— 限定于公告、组件或项目范围，包含理由、有效期和审批工作流。 ### 报告与协作 - **报告** —— 四份详细的独立报告（风险摘要、许可证合规性、漏洞详情、SBOM 清单）**外加一份汇总报告**。支持浏览器内实时预览，并可下载 **HTML、PDF、Excel (XLSX) 和 CSV** 格式（带品牌标识的 HTML 报告是视觉核心）。 - **定时报告推送** —— 可通过 UI 配置的定时任务（每日 / 每周 / 每月；可选报告、格式和收件人），**通过 SMTP 发送邮件**（在 UI 中配置；nodemailer）。包含“立即运行”、推送历史记录，以及未设置 SMTP 时的沙箱测试收件箱。 - **集成** —— 具有实时“测试”按钮的出站 **webhook** 和 **Slack** 推送；在扫描/告警事件时触发。 - **告警** 带有实时通知铃铛（Server-Sent Events）。 - 每一个重要操作的**不可变审计日志**。 ### 平台与安全 - **JWT 认证**，支持工作区切换的**多租户**工作区。 - **基于角色的访问控制**：`viewer → auditor → developer → secops → admin → owner`。 - React 仪表盘，包含 KPI、严重程度分布、14 天趋势以及最容易受攻击的组件。 ## 技术栈 - **后端：** Node + Express + TypeScript + **内置 SQLite** (`node:sqlite` —— 无需 Prisma，无需原生插件，无需下载引擎二进制文件)，JWT 认证。 - **前端：** React + Vite + Tailwind + Recharts + React Router。 - **情报：** OSV.dev, CISA KEV, FIRST EPSS, deps.dev（全部在本地镜像）。 - **导出：** PDFKit (PDF), ExcelJS (XLSX), CycloneDX (SBOM)。 ## 项目结构 ``` dep-warden/ ├─ backend/ Express API (port 4000), node:sqlite store │ ├─ src/lib/schema.ts Data model (tenants, scans, findings, mirror tables, …) │ ├─ src/lib/db.ts Lightweight SQLite data layer (Prisma-compatible API) │ └─ src/ │ ├─ index.ts App entry, mounts routes, starts mirror scheduler │ ├─ seed.ts Production bootstrap (admin user, reference data) │ ├─ routes/ auth.ts, api.ts │ ├─ lib/ parser.ts, jar.ts, semver.ts, auth.ts, events.ts, db.ts, prisma.ts │ └─ services/ scanner, osv, mirror, mirrorStore, licenseResolver, │ reportExport, notify ├─ frontend/ React + Vite app (port 5180) │ └─ src/pages/ Dashboard, Projects, NewScan, ScanDetail, Findings, │ Advisories, Licenses, Alerts, Policy, Exceptions, │ Reports, Audit, Integrations, DataSources, Settings, Search └─ docs/ User Guide (.docx) + screenshots ``` ## 入门指南 ``` # 从 dep-warden/ 目录 npm install # root tooling (concurrently) npm run setup # installs backend + frontend, seeds reference data (tables auto-create on first run) npm run dev # API on http://localhost:4000, UI on http://localhost:5180 ``` 打开 **http://localhost:5180** 并使用初始化的管理员账户登录，然后前往 **New Scan → Load sample → Run scan**。 ### 默认凭据 | 字段 | 默认值 | 覆盖项 | |-------|---------|----------| | 邮箱 | `admin@depwarden.in` | `SEED_ADMIN_EMAIL` | | 密码 | `changeme` | `SEED_ADMIN_PASSWORD` | ### 配置（环境变量） 在 **`backend/.env`** 中设置这些变量（启动时自动加载 —— 从 [`backend/.env.example`](backend/.env.example) 复制即可），或设置为真实的环境变量 （其优先级高于文件）。无需 `dotenv` 依赖。 | 变量 | 默认值 | 用途 | |----------|---------|---------| | `PORT` | `4000` | 后端 API 端口 | | `JWT_SECRET` | 开发密钥 | Token 签名密钥 —— **在生产环境中务必设置** | | `SEED_ADMIN_EMAIL` | `admin@depwarden.in` | 引导管理员邮箱 | | `SEED_ADMIN_PASSWORD` | `changeme` | 引导管理员密码 | | `SEED_ADMIN_NAME` | `Administrator` | 引导管理员显示名称 | | `SEED_TENANT_SLUG` | `default` | 引导工作区 Slug | | `SEED_TENANT_NAME` | `My Organization` | 引导工作区名称 | | `MAX_UPLOAD_MB` | `50` | 最大上传 / 请求体大小，单位为 MB（文件上传**和**粘贴的清单） | | `DB_DRIVER` | `sqlite` | 存储引擎：`sqlite`（文件，持久化）或 `memory`（临时）。使用 Node 内置的 SQLite —— 无需下载引擎二进制文件 | | `DB_FILE` | `./data/depwarden.db` | SQLite 文件位置（sqlite 驱动）。也支持 `DATABASE_URL`（带有可选的 `file:` 前缀） | | `INSECURE_TLS` | `false` | 跳过**所有**出站 HTTPS 的 TLS 证书验证（企业代理的最后手段 —— 仅限受信任的网络） | | `NODE_EXTRA_CA_CERTS` | — | CA Bundle 的路径（信任企业代理 CA 的首选方法，保持开启验证） | | `MAVEN_REPO_URL` | `https://repo1.maven.org/maven2` | 用于有效 POM 解析的 Maven 仓库 | | `JAR_MAX_EMBEDDED_POMS` | `12` | 每个压缩包解析的最大内嵌 `pom.xml` 文件数（限制获取扇出） | 前端将 `/api` 代理到 `http://localhost:4000`（参见 `frontend/vite.config.ts`）。 ## 扫描工作原理 1. **解析** —— `backend/src/lib/parser.ts`（对于压缩包则是 `jar.ts`）检测格式并 提取组件 + 依赖项边。 2. **关联** —— `services/scanner.ts` 通过 `services/osv.ts`（使用 `lib/semver.ts` 进行范围检查）将每个组件与 OSV 镜像进行匹配，并用 KEV + EPSS 进行扩充。 3. **解析许可证** —— `services/licenseResolver.ts`（deps.dev，本地缓存）。 4. **评分与门禁** —— 计算并持久化风险评分、SBOM 和策略判定。 5. **通知** —— `scan.completed` 事件通过 SSE 扇出并推送到已配置的集成。 读取采用**镜像优先**：`services/mirror.ts` 维护本地快照， 而 `services/mirrorStore.ts` 负责提供服务，因此当上游不可达时，步骤 2-3 仍可继续工作。 ## 角色与权限 访问权限在每个端点强制执行；每个角色都继承其下方角色的权限。 | 角色 | 可执行操作 | |------|--------| | Viewer (查看者) | 读取仪表盘、发现结果、公告、许可证、报告 | | Auditor (审计员) | + 读取审计日志 | | Developer (开发者) | + 运行扫描、请求例外、生成报告 | | SecOps (安全运维) | + 编辑策略、批准/拒绝例外 | | Admin (管理员) | + 管理集成和成员、触发镜像刷新 | | Owner (所有者) | 完整的工作区控制权 | ## API 表面（高层视图） 所有路由都在 `/api` 下，并且需要 Bearer token（除了 `/api/auth/login`）。 - **认证：** `POST /auth/login`, `POST /auth/switch-tenant`, `GET /auth/me` - **扫描：** `POST /scans`, `GET /scans`, `GET /scans/:id`, `GET /scans/:id/sbom`, `GET /scans/:id/upgrade-guidance`, `POST /scans/:id/recorrelate` - **探索：** `GET /dashboard`, `GET /projects`, `GET /findings`, `GET /graph/:scanId`, `GET /graph/impact/:advisoryId`, `GET /search`, `GET /advisories` - **治理：** `GET/PUT /policy`, `GET/POST /exceptions`, `POST /exceptions/:id/:decision` - **运维：** `GET /alerts`, `GET /licenses`, `GET /audit`, `GET/POST/DELETE /integrations`, `POST /integrations/:id/test` - **报告：** `GET /report-preview?kind=master|individual&type=…`, `GET /-render?…&format=html|pdf|xlsx|csv`, `GET/POST/PUT/DELETE /report-schedules`, `POST /report-schedules/:id/run`, `GET /report-runs`, `GET/PUT /mail-settings`, `POST /mail-settings/test` - **镜像：** `GET /mirror`, `POST /mirror/refresh` - **实时：** `GET /events` (SSE) ## 测试 完整的端到端回归测试套件（零额外依赖 —— 仅使用 Node 的 `fetch`/`http`/`assert`） 针对实时服务器测试了每一项功能： ``` # backend 必须运行在 :4000 node backend/_regression.mjs ``` 它涵盖了认证/RBAC、所有 8 个生态系统扫描器（解析 + 真实 OSV 关联）、SBOM、发现结果 筛选器、依赖图、策略、例外、告警、许可证、审计、集成（真实的 webhook 推送）、报告（真实的 PDF/XLSX）、搜索、公告和镜像 —— 共 **82 项检查**。 ## 文档 包含每个屏幕带注释截图的完整最终用户手册位于 `docs/DepWarden_User_Guide.docx`。 ## 注意事项与路线图 事件总线（`lib/events.ts`）是一个扇出到 SSE 的进程内 `EventEmitter`； 蓝图中用于分布式架构的替代方案（Kafka + Redis, Postgres, 外部调度器）是目前 剩余的单实例与分布式架构的切换项，只有在扩展至超过单个后端进程时才会发挥作用。

标签：DevSecOps, GNU通用公共许可证, MITM代理, Node.js, 上游代理, 依赖管理, 文档安全, 自动化攻击, 配置审计