SalkCoding/Oswl

## 什么是 OsWL？ **OsWL**（开源软件监控清单）是一个内部 **SCA（软件成分分析）** 平台，用于跟踪和管理 OSS 依赖项中的安全漏洞 (CVE) 和许可证风险。 它为您的整个软件组合提供了一个统一的仪表板——连接您的 Git 仓库进行自动导入，或通过 CLI 推送扫描结果，然后立即查看按 CVSS 排名的漏洞列表、许可证合规状态、随时间变化的风险趋势以及 AI 生成的洞察。 ### 核心功能 | 功能 | 描述 | |---|---| | **安全中心** | 包含 CVSS 评分、严重性排名和状态管理（待处理 / 已抑制 / 误报）的完整 CVE 列表 | | **许可证分析** | 对每个依赖项进行 SPDX 许可证检测，并执行策略（允许 / 警告 / 限制） | | **风险趋势** | 最多包含 10 次扫描的历史风险图表，显示 CVE 数量和许可证态势变化 | | **版本差异对比** | 并排比较两次扫描结果——新增、移除和更改的依赖项 | | **快速导入** | 通过 VCS 连接从 GitHub / GitLab / Bitbucket 一键导入 | | **CLI 集成** | 通过 REST API 提交与语言无关的扫描，支持项目范围的 API 密钥 | | **AI 洞察** | 可选的由 LLM 生成的风险摘要，涵盖 CVE 态势和许可证合规性 | | **基于角色的访问控制** | 角色模板（管理员 / 开发者 / 查看者）以及每个项目的成员资格 | | **审计日志** | 针对所有用户和系统事件的不可变审计日志，支持 CSV 导出 | | **双因素认证 / 受信任设备** | 基于邮件 OTP 的双因素认证，支持基于浏览器的受信任设备 | ## 快速开始 ### 前置条件 | 工具 | 版本 | |---|---| | JDK | 25+ | | Gradle Wrapper | 已包含（`./gradlew`） | | PostgreSQL | 15+（生产环境） | | (可选) Docker | 用于在本地运行 PostgreSQL | ### 1. 克隆仓库 ``` git clone https://github.com/SalkCoding/Oswl.git cd Oswl ``` ### 2. 本地运行（H2 文件模式） ``` ./gradlew bootRun # 应用程序启动于 http://localhost:8080 ``` 默认激活 `local` profile。它使用内嵌的 H2 数据库（`./oswl-db.mv.db`）——无需外部数据库。 首次运行时，**设置向导**将自动在 `http://localhost:8080/setup` 打开。 完成向导以创建第一个系统管理员账户。 ### 3. 使用 PostgreSQL 运行（生产 profile） ``` export SPRING_PROFILES_ACTIVE=prod export DB_URL=jdbc:postgresql://localhost:5432/oswl export DB_USERNAME=oswl export DB_PASSWORD=your_password export OSWL_ENCRYPTION_KEY=$(openssl rand -base64 32) ./gradlew bootRun ``` ## 构建 ``` # 完整构建（编译 Java + Tailwind CSS） ./gradlew build # 生产 JAR 检查（仅限本地的测试端点不得打包） ./gradlew verifyProdJar # 仅重新构建 Tailwind CSS ./gradlew buildTailwindCss # 运行测试 ./gradlew test # 测试覆盖率报告 → build/reports/jacoco/test/html/index.html ./gradlew jacocoTestReport ``` ## 配置参考 所有设置均通过环境变量或 `application.yaml` profile 进行控制。 | 变量 | 默认值 | 描述 | |---|---|---| | `SPRING_PROFILES_ACTIVE` | `local` | 激活的 profile：`local` 或 `prod` | | `OSWL_ENCRYPTION_KEY` | *(仅限本地开发)* | 存储机密（VCS token）的加密密钥。**在 `prod` 环境中必填**——缺少此项应用将无法启动。使用 `openssl rand -base64 32` 生成 | | `DB_URL` | `jdbc:postgresql://localhost:5432/oswl` | PostgreSQL JDBC URL（prod profile） | | `DB_USERNAME` | `oswl` | 数据库用户名（prod profile） | | `DB_PASSWORD` | `oswl` | 数据库密码（prod profile） | | `OSWL_CLONE_TEMP_DIR` | 系统 temp | 在快速导入期间用于临时 git 克隆的目录 | | `OSWL_GITHUB_API_BASE` | `https://api.github.com` | GitHub API 基础 URL（针对 GHES 进行覆盖） | | `OSWL_RISK_TREND_LIMIT` | `10` | 风险趋势图表中显示的最大扫描次数 | | `OSWL_AUDIT_MAX_PAGE_SIZE` | `200` | 审计日志 API 中每页的最大记录数 | | `OSWL_AUDIT_RETENTION_MONTHS` | `6` | 审计日志记录被自动删除前的保留月数 | ## 本地开发附加说明 ### H2 控制台 ``` URL: http://localhost:8080/h2-console JDBC: jdbc:h2:file:./oswl-db User: sa Pass: (empty) ``` ### OTP 邮件（local profile） `local` profile 会启动一个内嵌的 **GreenMail** SMTP 服务器。不会发送真实邮件。 OTP 验证码会显示在服务器日志中： ``` *** OTP CODE: 123456 *** ``` ### 填充测试数据 登录后，调用： ``` GET http://localhost:8080/data/test ``` 这将重置**所有**现有数据，并使用大量示例项目、扫描、CVE 和许可证填充数据库。 ## 架构概览 ``` Browser / CLI │ ▼ Spring MVC Controllers (thin — delegates to Service) │ ▼ Service Layer (business logic, transactions) │ ┌─┴──────────────────┐ ▼ ▼ JPA Repositories External Clients (PostgreSQL / H2) (OSV · deps.dev · VCS APIs) ``` **核心领域模型：** ``` Project └── ProjectVersion (per branch) └── ScanResult (per CLI / Quick Import scan) └── ScanComponent └── DependencyPath Library (shared across projects — group:artifact@version) └── Cve └── LicensePolicyEntry ``` ## API 文档 在 **`local` profile** 下，可以通过 `http://localhost:8080/swagger-ui.html` 访问交互式 Swagger UI。在 `prod` 环境中**已禁用**。 ## 文档 完整文档可在 [`docs/`](docs/) 文件夹和 [GitHub Wiki](https://github.com/SalkCoding/Oswl/wiki)（推送至 `main` 分支时从 `docs/` 自动同步）中查看。韩语文档位于 [`docs/ko/`](docs/ko/)。 | 页面 | 描述 | |---|---| | [首页](docs/Home.md) | 平台概览和导航指南 | | [新手入门](docs/Getting-Started.md) | 安装、设置向导、第一个项目 | | [用户指南](docs/User-Guide.md) | 仪表板的日常使用 | | [快速导入](docs/Quick-Import.md) | 从 GitHub / GitLab / Bitbucket 导入项目 | | [CLI 集成](docs/CLI-Integration.md) | 从构建流水线提交扫描 | | [安全中心](docs/Security-Center.md) | 管理漏洞 (CVE) | | [许可证分析](docs/License-Analysis.md) | 许可证合规性和策略管理 | | [风险趋势](docs/Risk-Trend.md) | 解读历史风险图表 | | [版本差异对比](docs/Version-Diff.md) | 比较两次扫描结果 | | [系统管理](docs/Administration.md) | 用户、角色、审计日志、安全设置 | | [授权层级](docs/Authorization-Layers.md) | 角色模板与项目成员资格 | | [生产环境部署](docs/Production-Deployment-Checklist.md) | 生产环境检查清单 | | [数据库 schema](docs/Database-Schema.md) | `ddl-auto` 策略和 SQL 迁移 | | [扫描 API 安全](docs/Scan-Api-Security.md) | CLI 扫描认证和审计日志 | | [API 参考](docs/API-Reference.md) | REST API endpoint 摘要 | | [术语表](docs/Glossary.md) | 术语和定义 | ## 作者 OsWL 由 **[SalkCoding](https://github.com/SalkCoding)** 开发和维护。 | 作者 | 角色 | GitHub | |---|---|---| | SalkCoding | 项目负责人和主要维护者 | [@SalkCoding](https://github.com/SalkCoding) | | Tengball | 设计和 UI/UX | [@Tengball](https://github.com/Tengball) | 欢迎通过 [GitHub Issues](https://github.com/SalkCoding/Oswl/issues) 提出问题、反馈或合作咨询。 ## 许可证 本项目基于 [MIT 许可证](LICENSE) 授权。

标签：GPT, JS文件枚举, PostgreSQL, Spring Boot, 后台面板检测, 域名枚举, 开源合规, 测试用例, 漏洞管理, 许可证分析