kato83/mayu

# Mayu [日本語版 (日语)](README_ja.md) 一个统一的漏洞情报工具，聚合多个来源（OSV、NVD 等），通过 CLI、API 和 Web UI 进行跨平台查询。 ## 概述 Mayu 将来自 [OSV](https://osv.dev/) 生态系统的漏洞数据提取到本地 PostgreSQL 数据库中，从而实现对已知漏洞的快速跨平台搜索和分流处理。 **当前功能：** - 从 GCS bucket 完整导入和增量导入 OSV 漏洞数据 - 基于 CLI 的漏洞搜索，支持按 ID、包名、生态系统或别名查询 - 支持所有 OSV 生态系统（Go、PyPI、npm、Maven、crates.io 等） - 保留原始的 OSV JSON 以确保数据的完全可逆性 ## 命名 **Mayu** 来源于日语词汇 *繭 (mayu)*，意为“茧”——蚕为自己吐丝结成的保护壳。这个名字反映了该工具的目的：利用漏洞情报为您的环境包裹一层温和而富有韧性的保护。作为一个四个字母的名字，且易于小写化，它也非常适合现代的 CLI / API / Web UI 工具链（`mayu`、`mayu-server` 等）。 ## 快速开始 ### 前置条件 - [Go 1.26+](https://go.dev/)（通过 [asdf](https://asdf-vm.com/) 管理） - [Docker](https://www.docker.com/) & Docker Compose - [golang-migrate](https://github.com/golang-migrate/migrate) CLI ### 设置 ``` # Clone repository git clone https://github.com/kato83/mayu.git cd mayu # 通过 asdf 安装 Go asdf install # 启动 PostgreSQL make docker-up # 运行数据库迁移 make migrate-up # 构建 CLI make build ``` ### 导入漏洞数据 ``` # 导入所有 Go ecosystem 漏洞（完全同步） ./bin/mayu ingest --ecosystem Go # 通过 delta update 导入（仅同步自上次同步以来的新增/修改） ./bin/mayu ingest --ecosystem Go --update # 导入所有受支持的 ecosystem（每个 ecosystem 独立的 all.zip） ./bin/mayu ingest --all # 以自定义并发数导入所有 ecosystem ./bin/mayu ingest --all --concurrency 5 --store-workers 8 # 从单个顶层 all.zip 批量导入（约 1.3GB，一次性导入所有 ecosystem） ./bin/mayu ingest --all --bulk ``` ### 搜索漏洞 ``` # 按 vulnerability ID 搜索 ./bin/mayu search --id GO-2024-2687 # 按 package name 搜索 ./bin/mayu search --package golang.org/x/crypto # 按 ecosystem 搜索 ./bin/mayu search --ecosystem Go --limit 10 # 按 CVE alias 搜索 ./bin/mayu search --alias CVE-2024-24790 # 按 Package URL (purl) 搜索 ./bin/mayu search --purl pkg:npm/%40angular/core # 位置参数（自动检测 ID 或 alias） ./bin/mayu search CVE-2024-24790 # 按 severity level 过滤 ./bin/mayu search --severity critical --ecosystem Go # 按日期过滤（自该修改时间起） ./bin/mayu search --since 2024-01-01 --ecosystem npm # 按 affected version 过滤 ./bin/mayu search --package golang.org/x/crypto --version 0.17.0 # 分页 ./bin/mayu search --ecosystem Go --limit 10 --offset 20 # 仅统计结果数量 ./bin/mayu search --ecosystem Go --count # 详细视图（所有字段） ./bin/mayu search --id GO-2024-2687 --detail # 用于脚本的 JSON 输出 ./bin/mayu search --id GO-2024-2687 --format json # CSV 导出 ./bin/mayu search --ecosystem Go --format csv > vulns.csv ``` ### 启动 API Server ``` # 启动 API server（默认端口：8080） ./bin/mayu serve # 在自定义端口上启动 ./bin/mayu serve --addr :3000 # OpenAPI spec 可在 http://localhost:8080/openapi.yaml 获取 ``` ## CLI 参考 ### `mayu ingest` 将漏洞数据从 OSV 导入到本地数据库。 | 标志 | 描述 | 默认值 | |------|-------------|---------| | `--ecosystem` | 要导入的生态系统（例如 Go、PyPI、npm） | — | | `--all` | 导入所有生态系统（从 GCS 动态获取） | `false` | | `--bulk` | 使用顶层的 all.zip 进行批量导入（配合 `--all`） | `false` | | `--update` | 执行增量更新而不是完全导入 | `false` | | `--source` | 从转换后的源导入（nvd、debian） | — | | `--concurrency` | 并行导入的生态系统数量（配合 `--all`） | `3` | | `--store-workers` | 每个生态系统并行执行的数据库存储 worker 数量 | CPU 核心数 - 1 | | `--db-url` | PostgreSQL 连接 URL | `$DATABASE_URL` 或 `localhost` | | `--batch-size` | 每次批量插入的漏洞数量 | `100` | ### `mayu search` 在本地数据库中搜索漏洞。 | 标志 | 描述 | 默认值 | |------|-------------|---------| | `--id` | 按漏洞 ID 搜索 | — | | `--package` | 按包名搜索 | — | | `--ecosystem` | 按生态系统过滤 | — | | `--alias` | 按别名搜索（例如 CVE ID） | — | | `--purl` | 按 Package URL 搜索（例如 `pkg:npm/%40angular/core`） | — | | `--severity` | 按 CVSS 严重级别过滤（critical、high、medium、low、none） | — | | `--since` | 按修改日期过滤（YYYY-MM-DD 或 RFC3339） | — | | `--version` | 按受影响版本过滤 | — | | `--format` | 输出格式：`table`、`json`、`csv` | `table` | | `--limit` | 最大结果数 | `20` | | `--offset` | 分页偏移量 | `0` | | `--count` | 仅显示结果计数 | `false` | | `--detail` | 显示每个结果的详细信息 | `false` | | `--db-url` | PostgreSQL 连接 URL | `$DATABASE_URL` 或 `localhost` | ### `mayu version` 打印版本信息。 ### `mayu serve` 启动 API server，以便通过编程方式访问漏洞数据。 | 标志 | 描述 | 默认值 | |------|-------------|---------| | `--addr` | 监听地址（host:port） | `:8080` | | `--db-url` | PostgreSQL 连接 URL | `$DATABASE_URL` 或 `localhost` | **Endpoints：** | 方法 | 路径 | 描述 | |--------|------|-------------| | GET | `/api/v1/vulnerabilities` | 搜索漏洞（参数与 CLI 搜索相同） | | GET | `/api/v1/vulnerabilities/{id}` | 通过 OSV ID 获取单个漏洞 | | GET | `/healthz` | 健康检查 | | GET | `/openapi.yaml` | OpenAPI 3.1 规范 | **示例：** ``` # 在默认端口上启动 server ./bin/mayu serve # 在自定义端口上启动 ./bin/mayu serve --addr :3000 # 查询 API curl "http://localhost:8080/api/v1/vulnerabilities?ecosystem=Go&limit=5" curl "http://localhost:8080/api/v1/vulnerabilities/GO-2024-2687" curl "http://localhost:8080/api/v1/vulnerabilities?package=golang.org/x/crypto" curl "http://localhost:8080/api/v1/vulnerabilities?severity=critical" curl "http://localhost:8080/api/v1/vulnerabilities?purl=pkg:golang/golang.org/x/crypto" ``` ## 架构 ``` graph TD CLI["CLI (cmd/mayu)"] CLI --> Ingest[ingest] CLI --> Search[search] CLI --> Serve[serve] Ingest --> Fetcher["Fetcher (GCS)"] Ingest --> Parser["Parser (OSV)"] Ingest --> IngestPipeline["Ingest (Pipeline)"] Search --> Store["Store (PG)"] Serve --> Server["Server (HTTP/REST)"] Server --> Store IngestPipeline --> Store Store --> DB[(PostgreSQL)] ``` ## 数据源 | 来源 | 状态 | 方法 | |--------|--------|--------| | [OSV](https://osv.dev/) | ✅ 支持 | GCS bucket (`gs://osv-vulnerabilities/`) | | NVD（通过 OSV） | ✅ 支持 | 包含在 OSV 数据中 | | [NVD CVE（已转换）](https://storage.googleapis.com/cve-osv-conversion/index.html?prefix=osv-output/) | ✅ 支持 | `mayu ingest --source nvd` | | [Debian Security Advisories](https://storage.googleapis.com/debian-osv/index.html) | ✅ 支持 | `mayu ingest --source debian` | | 来源 | 状态 | 方法 | |--------|--------|--------| | KEV | 🔵 计划中 | — | | EPSS | 🔵 计划中 | — | ## 开发 ``` # 运行单元测试 make test # 运行集成测试（需要 PostgreSQL） make docker-up && make migrate-up make test-integration # Lint make lint # 构建（开发版，包含 debug symbols） make build # 构建（发布版，stripped binary 体积减小约 30%） make build-release # 停止 PostgreSQL make docker-down ``` ## 配置 | 环境变量 | 描述 | 默认值 | |---------------------|-------------|---------| | `DATABASE_URL` | PostgreSQL 连接字符串 | `postgres://mayu:mayu@localhost:5432/mayu?sslmode=disable` | ## 许可证 [MIT](LICENSE) ## 路线图 请查看 [docs/PLAN.md](docs/PLAN.md) 了解完整的实施计划。 - [x] 阶段 1：数据 Pipeline（OSV 提取） - [x] 阶段 2：CLI（提取 + 搜索） - [x] 阶段 3：CI/CD（GitHub Actions） - [x] 阶段 4：API Server（REST） - [ ] 阶段 5：Web UI（Angular） - [ ] 阶段 6：额外数据源（KEV、EPSS、MITRE CVE）

标签：EVTX分析, 日志审计, 测试用例, 请求拦截